Files
karaoke-gen/docs/REPLAY.md
T
Andrew Beveridge ☄️andClaude Opus 4.8 8ce0d39faa fix(lyrics-review): Tap To Sync timing corruption + padded edit-segment timeline (#956)
## 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>
2026-08-29 17:17:10 -04:00

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's edit_log. Purely read-only.
  • Frontend ?replay=1 on the review/instrumental route: bypasses the state gate (admins), renders the existing UI with isReadOnly (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:

  1. Open http://localhost:3000, open DevTools console, and sign in as admin:
    localStorage.setItem('karaoke_access_token', 'replay-local-token')  // matches ADMIN_TOKENS
    
    Reload — you're now admin@nomadkaraoke.com.
  2. 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

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):

  1. 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.
  2. 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.