feat: check exact-length lyrics against the vocals, and align them by hand

- LRCLIB's copy of a track's own length was trusted as the track's
  timing and never checked. Green Day "Basket Case" (the video) sings
  16 s after that copy's first line. Exact-length LRCLIB lyrics are now
  checked against the vocals too and moved when the gap is clearly a
  second or more; a transcription and a file's own lyrics are never
  moved (#716).
- The Lyrics tab gets Align: start the lyrics (or a chosen line) at the
  playhead, nudge earlier or later with the offset shown, auto-detect
  from the vocals (saying so when it cannot tell), and reset. The offset
  is kept beside the lyrics (offset_sec in lyrics.json, or the browser's
  store), never rewritten into them, and survives a re-split. New
  endpoints POST /api/jobs/{id}/lyrics/offset and .../lyrics/align
  (#717).
- Acceptance check L4 runs auto-detect on the real Basket Case video.

Author: Thales

app/api/jobs.py

@@ -21,6 +21,7 @@
     JOB_ID_RE,
     JOBS_DIR,
     LYRICS_LOOKUP_BUDGET_SEC,
+    LYRICS_OFFSET_MAX_SEC,
     MAX_PENDING_UPLOAD_JOBS,
     MAX_PENDING_URL_JOBS,
     STEM_NAMES,
@@ -49,7 +50,9 @@
 from app.pipeline.download import InvalidYouTubeURL, fetch_audio_tags, validate_youtube_url
 from app.pipeline.errors import classify_failure
 from app.pipeline.identify import can_identify_title, identify_and_find_band
+from app.pipeline.lyrics_align import detect_offset
 from app.pipeline.lyrics_lookup import (
+    _TEXT_MAX_CHARS,
     build_query,
     candidates_path,
     copy_lyrics,
@@ -59,6 +62,7 @@
     lyrics_settled,
     read_candidates,
     read_lyrics,
+    set_lyrics_offset,
 )
 from app.pipeline.runner import _pipeline_lock
 from app.pipeline.vocal_split import split_vocals
@@ -1058,6 +1062,134 @@ def get_lyrics(job_id: str) -> Response:
     raise HTTPException(status_code=404, detail="no lyrics")
 
 
+class LyricsOffsetBody(BaseModel):
+    """How many seconds later than their own timing the lyrics are shown:
+    negative for earlier, 0 for their own timing again."""
+
+    offset_sec: float = Field(
+        ge=-LYRICS_OFFSET_MAX_SEC, le=LYRICS_OFFSET_MAX_SEC, allow_inf_nan=False
+    )
+
+
+class LyricsAlignBody(BaseModel):
+    """Synced lyrics kept only in the browser (found by the tab's own
+    LRCLIB lookup), to estimate against the track's vocals without saving
+    anything. Omitted for the lyrics the server keeps (lyrics.json)."""
+
+    synced: str | None = Field(default=None, max_length=_TEXT_MAX_CHARS)
+
+
+def _lyrics_job(job_id: str) -> tuple[Job, Path]:
+    """The job and its directory, for a lyrics edit: 404 for a malformed or
+    unknown id, or one whose lyrics.json would resolve outside JOBS_DIR."""
+    if not JOB_ID_RE.match(job_id):
+        raise HTTPException(status_code=404, detail="job not found")
+    job = registry_get(job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="job not found")
+    job_dir = _job_dir(job_id)
+    if not lyrics_path(job_dir).resolve().is_relative_to(JOBS_DIR.resolve()):
+        raise HTTPException(status_code=404, detail="no lyrics")
+    return job, job_dir
+
+
+def _synced_lyrics(job_dir: Path) -> dict:
+    """Blocking: the job's lyrics.json when it has synced lyrics. 404 when it
+    has none, 409 when they are text only and have no timing to move."""
+    entry = read_lyrics(job_dir) if lyrics_path(job_dir).is_file() else None
+    if entry is None:
+        raise HTTPException(status_code=404, detail="no lyrics")
+    if not entry["synced"]:
+        raise HTTPException(status_code=409, detail="lyrics are not synced")
+    return entry
+
+
+# A lyrics edit's body: an offset, or at most _TEXT_MAX_CHARS of LRC, which
+# as UTF-8 runs to four bytes a character.
+_LYRICS_BODY_MAX_BYTES = 4 * _TEXT_MAX_CHARS + 1024
+
+
+async def _lyrics_body(request: Request, model: type[BaseModel], empty_ok: bool = False):
+    """A lyrics edit's JSON body as ``model``: None for no body at all when
+    ``empty_ok``. 413 past _LYRICS_BODY_MAX_BYTES, else 422 for anything that
+    is not the model, with NaN and Infinity refused while parsing (see
+    _reject_non_finite) and nothing sent back of what was submitted."""
+    declared = request.headers.get("content-length", "")
+    if declared.isdigit() and int(declared) > _LYRICS_BODY_MAX_BYTES:
+        raise HTTPException(status_code=413, detail="body too large")
+    raw = await request.body()
+    if len(raw) > _LYRICS_BODY_MAX_BYTES:
+        raise HTTPException(status_code=413, detail="body too large")
+    if not raw.strip() and empty_ok:
+        return None
+    try:
+        data = json.loads(raw, parse_constant=_reject_non_finite)
+    except (ValueError, UnicodeDecodeError) as exc:
+        raise HTTPException(status_code=422, detail="invalid JSON body") from exc
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=422, detail="expected a JSON object")
+    try:
+        return model(**data)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail="invalid lyrics edit") from exc
+
+
+@router.post("/{job_id}/lyrics/offset")
+async def set_lyrics_offset_route(job_id: str, request: Request) -> dict:
+    """Keep the user's alignment of the track's synced lyrics (the Lyrics
+    tab's Align panel): {"offset_sec": seconds later, negative for earlier,
+    0 for their own timing}. Kept beside the synced text in lyrics.json, which
+    is never rewritten, and applied by the page. Answers the offset kept."""
+    job, job_dir = _lyrics_job(job_id)
+    body = await _lyrics_body(request, LyricsOffsetBody)
+    await asyncio.to_thread(_synced_lyrics, job_dir)
+    entry = await asyncio.to_thread(set_lyrics_offset, job, job_dir, body.offset_sec)
+    if entry is None:
+        raise HTTPException(status_code=500, detail="could not save lyrics")
+    return {"offset_sec": entry["offset_sec"]}
+
+
+@router.post("/{job_id}/lyrics/align")
+async def align_lyrics_route(job_id: str, request: Request) -> dict:
+    """Estimate from the vocals stem how much later the lyrics are sung on
+    this track than their stamps say, whatever timing they were saved with
+    (the Align panel's Auto-detect): {"confident": bool, "offset_sec":
+    seconds or null}.
+
+    Without a body, for the lyrics the server keeps: a confident estimate is
+    kept as their offset, as POST .../lyrics/offset would, and one that is
+    not leaves them as they are. With {"synced": ...}, lyrics the browser
+    keeps: only the estimate is answered, and nothing is saved.
+
+    Outside _pipeline_lock, like GET .../vocal-envelope: at most one streamed
+    read of one stem, and none when its envelope is already kept."""
+    job, job_dir = _lyrics_job(job_id)
+    body = await _lyrics_body(request, LyricsAlignBody, empty_ok=True)
+    if job.status != "done":
+        raise HTTPException(status_code=409, detail="job not ready")
+    stems_dir = (job_dir / "stems").resolve()
+    if not stems_dir.is_relative_to(JOBS_DIR.resolve()):
+        raise HTTPException(status_code=404, detail="job not found")
+    kept_here = body is None or body.synced is None
+    if kept_here:
+        synced = (await asyncio.to_thread(_synced_lyrics, job_dir))["synced"]
+    else:
+        synced = body.synced
+    try:
+        shift = await asyncio.to_thread(detect_offset, synced, stems_dir)
+    except Exception:
+        logger.exception("lyrics alignment failed for %s", job_id)
+        raise HTTPException(status_code=500, detail="could not align lyrics") from None
+    if shift is None or abs(shift) > LYRICS_OFFSET_MAX_SEC:
+        return {"confident": False, "offset_sec": None}
+    if kept_here:
+        entry = await asyncio.to_thread(set_lyrics_offset, job, job_dir, shift)
+        if entry is None:
+            raise HTTPException(status_code=500, detail="could not save lyrics")
+        shift = entry["offset_sec"]
+    return {"confident": True, "offset_sec": shift}
+
+
 # Upper bound on an edited grid. A 20-minute track at 300 BPM is ~6000 beats;
 # 20000 leaves generous headroom while refusing a payload crafted to exhaust
 # memory or disk.

