feat(medley): per-section backing_vocals_db for the karaoke track (v0.278.6) (#1184)

## Summary
The Fiverr medley customer said the backing singers in two songs were
too loud to sing over in tune, and asked for them as a faint background.

- **New option:** a per-section `backing_vocals_db` in the medley spec.
For the karaoke track only, the section is rebuilt from the clean
instrumental plus the backing-vocal stem at that level, e.g. `-14` for a
faint background. The rest of the karaoke track, the clean instrumental
and the guide are unchanged.
- **Cached mix:** the mix is cached per job/level, written to a
`.partial.flac` and renamed, so an interrupted run never leaves a
truncated mix to be reused. If the job has no backing stem, it stops
with a clear error.
- **Docs:** `docs/MEDLEYS.md` spec table.

## Testing
- `test_make_medley.py`: parsing, the ffmpeg graph, only the karaoke
variant changing, the atomic write and the cache. 20 + chord-chart tests
pass.
- Real data: the customer's medley with `-14` on Remember When and On
the Other Hand.
- Only those two sections change; the others differ by ≤ -43 dB, which
is crossfade overlap.
  - Overall section loudness is unchanged.
- A local CodeRabbit review found 1 issue (stale or partial cache). It
is fixed.

@coderabbitai ignore

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 5.5 authored and GitHub committed 2026-10-18 15:04:43 -04:00
1 parent 03ee693f28
commit 9d6aa3df7d
4 files changed
+65 -2

No files matched your search

+1
View File
@@ -57,6 +57,7 @@ section:
| `join: "gap"` + `join_duration` | Insert this much silence instead |
| `fade_out_start` | "Pot out": fader drops from this source second to the section `end` |
| `fade_in` | "Pot in": fade-in length at the start of the section |
| `backing_vocals_db` | Karaoke track only: rebuild this section from the clean instrumental + backing vocals at this level, e.g. `-14` = a faint background (a customer found the backing singers in two songs pulled them off pitch). The clean and guide tracks are unchanged |
| `theme_job_id` (top level) | Whose theme to render with (default: the first section's job) |
```bash
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.278.5"
version = "0.278.6"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"
+28 -1
View File
@@ -66,6 +66,8 @@ class Section:
fade_in: float = 0.0 # "pot in": fade-in length at the start of this section
fade_out_start: Optional[float] = None # "pot out": source second the fader starts dropping
label: str = ""
# Karaoke track only: backing vocals at this level (dB) instead of as mixed, e.g. -14 = faint
backing_vocals_db: Optional[float] = None
def parse_spec(spec: dict) -> list[Section]:
@@ -82,6 +84,7 @@ def parse_spec(spec: dict) -> list[Section]:
fade_in=float(s.get("fade_in", 0.0)),
fade_out_start=None if s.get("fade_out_start") is None else float(s["fade_out_start"]),
label=s.get("label", ""),
backing_vocals_db=None if s.get("backing_vocals_db") is None else float(s["backing_vocals_db"]),
)
if sec.end is not None and sec.end <= sec.start:
raise ValueError(f"section {i}: end must be after start")
@@ -252,6 +255,30 @@ def variant_path(workdir: str, job_id: str, variant: str) -> str:
return os.path.join(d, "stems", stem)
def backing_mix_args(clean: str, backing: str, gain_db: float, out: str) -> list[str]:
"""ffmpeg args: clean instrumental + backing vocals at gain_db (sample-aligned stems)."""
return ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", clean, "-i", backing,
"-filter_complex", f"[1:a]volume={gain_db:.1f}dB[b];[0:a][b]amix=inputs=2:normalize=0[out]",
"-map", "[out]", "-c:a", "flac", out]
def section_audio(workdir: str, sec: Section, variant: str) -> str:
"""Audio file for one section of one variant (the karaoke track can have its backing
vocals turned down per section, built once from the clean + backing stems)."""
if variant != KARAOKE_VARIANT or sec.backing_vocals_db is None:
return variant_path(workdir, sec.job_id, variant)
stems = os.path.join(job_dir(workdir, sec.job_id), "stems")
out = os.path.join(stems, f"instrumental_backing_{sec.backing_vocals_db:+.1f}dB.flac")
if not os.path.exists(out):
backing = os.path.join(stems, "backing_vocals.flac")
if not os.path.exists(backing):
raise SystemExit(f"{sec.job_id}: backing_vocals_db needs stems/backing_vocals.flac (not in this job)")
partial = out[:-len(".flac")] + ".partial.flac" # never leave a truncated mix to be reused
_run(backing_mix_args(os.path.join(stems, "instrumental_clean.flac"), backing, sec.backing_vocals_db, partial))
os.replace(partial, out)
return out
def section_durations(sections: list[Section], workdir: str) -> list[float]:
durs = []
for sec in sections:
@@ -299,7 +326,7 @@ def cmd_audio(spec: dict, workdir: str, outdir: str):
for variant in VARIANTS:
inputs, gains = [], []
for sec in sections:
p = variant_path(workdir, sec.job_id, variant)
p = section_audio(workdir, sec, variant)
gains.append(SEGMENT_TARGET_LUFS - measure_lufs(p, sec.start, sec.end))
inputs += ["-ss", str(sec.start)] + (["-to", str(sec.end)] if sec.end is not None else []) + ["-i", p]
wav = os.path.join(outdir, f"medley_{variant}.wav")
+35
View File
@@ -4,6 +4,7 @@ The script isn't part of the installed package, so we load it by path.
"""
import importlib.util
import os
import sys
from pathlib import Path
@@ -161,3 +162,37 @@ class TestMaster:
assert "loudnorm" not in f # dynamic loudnorm boosted near-silent intros into artifacts
assert f.endswith("aresample=44100")
class TestBackingVocals:
def test_parsed_per_section(self):
spec = {"sections": [{"job_id": "a", "end": 10.0}, {"job_id": "b", "end": 9.0, "backing_vocals_db": -14}]}
assert [s.backing_vocals_db for s in medley.parse_spec(spec)] == [None, -14.0]
def test_mix_is_clean_plus_quieter_backing(self):
args = medley.backing_mix_args("clean.flac", "bv.flac", -14.0, "out.flac")
graph = args[args.index("-filter_complex") + 1]
assert graph == "[1:a]volume=-14.0dB[b];[0:a][b]amix=inputs=2:normalize=0[out]"
assert args[args.index("-i") + 1] == "clean.flac" and args[-1] == "out.flac"
def test_only_the_karaoke_track_changes(self, tmp_path, monkeypatch):
sec = medley.parse_spec({"sections": [{"job_id": "b", "end": 9.0, "backing_vocals_db": -14}]})[0]
monkeypatch.setattr(medley, "variant_path", lambda w, j, v: f"{v}.flac")
stems = tmp_path / "b" / "stems"
stems.mkdir(parents=True)
with pytest.raises(SystemExit): # no backing stem for this job
medley.section_audio(str(tmp_path), sec, medley.KARAOKE_VARIANT)
(stems / "backing_vocals.flac").write_bytes(b"")
calls = []
def fake_run(args, **kw):
calls.append(args)
open(args[-1], "w").close()
monkeypatch.setattr(medley, "_run", fake_run)
assert medley.section_audio(str(tmp_path), sec, "instrumental_clean") == "instrumental_clean.flac"
out = medley.section_audio(str(tmp_path), sec, medley.KARAOKE_VARIANT)
assert out.endswith("stems/instrumental_backing_-14.0dB.flac") and os.path.exists(out)
assert calls[0][-1].endswith(".partial.flac") # written aside, then renamed
medley.section_audio(str(tmp_path), sec, medley.KARAOKE_VARIANT)
assert len(calls) == 1 # cached