Files
Andrew Beveridge ☄️andClaude Opus 4.7 7268dfd830 feat(duet): multi-singer karaoke support + local CLI review fixes (#730)
## Summary

- **New feature:** Multi-singer / duet support. Review UI gains a "Duet
Mode" toggle and a per-segment chip to assign Singer 1 / Singer 2 /
Both. Rendered MP4 shows each singer in their signature color (blue /
pink / yellow), sweeping to a near-white tint of the same hue as each
word is sung.
- **Unplanned but necessary:** ~15 local CLI regression fixes that
landed alongside. The i18n work on `main` (LocaleRedirect, static-export
locale prefixes) silently broke the local `karaoke-gen` CLI review flow;
shipped-with-package `ReviewServer` was also missing several
`/api/review/{jobId}/*` endpoint aliases that the unified frontend
expects. This branch closes all of that so the local flow works
end-to-end again.

Full design spec:
[`docs/archive/2026-04-21-multi-singer-duets-design.md`](./docs/archive/2026-04-21-multi-singer-duets-design.md).
Implementation plan:
[`docs/archive/2026-04-21-multi-singer-duets-plan.md`](./docs/archive/2026-04-21-multi-singer-duets-plan.md).

## Changes — Duet Feature

**Backend**
- `Word.singer` / `LyricsSegment.singer` optional fields (`SingerId =
Literal[0,1,2]`, 0=Both)
- `DEFAULT_KARAOKE_STYLE` gains a `singers` block with per-singer colors
(unhighlighted = signature color, highlighted = near-white hue tint)
- `CDG_DUET_SINGERS` palette constant (+ `build_cdg_lyrics` helper —
wired into the render flow but not yet fed into `CDGGenerator`'s TOML
builder; follow-up tracked in `docs/LESSONS-LEARNED.md`)
- `ass/style.py` gains `build_karaoke_styles` factory that emits one ASS
style per singer in use
- `LyricsLine` / `LyricsScreen` / `SubtitlesGenerator` /
`SegmentResizer` all forward segment + word singer fields through the
render chain (several bugs where rebuilds silently dropped the field
were fixed)
- `is_duet` flag persisted in review-session `state_data` (cloud) and
captured by the local `ReviewServer` with a latch-up-only semantic on
`complete_review` so InstrumentalSelector can't accidentally downgrade
it
- `CorrectionOperations.generate_preview_video` threads `is_duet` into
the inner `preview_config`
- `render_video_worker` reads `is_duet` from state_data and propagates
through `OutputGenerator` → `SubtitlesGenerator` (both local + GCE
paths)

**Frontend (`frontend/`, sources only — bundle at
`karaoke_gen/nextjs_frontend/out/` also rebuilt)**
- `SingerId` type + optional `singer` on `Word` / `LyricsSegment` /
`CorrectionData.is_duet`
- `duet.ts` helpers: `cycleSinger`, `resolveSegmentSinger`,
`collectSingersInUse`, `hasMultipleSingers`, `hasWordOverrides`
- `SingerChip` component (click to cycle 1 → 2 → Both, shows `*` when
words have overrides)
- `Header` "Duet Mode" toggle (opt-in, hides chip column when off)
- `TranscriptionView` renders chip + subtle row-tint gradient when duet
is on
- `LyricsAnalyzer` manages `isDuet` state, includes it in save payloads
- `segmentOperations.ts` extends split/merge/addBefore/delete with
singer-inheritance rules (including the tricky implicit-vs-explicit
singer case)
- Keyboard shortcuts `1` / `2` / `B` on a focused segment
- `InstrumentalSelector` falls back to `hasMultipleSingers(segments)`
when `correctionData.is_duet` is missing
- Auto-enable duet on session-restore when restored data shows
multi-singer evidence
- `lyricsReview.duet.*` namespace added to `frontend/messages/en.json`
and auto-translated to all 32 other locales

**i18n**
- Every new user-visible string goes through `next-intl`; the
translation pipeline ran for each en.json change
- Backend new error strings added to
`backend/translations/{en,es,de}.json` and tracked via
`.en-snapshot.json`

## Changes — Local CLI Review Regression Fixes

These were uncovered while trying to manually validate the duet feature
end-to-end. They land in this PR because blocking validation would have
blocked the feature.

- `ReviewServer` now serves the `/{locale}/app/jobs/local/review` (and
broader `/{locale}/app/...`) paths that `LocaleRedirect` unconditionally
bounces to — discovers valid locales from the frontend build
- Added missing `/api/review/{jobId}/...` aliases: `search-lyrics` (new
handler using `CorrectionOperations.search_lyrics_sources`),
`add-lyrics`, `handlers` (POST, matching cloud), `audio/{stem-or-hash}`
(dispatches stems vs audio-by-hash), `instrumental-analysis`,
`waveform-data`, `v1/annotations`, `sessions` stubs
- Review-session history persistence added (external session)
- `job-router-routes.ts` now parses locale-prefixed pathnames so
`/en/app/jobs/local/instrumental` renders the InstrumentalSelector
instead of the lyrics review fallback
- Test-mock signatures updated for the `run_combined_review` 3-tuple
return

## Testing

- [x] Unit tests pass: **1606 package tests + 3002 backend tests + 848
frontend tests**, all green. Coverage: 69.29% (≥69% gate)
- [x] Integration tests pass (including new end-to-end multi-singer
fixture tests)
- [x] Playwright production E2E spec compiles
(`frontend/e2e/production/duet-review.spec.ts`)
- [x] Manual validation done end-to-end on Lady Gaga × Bradley Cooper —
"Shallow (145s duet clip)" — full pipeline produces a proper
duet-rendered MP4 with three per-singer ASS styles tagged correctly
against dialogue lines (6 Singer 1, 16 Singer 2, 4 Both across this
clip). Checked-in fixture at `tests/data/Shallow-Duet-145.ogg`.
- [ ] Manual validation against a second track with dense
call-and-response (spec listed Eminem × Rihanna "Love the Way You Lie")
— not done this PR; can follow up after merge if anything surprising
surfaces
- [ ] End-to-end CDG duet output — still deferred (see Known Follow-Ups)

## Review

- [x] Local code-review done via `feature-dev:code-reviewer` agent
(CodeRabbit CLI fell over on the 3605-file bundle rebuild commit)
- [x] Two findings addressed in commit `da3004ea`: handlers HTTP method,
mergeSegment implicit-singer case

@coderabbitai ignore

## Known Follow-Ups

- `build_cdg_lyrics` helper is implemented and unit-tested but
`CDGGenerator` still constructs its TOML config directly rather than via
`SettingsLyric`. CDG output from duet jobs renders in solo colors today.
Documented in `docs/LESSONS-LEARNED.md`; not required for the MP4/ASS
path which is the feature's primary surface.
- Cloud `complete_review` overwrites `is_duet` in state_data
unconditionally (local server has latch-only semantics). In practice the
frontend's `hasMultipleSingers` fallback in `InstrumentalSelector` keeps
this consistent, but the cloud could gain the same latch for parity.

## Version

Bumped `pyproject.toml` from `0.171.0` → `0.171.1`.

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

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-22 23:27:21 -04:00
..