diff --git a/backend/api/routes/review.py b/backend/api/routes/review.py index 007dc580..199704e0 100644 --- a/backend/api/routes/review.py +++ b/backend/api/routes/review.py @@ -45,7 +45,7 @@ from backend.services.job_logging import job_log_context, JobLogger from backend.services.tracing import create_span, add_span_attribute, add_span_event from backend.services.auto_approval.instrumental import with_unified_recommendation from backend.services.encoding_service import get_encoding_service -from backend.api.dependencies import require_auth, require_review_auth +from backend.api.dependencies import require_admin, require_auth, require_review_auth from backend.utils.stems import vocals_stem_path as _vocals_stem_path from backend.services.auth_service import UserType from backend.config import get_settings @@ -909,6 +909,10 @@ async def get_correction_data( # "evidenced" gaps and offers the reference lines for insertion. corrections_data['vocal_gaps'] = job.state_data.get('vocal_gaps') or None + # Admin "perfectly synced" mark (word-timing reference set), so a re-review + # shows the existing mark and can revoke it. + corrections_data['sync_reference'] = job.state_data.get('sync_reference') or None + # Per-screen skip (C1): tell the frontend whether each review half is # confidently auto-resolved, so it can skip the instrumental screen (or the # lyrics screen). Derived from the stored auto-approval verdict + the job's @@ -1327,6 +1331,44 @@ async def complete_review( } +class SyncReferenceRequest(_PydBaseModel): + verified: bool + notes: Optional[str] = None + + +@router.post("/{job_id}/sync-reference") +async def set_sync_reference(job_id: str, body: SyncReferenceRequest, auth_result=Depends(require_admin)): + """Admin-only: mark this job's reviewed word timing as "perfectly synced". + + Verified jobs form the reference set for word-timing training and evaluation + (full-auto v2). A tick means the admin is confident the sync is right, from a + listen or a confident spot-check; jobs never marked are treated as unverified. + """ + from datetime import datetime, timezone + + job_manager = JobManager() + job = await asyncio.to_thread(job_manager.get_job, job_id) + if not job: + raise HTTPException(status_code=404, detail=t("en", "review.jobNotFound")) + # A "verified" mark vouches for reviewed timing, so it needs saved review output. + lyrics_urls = ((job.file_urls or {}).get("lyrics") or {}) if isinstance(job.file_urls, dict) else {} + if body.verified and not lyrics_urls.get("corrections_updated"): + # Older jobs may have the file without the file_urls pointer (same fallback + # get_correction_data uses). + direct = f"jobs/{job_id}/lyrics/corrections_updated.json" + if not await asyncio.to_thread(StorageService().file_exists, direct): + raise HTTPException(status_code=409, detail="No reviewed lyrics saved yet; save the review first") + record = { + "verified": body.verified, + "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, + } + 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']}") + return {"status": "success", "sync_reference": record} + + def _fake_complete_failure_hook(job_id: str) -> None: """Raise a 503 once when the job's user set ``review_complete_fail_once`` (fake workers only).""" from backend.services.fake_workers.config import consume_review_complete_failure diff --git a/backend/tests/test_review_sync_reference.py b/backend/tests/test_review_sync_reference.py new file mode 100644 index 00000000..286a4240 --- /dev/null +++ b/backend/tests/test_review_sync_reference.py @@ -0,0 +1,103 @@ +"""POST /api/review/{job_id}/sync-reference: admin-only "perfectly synced" mark that +puts a job's reviewed word timing in the reference set (full-auto v2).""" +from unittest.mock import MagicMock, patch + +import pytest +from fastapi import HTTPException +from fastapi.testclient import TestClient + +from backend.api.dependencies import require_admin, require_auth +from backend.main import app +from backend.services.auth_service import AuthResult, UserType + + +def _admin(): + return AuthResult(is_valid=True, user_type=UserType.ADMIN, remaining_uses=999, message="ok", + is_admin=True, user_email="andrew@nomadkaraoke.com") + + +@pytest.fixture +def jm(): + m = MagicMock() + m.get_job.return_value = MagicMock( + job_id="j1", file_urls={"lyrics": {"corrections_updated": "jobs/j1/lyrics/corrections_updated.json"}}) + return m + + +@pytest.fixture +def client(jm): + async def fake_admin(): + return _admin() + + saved = dict(app.dependency_overrides) + app.dependency_overrides[require_admin] = fake_admin + try: + with patch("backend.api.routes.review.JobManager", return_value=jm): + yield TestClient(app) + finally: + app.dependency_overrides.clear(); app.dependency_overrides.update(saved) + + +def test_admin_marks_job_verified(client, jm): + r = client.post("/api/review/j1/sync-reference", json={"verified": True, "notes": " spot-checked chorus "}) + assert r.status_code == 200 + jid, key, record = jm.update_state_data.call_args.args + assert (jid, key) == ("j1", "sync_reference") + assert record["verified"] is True + assert record["by"] == "andrew@nomadkaraoke.com" + assert record["notes"] == "spot-checked chorus" + assert record["at"] + + +def test_blank_notes_stored_as_none(client, jm): + client.post("/api/review/j1/sync-reference", json={"verified": False, "notes": " "}) + assert jm.update_state_data.call_args.args[2]["notes"] is None + assert jm.update_state_data.call_args.args[2]["verified"] is False + + +def test_unknown_job_404(client, jm): + jm.get_job.return_value = None + r = client.post("/api/review/nope/sync-reference", json={"verified": True}) + assert r.status_code == 404 + jm.update_state_data.assert_not_called() + + +def test_missing_verified_is_422(client): + assert client.post("/api/review/j1/sync-reference", json={}).status_code == 422 + + +def test_non_admin_forbidden(jm): + async def fake_user(): + return AuthResult(is_valid=True, user_type=UserType.UNLIMITED, remaining_uses=999, message="ok", + is_admin=False, user_email="someone@example.com") + + saved = dict(app.dependency_overrides) + app.dependency_overrides.pop(require_admin, None) # conftest stubs it to always-admin + app.dependency_overrides[require_auth] = fake_user + try: + with patch("backend.api.routes.review.JobManager", return_value=jm): + r = TestClient(app).post("/api/review/j1/sync-reference", json={"verified": True}) + assert r.status_code == 403 + jm.update_state_data.assert_not_called() + finally: + app.dependency_overrides.clear(); app.dependency_overrides.update(saved) + + +def test_verified_requires_saved_review(client, jm): + jm.get_job.return_value = MagicMock(job_id="j1", file_urls={"lyrics": {}}) + with patch("backend.api.routes.review.StorageService") as st: + st.return_value.file_exists.return_value = False + r = client.post("/api/review/j1/sync-reference", json={"verified": True}) + assert r.status_code == 409 + jm.update_state_data.assert_not_called() + # revoking is always allowed + assert client.post("/api/review/j1/sync-reference", json={"verified": False}).status_code == 200 + + +def test_verified_accepts_direct_path_file(client, jm): + jm.get_job.return_value = MagicMock(job_id="j1", file_urls={}) + with patch("backend.api.routes.review.StorageService") as st: + st.return_value.file_exists.return_value = True + 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") diff --git a/docs/API.md b/docs/API.md index eff919c0..7c8215e8 100644 --- a/docs/API.md +++ b/docs/API.md @@ -452,6 +452,16 @@ Content-Type: application/json Saves corrections, stores instrumental selection, and triggers video rendering. The instrumental selection is now required as part of the combined review flow. +#### Mark sync as reference (admin only) + +``` +POST /api/review/{job_id}/sync-reference +{"verified": true, "notes": "optional"} +``` +Admin users only (403 otherwise). Stores `state_data.sync_reference = {verified, by, at, notes}`. +Verified jobs form the word-timing reference set for aligner training/evaluation (full-auto v2). +The lyrics review modal shows the checkbox to admins; unticked jobs are treated as unverified. + #### Generate Preview ```http diff --git a/frontend/components/lyrics-review/LyricsAnalyzer.tsx b/frontend/components/lyrics-review/LyricsAnalyzer.tsx index 30dac7e2..0ba40a5d 100644 --- a/frontend/components/lyrics-review/LyricsAnalyzer.tsx +++ b/frontend/components/lyrics-review/LyricsAnalyzer.tsx @@ -117,6 +117,7 @@ interface ApiClient { getWaveformData?: (numPoints?: number) => Promise<{ amplitudes: number[]; duration_seconds?: number; duration?: number }> // Optional: separation-status poll for stems that land after page load (cloud mode). getInstrumentalState?: LyricsReviewApiClient['getInstrumentalState'] + setSyncReference?: LyricsReviewApiClient['setSyncReference'] completeReview: () => Promise<{ status: string; job_status: string; message: string }> // Review session methods (optional - available in cloud mode) saveReviewSession?: LyricsReviewApiClient['saveReviewSession'] @@ -1151,7 +1152,9 @@ export default function LyricsAnalyzer({ }, [saveSession]) // Submit to server (save corrections, don't complete review yet) - const handleSubmitToServer = useCallback(async () => { + const handleSubmitToServer = useCallback(async ( + opts?: { syncReference?: { verified: boolean; notes?: string } }, + ) => { if (!apiClient) return // Block submission of lyrics that still have no timing (e.g. custom lyrics @@ -1172,6 +1175,17 @@ export default function LyricsAnalyzer({ // 1. Save corrections (not final submission yet), including current duet flag await apiClient.submitCorrections(dataToSubmit, isDuet) + // 1b. Admin "perfectly synced" mark — only now that the timing it vouches for + // is saved. Best-effort: never blocks or fails the review. + if (opts?.syncReference && apiClient.setSyncReference) { + try { + await apiClient.setSyncReference(opts.syncReference.verified, opts.syncReference.notes) + } catch (error) { + console.error('Failed to save sync reference mark:', error) + toast.error(t('toasts.syncReferenceSaveFailed')) + } + } + // 2. Save edit log (non-blocking) if (editLog.entries.length > 0) { try { diff --git a/frontend/components/lyrics-review/__tests__/ReviewChangesModal.syncReference.test.tsx b/frontend/components/lyrics-review/__tests__/ReviewChangesModal.syncReference.test.tsx new file mode 100644 index 00000000..39fd904e --- /dev/null +++ b/frontend/components/lyrics-review/__tests__/ReviewChangesModal.syncReference.test.tsx @@ -0,0 +1,82 @@ +import { render, screen } from '@testing-library/react' +import userEvent from '@testing-library/user-event' +import ReviewChangesModal from '../modals/ReviewChangesModal' +import type { CorrectionData } from '@/lib/lyrics-review/types' +import { useAuth } from '@/lib/auth' + +jest.mock('../PreviewVideoSection', () => { + const React = require('react') + return { + __esModule: true, + default: React.forwardRef(function MockPreview(_props: unknown, ref: unknown) { + React.useImperativeHandle(ref, () => ({ auditionInstrumental: jest.fn() })) + return
Preview
+ }), + } +}) + +const data = { + original_segments: [], reference_lyrics: {}, anchor_sequences: [], gap_sequences: [], + resized_segments: [], corrections_made: 0, confidence: 1, corrections: [], metadata: {}, + corrected_segments: [{ text: 'Hello', words: [], start_time: 0, end_time: 1 }], +} as unknown as CorrectionData + +function client() { + return { generatePreviewVideo: jest.fn(), getPreviewVideoStatus: jest.fn(), getPreviewVideoUrl: jest.fn() } +} + +function setRole(role: string | null) { + useAuth.setState({ user: role ? ({ email: 'a@nomadkaraoke.com', role } as any) : null }) +} + +describe('ReviewChangesModal sync-reference mark (admin only)', () => { + afterEach(() => setRole(null)) + + it('is hidden for non-admin users', () => { + setRole('user') + render() + expect(screen.queryByTestId('sync-reference')).not.toBeInTheDocument() + }) + + it('passes the mark with notes to onSubmit when an admin ticks it', async () => { + setRole('admin') + const onSubmit = jest.fn() + render() + await userEvent.click(screen.getByTestId('sync-reference-checkbox')) + await userEvent.type(screen.getByTestId('sync-reference-notes'), 'spot-checked') + await userEvent.click(screen.getByRole('button', { name: /proceed to instrumental/i })) + expect(onSubmit).toHaveBeenCalledWith({ syncReference: { verified: true, notes: 'spot-checked' } }) + }) + + it('sends no mark when the admin leaves it unticked', async () => { + setRole('admin') + const onSubmit = jest.fn() + render() + expect(screen.getByTestId('sync-reference')).toBeInTheDocument() + await userEvent.click(screen.getByRole('button', { name: /proceed to instrumental/i })) + expect(onSubmit).toHaveBeenCalledWith() + }) + + it('starts ticked from a saved mark and sends verified=false when revoked', async () => { + setRole('admin') + const onSubmit = jest.fn() + const marked = { ...data, sync_reference: { verified: true, notes: 'old note' } } as CorrectionData + render() + const box = screen.getByTestId('sync-reference-checkbox') as HTMLInputElement + expect(box.checked).toBe(true) + await userEvent.click(box) + await userEvent.click(screen.getByRole('button', { name: /proceed to instrumental/i })) + expect(onSubmit).toHaveBeenCalledWith({ syncReference: { verified: false, notes: 'old note' } }) + }) + + it('sends verified=false once touched, even with no saved mark', async () => { + setRole('admin') + const onSubmit = jest.fn() + render() + const box = screen.getByTestId('sync-reference-checkbox') + await userEvent.click(box) + await userEvent.click(box) + await userEvent.click(screen.getByRole('button', { name: /proceed to instrumental/i })) + expect(onSubmit).toHaveBeenCalledWith({ syncReference: { verified: false, notes: undefined } }) + }) +}) diff --git a/frontend/components/lyrics-review/modals/ReviewChangesModal.tsx b/frontend/components/lyrics-review/modals/ReviewChangesModal.tsx index 3485d996..d881e6c2 100644 --- a/frontend/components/lyrics-review/modals/ReviewChangesModal.tsx +++ b/frontend/components/lyrics-review/modals/ReviewChangesModal.tsx @@ -9,6 +9,7 @@ import { AlertTriangle, ArrowLeft, ArrowRight, Loader2 } from 'lucide-react' import PreviewVideoSection, { PreviewVideoHandle } from '../PreviewVideoSection' import BackingVocalsWaveform from '../BackingVocalsWaveform' import type { LateInstrumentalStatus } from '@/lib/lyrics-review/hooks/useLateInstrumentalStems' +import { useAuth } from '@/lib/auth' interface WaveformDataResult { amplitudes: number[] @@ -41,7 +42,9 @@ interface ReviewChangesModalProps { /** Late-stems poll state: `waiting` = audio separation still running, so the * instrumental choice isn't available yet; `gave_up` = it didn't arrive in time. */ stemsStatus?: LateInstrumentalStatus - onSubmit: () => void + /** `syncReference` is set only for admins who ticked (or un-ticked a previously + * saved) "perfectly synced" mark; the caller saves it after the timing is saved. */ + onSubmit: (opts?: { syncReference?: { verified: boolean; notes?: string } }) => void isSubmitting?: boolean apiClient?: ApiClient | null timingOffsetMs?: number @@ -152,9 +155,24 @@ export default function ReviewChangesModal({ ) } + // Admin-only "perfectly synced" mark: verified jobs join the word-timing reference + // set used to train and evaluate the aligner. Unticked = unverified. Starts from + // the saved mark so a re-review can see and revoke it. + const isAdmin = useAuth((s) => s.user?.role === 'admin') + const savedVerified = !!data.sync_reference?.verified + const [syncVerified, setSyncVerified] = useState(savedVerified) + const [syncNotes, setSyncNotes] = useState(data.sync_reference?.notes || '') + // Once touched, always send the current state: a mark saved earlier in this + // session (then a failed submit) must still be revocable by un-ticking. + const [syncTouched, setSyncTouched] = useState(false) + const handleSubmit = () => { if (isSubmitting) return - onSubmit() + if (isAdmin && (syncVerified || savedVerified || syncTouched)) { + onSubmit({ syncReference: { verified: syncVerified, notes: syncNotes.trim() || undefined } }) + } else { + onSubmit() + } } return ( @@ -304,6 +322,34 @@ export default function ReviewChangesModal({ )} + {isAdmin && ( +
+ + {syncVerified && ( + setSyncNotes(e.target.value)} + placeholder={t('syncReferenceNotesPlaceholder')} + className="w-full rounded border bg-background px-2 py-1 text-xs" + data-testid="sync-reference-notes" + /> + )} +
+ )} +