From c133b64c7da825737d3d71adea9ae27e395ce976 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andrew=20Beveridge=20=E2=98=84=EF=B8=8F?= Date: Sun, 8 Nov 2026 18:56:59 -0500 Subject: [PATCH] fix(quick-version): retry LRCLIB with a cleaned title + honour lyrics overrides (v0.294.1) (#1257) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Why At a kjbox show on 2026-11-06, the make-it quick version for Sombr "My Body Isn't Ready (Orchestral Version Live From Sound City)" (job `f9764a9f`) rendered with only "(lyrics unavailable)" on screen. The singer heard the backing track with no lyrics. LRCLIB only has this song under the plain title. ## What - `fetch_lrclib_lyrics`: if the exact `/get` and `/search` find nothing, retry `/search` once with the title cleaned (`clean_title`: trailing `(…)`/`[…]` groups and `- Live …`/`- Remaster` style suffixes removed). - A synced hit from the retry keeps its timing only when its length is within **4 s** of the audio, because a different length usually means a different recording (studio vs live). Any other hit is used as plain lyrics (constant crawl). - Plain lyrics found under the exact title still win, and titles with nothing to clean make no extra request. - The quick render now searches with the job's `lyrics_artist`/`lyrics_title` overrides, else the title without a tempo label, the same names the review page uses. The displayed artist/title are unchanged. - Companion: kjbox v0.150.0 (nomadkaraoke/kjbox#314, deployed) lets the KJ add lyrics on the box when a draft still comes back without any. ## Testing - `backend/tests/test_quick_version.py`: 56 pass, including 17 new tests (cleaned-title retry: matching sync, wrong-length sync downgraded to plain, no duration, exact plain wins, failure paths, no retry for plain titles; `clean_title` cases; lyrics-search names incl. tempo label and overrides). - Live LRCLIB check: `fetch_lrclib_lyrics('Sombr', "My Body Isn't Ready (Orchestral Version Live From Sound City)", 224.5)` returns **synced, 37 lines**. Before this change it returned nothing. - Local CodeRabbit review: 0 findings. Full suite left to CI. @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_012RYLVWXLyvTmHNnqQu3rzA Co-authored-by: Claude Opus 5.5 --- backend/services/quick_version/renderer.py | 69 ++++++++++++++++- backend/services/quick_version/service.py | 10 ++- backend/tests/test_quick_version.py | 88 ++++++++++++++++++++++ docs/ARCHITECTURE.md | 7 ++ pyproject.toml | 2 +- 5 files changed, 172 insertions(+), 4 deletions(-) diff --git a/backend/services/quick_version/renderer.py b/backend/services/quick_version/renderer.py index 5387e4ce..d7bd5335 100644 --- a/backend/services/quick_version/renderer.py +++ b/backend/services/quick_version/renderer.py @@ -49,6 +49,30 @@ TimedLine = Tuple[str, Optional[float]] _LRC_RE = re.compile(r"\[(\d+):(\d+(?:\.\d+)?)\]") +# A synced LRCLIB result found under a *cleaned* title is often a different +# recording (studio vs "Live From ..."), so its timing is only trusted when the +# lengths agree this closely; otherwise its words scroll at a constant pace. +CLEAN_TITLE_SYNC_TOLERANCE_S = 4.0 + +# Trailing "(...)" / "[...]" groups and " - Live at ..." style suffixes that stop +# LRCLIB matching the plain song (kjbox quick_lyrics.clean_title mirrors this). +_TRAILING_GROUP_RE = re.compile(r"\s*[\(\[][^\(\)\[\]]*[\)\]]\s*$") +_DASH_SUFFIX_RE = re.compile( + r"\s+-\s+.*\b(live|version|remaster(ed)?|mix|edit|acoustic|orchestral|session|demo|mono|stereo)\b.*$", + re.IGNORECASE) + + +def clean_title(title: str) -> str: + """'Song (Live From X) [HD]' / 'Song - 2011 Remaster' → 'Song' (never empty).""" + t = (title or "").strip() + while True: + stripped = _TRAILING_GROUP_RE.sub("", t) + if stripped == t or not stripped.strip(): + break + t = stripped + t = _DASH_SUFFIX_RE.sub("", t) + return t.strip() or (title or "").strip() + @dataclass class Lyrics: @@ -151,9 +175,46 @@ def fetch_lrclib_lyrics( except (requests.RequestException, ValueError) as exc: logger.warning(f"LRCLIB search failed: {exc}") + # Decorated titles ("My Song (Orchestral Version Live From X)") rarely match + # on LRCLIB: retry once with the plain title. Exact-title plain lyrics still + # win over this looser match. + cleaned = clean_title(title) + if exact_plain is None and cleaned and cleaned.casefold() != (title or "").strip().casefold(): + exact_plain = _search_cleaned_title(artist, cleaned, duration, timeout, session) + return exact_plain +def _search_cleaned_title(artist: str, cleaned: str, duration: Optional[float], timeout: float, + session: requests.Session) -> Optional[Lyrics]: + """Search LRCLIB with a cleaned title. Synced timing is kept only for a hit + whose length matches the audio; any other hit is used as plain lyrics.""" + try: + r = lrclib_client.get(f"{LRCLIB_BASE}/search", {"q": f"{artist} {cleaned}"}, user_agent=USER_AGENT, + timeout=timeout, session=session, retry=False) + if r.status_code != 200: + return None + hits = [h for h in (r.json() or []) if isinstance(h, dict)] + except (requests.RequestException, ValueError) as exc: + logger.warning(f"LRCLIB cleaned-title search failed: {exc}") + return None + fallback: Optional[Lyrics] = None + for hit in sorted(hits, key=lambda h: 0 if h.get("syncedLyrics") else 1): + got = lyrics_from_lrclib_payload(hit) + if got is None: + continue + hit_duration = hit.get("duration") + if (got.kind == "synced" and duration and isinstance(hit_duration, (int, float)) + and abs(hit_duration - duration) <= CLEAN_TITLE_SYNC_TOLERANCE_S): + logger.info(f"Quick lyrics: synced match via cleaned title {cleaned!r}") + return got + if fallback is None and got.plain.strip(): + fallback = Lyrics("plain", got.plain) + if fallback is not None: + logger.info(f"Quick lyrics: plain lyrics via cleaned title {cleaned!r} (no length-matched sync)") + return fallback + + def resolve_timed_lines(lyrics: Optional[Lyrics]) -> Tuple[List[TimedLine], str]: """Lyrics → (line, anchor|None) pairs + tier label (synced / constant / none).""" if lyrics is None: @@ -326,15 +387,19 @@ def render_quick_video( workdir: str, lyrics: Optional[Lyrics] = None, fetch_lyrics: bool = True, + lyrics_artist: Optional[str] = None, + lyrics_title: Optional[str] = None, settings: Optional[RenderSettings] = None, ffmpeg_timeout: float = 600.0, ) -> RenderResult: - """Render the quick video. ``lyrics`` overrides the LRCLIB fetch.""" + """Render the quick video. ``lyrics`` overrides the LRCLIB fetch; + ``lyrics_artist``/``lyrics_title`` (the job's lyrics-search overrides) are + what LRCLIB is searched with, while ``artist``/``title`` are displayed.""" s = settings or RenderSettings() duration = probe_duration(instrumental_path) if lyrics is None and fetch_lyrics: - lyrics = fetch_lrclib_lyrics(artist, title, duration) + lyrics = fetch_lrclib_lyrics(lyrics_artist or artist, lyrics_title or title, duration) timed_lines, tier = resolve_timed_lines(lyrics) if tier == "synced": diff --git a/backend/services/quick_version/service.py b/backend/services/quick_version/service.py index 8c695b49..03b589bf 100644 --- a/backend/services/quick_version/service.py +++ b/backend/services/quick_version/service.py @@ -29,6 +29,7 @@ from typing import Any, Callable, Dict, Optional, Tuple from backend.services.job_notification_service import is_kjbox_job from backend.services.quick_version.renderer import render_quick_video +from backend.services.tempo_label import strip_tempo_suffix logger = logging.getLogger(__name__) @@ -161,10 +162,13 @@ class QuickVersionRender: def __init__(self, job_id: str, artist: str, title: str, instrumental: str, vocals: Optional[str], workdir: str, job_manager: Any, storage: Any, job_log: Any = None, - started_monotonic: Optional[float] = None, separation_seconds: Optional[float] = None): + started_monotonic: Optional[float] = None, separation_seconds: Optional[float] = None, + lyrics_artist: Optional[str] = None, lyrics_title: Optional[str] = None): self.job_id = job_id self.artist = artist or "Unknown" self.title = title or "Unknown" + self.lyrics_artist = lyrics_artist + self.lyrics_title = lyrics_title self.instrumental = instrumental self.vocals = vocals self.workdir = workdir @@ -195,6 +199,7 @@ class QuickVersionRender: result = render_quick_video( instrumental_path=self.instrumental, vocals_path=self.vocals, artist=self.artist, title=self.title, out_path=out_path, workdir=render_dir, + lyrics_artist=self.lyrics_artist, lyrics_title=self.lyrics_title, ) render_seconds = time.monotonic() - t0 gcs_path = f"jobs/{self.job_id}/quick/quick.mp4" @@ -259,6 +264,9 @@ def start_quick_version( return QuickVersionRender( job_id, job.artist, job.title, inst, vocals, workdir, job_manager, storage, job_log, started_monotonic=started, separation_seconds=sep_seconds, + # Same lyrics-search names the review page uses (never a tempo label). + lyrics_artist=getattr(job, "lyrics_artist", None) or job.artist, + lyrics_title=getattr(job, "lyrics_title", None) or strip_tempo_suffix(job.title), ).start() except Exception as exc: logger.warning(f"[job:{job_id}] Quick version skipped after error (non-fatal): {exc}", exc_info=True) diff --git a/backend/tests/test_quick_version.py b/backend/tests/test_quick_version.py index b1aa85f7..85eb0ede 100644 --- a/backend/tests/test_quick_version.py +++ b/backend/tests/test_quick_version.py @@ -12,6 +12,20 @@ from backend.services.quick_version import renderer as r from backend.services.quick_version import service as qs +class TestCleanTitle: + @pytest.mark.parametrize("raw,clean", [ + ("My Body Isn't Ready (Orchestral Version Live From Sound City)", "My Body Isn't Ready"), + ("Creep (Acoustic) [Remastered 2009]", "Creep"), + ("Song - Live at Wembley", "Song"), + ("Song - 2011 Remaster", "Song"), + ("Rock - Paper - Scissors", "Rock - Paper - Scissors"), + ("(Intro)", "(Intro)"), + ("", ""), + ]) + def test_clean_title(self, raw, clean): + assert r.clean_title(raw) == clean + + # --------------------------------------------------------------------------- # # Lyrics parsing / tiers # --------------------------------------------------------------------------- # @@ -70,6 +84,56 @@ class TestFetchLrclib: got = r.fetch_lrclib_lyrics("A", "T", None) assert got.kind == "plain" and got.plain == "plain words" + def test_decorated_title_retries_cleaned_with_length_matched_sync(self): + sess = self._session([ + _resp(404, {}), + _resp(200, []), + _resp(200, [ + {"syncedLyrics": "[00:01.00]studio", "duration": 217}, + {"syncedLyrics": "[00:02.00]live", "duration": 223}, + ]), + ]) + with patch.object(r.requests, "Session", return_value=sess): + got = r.fetch_lrclib_lyrics("Sombr", "My Body Isn't Ready (Orchestral Version Live From X)", 224.5) + assert got.kind == "synced" and got.timed == [(2.0, "live")] + assert sess.get.call_args.kwargs["params"] == {"q": "Sombr My Body Isn't Ready"} + + def test_cleaned_title_sync_with_wrong_length_becomes_plain(self): + sess = self._session([ + _resp(404, {}), + _resp(200, []), + _resp(200, [{"syncedLyrics": "[00:01.00]a\n[00:02.00]b", "duration": 180}]), + ]) + with patch.object(r.requests, "Session", return_value=sess): + got = r.fetch_lrclib_lyrics("A", "Song (Live)", 224.5) + assert got.kind == "plain" and got.plain == "a\nb" and got.timed is None + + def test_cleaned_title_without_duration_never_trusts_sync(self): + sess = self._session([_resp(404, {}), _resp(200, []), + _resp(200, [{"syncedLyrics": "[00:01.00]a", "duration": 200}])]) + with patch.object(r.requests, "Session", return_value=sess): + assert r.fetch_lrclib_lyrics("A", "Song (Live)", None).kind == "plain" + + def test_exact_plain_beats_cleaned_retry(self): + sess = self._session([_resp(200, {"plainLyrics": "exact"}), _resp(200, [])]) + with patch.object(r.requests, "Session", return_value=sess): + got = r.fetch_lrclib_lyrics("A", "Song (Live)", 200) + assert got.plain == "exact" and sess.get.call_count == 2 + + def test_cleaned_retry_failures_return_none(self): + err = r.requests.RequestException("down") + for third in (err, _resp(500, {}), _resp(200, [{"plainLyrics": " "}, "junk"])): + sess = self._session([_resp(404, {}), _resp(200, []), third]) + with patch.object(r.requests, "Session", return_value=sess): + assert r.fetch_lrclib_lyrics("A", "Song (Live)", 200) is None + assert sess.get.call_count == 3 + + def test_undecorated_title_does_not_retry(self): + sess = self._session([_resp(404, {}), _resp(200, [])]) + with patch.object(r.requests, "Session", return_value=sess): + assert r.fetch_lrclib_lyrics("A", "Song", 200) is None + assert sess.get.call_count == 2 + def test_network_errors_return_none(self): err = r.requests.RequestException("down") sess = self._session([err, err]) @@ -289,6 +353,30 @@ class TestStartQuickVersion: ready = jm.update_state_data.call_args_list[-1].args[2] assert ready["lyrics_tier"] == "synced" and ready["line_count"] == 42 and "ready_at" in ready + @pytest.mark.parametrize("overrides,expected", [ + ({}, ("Artist", "Song")), + ({"title": "Song (90% Tempo)"}, ("Artist", "Song")), + ({"lyrics_artist": "LA", "lyrics_title": "LT"}, ("LA", "LT")), + ]) + def test_lyrics_search_names(self, tmp_path, overrides, expected): + seen = {} + + def fake_render(**kw): + seen.update(kw) + open(kw["out_path"], "wb").write(b"x") + return r.RenderResult(kw["out_path"], "synced", 1, 1.0) + + job = _job() + job.artist, job.title = "Artist", "Song" + for k, v in overrides.items(): + setattr(job, k, v) + with patch.object(qs, "render_quick_video", side_effect=fake_render): + run = qs.start_quick_version(job, "a.flac", str(tmp_path), "/m", Mock(), Mock(), + separator_factory=_FakeSeparator) + assert run.join(10) + assert (seen["lyrics_artist"], seen["lyrics_title"]) == expected + assert seen["title"] == job.title # display title untouched + def test_separation_failure_is_non_fatal(self, tmp_path): jm = Mock() diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 89d20550..2d63a168 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -827,6 +827,13 @@ full NOMAD version. Code: `backend/services/quick_version/` (a port of kjbox `fa crawl PNG + one ffmpeg `overlay` pass, 854×480, vocals mixed back in at 30% as a guide. Every ffmpeg input and the output are bounded with `-t `: the GPU image's ffmpeg 4.4 never ends on `-shortest` alone once `amix` is involved (first prod job ran into the 300 s join timeout). + LRCLIB is searched with the job's `lyrics_artist`/`lyrics_title` overrides (else artist + title + without a tempo label). If the exact title finds nothing, it retries once with the title's + decorations stripped (`clean_title`: trailing `(…)`/`[…]`, `- Live …`/`- Remaster` suffixes). A + synced hit from that retry keeps its timing only when its length is within 4 s of the audio + (otherwise it is likely another recording, e.g. studio vs live), and anything else becomes a constant + crawl. Added after a "… (Orchestral Version Live From Sound City)" draft rendered with no lyrics + (2026-11-06). kjbox can also add lyrics to a lyric-less draft on the box (kjbox v0.150.0). 3. Uploads `jobs/{id}/quick/quick.mp4` → `file_urls.quick.video_mp4`, and records `state_data.quick_version = {status: separating|rendering|ready|failed, lyrics_tier, ready_at, …}`. 4. The worker joins the render (≤300 s) before cleaning up its temp dir — even when the ensemble diff --git a/pyproject.toml b/pyproject.toml index 2fef1ffb..530dc04b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "karaoke-gen" -version = "0.294.0" +version = "0.294.1" 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"