Files
Andrew Beveridge ☄️andClaude Opus 4.8 b8e67e6ba6 feat: emit + push original-vocals guide on NOMAD render (write-path) (#875)
## Summary

Makes the kjbox **"Original Vocals"** sing-along guide
**self-maintaining**. When karaoke-gen finalises a new public NOMAD
master, it now automatically emits an aligned original-vocals guide and
pushes it to GCS — no re-run of the kjbox retro-fit pipeline.

**Key insight:** at render time karaoke-gen already has the isolated
`mixed_vocals` stem (a byproduct of the karaoke instrumental) and knows
the exact intro offset (the job's style `intro_video_duration`). So the
guide is simply `silence[intro] + vocals`, capped to the master's
duration — **no correlation, no review, no alignment measurement**.

## Changes

- `backend/services/original_vocals_guide.py` (new): pure ffmpeg builder
(`adelay` + `-f flac`, atomic `.part` rename) + `probe_duration`.
Best-effort, never raises.
- `nomad_master_mirror`: `push_vocals_guide` +
`delete_vocals_guides_by_brand` (siblings of the 720p methods);
brand-recycle cleanup now clears guides too.
- `video_worker_orchestrator`: `_emit_original_vocals_guide` pulls the
`mixed_vocals` stem from `jobs/{id}/stems/vocals_clean.flac`, resolves
the **actual** intro duration (long-intro styles honoured; `0`
preserved), caps to the master, registers it in `output_files`.
- `gdrive_service`: pushes the guide beside the 720p master (same
Nomad-brand gating + best-effort/distribution-warning contract).
- `config`: `nomad_vocals_guide_gcs_prefix` (`files/Nomad
Karaoke/vocals-padded`).

## Behaviour

- **Public NOMAD only** (`is_nomad_public_brand`, skips `NOMADNP`).
Shares the `nomad_master_fast_sync_enabled` gate.
- **Inert** until the kjbox device pulls the new prefix into
`NOMAD-vocals-padded/` (separate kjbox PR) — guides just accumulate in
GCS. Existing 1,459 device guides untouched.
- Every step best-effort: a guide failure is a distribution warning,
never fatal.

## Testing

- Builder unit tests (synthetic tone+silence): offset, duration cap,
valid flac, best-effort `None` paths.
- Mirror push/delete + gating; gdrive + orchestrator wiring; intro=0 /
long-intro resolution.
- Full backend suite: **3711 passed** (excl. emulator). CodeRabbit: 1
finding (intro-0 truthiness) fixed.

Design spec:
`docs/superpowers/specs/2026-07-09-original-vocals-writepath-design.md`

@coderabbitai ignore

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-09 01:26:11 -04:00
..