Files
karaoke-gen/scripts
Andrew Beveridge ☄️andClaude Opus 5.5 777daaf25f Missing-lyrics gate: block auto-approval when singing has no lyrics and the reference has lines there (v0.258.0) (#1097)
## Summary
Phase 2a of the missing-lyrics work (phase 1: #1095, shadow detector +
backfill).

**Audit** (262 completed jobs, 60 days, server-side
`scripts/audit_vocal_gaps.py`):
- Longest unlyricked vocal run per job: p50 0.7s, p90 5.1s, p99 22.4s.
47 jobs (18%) have a run of 3s or more, far too many to gate on audio
alone.
- Cross-checked against **synced** reference lyrics (LRCLIB line
timestamps): of 57 suspect gaps that have a synced reference, only 15
contain a reference line. Audio-only is ~25% precise. The rest are vocal
chops, samples, ad-libs and synth bleed, mostly in drum & bass tracks.
- **Evidence-based rule:** a gap is reliable when the reference lyrics
place lines in it.

**Changes**
- `vocal_gaps` 0.2.0: records the synced reference lines inside each
gap. `evidenced` = suspect vocal run AND reference lines, either synced
or between the neighbouring anchors.
- Scorer 0.5.0: new never-auto `missing-lyrics-gate` with a readable
reason, e.g. *"possible missing lyrics: ~10s of singing at 0:20-0:32 has
no transcribed words, and the reference lyrics have 3 line(s) there"*.
Audio-only gaps don't gate.
- The executor analyzes vocal gaps *before* scoring (off the event loop,
fingerprinted cache) and passes them to both scoring passes. It fails
open on pending audio or analysis errors.
- `GET /api/review/{id}/correction-data` now includes `vocal_gaps`, for
the upcoming review-UI marker (phase 2b).

On job 5710831e, the synced LRCLIB lines inside the gap are exactly the
three dropped lines. The genuine instrumentals have none.

## Testing
- `test_vocal_gaps.py`: synced lines with edge tolerance; section
headers ignored; evidence requires both singing and reference
(instrumental with misplaced reference lines doesn't gate; singing
without reference doesn't gate).
- `test_scorer.py`: reasons only for evidenced gaps; the gate overrides
confident lyrics; non-evidenced gaps don't gate.
- `test_executor.py`: evidenced gaps block auto-approval with the reason
and skip the timing check; cached evidenced gaps still gate.
- `test_combined_review_flow.py`: `vocal_gaps` is included in
correction-data.
- Full backend suite: 5211 passed.

Versioned 0.258.0 to follow #1096 (0.257.0).

No local CodeRabbit review (the CLI has no seat for this org), so this
is left open for the CodeRabbit bot.

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

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-30 23:56:48 -04:00
..
2026-01-05 01:33:17 +00:00