From d63c9781e1f3f262d98564426615bbe4e2afb8d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Thu, 5 Nov 2026 16:33:16 -0500 Subject: [PATCH] feat(replay): sync-triage verdict bar + vocal waveforms for stems-purged jobs (v0.292.0) (#1254) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- backend/api/routes/review.py | 24 +++- backend/tests/test_review_sync_reference.py | 39 +++++++ docs/REPLAY.md | 21 ++++ .../[locale]/app/jobs/[[...slug]]/client.tsx | 108 ++++++++++++++++++ .../__tests__/ReplaySyncVerdict.test.tsx | 55 +++++++++ frontend/lib/api.ts | 6 +- frontend/lib/lyrics-review/types.ts | 2 +- pyproject.toml | 2 +- 8 files changed, 250 insertions(+), 7 deletions(-) create mode 100644 frontend/components/lyrics-review/__tests__/ReplaySyncVerdict.test.tsx diff --git a/backend/api/routes/review.py b/backend/api/routes/review.py index 58956ed1..6dbd8326 100644 --- a/backend/api/routes/review.py +++ b/backend/api/routes/review.py @@ -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"}) diff --git a/backend/tests/test_review_sync_reference.py b/backend/tests/test_review_sync_reference.py index 286a4240..5476a6e7 100644 --- a/backend/tests/test_review_sync_reference.py +++ b/backend/tests/test_review_sync_reference.py @@ -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() diff --git a/docs/REPLAY.md b/docs/REPLAY.md index 239872a0..157e74a2 100644 --- a/docs/REPLAY.md +++ b/docs/REPLAY.md @@ -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=,,...#//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`). diff --git a/frontend/app/[locale]/app/jobs/[[...slug]]/client.tsx b/frontend/app/[locale]/app/jobs/[[...slug]]/client.tsx index 206cb693..d055de30 100644 --- a/frontend/app/[locale]/app/jobs/[[...slug]]/client.tsx +++ b/frontend/app/[locale]/app/jobs/[[...slug]]/client.tsx @@ -493,6 +493,13 @@ function LyricsReviewWrapper({ job, isLocalMode = false, isReplay = false }: { j {isReplay && } + {isReplay && ( + + )} {isReplay && ( ( + saved ? (saved.verified ? "synced" : "not") : null + ) + const [reasons, setReasons] = useState(saved?.reasons ?? []) + const [notes, setNotes] = useState(saved?.notes ?? "") + const [status, setStatus] = useState( + 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 ( +
+
+ Reference set: + + + { setNotes(e.target.value); markDirty() }} + /> + + + {status} +
+ {choice === "not" && ( +
+ {SYNC_NOT_REASONS.map((r) => ( + + ))} +
+ )} +
+ ) +} + /** * 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. diff --git a/frontend/components/lyrics-review/__tests__/ReplaySyncVerdict.test.tsx b/frontend/components/lyrics-review/__tests__/ReplaySyncVerdict.test.tsx new file mode 100644 index 00000000..4a122960 --- /dev/null +++ b/frontend/components/lyrics-review/__tests__/ReplaySyncVerdict.test.tsx @@ -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() + 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() + 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() + expect(screen.getByTestId('replay-sync-status')).toHaveTextContent('Saved: perfectly synced') + }) + + it('flags an unsaved change until it is saved', async () => { + render() + 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() + expect(screen.getByRole('button', { name: 'Save' })).toBeDisabled() + }) +}) diff --git a/frontend/lib/api.ts b/frontend/lib/api.ts index 3d20d810..03bc4ae5 100644 --- a/frontend/lib/api.ts +++ b/frontend/lib/api.ts @@ -4296,7 +4296,7 @@ export interface LyricsReviewApiClient { getInstrumentalState?: () => Promise 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 + setSyncReference?: (verified: boolean, notes?: string, reasons?: string[]) => Promise // 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 { + async setSyncReference(verified: boolean, notes?: string, reasons?: string[]): Promise { 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(response) }, diff --git a/frontend/lib/lyrics-review/types.ts b/frontend/lib/lyrics-review/types.ts index e635d834..1641d5ae 100644 --- a/frontend/lib/lyrics-review/types.ts +++ b/frontend/lib/lyrics-review/types.ts @@ -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?: { diff --git a/pyproject.toml b/pyproject.toml index d166768b..f44e8675 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 "] license = "MIT"