app/core/config.py

@@ -537,6 +537,15 @@ def _musicbrainz_user_agent() -> str:
 LYRICS_ALIGN_MIN_Z = 4.5
 LYRICS_ALIGN_MIN_RATIO = 1.15
 LYRICS_ALIGN_MIN_HITS = 0.6
+# LRCLIB's version the track's own length ("timing": "exact") is checked the
+# same way, and moved only when the voice clearly starts at least this much
+# later or earlier: a copy of the right length can still be timed to another
+# cut (Green Day "Basket Case": the video's lines start 16 s after the copy's).
+LYRICS_ALIGN_EXACT_MIN_SHIFT_SEC = 1.0
+# How far the Lyrics tab's Align panel may move a track's lyrics, either way
+# ("offset_sec" in lyrics.json, POST /api/jobs/{id}/lyrics/offset): a long
+# intro or a medley's later verse, and no further.
+LYRICS_OFFSET_MAX_SEC = 600
 # Lyrics that lost their letters outside ASCII, mended from a reference that
 # has them (app/pipeline/lyrics_repair.py). A copy with no intact twin on
 # LRCLIB is checked against the audio only when it has at least this many

app/pipeline/lyrics_align.py

@@ -1,5 +1,8 @@
 """Moving LRCLIB's timing onto this track, for lyrics from a version of
-another length (lyrics_lookup.py saves those with "timing": "unverified").
+another length (lyrics_lookup.py saves those with "timing": "unverified"),
+and for a version of the same length whose lines the vocals show start at
+least LYRICS_ALIGN_EXACT_MIN_SHIFT_SEC away: a copy the track's length can
+still be timed to another cut, and its length alone proved nothing.
 
 A version of a song a few seconds longer or shorter than the track is most
 often the same recording with more or less lead-in: a video's intro, a
@@ -32,6 +35,7 @@
 from numpy.lib.stride_tricks import sliding_window_view
 
 from app.core.config import (
+    LYRICS_ALIGN_EXACT_MIN_SHIFT_SEC,
     LYRICS_ALIGN_MAX_OFFSET_SEC,
     LYRICS_ALIGN_MIN_HITS,
     LYRICS_ALIGN_MIN_LINES,
@@ -203,24 +207,49 @@ def _envelope(stems_dir: Path) -> tuple[float, list[int]] | None:
     return vocal_envelope(vocals, _ENVELOPE_HOP_SEC)
 
 
+def detect_offset(synced: str, stems_dir: Path) -> float | None:
+    """How many seconds later ``synced``'s lines are sung on this track, from
+    the vocals stem in ``stems_dir``, whatever timing they were saved with:
+    the Lyrics tab's Auto-detect. None when the stem does not show it clearly,
+    or there is no stem. Blocking: may read the whole stem."""
+    envelope = _envelope(stems_dir)
+    if envelope is None:
+        return None
+    hop, db = envelope
+    return estimate_offset(line_starts(synced), onset_strength(db), hop)
+
+
 def align_lyrics(job: Job, job_dir: Path) -> str | None:
-    """Move unverified lyrics' timing onto this track, when the vocals stem
-    shows clearly by how much. Returns the timing the job's lyrics.json is
-    left with, or None when it has none to align. Never raises."""
+    """Move LRCLIB lyrics' timing onto this track, when the vocals stem shows
+    clearly by how much: a version of another length ("unverified") by any
+    amount, one of the track's length ("exact") only by at least
+    LYRICS_ALIGN_EXACT_MIN_SHIFT_SEC. A transcription or the file's own
+    lyrics are the track's timing already. Returns the timing the job's
+    lyrics.json is left with, or None when it has none to align. Never
+    raises."""
     # Imported here: lyrics_lookup imports this module.
     from app.pipeline.lyrics_lookup import read_lyrics, write_lyrics
 
     try:
         entry = read_lyrics(job_dir)
-        if entry is None or entry.get("timing") != "unverified" or not entry["synced"]:
+        if entry is None or not entry["synced"]:
             return entry.get("timing") if entry else None
+        timing = entry.get("timing")
+        # Aligned by hand in the Lyrics tab: the user's timing, not to guess at.
+        if "offset_sec" in entry:
+            return timing
+        checked = timing == "unverified" or (timing == "exact" and entry["source"] == "lrclib")
+        if not checked:
+            return timing
         envelope = _envelope(job_dir / "stems")
         if envelope is None:
-            return "unverified"
+            return timing
         hop, db = envelope
         shift = estimate_offset(line_starts(entry["synced"]), onset_strength(db), hop)
         if shift is None:
-            return "unverified"
+            return timing
+        if timing == "exact" and abs(shift) < LYRICS_ALIGN_EXACT_MIN_SHIFT_SEC:
+            return timing
         logger.info("[%s] lyrics timing moved by %+.2fs", job.id, shift)
         write_lyrics(
             job,

app/pipeline/lyrics_lookup.py

@@ -84,6 +84,7 @@
     LYRICS_LOOKUP_RETRIES,
     LYRICS_LOOKUP_RETRY_SEC,
     LYRICS_NOT_FOUND_RETRY_SEC,
+    LYRICS_OFFSET_MAX_SEC,
     LYRICS_OTHERS_MAX,
     LYRICS_SAME_RECORDING_SEC,
     TIMEOUT_LYRICS_LOOKUP,
@@ -1035,6 +1036,16 @@ def _clean_version(value: Any) -> dict[str, Any] | None:
     return version
 
 
+def clean_offset(value: Any) -> float | None:
+    """A lyrics offset in seconds, to the hundredth, or None when ``value``
+    is not a finite number within +-LYRICS_OFFSET_MAX_SEC."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    if not math.isfinite(value) or abs(value) > LYRICS_OFFSET_MAX_SEC:
+        return None
+    return round(float(value), 2) + 0.0  # + 0.0: never -0.0
+
+
 def clean_lyrics(value: Any) -> dict[str, Any] | None:
     """lyrics.json as read back from disk, or None when it is not one. A
     damaged or hand-edited file must not put anything malformed in front of
@@ -1053,6 +1064,12 @@ def clean_lyrics(value: Any) -> dict[str, Any] | None:
     # Only on lyrics whose lost letters were given back (lyrics_repair.py).
     if value.get("repaired") in LYRICS_REPAIRS:
         entry["repaired"] = value["repaired"]
+    # Only once the user has aligned them in the Lyrics tab: seconds later
+    # (earlier when negative) than the synced text says, applied by the page.
+    # A value out of bounds is dropped rather than the whole file.
+    offset = clean_offset(value.get("offset_sec"))
+    if offset is not None:
+        entry["offset_sec"] = offset
     others = value.get("others")
     cleaned = [_clean_version(o) for o in (others if isinstance(others, list) else [])]
     entry["others"] = [o for o in cleaned if o is not None][:LYRICS_OTHERS_MAX]
@@ -1160,9 +1177,31 @@ def keep_answer(job: Job, job_dir: Path, answer: LookupAnswer) -> bool:
     return True
 
 
+# One edit of lyrics.json at a time from the Lyrics tab: each reads the file,
+# changes the offset and writes it back whole.
+_OFFSET_LOCK = threading.Lock()
+
+
+def set_lyrics_offset(job: Job, job_dir: Path, offset: float) -> dict[str, Any] | None:
+    """Keep ``offset`` seconds as the user's alignment of the job's synced
+    lyrics (0 is their own timing again) and return the entry as written.
+    None when the job has no synced lyrics or they could not be written. The
+    synced text itself is never rewritten, so their own timing stays there."""
+    cleaned = clean_offset(offset)
+    if cleaned is None:
+        return None
+    with _OFFSET_LOCK:
+        entry = read_lyrics(job_dir)
+        if entry is None or not entry["synced"]:
+            return None
+        entry = {**entry, "offset_sec": cleaned}
+        return entry if write_lyrics(job, job_dir, entry) else None
+
+
 def copy_lyrics(src_dir: Path, dest_dir: Path) -> bool:
     """Copy a job's lyrics.json and candidates file to another job of the
