From 9d6aa3df7d0d286173f98fe7d4c03ea6f074c9bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Sun, 18 Oct 2026 15:04:43 -0400 Subject: [PATCH] feat(medley): per-section backing_vocals_db for the karaoke track (v0.278.6) (#1184) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 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 --- docs/MEDLEYS.md | 1 + pyproject.toml | 2 +- scripts/medley/make_medley.py | 29 +++++++++++++++++++++++++++- tests/unit/test_make_medley.py | 35 ++++++++++++++++++++++++++++++++++ 4 files changed, 65 insertions(+), 2 deletions(-) diff --git a/docs/MEDLEYS.md b/docs/MEDLEYS.md index 0f6e0a90..952d7833 100644 --- a/docs/MEDLEYS.md +++ b/docs/MEDLEYS.md @@ -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 diff --git a/pyproject.toml b/pyproject.toml index 56aceeac..893604a2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 "] license = "MIT" diff --git a/scripts/medley/make_medley.py b/scripts/medley/make_medley.py index cda02365..a7257388 100644 --- a/scripts/medley/make_medley.py +++ b/scripts/medley/make_medley.py @@ -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") diff --git a/tests/unit/test_make_medley.py b/tests/unit/test_make_medley.py index 5bed582d..db568cc7 100644 --- a/tests/unit/test_make_medley.py +++ b/tests/unit/test_make_medley.py @@ -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 +