fix(quick-version): retry LRCLIB with a cleaned title + honour lyrics overrides (v0.294.1) (#1257)

## 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 <noreply@anthropic.com>
This commit is contained in:
Andrew Beveridge ☄️andClaude Opus 5.5 authored and GitHub committed 2026-11-08 18:56:59 -05:00
1 parent cd11088be5
commit c133b64c7d
5 files changed
+172 -4

No files matched your search

+67 -2
View File
@@ -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":
+9 -1
View File
@@ -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)
+88
View File
@@ -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()
+7
View File
@@ -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 <duration>`: 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
+1 -1
View File
@@ -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 <andrew@beveridge.uk>"]
license = "MIT"