-    same recording (a re-split). True when lyrics.json was copied."""
+    same recording (a re-split), with any alignment the user gave the lyrics
+    (offset_sec). True when lyrics.json was copied."""
     copied = False
     for path in (lyrics_path(src_dir), candidates_path(src_dir)):
         if not path.is_file():

static/css/daw.css

@@ -3922,12 +3922,53 @@ input, textarea { font-family: inherit; }
 .lyrics-match { display: flex; flex-direction: column; min-width: 0; }
 .lyrics-match-title { font-size: 13px; font-weight: 600; color: var(--fg); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .lyrics-match-meta { font-size: 11px; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.lyrics-tools { display: flex; gap: 12px; }
+.lyrics-tools { display: flex; flex-wrap: wrap; gap: 4px 12px; }
 .lyrics-link {
   padding: 0; background: none; border: none; cursor: pointer;
   color: var(--accent); font-size: 11px; font-weight: 600;
 }
 .lyrics-link:hover { text-decoration: underline; }
+/* Align, for lyrics with no timing to move: still focusable, so its tooltip
+   says why (lyrics.js). */
+.lyrics-link[aria-disabled="true"] { color: var(--muted); cursor: default; }
+.lyrics-link[aria-disabled="true"]:hover { text-decoration: none; }
+
+/* The Align panel: under the tools row, the sidebar's width, every control a
+   button so the keys reach them all. The nudges sit either side of the
+   offset they change. */
+.lyrics-align {
+  display: flex; flex-direction: column; gap: 6px;
+  padding: 8px; border: 1px solid var(--border); border-radius: 8px; background: var(--panel);
+}
+.lyrics-align-hint { margin: 0; font-size: 10.5px; line-height: 1.4; color: var(--muted); }
+.lyrics-align-target {
+  margin: 0; font-size: 11px; color: var(--fg-2);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.lyrics-align-target:empty { display: none; }
+.lyrics-align-btn {
+  min-height: 26px; padding: 0 8px; border-radius: 6px;
+  background: var(--panel-2); border: 1px solid var(--border-strong);
+  color: var(--fg-2); font-family: inherit; font-size: 11px; font-weight: 600;
+  cursor: pointer; transition: background var(--t-fast), color var(--t-fast);
+}
+.lyrics-align-btn:hover { background: var(--panel-3); color: var(--fg); }
+.lyrics-align-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+.lyrics-align-btn[aria-busy="true"] { cursor: progress; opacity: 0.6; }
+.lyrics-align-start { width: 100%; color: var(--accent); border-color: var(--accent); }
+.lyrics-align-nudges { display: flex; align-items: center; gap: 4px; }
+.lyrics-align-nudge { flex: 0 0 auto; padding: 0 6px; font-family: var(--font-mono); font-variant-numeric: tabular-nums; }
+.lyrics-align-offset {
+  flex: 1 1 auto; min-width: 0; text-align: center;
+  font-family: var(--font-mono); font-size: 12px; font-weight: 600; color: var(--fg);
+  font-variant-numeric: tabular-nums; white-space: nowrap;
+}
+.lyrics-align-actions { display: flex; gap: 6px; }
+.lyrics-align-actions .lyrics-align-btn { flex: 1 1 0; min-width: 0; }
+.lyrics-align-message { margin: 0; font-size: 11px; line-height: 1.4; color: var(--fg-2); }
+.lyrics-align-message:empty { display: none; }
+.lyrics-align-message.muted, .lyrics-align-message.loading { color: var(--muted); }
+.lyrics-align-message.error { color: var(--danger); }
 /* display: flex would otherwise outrank the hidden attribute that folds it. */
 .lyrics-version-list[hidden] { display: none; }
 .lyrics-version-list { list-style: none; margin: 2px 0 0; padding: 0; display: flex; flex-direction: column; gap: 2px; max-height: 180px; overflow-y: auto; }
@@ -3963,6 +4004,9 @@ input, textarea { font-family: inherit; }
 /* The line after it, a step brighter than the rest, so the next words can be
    read before they are due. */
 .lyrics-line.next { color: var(--fg-2); }
+/* While the Align panel is open, the line last clicked, which Start lyrics
+   here moves instead of the first. */
+.lyrics-body.aligning .lyrics-line.picked { outline: 1px dashed var(--border-strong); outline-offset: -1px; }
 /* The karaoke wipe, one word at a time: sung words take the accent, and the
    word being sung is filled left to right up to --fill, set every frame by
    lyrics.js. Per word rather than across the whole line, so a line that wraps