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"
+ />
+ )}
+
+ )}
+