feat(replay): sync-triage verdict bar + vocal waveforms for stems-purged jobs (v0.292.0) (#1254)

## Summary
Andrew found the standalone triage page unintuitive, with no way to scan
visually. So the **real review UI in replay mode** becomes the triage
tool for the word-timing reference set (full-auto v2): anchors, gaps,
waveforms and audio he already knows.

## Changes
- **`ReplaySyncVerdict` bar** (replay only, admin): Perfectly synced /
Not perfect, reason chips, notes, Save / **Save & next job** through the
existing `queue` URL param.
  - It shows the saved verdict and flags unsaved changes.
- It saves via `POST /api/review/{id}/sync-reference`, the same store as
the review-modal checkbox from #1242, which now also accepts `reasons`
(trimmed, max 10).
- **Vocal waveform for old jobs:** storage retention purges stems after
30 days, so replaying old jobs showed no waveform. `_review_vocals_path`
now falls back to the backfilled `training/lead_vocals/{job_id}.flac`,
but only for stems-purged jobs. It's used by the vocals stream and
vocals-peaks.
- Docs: REPLAY.md § Sync triage.

## Testing
- Backend: reasons stored trimmed and capped; waveform fallback
(registered stem preferred, purged → training copy, unpurged never
checks storage). `test_routes_review` + `test_derived_vocals` +
sync-reference tests: 143 pass.
- Frontend: `ReplaySyncVerdict.test.tsx` (save & next, reasons + notes,
saved state, unsaved flag, disabled until chosen): 5 pass. tsc shows no
new errors.
- **Manual:** local replay (read-only against prod data) on a Feb-2026
stems-purged job (83414c76). The verdict bar renders, and Waveforms mode
shows the vocal waveform via the fallback (vocals-peaks 200).
- CodeRabbit ran locally; its one finding (unsaved state) is fixed.

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_012RYLVVVPsvPbXFhRYY5VSJ

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 5.5 authored and GitHub committed 2026-11-05 21:33:16 +00:00
1 parent 394def0b53
commit d63c9781e1
8 files changed
+250 -7

No files matched your search

+22 -2
View File
@@ -582,6 +582,24 @@ def _dev_audio_proxy_enabled() -> bool:
return os.environ.get("REVIEW_AUDIO_PROXY", "").lower() in ("1", "true", "yes")
def _review_vocals_path(job) -> Optional[str]:
"""Vocals stem for the review waveform. Storage retention purges separated stems
30 days after completion; for those jobs fall back to the backfilled word-timing
training copy of the lead stem (``training/lead_vocals/{job_id}.flac``), so
replaying an old job still shows the vocal waveform. Blocking (GCS exists check)."""
from datetime import datetime as _dt
path = _vocals_stem_path(job)
purged = getattr(job, "stems_purged_at", None)
if path or not isinstance(purged, (_dt, str)) or not purged:
return path
training = f"training/lead_vocals/{job.job_id}.flac"
try:
return training if StorageService().file_exists(training) else None
except Exception: # noqa: BLE001 - best-effort fallback
return None
def _dev_audio_url(job_id: str, gcs_path: Optional[str], base_url: str = "") -> Optional[str]:
"""Build an ABSOLUTE dev-proxy URL for a review audio/image artifact.
@@ -1047,7 +1065,7 @@ async def _stream_audio(job_id: str, request: Optional[Request] = None, stem: Li
if stem == "input":
audio_gcs_path = job.input_media_gcs_path
elif stem == "vocals":
audio_gcs_path = _vocals_stem_path(job)
audio_gcs_path = await asyncio.to_thread(_review_vocals_path, job)
if not audio_gcs_path:
# Audio separation is decoupled from the lyrics-review critical path, so a
# user can open review before the vocal stems have been uploaded (the stem
@@ -1347,6 +1365,7 @@ async def complete_review(
class SyncReferenceRequest(_PydBaseModel):
verified: bool
notes: Optional[str] = None
reasons: Optional[List[str]] = None # why not perfectly synced (preset chips)
@router.post("/{job_id}/sync-reference")
@@ -1376,6 +1395,7 @@ async def set_sync_reference(job_id: str, body: SyncReferenceRequest, auth_resul
"by": auth_result.user_email or str(auth_result.user_type),
"at": datetime.now(timezone.utc).isoformat(),
"notes": (body.notes or "").strip()[:2000] or None,
"reasons": [r.strip()[:80] for r in (body.reasons or []) if r and r.strip()][:10] or None,
}
await asyncio.to_thread(job_manager.update_state_data, job_id, "sync_reference", record)
logger.info(f"Job {job_id}: sync_reference verified={body.verified} by {record['by']}")
@@ -2496,7 +2516,7 @@ async def get_vocals_peaks(
if not job:
raise HTTPException(status_code=404, detail=t("en", "review.jobNotFound"))
vocals_path = _vocals_stem_path(job)
vocals_path = await asyncio.to_thread(_review_vocals_path, job)
if not vocals_path:
if not job.state_data.get("audio_complete", False):
return Response(status_code=202, headers={"Retry-After": "15"})
@@ -101,3 +101,42 @@ def test_verified_accepts_direct_path_file(client, jm):
r = client.post("/api/review/j1/sync-reference", json={"verified": True})
assert r.status_code == 200
st.return_value.file_exists.assert_called_with("jobs/j1/lyrics/corrections_updated.json")
def test_reasons_stored_trimmed_and_capped(client, jm):
reasons = ["timing off in places", " lyrics errors ", ""] + [f"r{i}" for i in range(20)]
client.post("/api/review/j1/sync-reference", json={"verified": False, "reasons": reasons})
stored = jm.update_state_data.call_args.args[2]["reasons"]
assert stored[:2] == ["timing off in places", "lyrics errors"]
assert len(stored) == 10
# --- vocal waveform for old (stems-purged) jobs falls back to the backfilled lead stem ---
def _job(stems=None, purged=None):
j = MagicMock()
j.job_id = "j1"
j.file_urls = {"stems": stems or {}}
j.stems_purged_at = purged
return j
def test_review_vocals_path_prefers_registered_stem():
from backend.api.routes.review import _review_vocals_path
assert _review_vocals_path(_job({"vocals_clean": "jobs/j1/stems/vocals_clean.flac"})) == "jobs/j1/stems/vocals_clean.flac"
def test_review_vocals_path_purged_job_uses_training_copy():
from backend.api.routes.review import _review_vocals_path
with patch("backend.api.routes.review.StorageService") as st:
st.return_value.file_exists.return_value = True
assert _review_vocals_path(_job(purged="2026-10-05")) == "training/lead_vocals/j1.flac"
st.return_value.file_exists.return_value = False
assert _review_vocals_path(_job(purged="2026-10-05")) is None
def test_review_vocals_path_unpurged_job_never_checks_training():
from backend.api.routes.review import _review_vocals_path
with patch("backend.api.routes.review.StorageService") as st:
assert _review_vocals_path(_job()) is None
st.assert_not_called()
+21
View File
@@ -84,3 +84,24 @@ easy to talk through what the AI got right, what you overrode, and what's left.
AI-corrected words tagged (`ai_corrected`, `original_text`, `timing_estimated`).
- If a job had its outputs deleted (admin "delete outputs"), stems may be gone and
audio won't load — the lyrics/action-log still work.
## Sync triage: building the word-timing reference set (full-auto v2)
Replay doubles as the triage UI for the **perfectly synced** reference set: the jobs whose
reviewed word timing is trusted for aligner training and evaluation. In production, open
replay as an admin with a `queue` of job ids:
```
https://gen.nomadkaraoke.com/en/app/jobs?replay=1&queue=<id1>,<id2>,...#/<id1>/review
```
A **Reference set** bar under the replay nav records the verdict:
- **Perfectly synced**: a confident spot-check is enough (anchors, waveforms, a listen to anything suspicious).
- **Not perfect**: tick reason chips, add optional notes.
- **Save & next job** saves and moves to the next queued job.
Verdicts go to `state_data.sync_reference` through `POST /api/review/{job_id}/sync-reference`
(admin only), the same store as the review modal's "perfectly synced" checkbox.
For jobs whose stems storage retention purged, the vocal waveform falls back to the
backfilled training copy `training/lead_vocals/{job_id}.flac` (`_review_vocals_path`).
@@ -493,6 +493,13 @@ function LyricsReviewWrapper({ job, isLocalMode = false, isReplay = false }: { j
</header>
{isReplay && <ReplayNavBar jobId={job.job_id} screen="review" />}
{isReplay && (
<ReplaySyncVerdict
key={job.job_id}
jobId={job.job_id}
saved={correctionData.sync_reference ?? null}
/>
)}
{isReplay && (
<ReplayActionLog
editLog={correctionData.replay?.edit_log ?? null}
@@ -577,6 +584,107 @@ function ReplayNavBar({ jobId, screen }: { jobId: string; screen: "review" | "in
)
}
const SYNC_NOT_REASONS = [
"didn't really check it",
"timing off in places",
"lyrics errors",
"vocalization section approximate",
"missing ad-libs / backing lines",
"audio/separation issue",
"other",
]
/**
* ReplaySyncVerdict — triage for the word-timing reference set (full-auto v2). While
* replaying a completed job, mark it "perfectly synced" (a confident spot-check is
* enough) or not, with reasons/notes. Saves to state_data.sync_reference via the same
* admin endpoint as the review-modal checkbox, then moves to the next queued job.
* Internal admin tool (English-only, like the rest of replay).
*/
export function ReplaySyncVerdict({
jobId,
saved,
}: {
jobId: string
saved: { verified: boolean; by?: string; at?: string; notes?: string | null; reasons?: string[] | null } | null
}) {
const [choice, setChoice] = useState<"synced" | "not" | null>(
saved ? (saved.verified ? "synced" : "not") : null
)
const [reasons, setReasons] = useState<string[]>(saved?.reasons ?? [])
const [notes, setNotes] = useState(saved?.notes ?? "")
const [status, setStatus] = useState<string>(
saved ? `Saved: ${saved.verified ? "perfectly synced" : "not perfect"}${saved.at ? ` · ${saved.at.slice(0, 16).replace("T", " ")}` : ""}` : "Not triaged yet"
)
const [busy, setBusy] = useState(false)
const markDirty = () => setStatus("Unsaved changes")
const nextJob = () => {
const queue = new URLSearchParams(window.location.search).get("queue")?.split(",").map((x) => x.trim()).filter(Boolean) ?? []
const i = queue.indexOf(jobId)
return i >= 0 && i < queue.length - 1 ? queue[i + 1] : null
}
const save = async (advance: boolean) => {
if (!choice || busy) return
setBusy(true)
try {
await createLyricsReviewApiClient(jobId).setSyncReference!(
choice === "synced",
notes.trim() || undefined,
choice === "not" ? reasons : undefined
)
setStatus(`Saved: ${choice === "synced" ? "perfectly synced" : "not perfect"}`)
const n = advance ? nextJob() : null
if (n) window.location.hash = `#/${n}/review`
} catch (e) {
setStatus(`Save failed: ${e instanceof Error ? e.message : String(e)}`)
} finally {
setBusy(false)
}
}
const pill = (active: boolean, tone: "good" | "bad") =>
`px-3 py-1 rounded text-sm font-medium border ${
active
? tone === "good" ? "bg-green-600 text-white border-green-600" : "bg-red-600 text-white border-red-600"
: "hover:bg-muted"
}`
return (
<div className="mx-4 mt-2 rounded-lg border bg-card px-3 py-2 space-y-2" data-testid="replay-sync-verdict">
<div className="flex flex-wrap items-center gap-2">
<span className="text-xs text-muted-foreground mr-1">Reference set:</span>
<button className={pill(choice === "synced", "good")} onClick={() => { setChoice("synced"); markDirty() }}>Perfectly synced</button>
<button className={pill(choice === "not", "bad")} onClick={() => { setChoice("not"); markDirty() }}>Not perfect</button>
<input
className="flex-1 min-w-[12rem] rounded border bg-background px-2 py-1 text-sm"
placeholder="Notes (optional)"
value={notes}
onChange={(e) => { setNotes(e.target.value); markDirty() }}
/>
<button className="px-3 py-1 rounded text-sm font-medium border hover:bg-muted" disabled={!choice || busy} onClick={() => save(false)}>Save</button>
<button className="px-3 py-1 rounded text-sm font-medium bg-primary text-primary-foreground disabled:opacity-40" disabled={!choice || busy} onClick={() => save(true)}>Save & next job →</button>
<span className="text-xs text-muted-foreground" data-testid="replay-sync-status">{status}</span>
</div>
{choice === "not" && (
<div className="flex flex-wrap gap-x-4 gap-y-1">
{SYNC_NOT_REASONS.map((r) => (
<label key={r} className="text-xs text-muted-foreground flex items-center gap-1">
<input
type="checkbox"
checked={reasons.includes(r)}
onChange={(e) => { setReasons(e.target.checked ? [...reasons, r] : reasons.filter((x) => x !== r)); markDirty() }}
/>
{r}
</label>
))}
</div>
)}
</div>
)
}
/**
* ReplayActionLog — read-only summary of the reviewer's ordered edit_log for a
* completed job, shown in replay mode so Andrew can narrate what he did and why.
@@ -0,0 +1,55 @@
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
const setSyncReference = jest.fn().mockResolvedValue(undefined)
jest.mock('@/lib/api', () => ({
...jest.requireActual('@/lib/api'),
createLyricsReviewApiClient: () => ({ setSyncReference }),
}))
// eslint-disable-next-line import/first
import { ReplaySyncVerdict } from '@/app/[locale]/app/jobs/[[...slug]]/client'
describe('ReplaySyncVerdict (replay triage for the timing reference set)', () => {
beforeEach(() => {
setSyncReference.mockClear()
window.history.replaceState({}, '', '/en/app/jobs?replay=1&queue=a1,b2,c3#/b2/review')
})
it('saves "perfectly synced" and moves to the next queued job', async () => {
render(<ReplaySyncVerdict jobId="b2" saved={null} />)
expect(screen.getByTestId('replay-sync-status')).toHaveTextContent('Not triaged yet')
await userEvent.click(screen.getByRole('button', { name: 'Perfectly synced' }))
await userEvent.click(screen.getByRole('button', { name: /save & next job/i }))
expect(setSyncReference).toHaveBeenCalledWith(true, undefined, undefined)
expect(window.location.hash).toBe('#/c3/review')
})
it('saves "not perfect" with reasons and notes', async () => {
render(<ReplaySyncVerdict jobId="b2" saved={null} />)
await userEvent.click(screen.getByRole('button', { name: 'Not perfect' }))
await userEvent.click(screen.getByLabelText('timing off in places'))
await userEvent.type(screen.getByPlaceholderText('Notes (optional)'), 'chorus 2 late')
await userEvent.click(screen.getByRole('button', { name: 'Save' }))
expect(setSyncReference).toHaveBeenCalledWith(false, 'chorus 2 late', ['timing off in places'])
expect(window.location.hash).toBe('#/b2/review')
})
it('shows the saved verdict and keeps Save disabled until a choice exists', () => {
render(<ReplaySyncVerdict jobId="b2" saved={{ verified: true, at: '2026-11-04T10:00:00+00:00' }} />)
expect(screen.getByTestId('replay-sync-status')).toHaveTextContent('Saved: perfectly synced')
})
it('flags an unsaved change until it is saved', async () => {
render(<ReplaySyncVerdict jobId="b2" saved={{ verified: true }} />)
await userEvent.click(screen.getByRole('button', { name: 'Not perfect' }))
expect(screen.getByTestId('replay-sync-status')).toHaveTextContent('Unsaved changes')
await userEvent.click(screen.getByRole('button', { name: 'Save' }))
expect(screen.getByTestId('replay-sync-status')).toHaveTextContent('Saved: not perfect')
})
it('keeps Save disabled until a choice exists', () => {
render(<ReplaySyncVerdict jobId="a1" saved={null} />)
expect(screen.getByRole('button', { name: 'Save' })).toBeDisabled()
})
})
+3 -3
View File
@@ -4296,7 +4296,7 @@ export interface LyricsReviewApiClient {
getInstrumentalState?: () => Promise<InstrumentalState>
completeReview: () => Promise<{ status: string; job_status: string; message: string }>
/** Admin only: mark the reviewed timing "perfectly synced" (word-timing reference set). */
setSyncReference?: (verified: boolean, notes?: string) => Promise<void>
setSyncReference?: (verified: boolean, notes?: string, reasons?: string[]) => Promise<void>
// Review session methods
saveReviewSession: (data: CorrectionData, editCount: number, trigger: string, summary: ReviewSessionSummary) => Promise<{ status: string; session_id?: string; reason?: string }>
listReviewSessions: () => Promise<{ sessions: ReviewSession[] }>
@@ -4517,14 +4517,14 @@ export function createLyricsReviewApiClient(jobId: string): LyricsReviewApiClien
* modal still calls this on an audio load error (e.g. a transient network blip), and
* it's cheap and harmless. Resolved to absolute token URLs like getCorrectionData.
*/
async setSyncReference(verified: boolean, notes?: string): Promise<void> {
async setSyncReference(verified: boolean, notes?: string, reasons?: string[]): Promise<void> {
const response = await apiFetch(`${API_BASE_URL}/api/review/${jobId}/sync-reference`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
...getAuthHeaders()
},
body: JSON.stringify({ verified, notes: notes || null }),
body: JSON.stringify({ verified, notes: notes || null, reasons: reasons?.length ? reasons : null }),
})
await handleResponse<unknown>(response)
},
+1 -1
View File
@@ -190,7 +190,7 @@ export interface CorrectionData {
// which gaps are still open from the current segments, never mutates this.
vocal_gaps?: VocalGapsResult | null
// Admin "perfectly synced" mark (word-timing reference set), if one was saved.
sync_reference?: { verified: boolean; by?: string; at?: string; notes?: string | null } | null
sync_reference?: { verified: boolean; by?: string; at?: string; notes?: string | null; reasons?: string[] | null } | null
// Replay mode (read-only re-open of a completed job via ?replay=true). Present
// only in replay; carries the reviewer's ordered edit log for narration.
replay?: {
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.291.2"
version = "0.292.0"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"