## Summary Fixes **Tap To Sync timing corruption** in the Edit Segment modal and reworks the segment timeline for easier re-timing of the first/last words. ### Tap To Sync fixes (`useManualSync`) - **Negative durations on re-sync** — the overlap-correction effect pulled a just-tapped word's end back to the *next* word's **stale** start (it hadn't been re-tapped yet), producing `end_time < start_time`. The sanitizer then reported *"Fixed N word timing(s) that fell outside this segment"* on reopen. Now guarded + clamped so it never inverts. - **First word squished / segment start ratcheting** — `clampSyncTime` forced every tap into the tight `[segStart, segEnd]`, so a legit tap in the 3s playback lead-in got shoved up to `segStart` and the start could never be re-synced earlier. Now allows taps in `[segStart − leadIn, segEnd + leadOut]` (floored at 0). - **Last word cut off** — symmetric lead-out + auto-stop no longer fires while the spacebar is held, so the last word can extend the segment (hold past the end / default-duration overshoot) instead of being truncated. - Both keyboard **and touch** sync paths use the widened window. ### Edit Segment timeline UX - ±1s **greyed context padding** on each side (dashed boundary), **faded waveform** outside the segment, and **neighbouring segments' words** as read-only context blocks. Word bars, drag, ruler, cursor and click-to-scrub all map over the padded view; words can be dragged/synced into the padding to extend the segment. - Modal widened `960px → 95vw / max 1400px`. - Header **play button** starts 1s before and auto-stops 1s after the segment. ### Dev tooling (dev-gated, no prod impact) - `&edit=1` makes a replay session editable locally (guarded by `NODE_ENV !== 'production'`) so the real review UI can be exercised against real job data + audio. Documented in `docs/REPLAY.md`. - `review_test_fixtures.py` now serves a synthetic **click-track** so Tap To Sync is exercisable offline. ## Testing - New/expanded unit tests in `hooks/__tests__/useManualSync*.ts(x)`: negative-duration regression (fails on old code, passes on fix), lead-in/lead-out clamp cases, and segment-end extension. All 13 pass; 178 lyrics-review + hook tests green. - Typecheck clean on touched files. - Verified end-to-end in the browser against a real completed job (replay + real vocals): tap-sync produces valid monotonic timings, no sanitizer banner, first/last words extend correctly, timeline padding + fade + neighbour words render as intended. ## Notes - CodeRabbit reviewed locally; its one finding (touch path missing the lead window) is fixed. @coderabbitai ignore --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
4.0 KiB
Review Replay (read-only re-open of completed jobs)
Re-open the real lyrics-review and instrumental-selection UIs for a job that's already completed, with full audio playback + backing-vocals previews (streamed from GCS), plus a side panel showing your ordered actions (AI-accept / AI-reject / manual / timing) from the stored edit log.
Built for the fully-automated-review recording program — see
docs/archive/2026-08-25-full-auto-review-design.md.
What it is
- Backend
GET /api/review/{job_id}/correction-data?replay=true(admin/owner only): serves the same payload for a job in any status — skips the AWAITING_REVIEW/IN_REVIEW gate and the status-transition side-effect, and attaches the reviewer'sedit_log. Purely read-only. - Frontend
?replay=1on the review/instrumental route: bypasses the state gate (admins), renders the existing UI withisReadOnly(no submit / no mutations), and shows the Replay action log panel. REVIEW_AUDIO_PROXY=1(local dev only): the backend streams review audio bytes instead of GCS signed URLs, because local user ADC can't sign. Inert in prod.
Run it locally (against real prod data, read-only)
# Terminal 1 — backend (needs `gcloud auth application-default login` with read
# access to Firestore `jobs` + the GCS bucket; makes NO writes):
./scripts/run-replay-local.sh
# Terminal 2 — frontend:
cd frontend && npm run dev # http://localhost:3000
Then in the browser:
- Open http://localhost:3000, open DevTools console, and sign in as admin:
Reload — you're now
localStorage.setItem('karaoke_access_token', 'replay-local-token') // matches ADMIN_TOKENSadmin@nomadkaraoke.com. - Open a job in replay:
- Lyrics review:
http://localhost:3000/en/app/jobs?baseApiUrl=http://127.0.0.1:8000&replay=1#/<JOB_ID>/review - Instrumental screen:
http://localhost:3000/en/app/jobs?baseApiUrl=http://127.0.0.1:8000&replay=1#/<JOB_ID>/instrumental
- Lyrics review:
Audio, vocals waveform, and backing-vocals previews all play (proxied through the local backend). The submit/mutation controls are hidden; nothing can be changed.
Editable replay (&edit=1) — dev only
Append &edit=1 to the replay URL to make the review UI editable against the
real job's data + audio (e.g. to exercise Tap To Sync / segment editing locally):
http://localhost:3000/en/app/jobs?baseApiUrl=http://127.0.0.1:8000&replay=1&edit=1#/<JOB_ID>/review
The header reads "Replay (editable · dev)". This flag is guarded by
NODE_ENV !== 'production' — it is ignored in production builds, where replay stays
strictly read-only. Edits are local-only (the replay backend makes no writes).
Using it for the recording sessions
Work through the job list in the private corpus
(~/Projects/nomadkaraoke/docs/automation-corpus/). For each job, with the replay
UI open, narrate the two things we're capturing (the agent writes them into the
corpus record):
- Lyrics — what I corrected and why (per manual edit / AI rejection: why the AI was wrong, how you knew the right answer, whether a deterministic check could catch it). Timings too: which timing adjustments you make, and what signal (e.g. the separated vocal audio) could detect them automatically.
- Backing vocals — what I heard and how I decided (clean vs. with-backing, why; what would make it a clear yes/no vs. a judgement call).
The action-log panel groups your edits as AI ✓ / AI ✗ / manual / timing so it's easy to talk through what the AI got right, what you overrode, and what's left.
Notes / limitations
- Fidelity is "final state + ordered action log", not a per-keystroke visual replay
(no intermediate full-state snapshots are stored). The final lyrics are shown with
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.