Merge remote-tracking branch 'origin/main' into unheard-lines

Reviewed-on: #26
Reviewed-by: branderson <brad@branderson.io>

.dejima/allowed-domains

@@ -0,0 +1,6 @@
+deb.debian.org
+security.debian.org
+pypi.org
+files.pythonhosted.org
+download.pytorch.org
+download-r2.pytorch.org

.gitea/workflows/tests.yml

@@ -0,0 +1,86 @@
+name: tests
+
+# `pull_request_target` reads this file from the base branch, so a pull
+# request cannot change what runs or where (including `runs-on:`). The run's
+# ref is therefore the base branch, and the checkout has to name the head.
+on:
+  pull_request_target:
+
+jobs:
+  test:
+    # No Docker socket, and egress limited to .dejima/allowed-domains on main.
+    runs-on: dejima-confined
+
+    # Node for actions/checkout; Debian bookworm's python3 is the 3.11 the
+    # Dockerfile ships.
+    container:
+      image: node:22-bookworm
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      # Inline rather than a script in the repository: the files come from the
+      # branch under test, so a script would be missing from older branches.
+      - name: Check the hosts this job fetches from are reachable
+        run: |
+          set -u
+          bad=""
+          for host in deb.debian.org security.debian.org pypi.org \
+                      files.pythonhosted.org download.pytorch.org \
+                      download-r2.pytorch.org; do
+            resolved=""
+            for attempt in 1 2 3 4; do
+              getent hosts "$host" >/dev/null 2>&1 && { resolved=yes; break; }
+              sleep 2
+            done
+            if [ -z "$resolved" ]; then
+              echo "no    $host - does not resolve"; bad="$bad $host(dns)"; continue
+            fi
+            # Any HTTP answer proves the connection; curl reports 000 for none.
+            code="$(curl -sS -o /dev/null --max-time 20 --retry 2 -w '%{http_code}' "https://$host/" 2>/dev/null || true)"
+            case "${code:-000}" in
+              000) echo "no    $host - resolves, but nothing answered over https"
+                   bad="$bad $host(net)" ;;
+              *)   echo "ok    $host (http $code)" ;;
+            esac
+          done
+          [ -z "$bad" ] && exit 0
+          {
+            echo
+            echo "Unreachable:$bad"
+            echo
+            echo "The confined tier reaches only what .dejima/allowed-domains on"
+            echo "main declares, rendered onto the runner separately from the"
+            echo "merge. On the runner:"
+            echo "  sudo dejima-ci-allowlist show    - is the name listed?"
+            echo "  sudo dejima-ci-allowlist check   - is a change pending?"
+            echo "  sudo dejima-ci-allowlist render  - apply it now"
+            echo "A (dns) failure is the resolver; a (net) one is the packet"
+            echo "filter, which sudo dejima-ci-firewall reapplies."
+            echo
+            echo "download.pytorch.org redirects its wheels to"
+            echo "download-r2.pytorch.org, so both have to be allowed."
+          } >&2
+          exit 1
+
+      - name: Install Python
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends python3 python3-venv
+          python3 -m venv /opt/venv
+          # bookworm's pip 23.0 rejects the PyTorch index's typing_extensions
+          # wheel over its name's spelling, then cannot build it from source
+          /opt/venv/bin/pip install --retries 5 --upgrade pip
+          echo /opt/venv/bin >> "$GITHUB_PATH"
+
+      # The CPU build first: torch from PyPI is the CUDA build, several GB of
+      # libraries no test uses. The install below then finds torch satisfied.
+      - name: Install CPU-only torch
+        run: pip install --retries 5 torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install songtrace
+        run: pip install --retries 5 -e '.[dev]'
+
+      - run: pytest

README.md

@@ -34,6 +34,27 @@ printing the low-confidence regions it found (e.g.
 editor such as [Yass](https://www.yass-along.com/) or
 [USDX](https://usdx.eu/) and touch those spots up before playing.
 
+## Reviewing a song
+
+The web UI plays the finished song folder back against the review, so you can
+check the timing without loading it into a game first. Pick a song in the
+queue and the review panel gets the packaged video with a transport above the
+lyrics; as it plays, the line being sung is highlighted, words light up as
+they are reached, and a playhead sweeps each line against its notes. Click any
+line or word to play from there.
+
+Playback is modelled on the game: the `#MP3` is the audio and the clock, and
+the `#VIDEO` is muted background slaved to it. It also uses the same seconds
+the notes were generated from, so a word that lights up late in the browser is
+late in the game too.
+
+The packaged video has its audio track stripped for the same reason. It is the
+same recording as the `#MP3`, so a player that does not mute the video plays
+both at once, a few frames apart, which is heard as an echo. Songs built
+before this change still have it — check with `ffprobe <song>.mp4` for an
+audio stream, and rebuild with **Restart from** set to `package` to clear it
+without re-downloading.
+
 ## Configuration
 
 Config is TOML. Resolution order:
@@ -51,7 +72,9 @@ $EDITOR config.toml   # set whisper_url at minimum
 
 See `config.example.toml` for every available field (`whisper_url`,
 `whisper_api_key`, `whisper_model`, `whisper_api`, `output_dir`, `work_dir`,
-`creator`, `demucs_model`, `crepe_model`, `device`, `bind_host`, `port`).
+`creator`, `demucs_model`, `crepe_model`, `device`, `bind_host`, `port`,
+`ytdlp_clients`, `ytdlp_cookies`, `ytdlp_impersonate`,
+`ytdlp_pot_provider_url`, `ytdlp_version`).
 
 `whisper_api` selects the wire format: `"openai"` (default) speaks the
 OpenAI-compatible `POST {whisper_url}/audio/transcriptions` API; `"asr-webservice"`
@@ -85,6 +108,30 @@ Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/)
 installed on the host; `docker-compose.yml` requests one GPU via the
 `nvidia` device driver.
 
+## Sharing the GPU
+
+`songtrace serve` is long-lived but only wants the GPU in bursts, so it hands
+it back after every stage rather than holding it for the life of the process.
+Three stages load a model — `separate` (Demucs), `align` (wav2vec2) and
+`pitch` (torchcrepe) — and each one's weights are dropped as soon as that
+stage finishes, followed by `torch.cuda.empty_cache()` to return the
+allocator's freed blocks to the driver instead of keeping them for reuse. This
+matters most between `separate` and `align`: `transcribe` sits between them
+waiting on your Whisper server, which can be minutes of a GPU nothing is
+using.
+
+Stages that gave memory back say so in the job log:
+
+```
+[separate] released 3704 MiB of GPU memory
+```
+
+The cost is reloading each model once per job instead of once per process,
+which is seconds against stages that run for minutes. What this does not
+release is the CUDA context itself, a few hundred MB that belongs to the
+process until it exits; freeing that would mean running each stage in a
+subprocess. If you need every last MB back, stop the container between runs.
+
 ## Bare-metal
 
 ```sh
@@ -117,10 +164,74 @@ songtrace make --title "..." --artist "..." --lyrics lyrics.txt \
 Valid stages, in pipeline order: `acquire`, `separate`, `transcribe`,
 `align`, `pitch`, `notes`, `grid`, `package`.
 
+In the web UI this is what selecting a queue entry does: its title, artist,
+lyrics and the rest come back up in the form, so you can adjust them and hit
+REBUILD SONG. Only the stages your edit actually invalidates are rerun —
+fixing a line of lyrics realigns without re-downloading or re-separating.
+CREATE SONG, at the top of the queue, clears the page to start a fresh one.
+
+That planning works off the fields you changed, which cannot see a change in
+songtrace itself: after an upgrade, a rebuild of an older song finds every
+stage cached and does nothing. **Restart from** on the rebuild form is the way
+to redo a stage anyway — pick `package` to repackage without re-downloading.
+It can only widen what is rerun, so an edit that invalidates an earlier stage
+still wins.
+
+**REBUILD ALL FROM…**, under CREATE SONG, does the same for every song at once:
+pick the stage an update improved and each song is rebuilt from there with the
+inputs it has now. Every song starts ticked; untick any already rebuilt by hand
+(each shows when it was last built). Songs still in progress are skipped, as
+are songs whose uploaded video is gone when the stage is `acquire`.
+
+## YouTube download failures
+
+`HTTP Error 403: Forbidden` from the acquire stage means YouTube served the
+page but refused the media URL. In rough order of likelihood:
+
+1. **yt-dlp is stale.** YouTube changes its defences every few weeks, so
+   songtrace keeps yt-dlp current itself. Once a day, and again whenever a
+   download fails outright, it checks PyPI for a newer stable release,
+   installs it under `$XDG_CACHE_HOME/songtrace/` (`/data/models/cache` in the
+   container), and tries it before the copy installed with songtrace. That
+   copy is never modified and is always the fallback, so a release that breaks
+   compatibility costs a retry rather than the download. The job log names
+   the yt-dlp version behind each attempt.
+
+   `ytdlp_version` overrides this: `"bundled"` uses only the installed copy,
+   and a release number such as `"2026.08.19"` pins that release instead of
+   the newest.
+
+2. **Missing JS runtime.** yt-dlp needs `yt-dlp-ejs` plus a JavaScript engine
+   to solve YouTube's player challenges; without them it silently falls back to
+   formats that 403. The `[default,curl-cffi,deno]` extras in `pyproject.toml`
+   cover this, for both the installed copy and the ones fetched at runtime.
+   Check with `docker compose exec songtrace yt-dlp -v --simulate <url>` — the debug
+   header must show a `JS runtimes:` line that is not `none`.
+
+3. **The IP is rate-limited or flagged.** Datacenter and VPN ranges get
+   throttled hardest. Try from another network before changing config.
+
+4. **A PO token is required.** If the log says so explicitly, run
+   [bgutil-ytdlp-pot-provider](https://github.com/Brainicism/bgutil-ytdlp-pot-provider)
+   as a sidecar, install its plugin into the image, and point
+   `ytdlp_pot_provider_url` at it.
+
+`ytdlp_clients` retries the download against each listed player client in
+turn, so a client that YouTube has broken is skipped automatically.
+`ytdlp_cookies` (a Netscape cookie jar, for age-gated videos) and
+`ytdlp_impersonate` (a browser TLS fingerprint, e.g. `"chrome"`) are the other
+two levers. Do not use a cookie jar from an account you care about — YouTube
+bans for automated access.
+
+Failed downloads leave the work dir intact, so re-running the job resumes
+rather than starting over.
+
 ## Regenerating the web UI screenshot
 
 `scripts/screenshot_webui.py` seeds the real app with a fixed set of jobs
-covering every status and screenshots it to `docs/images/webui.png`:
+covering every status and screenshots it to `docs/images/webui.png`. It uses
+`ffmpeg` to give the selected song a playable folder so the shot includes the
+player; without `ffmpeg` on `PATH` it still runs, just without it.
 
 ```sh
 pip install -e '.[dev]'

config.example.toml

@@ -11,3 +11,13 @@ creator = "brad"
 # device = "cuda"
 bind_host = "0.0.0.0"
 # port = 8000
+
+# YouTube downloads. Each player client is tried in order until one works;
+# "default" means whatever yt-dlp currently picks for itself.
+# ytdlp_clients = ["default", "tv"]
+# ytdlp_cookies = "/config/youtube-cookies.txt"  # Netscape cookie jar
+# ytdlp_impersonate = "chrome"                   # TLS fingerprint to present
+# ytdlp_pot_provider_url = "http://bgutil-provider:4416"
+# Newer yt-dlp releases are fetched from PyPI at runtime and tried before the
+# bundled one; "bundled" turns that off, a release number pins one.
+# ytdlp_version = "auto"

pyproject.toml

@@ -5,7 +5,12 @@ description = "Generate UltraStar/Melody Mania karaoke songs from a video and re
 requires-python = ">=3.11"
 license = "AGPL-3.0-or-later"
 dependencies = [
-    "yt-dlp",
+    # yt-dlp declares no runtime deps of its own; the extras are what make
+    # YouTube work. "default" pulls yt-dlp-ejs (JS challenge solving) and the
+    # requests/urllib3 handlers, "deno" ships the JS runtime that executes it,
+    # and "curl-cffi" provides the --impersonate targets. Without them YouTube
+    # extraction degrades to HTTP 403 on the media URLs.
+    "yt-dlp[default,curl-cffi,deno]",
     "demucs",
     "torch",
     "torchaudio",

scripts/screenshot_webui.py

@@ -6,6 +6,9 @@ with a fixed set of jobs covering every status, then screenshots it.
 One-time setup: pip install -e '.[dev]' && playwright install chromium
 Run: python scripts/screenshot_webui.py
 """
+import json
+import shutil
+import subprocess
 import tempfile
 import threading
 import time
@@ -16,12 +19,36 @@ import uvicorn
 from playwright.sync_api import sync_playwright
 
 from songtrace.config import Config
-from songtrace.pipeline import PipelineError, PipelineResult
+from songtrace.pipeline import PipelineError, PipelineResult, song_slug
 from songtrace.web import create_app
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
 OUT_IMAGE = REPO_ROOT / "docs" / "images" / "webui.png"
 STAGES = ["acquire", "separate", "transcribe", "align", "pitch", "notes", "grid", "package"]
+DEFAULT_LYRICS = "[verse]\n...\n[chorus]\n...\n"
+
+# public domain (16th century English folk song, author unknown)
+GREENSLEEVES_LYRICS = """\
+Alas, my love, you do me wrong
+To cast me off discourteously
+For I have loved you well and long
+Delighting in your company
+
+Greensleeves was all my joy
+Greensleeves was my delight
+Greensleeves was my heart of gold
+And who but my lady Greensleeves
+
+I have been ready at your hand
+To grant whatever you would crave
+I have both waged life and land
+Your love and good will for to have
+
+Greensleeves was all my joy
+Greensleeves was my delight
+Greensleeves was my heart of gold
+And who but my lady Greensleeves
+"""
 
 # order matters: the app has one worker thread, so each job runs in submission
 # order. "running" must be submitted after the done/failed ones complete and
@@ -33,12 +60,59 @@ SONGS = [
     ("Pink Moon", "Nick Drake", "done",
      {"warnings": ["2 low-confidence notes near 0:38–0:41",
                     "1 low-confidence note near 1:22–1:24"]}),
+    ("Landslide", "Fleetwood Mac", "done",
+     {"warnings": ["1 low-confidence note near 0:52–0:55"]}),
+    ("Greensleeves", "Traditional", "done",
+     {"lyrics": GREENSLEEVES_LYRICS,
+      "warnings": ["1 low-confidence note near 0:45–0:47",
+                   "1 line dropped (not sung) near \"for i have loved\"",
+                   "missing lyrics near 2:10–2:18"],
+      "review": {
+          "lines": [
+              # Pitches are the real Greensleeves melody (E natural minor, as
+              # arranged by Gilbert DeBenedetti, "Level 4 - Flowing"), converted
+              # to UltraStar semitones (0 = C4 = MIDI 60): E5=16 F#5=18 G5=19
+              # A5=21 B4=11 D5=14.
+              {"index": 0, "text": "Alas, my love, you do me wrong",
+               "dropped": False,
+               "notes": [{"start": 10.0, "end": 10.4, "pitch": 16, "low_confidence": False},
+                         {"start": 10.4, "end": 10.6, "pitch": 18, "low_confidence": False},
+                         {"start": 10.6, "end": 11.2, "pitch": 19, "low_confidence": False},
+                         {"start": 11.2, "end": 11.5, "pitch": 21, "low_confidence": False},
+                         {"start": 11.5, "end": 11.7, "pitch": 19, "low_confidence": False},
+                         {"start": 11.7, "end": 11.9, "pitch": 18, "low_confidence": False},
+                         {"start": 11.9, "end": 12.9, "pitch": 14, "low_confidence": False}],
+               "words": [{"text": "Alas,", "start": 10.0, "end": 10.4},
+                         {"text": "my", "start": 10.4, "end": 10.6},
+                         {"text": "love,", "start": 10.6, "end": 11.2},
+                         {"text": "you", "start": 11.2, "end": 11.5},
+                         {"text": "do", "start": 11.5, "end": 11.7},
+                         {"text": "me", "start": 11.7, "end": 11.9},
+                         {"text": "wrong", "start": 11.9, "end": 12.9}]},
+              {"index": 1, "text": "To cast me off discourteously",
+               "dropped": False,
+               "notes": [{"start": 44.0, "end": 44.3, "pitch": 11, "low_confidence": False},
+                         {"start": 44.3, "end": 44.6, "pitch": 16, "low_confidence": False},
+                         {"start": 44.6, "end": 44.8, "pitch": 18, "low_confidence": False},
+                         {"start": 44.8, "end": 45.0, "pitch": 19, "low_confidence": False},
+                         {"start": 45.0, "end": 45.4, "pitch": 18, "low_confidence": True}],
+               "words": [{"text": "To", "start": 44.0, "end": 44.3},
+                         {"text": "cast", "start": 44.3, "end": 44.6},
+                         {"text": "me", "start": 44.6, "end": 44.8},
+                         {"text": "off", "start": 44.8, "end": 45.0},
+                         {"text": "discourteously", "start": 45.0, "end": 45.4}]},
+              {"index": 2, "text": "For I have loved you well and long",
+               "dropped": True, "notes": [], "words": []},
+          ],
+          "missing_spans": [{"start": 130.0, "end": 138.0}],
+      }}),
     ("Such Great Heights", "The Postal Service", "failed",
      {"error": "yt-dlp: unable to download video data: HTTP Error 403: Forbidden"}),
     ("Time Escaping", "Big Thief", "running", {}),
     ("Vampire in the Corner", "Magdalena Bay", "queued", {}),
 ]
-SELECTED = "Pink Moon"
+SELECTED = "Greensleeves"
+REVIEW_HEADING = "REVIEW"
 
 running_event = threading.Event()
 
@@ -51,6 +125,27 @@ def make_runner():
         if kind == "done":
             for s in STAGES:
                 log(f"[{s}] running")
+            if "review" in extra:
+                work = cfg.work_dir / song_slug(inp)
+                work.mkdir(parents=True, exist_ok=True)
+                notes = [
+                    {**n, "duration": n["end"] - n["start"], "text": "~",
+                     "line_index": line["index"]}
+                    for line in extra["review"]["lines"] for n in line["notes"]
+                ]
+                (work / "notes_sec.json").write_text(json.dumps({
+                    "notes": notes, "breaks": [], "warnings": extra["warnings"]}))
+                (work / "align_meta.json").write_text(json.dumps({
+                    "dropped_lines": [line["index"] for line in extra["review"]["lines"]
+                                      if line["dropped"]],
+                    "missing_spans": [[s["start"], s["end"]]
+                                      for s in extra["review"]["missing_spans"]],
+                }))
+                (work / "alignment.json").write_text(json.dumps([
+                    {"word": w["text"], "start": w["start"], "end": w["end"],
+                     "score": 0.9, "line_index": line["index"]}
+                    for line in extra["review"]["lines"] for w in line.get("words", [])
+                ]))
             out = cfg.output_dir / f"{inp.artist} - {inp.title}"
             out.mkdir(parents=True, exist_ok=True)
             return PipelineResult(output_dir=out, warnings=extra["warnings"])
@@ -65,22 +160,50 @@ def make_runner():
     return runner
 
 
-def start_server(tmp_path: Path) -> str:
+def start_server(tmp_path: Path) -> tuple[str, Config]:
     cfg = Config(whisper_url="http://localhost:9000/v1", output_dir=tmp_path / "out",
                  work_dir=tmp_path / "work", bind_host="127.0.0.1", port=8811)
     app = create_app(cfg, runner=make_runner())
     server = uvicorn.Server(uvicorn.Config(app, host=cfg.bind_host, port=cfg.port,
                                             log_level="warning"))
     threading.Thread(target=server.run, daemon=True).start()
-    return f"http://{cfg.bind_host}:{cfg.port}"
+    return f"http://{cfg.bind_host}:{cfg.port}", cfg
+
+
+def install_media(cfg: Config) -> bool:
+    """Give the selected song a playable folder, so the shot shows the player.
+
+    A flat fill rather than a test pattern: the point is the transport and the
+    lyric tracking underneath it, not the picture. Skipped without ffmpeg.
+    """
+    if shutil.which("ffmpeg") is None:
+        print("ffmpeg not found; screenshotting without the player")
+        return False
+    artist, title = next((a, t) for t, a, _, _ in SONGS if t == SELECTED)
+    slug = f"{artist} - {title}"
+    out = cfg.output_dir / slug
+    out.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-f", "lavfi",
+         "-i", "color=c=0x1A1430:s=640x360:d=60", "-c:v", "libx264",
+         "-pix_fmt", "yuv420p", "-preset", "ultrafast", "-an",
+         str(out / f"{slug}.mp4")], check=True)
+    subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-f", "lavfi",
+         "-i", "anullsrc=r=44100:cl=stereo:d=60", "-b:a", "64k",
+         str(out / f"{slug}.mp3")], check=True)
+    (out / f"{slug}.txt").write_text(
+        f"#TITLE:{title}\n#ARTIST:{artist}\n#MP3:{slug}.mp3\n#VIDEO:{slug}.mp4\n"
+        f"#BPM:240\n#GAP:10000\n: 0 4 16 Alas,\nE\n", encoding="utf-8")
+    return True
 
 
 def seed_jobs(base_url: str) -> None:
-    lyrics = "[verse]\n...\n[chorus]\n...\n"
     with httpx.Client(timeout=10) as client:
-        for title, artist, kind, _ in SONGS:
+        for title, artist, kind, extra in SONGS:
             resp = client.post(f"{base_url}/api/jobs", data={
-                "title": title, "artist": artist, "lyrics": lyrics,
+                "title": title, "artist": artist,
+                "lyrics": extra.get("lyrics", DEFAULT_LYRICS),
                 "youtube_url": "https://youtu.be/00000000000"})
             resp.raise_for_status()
             job_id = resp.json()["id"]
@@ -95,13 +218,25 @@ def seed_jobs(base_url: str) -> None:
                 time.sleep(0.05)
 
 
-def capture(base_url: str) -> None:
+def capture(base_url: str, with_player: bool) -> None:
     with sync_playwright() as p:
         browser = p.chromium.launch()
-        page = browser.new_page(viewport={"width": 1280, "height": 900})
+        page = browser.new_page(viewport={"width": 1280, "height": 1000})
         page.goto(base_url, wait_until="networkidle")
         page.get_by_text(SELECTED, exact=True).click()
-        page.wait_for_timeout(300)
+        page.wait_for_timeout(500)
+        if with_player:
+            # paused mid-line, so the shot carries the playhead and the sung /
+            # current word colouring rather than an untouched transport
+            page.evaluate("document.getElementById('player-media').currentTime = 11.6")
+            page.wait_for_timeout(400)
+            # scrolled to the review: the player pins to the top of #main and
+            # the tracked lines sit under it, which is the panel in use
+            page.evaluate("""() => {
+              const main = document.getElementById('main');
+              main.scrollTo(0, document.getElementById('review').offsetTop - 12);
+            }""")
+            page.wait_for_timeout(400)
         OUT_IMAGE.parent.mkdir(parents=True, exist_ok=True)
         page.screenshot(path=str(OUT_IMAGE))
         browser.close()
@@ -109,10 +244,11 @@ def capture(base_url: str) -> None:
 
 def main() -> None:
     with tempfile.TemporaryDirectory() as tmp:
-        base_url = start_server(Path(tmp))
+        base_url, cfg = start_server(Path(tmp))
         time.sleep(1)
         seed_jobs(base_url)
-        capture(base_url)
+        with_player = install_media(cfg)
+        capture(base_url, with_player)
     print(f"wrote {OUT_IMAGE}")
 
 

src/songtrace/config.py

@@ -1,6 +1,6 @@
 import os
 import tomllib
-from dataclasses import dataclass, fields
+from dataclasses import dataclass, field, fields
 from pathlib import Path
 
 
@@ -18,9 +18,18 @@ class Config:
     device: str = "cuda"
     bind_host: str = "127.0.0.1"
     port: int = 8000
+    # YouTube player clients to try, in order, until one yields a download.
+    # "default" means yt-dlp's own choice; see its extractor-args docs.
+    ytdlp_clients: list[str] = field(default_factory=lambda: ["default", "tv"])
+    ytdlp_cookies: Path | None = None
+    ytdlp_impersonate: str | None = None
+    ytdlp_pot_provider_url: str | None = None
+    # "auto" keeps yt-dlp current from PyPI, "bundled" uses only the copy
+    # installed with songtrace, and a release such as "2026.08.19" pins that.
+    ytdlp_version: str = "auto"
 
 
-_PATH_FIELDS = {"output_dir", "work_dir"}
+_PATH_FIELDS = {"output_dir", "work_dir", "ytdlp_cookies"}
 
 
 def load_config(path: Path | None = None) -> Config:

src/songtrace/models.py

@@ -0,0 +1,47 @@
+"""Handing the GPU back between stages.
+
+The GPU this runs on is shared, and `songtrace serve` outlives every job it
+runs, so a stage that caches its weights holds VRAM until the process exits —
+including while a later stage is waiting on the Whisper server, which can be
+minutes of a GPU nothing is using. Two things have to be undone: the caches
+themselves, and PyTorch's allocator, which keeps freed blocks for reuse rather
+than returning them to the driver.
+
+A stage that caches a model registers how to drop it with @on_release, so this
+module needs to know nothing about the pipeline. Registration happens at import
+time, which run_pipeline has already done by the time it calls release().
+"""
+import gc
+import sys
+from typing import Callable
+
+_callbacks: list[Callable[[], None]] = []
+
+
+def on_release(fn: Callable[[], None]) -> Callable[[], None]:
+    """Register a callback that drops a cached model."""
+    _callbacks.append(fn)
+    return fn
+
+
+def release() -> int:
+    """Drop every cached model and return its VRAM to the driver.
+
+    Answers the bytes handed back, which is the only part of this a caller can
+    show someone. Safe whenever: a stage that never loaded anything has nothing
+    to drop, and the allocator is left alone unless this process actually
+    initialised CUDA.
+    """
+    for callback in _callbacks:
+        callback()
+    # weights reach the allocator's free list only once the last reference
+    # goes, and a module graph is cyclic enough to outlive refcounting
+    gc.collect()
+    torch = sys.modules.get("torch")
+    if torch is None or not torch.cuda.is_available():
+        return 0
+    if not torch.cuda.is_initialized():
+        return 0
+    before = torch.cuda.memory_reserved()
+    torch.cuda.empty_cache()
+    return max(before - torch.cuda.memory_reserved(), 0)

src/songtrace/notes.py

@@ -23,6 +23,7 @@ class TimedNote:
     pitch: int            # UltraStar semitone (0 = C4 = MIDI 60)
     text: str             # display text incl. leading space / "~"
     low_confidence: bool
+    line_index: int
 
 
 def hz_to_midi_float(hz: float) -> float:
@@ -78,7 +79,8 @@ def syllabify(word: str, language: str | None) -> list[str]:
     return parts or [word]
 
 
-def build_notes(rows: list[dict], times, f0, conf, language: str | None
+def build_notes(rows: list[dict], times, f0, conf, language: str | None,
+                dropped_lines=(), missing_spans=(), ref_lines=None
                 ) -> tuple[list[TimedNote], list[float], list[str]]:
     notes: list[TimedNote] = []
     breaks: list[float] = []
@@ -92,7 +94,8 @@ def build_notes(rows: list[dict], times, f0, conf, language: str | None
         if not segs:
             pitch = notes[-1].pitch if notes else 0
             notes.append(_note(row["start"], row["end"] - row["start"], pitch,
-                               _text(row["word"], 0, line_initial), True))
+                               _text(row["word"], 0, line_initial), True,
+                               row["line_index"]))
             continue
         low = row["score"] < LOW_SCORE
         sylls = syllabify(row["word"], language)
@@ -100,14 +103,16 @@ def build_notes(rows: list[dict], times, f0, conf, language: str | None
             segs = _subdivide(segs, len(sylls))
         for i, (s, e, midi) in enumerate(segs):
             text = _text(sylls[i], i, line_initial) if i < len(sylls) else "~"
-            notes.append(_note(s, e - s, round(midi) - 60, text, low))
+            notes.append(_note(s, e - s, round(midi) - 60, text, low,
+                               row["line_index"]))
     _deoverlap(notes)
-    return notes, breaks, _warnings(notes)
+    return notes, breaks, _warnings(notes, dropped_lines, missing_spans, ref_lines or [])
 
 
 def _note(start: float, duration: float, pitch: int, text: str,
-          low: bool) -> TimedNote:
-    return TimedNote(float(start), float(duration), int(pitch), text, low)
+          low: bool, line_index: int) -> TimedNote:
+    return TimedNote(float(start), float(duration), int(pitch), text, low,
+                     int(line_index))
 
 
 def _deoverlap(notes: list[TimedNote]) -> None:
@@ -153,7 +158,8 @@ def _fmt(t: float) -> str:
     return f"{int(t // 60)}:{int(t % 60):02d}"
 
 
-def _warnings(notes: list[TimedNote]) -> list[str]:
+def _warnings(notes: list[TimedNote], dropped_lines=(), missing_spans=(),
+             ref_lines=()) -> list[str]:
     warnings, run = [], []
     for n in list(notes) + [None]:
         if n is not None and n.low_confidence:
@@ -164,4 +170,21 @@ def _warnings(notes: list[TimedNote]) -> list[str]:
                 f"{len(run)} low-confidence note{'' if len(run) == 1 else 's'} "
                 f"near {_fmt(first.start)}–{_fmt(last.start + last.duration)}")
             run = []
+    for group in _consecutive_runs(dropped_lines):
+        n = len(group)
+        text = " ".join(ref_lines[group[0]]) if group[0] < len(ref_lines) else ""
+        warnings.append(
+            f"{n} line{'' if n == 1 else 's'} dropped (not sung) near \"{text}\"")
+    for a, b in missing_spans:
+        warnings.append(f"missing lyrics near {_fmt(a)}–{_fmt(b)}")
     return warnings
+
+
+def _consecutive_runs(indices) -> list[list[int]]:
+    runs = []
+    for i in sorted(indices):
+        if runs and i == runs[-1][-1] + 1:
+            runs[-1].append(i)
+        else:
+            runs.append([i])
+    return runs

src/songtrace/pipeline.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable
 
+from . import models
 from .config import Config
 
 class PipelineError(Exception):
@@ -74,6 +75,14 @@ def run_pipeline(inp: SongInput, cfg: Config, log=print,
             log(f"[{stage.name}] cached, skipping")
             continue
         log(f"[{stage.name}] running")
-        stage.run(ctx)
+        # per stage rather than per job: each model is used by one stage, so
+        # holding it past that only keeps VRAM from whatever else wants it
+        try:
+            stage.run(ctx)
+        finally:
+            # logged only when it actually gave something back, so the line is
+            # evidence rather than noise on a box where this matters
+            if freed := models.release():
+                log(f"[{stage.name}] released {freed / 2**20:.0f} MiB of GPU memory")
     return PipelineResult(output_dir=cfg.output_dir / song_slug(inp),
                           warnings=read_warnings(work))

src/songtrace/rebuild.py

@@ -38,6 +38,17 @@ def plan(old: SongInput, new: SongInput) -> str | None:
     return min((FIELD_STAGE[f] for f in changed), key=STAGE_ORDER.index)
 
 
+def earliest(*stages: str | None) -> str | None:
+    """The earliest of the stages given, ignoring None ("nothing forced").
+
+    An operator's explicit choice is combined with plan()'s rather than
+    replacing it: the planner's stage is the latest that is still correct for
+    the edit, so a choice may only ever redo more.
+    """
+    named = [s for s in stages if s]
+    return min(named, key=STAGE_ORDER.index) if named else None
+
+
 def relocate_work(old: SongInput, new: SongInput, cfg: Config) -> bool:
     """Move the cached work dir when title/artist changed its slug.
 

src/songtrace/stages/acquire.py

@@ -2,14 +2,19 @@ import json
 import shutil
 from pathlib import Path
 
+from .. import ytdlp
+from ..config import Config
 from ..media import ffmpeg
 from ..pipeline import Ctx, PipelineError, Stage
 
 IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"}
+# yt-dlp's in-progress scratch files, which a failed attempt leaves behind.
+PARTIAL_EXTENSIONS = {".part", ".ytdl", ".temp"}
 
 
 def _classify_downloads(dest: Path) -> tuple[Path, Path | None]:
-    files = list(dest.glob("source_video.*"))
+    files = [p for p in dest.glob("source_video.*")
+             if p.suffix.lower() not in PARTIAL_EXTENSIONS]
     thumbs = [p for p in files if p.suffix.lower() in IMAGE_EXTENSIONS]
     videos = [p for p in files if p.suffix.lower() not in IMAGE_EXTENSIONS]
     if not videos:
@@ -18,17 +23,50 @@ def _classify_downloads(dest: Path) -> tuple[Path, Path | None]:
     return video, thumbs[0] if thumbs else None
 
 
-def download_youtube(url: str, dest: Path) -> tuple[Path, Path | None]:
-    import yt_dlp
-    opts = {
-        "outtmpl": str(dest / "source_video.%(ext)s"),
-        "format": "bestvideo*+bestaudio/best",
-        "writethumbnail": True,
-        "noplaylist": True,
-    }
-    with yt_dlp.YoutubeDL(opts) as ydl:
-        ydl.extract_info(url, download=True)
-    return _classify_downloads(dest)
+def _ydl_args(cfg: Config, dest: Path, client: str, url: str) -> list[str]:
+    args = [
+        "--output", str(dest / "source_video.%(ext)s"),
+        "--format", "bestvideo*+bestaudio/best",
+        "--write-thumbnail", "--no-playlist", "--no-progress",
+        "--retries", "10", "--fragment-retries", "10",
+        "--extractor-retries", "5",
+    ]
+    if client != "default":
+        args += ["--extractor-args", f"youtube:player_client={client}"]
+    if cfg.ytdlp_pot_provider_url:
+        args += ["--extractor-args",
+                 f"youtubepot-bgutilhttp:base_url={cfg.ytdlp_pot_provider_url}"]
+    if cfg.ytdlp_cookies:
+        args += ["--cookies", str(cfg.ytdlp_cookies)]
+    if cfg.ytdlp_impersonate:
+        args += ["--impersonate", cfg.ytdlp_impersonate]
+    return [*args, "--", url]
+
+
+def download_youtube(url: str, dest: Path, cfg: Config,
+                     log=print) -> tuple[Path, Path | None]:
+    clients = list(cfg.ytdlp_clients) or ["default"]
+    tried: list[str] = []
+    last: Exception | None = None
+    # If every copy fails, look for a release newer than the daily check found.
+    for refresh in (False, True):
+        for ydl in ytdlp.candidates(cfg, log, refresh):
+            if ydl.version in tried:
+                continue
+            tried.append(ydl.version)
+            for client in clients:
+                try:
+                    ydl.run(_ydl_args(cfg, dest, client, url), log)
+                    return _classify_downloads(dest)
+                except PipelineError as e:
+                    last = e
+                    log(f"yt-dlp {ydl.version} player_client={client} "
+                        f"failed: {e}")
+    raise PipelineError(
+        f"yt-dlp {', '.join(tried)} could not download {url} after trying "
+        f"player_client={', '.join(clients)}. Last error: {last}. "
+        "See the yt-dlp options in config.toml (cookies, impersonation, "
+        "PO token provider).")
 
 
 def _run(ctx: Ctx) -> None:
@@ -36,7 +74,8 @@ def _run(ctx: Ctx) -> None:
         raise PipelineError("provide exactly one of youtube_url / video_path")
     thumb = None
     if ctx.inp.youtube_url:
-        video, thumb = download_youtube(ctx.inp.youtube_url, ctx.work)
+        video, thumb = download_youtube(ctx.inp.youtube_url, ctx.work,
+                                       ctx.cfg, ctx.log)
     else:
         video = ctx.work / f"source_video{ctx.inp.video_path.suffix}"
         shutil.copyfile(ctx.inp.video_path, video)

src/songtrace/stages/align.py

@@ -1,12 +1,27 @@
 import json
 from pathlib import Path
 
-from ..lyrics import RefLyrics, alignment_token, normalize_lyrics
+import numpy as np
+import soundfile as sf
+
+from ..lyrics import alignment_token, normalize_lyrics
+from ..models import on_release
 from ..pipeline import Ctx, PipelineError, Stage
-from .transcribe import load_transcript, lyrics_similarity, vocal_sections
+from ..whisper_client import TranscriptSegment
+from .transcribe import (classify_lyrics_match, load_transcript, lyrics_similarity,
+                         recovered_spans, vocal_sections)
 
 SIMILARITY_THRESHOLD = 0.4
+# MMS_FA's wildcard token: any audio the transcript does not cover
+STAR = "*"
+# Singing is audio within this much of the stem's loud level; separation
+# bleed sits far below it.
+SINGING_BELOW_LOUD_DB = 25.0
+# Shorter stretches are breaths, ad-libs or Whisper's loose segment edges.
+MIN_UNHEARD_SEC = 3.0
 
+# a stage aligns section by section, so the model is cached across the calls
+# within one run and dropped at the end of it
 _model_cache = {}
 
 
@@ -17,6 +32,11 @@ def _get_model(device: str):
     return _model_cache[device]
 
 
+@on_release
+def unload_model() -> None:
+    _model_cache.clear()
+
+
 def force_align_section(vocals_path: Path, start: float, end: float,
                         tokens: list[str], device: str) -> list[tuple[float, float, float]]:
     import torch
@@ -32,7 +52,7 @@ def force_align_section(vocals_path: Path, start: float, end: float,
         waveform[:, lo:hi], sr, bundle.sample_rate)
     # MMS_FA only models a-z and apostrophe; anything else becomes the star token.
     vocab = bundle.get_dict()
-    tokens = ["".join(c if c in vocab else "*" for c in t) for t in tokens]
+    tokens = ["".join(c if c in vocab else STAR for c in t) for t in tokens]
     with torch.inference_mode():
         emission, _ = _get_model(device)(waveform.to(device))
         spans = bundle.get_aligner()(emission[0], bundle.get_tokenizer()(tokens))
@@ -42,16 +62,48 @@ def force_align_section(vocals_path: Path, start: float, end: float,
              sum(t.score for t in s) / len(s)) for s in spans]
 
 
-def _assign_lines_to_sections(ref: RefLyrics, sections) -> list[list[int]]:
-    """Split lyric lines across vocal sections proportionally to section duration."""
+def untranscribed_singing(vocals_path: Path, segments,
+                          frame: float = 0.05) -> list[tuple[float, float]]:
+    """Stretches of the vocal stem with singing in them but no transcript."""
+    data, sr = sf.read(str(vocals_path), dtype="float32", always_2d=True)
+    hop = int(sr * frame)
+    n = len(data) // hop
+    if n == 0:
+        return []
+    rms = np.sqrt((data[:n * hop].mean(1).reshape(n, hop) ** 2).mean(1))
+    db = 20 * np.log10(rms + 1e-10)
+    sung = db >= np.quantile(db, 0.9) - SINGING_BELOW_LOUD_DB
+    times = np.arange(n) * frame
+    for s in segments:
+        sung[(times >= min(s.start, s.end)) & (times < max(s.start, s.end))] = False
+    spans, start = [], None
+    for t, on in zip(times, sung):
+        if on and start is None:
+            start = float(t)
+        elif not on and start is not None:
+            spans.append((start, float(t)))
+            start = None
+    if start is not None:
+        spans.append((start, float(times[-1] + frame)))
+    # a breath or a quiet syllable must not split one unsung passage in two
+    merged: list[list[float]] = []
+    for a, b in spans:
+        if merged and a - merged[-1][1] < 1.0:
+            merged[-1][1] = b
+        else:
+            merged.append([a, b])
+    return [(a, b) for a, b in merged if b - a >= MIN_UNHEARD_SEC]
+
+
+def _assign_lines_to_sections(line_indices: list[int], sections) -> list[list[int]]:
+    """Split matched lyric line indices across vocal sections proportionally to section duration."""
     total = sum(b - a for a, b in sections) or 1.0
-    n_lines = len(ref.lines)
+    n = len(line_indices)
     groups, elapsed, start = [], 0.0, 0
     for i, (a, b) in enumerate(sections):
         elapsed += b - a
-        stop = n_lines if i == len(sections) - 1 else min(
-            n_lines, round(n_lines * elapsed / total))
-        groups.append(list(range(start, max(stop, start))))
+        stop = n if i == len(sections) - 1 else min(n, round(n * elapsed / total))
+        groups.append(line_indices[start:max(stop, start)])
         start = max(stop, start)
     return groups
 
@@ -85,9 +137,20 @@ def _enforce_monotonic(rows: list[dict]) -> None:
 def _align_section(vocals: Path, sec: tuple[float, float], words: list[tuple[str, int]],
                    language: str | None, device: str) -> list[dict]:
     tokens = [alignment_token(w, language) for w, _ in words]
-    alignable = [t for t in tokens if t]
-    aligned = iter(force_align_section(vocals, sec[0], sec[1], alignable, device)
-                   if alignable else [])
+    # A star before, between and after lines lets speech, laughter or an
+    # ad-lib there go unexplained rather than claim the next line's letters.
+    seq, prev_line = [], None
+    for (_, line_index), token in zip(words, tokens):
+        if not token:
+            continue
+        if line_index != prev_line:
+            seq.append(STAR)
+            prev_line = line_index
+        seq.append(token)
+    if seq:
+        seq.append(STAR)
+    spans = force_align_section(vocals, sec[0], sec[1], seq, device) if seq else []
+    aligned = iter(span for span, token in zip(spans, seq) if token != STAR)
     rows, blank = [], (None, None, 0.0)
     for (word, line_index), token in zip(words, tokens):
         start, end, score = next(aligned, blank) if token else blank
@@ -99,23 +162,36 @@ def _align_section(vocals: Path, sec: tuple[float, float], words: list[tuple[str
 
 def _run(ctx: Ctx) -> None:
     ref = normalize_lyrics(ctx.inp.lyrics_text)
-    segments = load_transcript(ctx)
+    segments = sorted(load_transcript(ctx), key=lambda s: s.start)
     sim = lyrics_similarity(segments, ref)
     if sim < SIMILARITY_THRESHOLD:
         raise PipelineError(
             f"lyrics don't match audio (similarity {sim:.2f}) — "
             "wrong lyrics or wrong recording?")
-    # normalised so an inverted span can never collapse a section onto one instant
-    sections = [(min(a, b), max(a, b)) for a, b in vocal_sections(segments)]
     vocals = ctx.work / "vocals.wav"
+    unheard = untranscribed_singing(vocals, segments)
+    dropped_lines, missing_spans = classify_lyrics_match(segments, ref,
+                                                         unheard=unheard)
+    # lines Whisper missed are aligned against the singing it had no text for;
+    # only that singing, so an untranscribed ad-lib cannot draw lines into it
+    recovered = [TranscriptSegment(a, b, "")
+                 for a, b in recovered_spans(segments, ref, unheard)]
+    # normalised so an inverted span can never collapse a section onto one instant
+    sections = [(min(a, b), max(a, b))
+                for a, b in vocal_sections(segments + recovered)]
+    matched = [i for i in range(len(ref.lines)) if i not in set(dropped_lines)]
     rows = []
-    for sec, line_idxs in zip(sections, _assign_lines_to_sections(ref, sections)):
+    for sec, line_idxs in zip(sections, _assign_lines_to_sections(matched, sections)):
         words = [(w, li) for li in line_idxs for w in ref.lines[li]]
         if words:
             rows.extend(_align_section(vocals, sec, words, ctx.inp.language,
                                        ctx.cfg.device))
     _enforce_monotonic(rows)
     (ctx.work / "alignment.json").write_text(json.dumps(rows))
+    (ctx.work / "align_meta.json").write_text(json.dumps({
+        "dropped_lines": dropped_lines,
+        "missing_spans": [list(s) for s in missing_spans],
+    }))
 
 
 def align_stage() -> Stage:

src/songtrace/stages/notes.py

@@ -3,6 +3,7 @@ from dataclasses import asdict
 
 import numpy as np
 
+from ..lyrics import normalize_lyrics
 from ..notes import build_notes
 from ..pipeline import Ctx, Stage
 
@@ -10,8 +11,15 @@ from ..pipeline import Ctx, Stage
 def _run(ctx: Ctx) -> None:
     rows = json.loads((ctx.work / "alignment.json").read_text())
     data = np.load(ctx.work / "pitch.npz")
+    meta_path = ctx.work / "align_meta.json"
+    meta = json.loads(meta_path.read_text()) if meta_path.exists() else {}
+    dropped_lines = meta.get("dropped_lines", [])
+    missing_spans = [tuple(s) for s in meta.get("missing_spans", [])]
+    ref_lines = normalize_lyrics(ctx.inp.lyrics_text).lines
     notes, breaks, warnings = build_notes(
-        rows, data["times"], data["f0"], data["conf"], ctx.inp.language)
+        rows, data["times"], data["f0"], data["conf"], ctx.inp.language,
+        dropped_lines=dropped_lines, missing_spans=missing_spans,
+        ref_lines=ref_lines)
     (ctx.work / "notes_sec.json").write_text(json.dumps({
         "notes": [asdict(n) for n in notes],
         "breaks": breaks,

src/songtrace/stages/package.py

@@ -51,11 +51,15 @@ def _run(ctx: Ctx) -> None:
     meta = json.loads((ctx.work / "meta.json").read_text())
     src_video = ctx.work / meta["video_file"]
     fmt, codec = ffprobe_codec(src_video)
+    # The video is background only: the song's audio is #MP3, and the two are
+    # the same recording. A player that does not mute the video plays both at
+    # once, which is heard as an echo, so the audio track is dropped here.
     if (fmt, codec) in GOOD_VIDEO:
-        shutil.copyfile(src_video, out / f"{slug}{src_video.suffix}")
+        ffmpeg("-i", str(src_video), "-c", "copy", "-an",
+               str(out / f"{slug}{src_video.suffix}"))
     else:
         ffmpeg("-i", str(src_video), "-c:v", "libx264", "-crf", "20",
-               "-preset", "medium", "-c:a", "aac", str(out / f"{slug}.mp4"))
+               "-preset", "medium", "-an", str(out / f"{slug}.mp4"))
         _set_header(txt, "VIDEO", f"{slug}.mp4")
     cover_src = ctx.inp.cover_path
     if cover_src is None and meta.get("thumbnail"):

src/songtrace/stages/pitch.py

@@ -1,9 +1,32 @@
+import sys
 from pathlib import Path
 
 import numpy as np
 
+from ..models import on_release
 from ..pipeline import Ctx, Stage
 
+# Separated vocal stems keep faint bleed that crepe still finds a pitch in, so
+# frames this far below the song's loud vocal level count as silence. Relative
+# rather than absolute, so it holds however loud the song was mastered.
+SILENCE_BELOW_LOUD_DB = 25.0
+
+
+@on_release
+def unload_model() -> None:
+    """torchcrepe caches its model as attributes on its own infer function."""
+    torchcrepe = sys.modules.get("torchcrepe")
+    if torchcrepe is None:
+        return
+    for attr in ("model", "capacity"):
+        if hasattr(torchcrepe.infer, attr):
+            delattr(torchcrepe.infer, attr)
+
+
+def mute_silence(conf: np.ndarray, loudness: np.ndarray) -> None:
+    """Zero the confidence of frames quiet enough to be bleed, in place."""
+    conf[loudness < np.quantile(loudness, 0.9) - SILENCE_BELOW_LOUD_DB] = 0.0
+
 
 def track_pitch(vocals_path: Path, model: str, device: str):
     import torchaudio
@@ -20,6 +43,7 @@ def track_pitch(vocals_path: Path, model: str, device: str):
         return_periodicity=True, batch_size=512)
     f0 = f0[0].cpu().numpy()
     conf = periodicity[0].cpu().numpy()
+    mute_silence(conf, torchcrepe.loudness.a_weighted(waveform, 16000, 160)[0].cpu().numpy())
     times = np.arange(len(f0)) * 0.01
     return times, f0, conf
 

src/songtrace/stages/transcribe.py

@@ -20,10 +20,112 @@ def _tokens(text: str) -> list[str]:
     return [t for w in text.split() if (t := alignment_token(w))]
 
 
+def match_lyrics(segments, ref: RefLyrics):
+    heard, seg_of = [], []
+    for si, s in enumerate(segments):
+        for t in _tokens(s.text):
+            heard.append(t)
+            seg_of.append(si)
+    pairs = [(t, li) for w, li in zip(ref.words, ref.word_line_index)
+             if (t := alignment_token(w))]
+    expected = [t for t, _ in pairs]
+    line_of = [li for _, li in pairs]
+    matcher = difflib.SequenceMatcher(a=heard, b=expected)
+    return matcher, seg_of, line_of
+
+
 def lyrics_similarity(segments, ref: RefLyrics) -> float:
-    heard = [t for s in segments for t in _tokens(s.text)]
-    expected = [t for w in ref.words if (t := alignment_token(w))]
-    return difflib.SequenceMatcher(a=heard, b=expected).ratio()
+    matcher, _, _ = match_lyrics(segments, ref)
+    return matcher.ratio()
+
+
+def _line_times(segments, matcher, seg_of, line_of) -> dict[int, tuple[float, float]]:
+    """For each reference line that was heard, the start of the first and the
+    end of the last transcript segment its words were heard in. Words in a
+    'replace' block are paired with heard words proportionally."""
+    times: dict[int, tuple[float, float]] = {}
+    for tag, ai1, ai2, bj1, bj2 in matcher.get_opcodes():
+        if tag not in ("equal", "replace"):
+            continue
+        for j in range(bj1, bj2):
+            seg = segments[seg_of[ai1 + (j - bj1) * (ai2 - ai1) // (bj2 - bj1)]]
+            a, b = times.get(line_of[j], (seg.start, seg.end))
+            times[line_of[j]] = (min(a, seg.start), max(b, seg.end))
+    return times
+
+
+def _unheard_runs(segments, ref: RefLyrics, unheard
+                  ) -> tuple[list[list[int]], list[list[tuple[float, float]]]]:
+    """Runs of reference lines with nothing heard for them, each with the
+    untranscribed singing between the heard lines either side of it."""
+    matcher, seg_of, line_of = match_lyrics(segments, ref)
+    times = _line_times(segments, matcher, seg_of, line_of)
+    alignable = set(line_of)
+    runs, spans, run, prev_end = [], [], [], 0.0
+
+    def close(next_start: float) -> None:
+        if run:
+            runs.append(list(run))
+            spans.append([(max(a, prev_end), min(b, next_start)) for a, b in unheard
+                          if a < next_start and b > prev_end])
+            run.clear()
+
+    for li in range(len(ref.lines)):
+        if li in times:
+            close(times[li][0])
+            prev_end = times[li][1]
+        elif li in alignable:
+            run.append(li)
+    close(float("inf"))
+    return runs, spans
+
+
+def recovered_spans(segments, ref: RefLyrics, unheard) -> list[tuple[float, float]]:
+    """The untranscribed singing that stands in for lines Whisper missed, so
+    alignment can place them there."""
+    return _merge_spans([sp for spans in _unheard_runs(segments, ref, unheard)[1]
+                         for sp in spans])
+
+
+def classify_lyrics_match(segments, ref: RefLyrics, pad: float = 1.0, unheard=()
+                          ) -> tuple[list[int], list[tuple[float, float]]]:
+    """Split reference lines into matched vs. dropped, and flag sung spans no
+    reference line explains.
+
+    dropped_lines: reference line indices covered only by 'insert' opcodes
+    (present in the lyrics, never heard), unless `unheard` (sung spans the
+    transcript has no text for) has singing between the heard lines either
+    side of them: then Whisper missed them, not the singer.
+
+    missing_spans: the padded, merged bounds of the heard segments behind
+    'delete' opcodes (heard, but matching no reference word). A segment can
+    also hold matched lines, so a span marks where to look, not words to
+    discard.
+    """
+    runs, run_spans = _unheard_runs(segments, ref, unheard)
+    dropped_lines = sorted(li for run, sp in zip(runs, run_spans) if not sp
+                           for li in run)
+
+    matcher, seg_of, _ = match_lyrics(segments, ref)
+    spans = []
+    for tag, ai1, ai2, _, _ in matcher.get_opcodes():
+        if tag != "delete":
+            continue
+        sis = [seg_of[i] for i in range(ai1, ai2)]
+        start = max(0.0, min(segments[si].start for si in sis) - pad)
+        end = max(segments[si].end for si in sis) + pad
+        spans.append((start, end))
+    return dropped_lines, _merge_spans(spans)
+
+
+def _merge_spans(spans: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    merged: list[list[float]] = []
+    for a, b in sorted(spans):
+        if merged and a <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], b)
+        else:
+            merged.append([a, b])
+    return [tuple(s) for s in merged]
 
 
 def _run(ctx: Ctx) -> None:

src/songtrace/static/index.html

@@ -111,6 +111,62 @@ body {
 }
 
 #sidebar .eyebrow, #jobs .empty-note { padding: 0 18px; }
+#create-song { display: block; width: calc(100% - 36px); margin: 0 18px 20px; padding: 9px 12px; }
+
+#rebuild-all { display: block; margin: -8px 18px 20px; }
+#rebuild-all-note { margin: -12px 18px 20px; }
+
+#rebuild-all-dialog {
+  width: min(480px, calc(100vw - 32px));
+  padding: 26px 28px;
+  color: var(--text);
+  background: var(--panel);
+  border: 1px solid var(--border);
+}
+#rebuild-all-dialog::backdrop { background: rgb(10 10 15 / 0.75); }
+#rebuild-all-dialog h2 {
+  margin: 0 0 14px;
+  font-family: var(--font-display);
+  font-weight: 700;
+  font-size: 0.8rem;
+  letter-spacing: 0.22em;
+  color: var(--text-muted);
+}
+#rebuild-all-form { display: grid; gap: 16px; }
+#rebuild-all-form p { margin: 0; font-size: 0.88rem; line-height: 1.5; }
+#rebuild-all-count { color: var(--warn); }
+#rebuild-all-songs { margin: 0; padding: 0; border: 0; min-width: 0; }
+#rebuild-all-songs legend {
+  margin-bottom: 6px;
+  padding: 0;
+  font-family: var(--font-display);
+  font-weight: 600;
+  font-size: 0.68rem;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+}
+#rebuild-all-list {
+  max-height: 40vh;
+  overflow-y: auto;
+  border-top: 1px solid var(--border);
+  border-bottom: 1px solid var(--border);
+}
+.rebuild-all-row {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 1px 10px;
+  align-items: baseline;
+  padding: 7px 4px;
+  font-size: 0.88rem;
+  cursor: pointer;
+}
+.rebuild-all-row input { accent-color: var(--purple); }
+.rebuild-all-row:has(input:disabled) { cursor: default; color: var(--text-muted); }
+.rebuild-all-row .meta { grid-column: 2; font-size: 0.76rem; color: var(--text-muted); }
+.rebuild-all-every { padding-top: 0; color: var(--text-muted); }
+#rebuild-all-error { min-height: 1.2em; color: var(--fail); }
+#rebuild-all-error:empty { display: none; }
 
 #jobs { display: flex; flex-direction: column; gap: 1px; margin-top: 8px; }
 
@@ -194,8 +250,13 @@ body {
 }
 
 #song-form { display: grid; gap: 18px; }
+.song-form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
+.song-form-main { display: grid; gap: 18px; align-content: start; }
+.song-form-lyrics textarea { height: 100%; flex: 1 1 auto; }
 .pair { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
 .field { display: flex; flex-direction: column; gap: 6px; }
+/* [hidden] is only display:none, which the rule above would otherwise win */
+.field[hidden], .keep-note[hidden] { display: none; }
 .field > span {
   font-family: var(--font-display);
   font-weight: 600;
@@ -220,7 +281,6 @@ input:not([type="file"]):hover { border-bottom-color: var(--text-muted); }
 input:not([type="file"]):focus { border-bottom-color: var(--aqua); }
 
 textarea {
-  min-height: 8.5rem;
   padding: 11px 13px;
   line-height: 1.6;
   background: var(--panel);
@@ -229,6 +289,7 @@ textarea {
 }
 textarea:hover { border-color: var(--text-muted); }
 textarea:focus { border-color: var(--aqua); }
+.song-form-lyrics textarea { min-height: 8.5rem; }
 
 input[type="file"] {
   font-size: 0.82rem;
@@ -304,6 +365,7 @@ button { cursor: pointer; }
   transition: background 120ms ease;
 }
 .primary:hover { background: #BE7BF9; }
+.primary:disabled { background: var(--control); color: var(--text-muted); cursor: not-allowed; }
 
 #form-error { margin: 12px 0 0; min-height: 1.2em; font-size: 0.85rem; color: var(--fail); }
 
@@ -316,20 +378,47 @@ button { cursor: pointer; }
 }
 #review h3 span { color: var(--text-muted); font-weight: 400; }
 
-#warnings { display: flex; flex-direction: column; gap: 1px; }
-.warn-row {
-  display: grid;
-  grid-template-columns: auto auto 1fr;
-  align-items: center;
-  gap: 10px;
-  padding: 10px 12px;
-  background: var(--panel);
+/* sticks to the top of #main so the video stays in frame as the lyrics scroll */
+#player { position: sticky; top: 0; z-index: 2; margin: 0 0 14px; padding: 6px 0 10px; background: var(--bg); }
+#player-video {
+  display: block;
+  width: 100%;
+  max-height: 30vh;
+  background: #000;
   border: 1px solid var(--border);
+  border-radius: 2px;
+}
+#player-video[hidden] { display: none; }
+/* the native transport renders light otherwise, against everything around it */
+#player-media { display: block; width: 100%; margin-top: 8px; color-scheme: dark; }
+
+#lyrics-review { display: flex; flex-direction: column; gap: 10px; }
+.review-line { padding: 8px 12px; background: var(--panel); border: 1px solid var(--border); }
+.review-line-active { background: var(--panel-raised); border-color: var(--aqua); }
+.review-word-sung { color: var(--text-muted); }
+.review-word-active { color: var(--aqua); font-weight: 600; }
+.review-playhead { position: absolute; top: 0; bottom: 0; width: 2px; margin-left: -1px; background: var(--aqua); }
+.review-seek { cursor: pointer; }
+.review-line-text { display: block; font-size: 0.9rem; }
+.review-line-dropped { opacity: 0.55; }
+.review-line-dropped .review-line-text { text-decoration: line-through; }
+.review-line-note { display: block; margin-top: 4px; font-size: 0.72rem; color: var(--text-muted); }
+.review-line-timeline { position: relative; margin-top: 4px; }
+.review-lane { position: absolute; top: 0; bottom: 0; }
+.review-lane-alt { background: var(--panel-raised); }
+.review-word-row { position: relative; height: 18px; }
+.review-word { position: absolute; top: 0; white-space: nowrap; font-size: 0.9rem; }
+.review-roll { position: relative; display: block; width: 100%; height: 20px; margin-top: 4px; }
+.review-note { fill: var(--aqua); }
+.review-note-low { fill: var(--warn); }
+.review-missing {
+  margin: 0;
+  padding: 6px 12px;
+  font-size: 0.78rem;
+  color: var(--warn);
+  background: var(--panel);
+  border: 1px dashed var(--border);
 }
-.warn-row + .warn-row { margin-top: 6px; }
-.warn-icon { color: var(--warn); }
-.warn-count { font-size: 0.85rem; }
-.warn-range { justify-self: end; font-family: var(--font-mono); font-size: 0.82rem; color: var(--text-muted); }
 
 .review-error { margin: 0 0 14px; font-size: 0.85rem; color: var(--fail); }
 
@@ -343,7 +432,7 @@ button { cursor: pointer; }
   border: 1px solid var(--border);
 }
 .output-path code { flex: 1; overflow-wrap: anywhere; font-family: var(--font-mono); font-size: 0.82rem; }
-#copy-path, .action, #cancel-rebuild {
+#copy-path, .action {
   flex: none;
   padding: 5px 12px;
   font-family: var(--font-display);
@@ -356,10 +445,11 @@ button { cursor: pointer; }
   border: 1px solid var(--control);
   border-radius: 2px;
 }
-#copy-path:hover, .action:hover, #cancel-rebuild:hover { border-color: var(--text-muted); }
+#copy-path:hover, .action:hover { border-color: var(--text-muted); }
 
 .form-actions { display: flex; align-items: center; gap: 14px; }
 .keep-note { margin: -8px 0 0; font-size: 0.78rem; color: var(--aqua); }
+#form-lock { margin: 0; font-size: 0.78rem; color: var(--text-muted); }
 #review-actions { display: flex; gap: 10px; margin-top: 14px; }
 #review-lineage { margin: -10px 0 14px; }
 .lineage {
@@ -464,6 +554,11 @@ button { cursor: pointer; }
   #stage-track { margin-left: 0; flex-wrap: wrap; }
 }
 
+@media (max-width: 720px) {
+  .song-form-grid { grid-template-columns: 1fr; }
+  .song-form-lyrics textarea { height: auto; }
+}
+
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation: none !important; transition: none !important; }
 }
@@ -477,41 +572,78 @@ button { cursor: pointer; }
     <div class="kana" aria-hidden="true">カラオケ</div>
   </div>
   <div>
+    <button type="button" id="create-song" class="primary">CREATE SONG</button>
+    <button type="button" id="rebuild-all" class="action">REBUILD ALL FROM…</button>
+    <p id="rebuild-all-note" class="empty-note" role="status" hidden></p>
     <h2 class="eyebrow">QUEUE</h2>
     <div id="jobs"></div>
   </div>
 </aside>
 
+<dialog id="rebuild-all-dialog" aria-labelledby="rebuild-all-heading">
+  <form id="rebuild-all-form" method="dialog">
+    <h2 id="rebuild-all-heading">REBUILD ALL SONGS</h2>
+    <p>Reruns the songs ticked below from the chosen stage onwards with the
+      inputs they have now, for when a songtrace update improves that stage.</p>
+    <label class="field">
+      <span>Restart from</span>
+      <select name="force_from" required></select>
+    </label>
+    <fieldset id="rebuild-all-songs">
+      <legend>Songs</legend>
+      <label class="rebuild-all-row rebuild-all-every">
+        <input type="checkbox" id="rebuild-all-toggle" checked>
+        <span>All songs</span>
+      </label>
+      <div id="rebuild-all-list"></div>
+    </fieldset>
+    <p id="rebuild-all-count"></p>
+    <p id="rebuild-all-error" role="alert"></p>
+    <div class="form-actions">
+      <button type="submit" class="primary">REBUILD SELECTED</button>
+      <button type="button" class="action" id="rebuild-all-cancel">CANCEL</button>
+    </div>
+  </form>
+</dialog>
+
 <main id="main">
   <section id="new-song">
     <h2>NEW SONG</h2>
     <form id="song-form">
-      <div class="pair">
-        <label class="field"><span>Title</span><input name="title" required></label>
-        <label class="field"><span>Artist</span><input name="artist" required></label>
-      </div>
-      <label class="field"><span>Lyrics</span><textarea name="lyrics" required></textarea></label>
-      <details>
-        <summary>Advanced</summary>
-        <div class="stack">
+      <div class="song-form-grid">
+        <div class="song-form-main">
+          <div class="pair">
+            <label class="field"><span>Title</span><input name="title" required></label>
+            <label class="field"><span>Artist</span><input name="artist" required></label>
+          </div>
           <label class="field"><span>YouTube URL</span><input name="youtube_url"></label>
           <label class="field"><span>Video file</span><input type="file" name="video"></label>
           <p class="keep-note" data-keep="video" hidden></p>
-          <div class="pair">
-            <label class="field"><span>Genre</span><input name="genre"></label>
-            <label class="field"><span>Year</span><input name="year" type="number"></label>
-          </div>
-          <div class="pair">
-            <label class="field"><span>Language</span><input name="language"></label>
-            <label class="field"><span>BPM override</span><input name="bpm" type="number" step="any"></label>
-          </div>
-          <label class="field"><span>Cover image</span><input type="file" name="cover"></label>
-          <p class="keep-note" data-keep="cover" hidden></p>
+          <label class="field" id="restart-field" hidden>
+            <span>Restart from</span>
+            <select name="force_from"></select>
+          </label>
+          <details>
+            <summary>Advanced</summary>
+            <div class="stack">
+              <div class="pair">
+                <label class="field"><span>Genre</span><input name="genre"></label>
+                <label class="field"><span>Year</span><input name="year" type="number"></label>
+              </div>
+              <div class="pair">
+                <label class="field"><span>Language</span><input name="language"></label>
+                <label class="field"><span>BPM override</span><input name="bpm" type="number" step="any"></label>
+              </div>
+              <label class="field"><span>Cover image</span><input type="file" name="cover"></label>
+              <p class="keep-note" data-keep="cover" hidden></p>
+            </div>
+          </details>
         </div>
-      </details>
+        <label class="field song-form-lyrics"><span>Lyrics</span><textarea name="lyrics" required></textarea></label>
+      </div>
       <div class="form-actions">
         <button type="submit" class="primary">CREATE SONG</button>
-        <button type="button" id="cancel-rebuild" hidden>CANCEL</button>
+        <p id="form-lock" hidden></p>
       </div>
     </form>
     <p id="form-error" role="alert"></p>
@@ -522,7 +654,11 @@ button { cursor: pointer; }
     <h3 id="review-title"></h3>
     <p id="review-lineage" hidden></p>
     <p id="review-error" class="review-error" hidden></p>
-    <div id="warnings"><p class="empty-note">no songs queued yet — nothing to review</p></div>
+    <div id="player" hidden>
+      <video id="player-video" muted playsinline preload="metadata"></video>
+      <audio id="player-media" controls preload="metadata"></audio>
+    </div>
+    <div id="lyrics-review"><p class="empty-note">no songs queued yet — nothing to review</p></div>
     <div id="output-path"></div>
     <div id="review-actions"></div>
     <details>
@@ -552,17 +688,20 @@ const nowTitle = document.getElementById("now-title");
 const stageTrack = document.getElementById("stage-track");
 const reviewActions = document.getElementById("review-actions");
 const reviewLineage = document.getElementById("review-lineage");
-const cancelRebuild = document.getElementById("cancel-rebuild");
+const createSong = document.getElementById("create-song");
+const formLock = document.getElementById("form-lock");
 const formHeading = document.querySelector("#new-song h2");
 const submitButton = form.querySelector("button[type=submit]");
 let rebuildOf = null;
+let formDirty = false;
+// set by CREATE SONG: the page is a blank sheet on purpose, so the poll must
+// not quietly select the newest song back into it
+let composing = false;
 let JOBS = [];
 let selectedId = null;
 let STAGES = [];
 let pollTimer = null;
 
-const WARN_RE = /^(\d+)\s+low-confidence notes?\s+near\s+(\d+:\d{2})–(\d+:\d{2})/;
-
 const STATE = {
   queued:  { glyph: "○", cls: "st-queued"  },
   running: { glyph: "◈", cls: "st-running" },
@@ -592,10 +731,16 @@ form.addEventListener("submit", async (e) => {
   if (!resp.ok) {
     const body = await resp.json().catch(() => ({}));
     formError.textContent = body.detail || `error: ${resp.status}`;
-    return;  // before the reset below, so a rejected submission is never retyped
+    return;
   }
   selectedId = (await resp.json()).id;
-  exitRebuild();
+  composing = false;
+  // the fields stay as submitted: the song just sent is the obvious starting
+  // point for the next one, and nothing has to be retyped to correct it. The
+  // queue's CREATE SONG button is what empties the form.
+  rebuildOf = null;
+  formDirty = false;
+  setFormMode(null, null);
   refreshJobs();
 });
 
@@ -620,7 +765,114 @@ for (const input of form.querySelectorAll('input[type="file"]')) {
   });
 }
 
-cancelRebuild.addEventListener("click", exitRebuild);
+// selecting another queue entry reloads the form, so track whether there is
+// anything of the operator's in there worth warning about first
+form.addEventListener("input", () => { formDirty = true; });
+
+// Always available, and the form is usually holding a selected song by now, so
+// this clears the whole page down to a blank sheet — fields, review, player and
+// queue selection — and brings the form back into view from wherever playback
+// scrolled the panel to. Leaving another song's review under an empty form
+// reads as though the two belong together.
+createSong.addEventListener("click", () => {
+  if (formDirty && !confirm("Discard your unsaved edits to this form?")) return;
+  composing = true;
+  selectedId = null;
+  for (const card of jobsDiv.querySelectorAll(".job")) card.removeAttribute("aria-current");
+  exitRebuild();
+  clearDetail("nothing selected");
+  document.getElementById("new-song").scrollIntoView({ block: "start", behavior: "smooth" });
+  form.elements.title.focus();
+});
+
+const rebuildAllButton = document.getElementById("rebuild-all");
+const rebuildAllNote = document.getElementById("rebuild-all-note");
+const rebuildAllDialog = document.getElementById("rebuild-all-dialog");
+const rebuildAllForm = document.getElementById("rebuild-all-form");
+const rebuildAllCount = document.getElementById("rebuild-all-count");
+const rebuildAllError = document.getElementById("rebuild-all-error");
+
+const rebuildAllList = document.getElementById("rebuild-all-list");
+const rebuildAllToggle = document.getElementById("rebuild-all-toggle");
+const rebuildAllSubmit = rebuildAllForm.querySelector("button[type=submit]");
+
+function rebuildAllBoxes() {
+  return [...rebuildAllList.querySelectorAll("input:not(:disabled)")];
+}
+
+function updateRebuildAllCount() {
+  const boxes = rebuildAllBoxes();
+  const chosen = boxes.filter(b => b.checked).length;
+  rebuildAllToggle.checked = chosen === boxes.length && chosen > 0;
+  rebuildAllToggle.indeterminate = chosen > 0 && chosen < boxes.length;
+  rebuildAllCount.textContent = chosen === 1 ? "1 song will be rebuilt."
+                                             : `${chosen} songs will be rebuilt.`;
+  // with nothing ticked no ids are sent, which the API reads as every song
+  rebuildAllSubmit.disabled = chosen === 0;
+}
+
+function rebuildAllRow(song) {
+  const busy = song.status === "queued" || song.status === "running";
+  const row = document.createElement("label");
+  row.className = "rebuild-all-row";
+  const box = document.createElement("input");
+  box.type = "checkbox";
+  box.name = "ids";
+  box.value = song.id;
+  box.checked = !busy;
+  box.disabled = busy;
+  const name = document.createElement("span");
+  name.textContent = `${song.title} · ${song.artist}`;
+  const meta = document.createElement("span");
+  meta.className = "meta";
+  const when = song.finished_at && new Date(song.finished_at * 1000).toLocaleString(
+    undefined, { dateStyle: "medium", timeStyle: "short" });
+  meta.textContent = busy ? "in progress, skipped"
+    : `${song.status === "failed" ? "failed" : song.rebuilt_from ? "rebuilt" : "built"} ${when || ""}`.trim();
+  row.append(box, name, meta);
+  return row;
+}
+
+rebuildAllButton.addEventListener("click", async () => {
+  rebuildAllError.textContent = "";
+  rebuildAllForm.reset();
+  const resp = await fetch("/api/rebuild-all");
+  const songs = resp.ok ? await resp.json() : [];
+  rebuildAllList.replaceChildren(...songs.map(rebuildAllRow));
+  updateRebuildAllCount();
+  rebuildAllDialog.showModal();
+});
+
+rebuildAllList.addEventListener("change", updateRebuildAllCount);
+rebuildAllToggle.addEventListener("change", () => {
+  for (const box of rebuildAllBoxes()) box.checked = rebuildAllToggle.checked;
+  updateRebuildAllCount();
+});
+
+document.getElementById("rebuild-all-cancel").addEventListener(
+  "click", () => rebuildAllDialog.close());
+
+rebuildAllForm.addEventListener("submit", async (e) => {
+  e.preventDefault();
+  const stage = rebuildAllForm.elements.force_from.value;
+  const resp = await fetch("/api/rebuild-all", {
+    method: "POST", body: new FormData(rebuildAllForm) });
+  if (!resp.ok) {
+    const body = await resp.json().catch(() => ({}));
+    rebuildAllError.textContent = body.detail || `error: ${resp.status}`;
+    return;
+  }
+  const { ids, skipped } = await resp.json();
+  rebuildAllDialog.close();
+  let note = `Queued ${ids.length} rebuild${ids.length === 1 ? "" : "s"} from ${stage}.`;
+  if (skipped.length) {
+    const reasons = [...new Set(skipped.map(s => s.reason))].join("; ");
+    note += ` Skipped ${skipped.length}: ${reasons}.`;
+  }
+  rebuildAllNote.textContent = note;
+  rebuildAllNote.hidden = false;
+  refreshJobs();
+});
 
 function jobCard(job) {
   const card = document.createElement("button");
@@ -695,6 +947,13 @@ function renderJobs(jobs) {
 async function loadStages() {
   const resp = await fetch("/api/stages");
   STAGES = (await resp.json()).stages;
+  // a rebuild redoes only what the edit invalidated, which cannot see a change
+  // in songtrace itself — this is how you redo a stage anyway
+  const select = form.elements.force_from;
+  select.replaceChildren(new Option("only what changed", ""),
+                         ...STAGES.map(s => new Option(s, s)));
+  rebuildAllForm.elements.force_from.replaceChildren(
+    new Option("choose a stage", ""), ...STAGES.map(s => new Option(s, s)));
 }
 
 function renderStageTrack(job) {
@@ -754,20 +1013,28 @@ async function refreshJobs() {
   const resp = await fetch("/api/jobs");
   const jobs = await resp.json();
   JOBS = jobs;
-  if (selectedId === null && jobs.length) selectedId = jobs[0].id;
+  // deliberately not via selectJob: the auto-selection on load fills the review
+  // panel but leaves the form blank, so landing on the page is still the way to
+  // start a new song. Clicking a queue entry is what loads its inputs.
+  if (!composing && selectedId === null && jobs.length) selectedId = jobs[0].id;
   renderJobs(jobs);
   renderNowBar(jobs);
   if (selectedId) refreshDetail();
-  else clearDetail();
+  else clearDetail(composing ? "nothing selected" : undefined);
   schedulePoll(jobs);
 }
 
 async function selectJob(id) {
+  // the form already holds this job; reloading it would drop edits in progress
+  const reload = id !== rebuildOf;
+  if (reload && formDirty && !confirm("Discard your unsaved edits to this form?")) return;
+  composing = false;
   selectedId = id;
   for (const card of jobsDiv.querySelectorAll(".job")) {
     if (card.dataset.id === id) card.setAttribute("aria-current", "true");
     else card.removeAttribute("aria-current");
   }
+  if (reload) await loadInputs(id, JOBS.find(j => j.id === id)?.status);
   refreshDetail();
 }
 
@@ -778,44 +1045,327 @@ function emptyNote(text) {
   return p;
 }
 
-function renderWarnings(job) {
-  const box = document.getElementById("warnings");
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+function fmtTime(t) {
+  const s = Math.round(t);
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+function missingSpanNode(span) {
+  const p = document.createElement("p");
+  p.className = "review-missing";
+  p.textContent = `♪ unmatched singing, ${fmtTime(span.start)}–${fmtTime(span.end)}`;
+  return p;
+}
+
+function pianoRoll(notes, minPitch, span, t0, t1) {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("class", "review-roll");
+  svg.setAttribute("viewBox", "0 0 100 20");
+  svg.setAttribute("preserveAspectRatio", "none");
+  const dur = Math.max(t1 - t0, 0.001);
+  for (const n of notes) {
+    const rect = document.createElementNS(SVG_NS, "rect");
+    const x = ((n.start - t0) / dur) * 100;
+    const w = Math.max(((n.end - n.start) / dur) * 100, 0.5);
+    const y = 18 - ((n.pitch - minPitch) / span) * 16;
+    rect.setAttribute("x", x.toFixed(2));
+    rect.setAttribute("width", w.toFixed(2));
+    rect.setAttribute("y", y.toFixed(2));
+    rect.setAttribute("height", "2");
+    rect.setAttribute("class", n.low_confidence ? "review-note review-note-low" : "review-note");
+    svg.append(rect);
+  }
+  return svg;
+}
+
+// Lays words out along a shared time axis (like a karaoke lyric line) so
+// each word's notes render directly beneath it instead of as one flat strip.
+function lineTimeline(words, notes, minPitch, span) {
+  const t0 = words[0].start;
+  const t1 = words[words.length - 1].end;
+  const dur = Math.max(t1 - t0, 0.001);
+  const box = document.createElement("div");
+  box.className = "review-line-timeline";
+  words.forEach((w, i) => {
+    const lane = document.createElement("div");
+    lane.className = "review-lane" + (i % 2 ? " review-lane-alt" : "");
+    lane.style.left = `${((w.start - t0) / dur) * 100}%`;
+    lane.style.width = `${Math.max(((w.end - w.start) / dur) * 100, 0.5)}%`;
+    box.append(lane);
+  });
+  const wordsRow = document.createElement("div");
+  wordsRow.className = "review-word-row";
+  for (const w of words) {
+    const label = document.createElement("span");
+    label.className = "review-word";
+    label.style.left = `${((w.start - t0) / dur) * 100}%`;
+    label.textContent = w.text;
+    wordsRow.append(label);
+  }
+  box.append(wordsRow);
+  if (notes.length) box.append(pianoRoll(notes, minPitch, span, t0, t1));
+  const playhead = document.createElement("div");
+  playhead.className = "review-playhead";
+  playhead.hidden = true;
+  box.append(playhead);
+  return box;
+}
+
+function lineNode(line, minPitch, span) {
+  const row = document.createElement("div");
+  row.className = "review-line" + (line.dropped ? " review-line-dropped" : "");
+  if (line.dropped) {
+    const text = document.createElement("span");
+    text.className = "review-line-text";
+    text.textContent = line.text;
+    row.append(text);
+    const note = document.createElement("span");
+    note.className = "review-line-note";
+    note.textContent = "not sung — dropped";
+    row.append(note);
+    return row;
+  }
+  if (line.words.length) {
+    row.append(lineTimeline(line.words, line.notes, minPitch, span));
+    return row;
+  }
+  const text = document.createElement("span");
+  text.className = "review-line-text";
+  text.textContent = line.text;
+  row.append(text);
+  if (line.notes.length) {
+    const t0 = line.notes[0].start;
+    const t1 = Math.max(...line.notes.map(n => n.end));
+    row.append(pianoRoll(line.notes, minPitch, span, t0, t1));
+  }
+  return row;
+}
+
+// What playback needs from a rendered line: the time range it was laid out
+// over, the word labels along it, and the bar that sweeps across it.
+function lineEntry(row, line) {
+  const laid = line.words.length ? line.words : line.notes;
+  if (!laid.length || line.dropped) return null;
+  const labels = [...row.querySelectorAll(".review-word")];
+  return {
+    row,
+    t0: laid[0].start,
+    t1: Math.max(...laid.map(x => x.end)),
+    words: line.words.map((w, i) => ({ el: labels[i], start: w.start, end: w.end })),
+    playhead: row.querySelector(".review-playhead"),
+  };
+}
+
+function buildLyricsReview(data) {
+  const allNotes = data.lines.flatMap(l => l.notes);
+  const pitches = allNotes.map(n => n.pitch);
+  const minPitch = pitches.length ? Math.min(...pitches) : 0;
+  const maxPitch = pitches.length ? Math.max(...pitches) : 0;
+  const span = Math.max(1, maxPitch - minPitch);
+  const spans = [...data.missing_spans].sort((a, b) => a.start - b.start);
+  const nodes = [];
+  const entries = [];
+  let spanIdx = 0;
+  for (const line of data.lines) {
+    const lineStart = line.notes.length ? Math.min(...line.notes.map(n => n.start)) : null;
+    while (spanIdx < spans.length && lineStart !== null && spans[spanIdx].start < lineStart) {
+      nodes.push(missingSpanNode(spans[spanIdx]));
+      spanIdx++;
+    }
+    const row = lineNode(line, minPitch, span);
+    const entry = lineEntry(row, line);
+    if (entry) entries.push(entry);
+    nodes.push(row);
+  }
+  while (spanIdx < spans.length) {
+    nodes.push(missingSpanNode(spans[spanIdx]));
+    spanIdx++;
+  }
+  return { nodes, entries };
+}
+
+// The song folder's own media, played against the same seconds the review was
+// built from, so the highlighted line is the one you are hearing.
+//
+// Modelled on the game: #MP3 is the audio and the clock, the video is muted
+// background slaved to it. Playing the video's own audio alongside the mp3 is
+// the same recording twice, a few frames apart, which is heard as an echo.
+const player = document.getElementById("player");
+const media = document.getElementById("player-media");
+const video = document.getElementById("player-video");
+const DRIFT = 0.25;  // seconds before the picture is worth re-seeking
+
+function slaveVideo(force) {
+  if (video.hidden || !video.getAttribute("src")) return;
+  if (force || Math.abs(video.currentTime - media.currentTime) > DRIFT) {
+    video.currentTime = media.currentTime;
+  }
+}
+
+for (const event of ["seeked", "ratechange"]) {
+  media.addEventListener(event, () => {
+    video.playbackRate = media.playbackRate;
+    slaveVideo(true);
+  });
+}
+media.addEventListener("pause", () => video.pause());
+let timeline = [];
+let activeEntry = null;
+let syncFrame = null;
+
+// the first line that has not finished yet: the one being sung, or the one
+// coming up while the track is between lines
+function entryAt(t) {
+  return timeline.find(e => t <= e.t1) ?? timeline[timeline.length - 1] ?? null;
+}
+
+function paintEntry(entry, t) {
+  for (const w of entry.words) {
+    w.el.classList.toggle("review-word-sung", t >= w.end);
+    w.el.classList.toggle("review-word-active", t >= w.start && t < w.end);
+  }
+  if (!entry.playhead) return;
+  const inside = t >= entry.t0 && t <= entry.t1;
+  entry.playhead.hidden = !inside;
+  if (inside) {
+    const frac = (t - entry.t0) / Math.max(entry.t1 - entry.t0, 0.001);
+    entry.playhead.style.left = `${frac * 100}%`;
+  }
+}
+
+function clearEntry(entry) {
+  entry.row.classList.remove("review-line-active");
+  if (entry.playhead) entry.playhead.hidden = true;
+  for (const w of entry.words) {
+    w.el.classList.remove("review-word-sung", "review-word-active");
+  }
+}
+
+function syncPlayback() {
+  const t = media.currentTime;
+  const entry = entryAt(t);
+  if (entry !== activeEntry) {
+    if (activeEntry) clearEntry(activeEntry);
+    activeEntry = entry;
+    if (entry) {
+      entry.row.classList.add("review-line-active");
+      focusActive();
+    }
+  }
+  if (entry) paintEntry(entry, t);
+}
+
+// centred so there is context either side, like a scrolling lyric sheet; only
+// while running, so it does not fight a reader who has scrolled away to look
+// at something else
+function focusActive() {
+  if (!activeEntry || media.paused) return;
+  activeEntry.row.scrollIntoView({ block: "center", behavior: "smooth" });
+}
+
+function pumpPlayback() {
+  syncPlayback();
+  slaveVideo(false);
+  syncFrame = media.paused ? null : requestAnimationFrame(pumpPlayback);
+}
+
+// timeupdate fires about four times a second, too coarse for a playhead
+media.addEventListener("play", () => {
+  if (syncFrame === null) syncFrame = requestAnimationFrame(pumpPlayback);
+  if (!video.hidden && video.getAttribute("src")) video.play().catch(() => {});
+  focusActive();  // the line may already be active from a seek while paused
+});
+for (const event of ["pause", "seeked", "loadedmetadata"]) {
+  media.addEventListener(event, syncPlayback);
+}
+
+function bindTimeline(entries) {
+  if (activeEntry) clearEntry(activeEntry);
+  activeEntry = null;
+  timeline = entries;
+  for (const entry of entries) {
+    entry.row.classList.add("review-seek");
+    entry.row.title = "click to play from here";
+    entry.row.addEventListener("click", (e) => {
+      const word = entry.words.find(w => w.el === e.target);
+      media.currentTime = word ? word.start : entry.t0;
+      if (media.paused) syncPlayback();
+    });
+  }
+}
+
+// Returns true when the folder gave us something to play. #MP3 is required —
+// it is the audio the game uses, so it is the one the review has to track.
+function setPlayerSource(job, available) {
+  const src = available?.audio ? `/api/jobs/${job.id}/media/audio` : "";
+  player.hidden = !src;
+  if (media.dataset.src === src) return !!src;
+  media.dataset.src = src;
+  if (src) media.src = src;
+  else { media.removeAttribute("src"); media.load(); }
+
+  video.hidden = !(src && available.video);
+  video.poster = available?.cover ? `/api/jobs/${job.id}/media/cover` : "";
+  if (!video.hidden) video.src = `/api/jobs/${job.id}/media/video`;
+  else { video.removeAttribute("src"); video.load(); }
+  return !!src;
+}
+
+function resetPlayer() {
+  // the 3s poll reaches here for every running job; reloading a cleared
+  // element each time would be pure churn
+  if (player.hidden && !timeline.length) return;
+  bindTimeline([]);
+  player.hidden = true;
+  media.pause();
+  video.pause();
+  media.dataset.src = "";
+  for (const el of [media, video]) {
+    el.removeAttribute("src");
+    el.removeAttribute("poster");
+    el.load();
+  }
+}
+
+async function renderLyricsReview(job) {
+  const box = document.getElementById("lyrics-review");
   if (job.status === "failed") {
+    delete box.dataset.jobId;
+    resetPlayer();
     box.replaceChildren(emptyNote("job failed — nothing to review"));
     return;
   }
   if (job.status !== "done") {
+    delete box.dataset.jobId;
+    resetPlayer();
     box.replaceChildren(emptyNote("waiting for this song to finish…"));
     return;
   }
-  if (!job.warnings.length) {
-    box.replaceChildren(emptyNote("no low-confidence regions — nothing to review"));
+  if (box.dataset.jobId === job.id) return;
+  const resp = await fetch(`/api/jobs/${job.id}/review`);
+  if (job.id !== selectedId) return;
+  if (!resp.ok) {
+    resetPlayer();
+    box.replaceChildren(emptyNote("no review data available"));
     return;
   }
-  const rows = job.warnings.map(w => {
-    const m = WARN_RE.exec(w);
-    const row = document.createElement("div");
-    row.className = "warn-row";
-    if (m) {
-      row.setAttribute("data-count", m[1]);
-      row.setAttribute("data-start", m[2]);
-      row.setAttribute("data-end", m[3]);
-      const icon = document.createElement("span");
-      icon.className = "warn-icon";
-      icon.textContent = "⚠";
-      const count = document.createElement("span");
-      count.className = "warn-count";
-      count.textContent = `${m[1]} note${m[1] === "1" ? "" : "s"}`;
-      const range = document.createElement("span");
-      range.className = "warn-range";
-      range.textContent = `${m[2]}–${m[3]}`;
-      row.append(icon, count, range);
-    } else {
-      row.textContent = w;
-    }
-    return row;
-  });
-  box.replaceChildren(...rows);
+  const data = await resp.json();
+  if (job.id !== selectedId) return;
+  box.dataset.jobId = job.id;
+  if (!data.lines.length) {
+    resetPlayer();
+    box.replaceChildren(emptyNote("no lyrics to review"));
+    return;
+  }
+  const { nodes, entries } = buildLyricsReview(data);
+  box.replaceChildren(...nodes);
+  // with nothing to play, a highlighted line and a click-to-seek cursor would
+  // both be promising something the song folder cannot deliver
+  const playable = setPlayerSource(job, data.media);
+  bindTimeline(playable ? entries : []);
+  if (playable) syncPlayback();
 }
 
 async function copyPath(path, button) {
@@ -875,40 +1425,63 @@ function renderOutputPath(job) {
   outputPathDiv.replaceChildren(wrap);
 }
 
-function clearDetail() {
+function clearDetail(why = "no songs queued yet") {
   reviewTitle.replaceChildren();
   reviewError.hidden = true;
   reviewError.textContent = "";
-  document.getElementById("warnings").replaceChildren(
-    emptyNote("no songs queued yet — nothing to review"));
+  resetPlayer();
+  // the review box, not an element that no longer exists: getting this wrong
+  // threw partway through and left the rest of the panel showing the old song
+  const box = document.getElementById("lyrics-review");
+  delete box.dataset.jobId;
+  box.replaceChildren(emptyNote(`${why} — nothing to review`));
   outputPathDiv.replaceChildren();
   reviewActions.replaceChildren();
   delete reviewActions.dataset.jobId;
   reviewLineage.replaceChildren();
   reviewLineage.hidden = true;
   delete reviewLineage.dataset.jobId;
-  detail.textContent = "no songs queued yet — nothing to log";
+  detail.textContent = `${why} — nothing to log`;
 }
 
-function setFormMode(inp) {
+// a rebuild is refused with 409 until the job settles, so the form says so
+// rather than letting the submission fail
+function setSubmitLock(status) {
+  const locked = rebuildOf !== null && (status === "queued" || status === "running");
+  submitButton.disabled = locked;
+  formLock.textContent = locked ? "editable once this run finishes" : "";
+  formLock.hidden = !locked;
+}
+
+function setFormMode(inp, status) {
   formHeading.textContent = rebuildOf ? "REBUILD" : "NEW SONG";
   submitButton.textContent = rebuildOf ? "REBUILD SONG" : "CREATE SONG";
-  cancelRebuild.hidden = !rebuildOf;
+  setSubmitLock(status);
+  // only a rebuild has stages to restart from; a new song always runs them all
+  document.getElementById("restart-field").hidden = !rebuildOf;
+  if (!rebuildOf) form.elements.force_from.value = "";
   for (const [field, key] of [["video", "video_filename"], ["cover", "cover_filename"]]) {
     const note = form.querySelector(`[data-keep="${field}"]`);
     const kept = rebuildOf && inp ? inp[key] : null;
     note.textContent = kept ? `keeping ${kept} — attach a file to replace it` : "";
     note.hidden = !kept;
   }
+  // the advanced fields carry into a rebuild whether or not the section is open,
+  // so anything actually set must not sit hidden behind a closed summary
+  form.querySelector("details").open = !!inp?.cover_filename ||
+    ["genre", "year", "language", "bpm"].some(n => form.elements[n].value);
 }
 
 function exitRebuild() {
   rebuildOf = null;
   form.reset();
-  setFormMode(null);
+  formDirty = false;
+  setFormMode(null, null);
 }
 
-async function startRebuild(id) {
+// selecting a queue entry brings its inputs back up, so a song can be adjusted
+// and rebuilt without being retyped
+async function loadInputs(id, status) {
   const resp = await fetch(`/api/jobs/${id}/input`);
   if (!resp.ok) return;
   const inp = await resp.json();
@@ -919,9 +1492,9 @@ async function startRebuild(id) {
     if (el && value !== null) el.value = value;
   }
   rebuildOf = id;
-  setFormMode(inp);
+  formDirty = false;
+  setFormMode(inp, status);
   formError.textContent = "";
-  form.elements.title.focus();
 }
 
 async function rerunJob(id) {
@@ -958,19 +1531,19 @@ async function deleteJob(id) {
     return;
   }
   if (selectedId === id) selectedId = null;
+  // the form is holding a job that no longer exists; a rebuild would 404
+  if (rebuildOf === id) exitRebuild();
   refreshJobs();
 }
 
 const ACTION_LABELS = {
   rerun: "RERUN",
-  edit: "EDIT & REBUILD",
   "rebuild-full": "REBUILD FROM SCRATCH",
   delete: "DELETE",
 };
 
 const ACTION_HANDLERS = {
   rerun: rerunJob,
-  edit: startRebuild,
   "rebuild-full": rebuildFullJob,
   delete: deleteJob,
 };
@@ -987,7 +1560,7 @@ function actionButton(action, jobId) {
 
 function renderActions(job) {
   // no controls mid-run: every endpoint answers 409 until the job settles
-  const doneActions = ["edit", "rebuild-full", "delete"];
+  const doneActions = ["rebuild-full", "delete"];
   const wanted = job.status === "failed" ? ["rerun", ...doneActions]
                : job.status === "done" ? doneActions : [];
   const shown = [...reviewActions.children].map(b => b.dataset.action);
@@ -1024,7 +1597,8 @@ async function refreshDetail() {
   reviewTitle.replaceChildren(`${job.title} `, artist);
   reviewError.hidden = !job.error;
   reviewError.textContent = job.error ?? "";
-  renderWarnings(job);
+  if (rebuildOf === job.id) setSubmitLock(job.status);
+  renderLyricsReview(job);
   renderOutputPath(job);
   renderLineage(job);
   renderActions(job);

src/songtrace/web.py

@@ -16,11 +16,15 @@ from fastapi.staticfiles import StaticFiles
 
 from . import rebuild as rebuild_policy
 from .config import Config
+from .lyrics import normalize_lyrics
 from .pipeline import (STAGE_ORDER, PipelineError, SongInput, read_warnings,
                        run_pipeline, song_slug)
+from .ultrastar import get_header, parse_ultrastar
 
 STATIC = Path(__file__).parent / "static"
 STAGE_LINE = re.compile(r"^\[(\w+)\] (?:running|cached, skipping)")
+# the song folder names its own media, exactly as the game reads it
+MEDIA_HEADERS = {"audio": "MP3", "video": "VIDEO", "cover": "COVER"}
 
 
 @dataclass
@@ -136,18 +140,18 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
 
     def _prepare_rebuild(job: Job, log) -> str | None:
         """Relocate cached work and report the stage this rebuild restarts from."""
-        if job.force_stage:
-            log(f"[rebuild] restarting from {job.force_stage} (forced rebuild from scratch)")
-            return job.force_stage
         if not job.rebuilt_from:
-            return None
+            return job.force_stage
         with lock:
             parent = jobs.get(job.rebuilt_from)
         if parent is None:
-            return None
-        force_from = rebuild_policy.plan(parent.inp, job.inp)
+            return job.force_stage
+        planned = rebuild_policy.plan(parent.inp, job.inp)
         changed = rebuild_policy.changed_fields(parent.inp, job.inp)
         rebuild_policy.relocate_work(parent.inp, job.inp, cfg)
+        # a stage the operator asked for can only widen what plan() decided,
+        # which is how "redo the packaging" reaches work nothing invalidated
+        force_from = rebuild_policy.earliest(planned, job.force_stage)
         log(f"[rebuild] restarting from {force_from or 'the first incomplete stage'}"
             f" ({', '.join(changed) if changed else 'nothing'} changed)")
         return force_from
@@ -244,6 +248,7 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
                       cover: UploadFile | None = File(None)):
         youtube_url, genre, language = (youtube_url or None, genre or None,
                                         language or None)
+        lyrics = lyrics.replace("\r\n", "\n")
         has_video = bool(video and video.filename)
         if bool(youtube_url) == has_video:
             raise HTTPException(400, "provide exactly one of youtube_url / video")
@@ -289,13 +294,20 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
                       lyrics: str = Form(...), youtube_url: str | None = Form(None),
                       genre: str | None = Form(None), year: int | None = Form(None),
                       language: str | None = Form(None), bpm: float | None = Form(None),
+                      force_from: str | None = Form(None),
                       video: UploadFile | None = File(None),
                       cover: UploadFile | None = File(None)):
         parent = _finished_job(job_id)
+        force_from = force_from or None
+        if force_from is not None and force_from not in STAGE_ORDER:
+            raise HTTPException(400, f"unknown stage {force_from!r}")
         # a cleared field arrives as "" from some clients; "" and None must not
         # look like different inputs to plan()
         youtube_url, genre, language = (youtube_url or None, genre or None,
                                         language or None)
+        # a browser submits a textarea with CRLF; without this every rebuild
+        # from the page looks like a lyrics edit and redoes the alignment
+        lyrics = lyrics.replace("\r\n", "\n")
         has_video = bool(video and video.filename)
         if youtube_url and has_video:
             raise HTTPException(400, "provide exactly one of youtube_url / video")
@@ -313,8 +325,54 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
                         youtube_url=youtube_url, video_path=video_path,
                         genre=genre, year=year, language=language,
                         cover_path=cover_path, bpm_override=bpm)
-        _require_source(parent.inp, inp, rebuild_policy.plan(parent.inp, inp))
-        return _enqueue(new_id, inp, rebuilt_from=job_id)
+        _require_source(parent.inp, inp, rebuild_policy.earliest(
+            rebuild_policy.plan(parent.inp, inp), force_from))
+        return _enqueue(new_id, inp, rebuilt_from=job_id, force_stage=force_from)
+
+    def _current_songs() -> list[Job]:
+        """The job that stands for each song now, newest first."""
+        with lock:
+            # a job that was rebuilt is history: its rebuild is the song now,
+            # possibly under another slug
+            rebuilt = {j.rebuilt_from for j in jobs.values()}
+            latest = {song_slug(j.inp): j for j in (jobs[i] for i in order)
+                      if j.id not in rebuilt}
+            position = {job_id: n for n, job_id in enumerate(order)}
+            return sorted(latest.values(), key=lambda j: position[j.id], reverse=True)
+
+    @app.get("/api/rebuild-all")
+    def rebuild_all_candidates():
+        return [{"id": j.id, "title": j.title, "artist": j.artist,
+                 "status": j.status, "rebuilt_from": j.rebuilt_from,
+                 "finished_at": j.finished_at}
+                for j in _current_songs()]
+
+    @app.post("/api/rebuild-all", status_code=201)
+    def rebuild_all(force_from: str = Form(...), ids: list[str] | None = Form(None)):
+        """Rebuild every song, or the ones in `ids`, from `force_from` on, for
+        when songtrace itself improved that stage. Each is an ordinary rebuild
+        with unchanged inputs."""
+        if force_from not in STAGE_ORDER:
+            raise HTTPException(400, f"unknown stage {force_from!r}")
+        songs = _current_songs()
+        queued, skipped = [], []
+        if ids is not None:
+            current = {j.id for j in songs}
+            skipped = [{"id": i, "reason": "no longer the current job for its song"}
+                       for i in ids if i not in current]
+            songs = [j for j in songs if j.id in set(ids)]
+        for job in songs:
+            if job.status in ("queued", "running"):
+                skipped.append({"id": job.id, "reason": "still in progress"})
+                continue
+            try:
+                _require_source(job.inp, job.inp, force_from)
+            except HTTPException as e:
+                skipped.append({"id": job.id, "reason": e.detail})
+                continue
+            queued.append(_enqueue(uuid.uuid4().hex, job.inp, rebuilt_from=job.id,
+                                   force_stage=force_from)["id"])
+        return {"ids": queued, "skipped": skipped}
 
     @app.get("/api/stages")
     def list_stages():
@@ -375,6 +433,69 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
         shutil.rmtree(cfg.work_dir / slug, ignore_errors=True)
         shutil.rmtree(cfg.output_dir / slug, ignore_errors=True)
 
+    def _resolve_media(job: Job, header: str) -> Path | None:
+        """The file a song folder's #MP3/#VIDEO/#COVER header points at."""
+        slug = song_slug(job.inp)
+        out = (cfg.output_dir / slug).resolve()
+        txt = out / f"{slug}.txt"
+        if not txt.exists():
+            return None
+        name = get_header(parse_ultrastar(txt.read_text(encoding="utf-8")), header)
+        if not name:
+            return None
+        # a header names a file in the song folder and nothing else
+        path = (out / name).resolve()
+        if path.parent != out or not path.is_file():
+            return None
+        return path
+
+    @app.get("/api/jobs/{job_id}/media/{kind}")
+    def get_media(job_id: str, kind: str):
+        header = MEDIA_HEADERS.get(kind)
+        if header is None:
+            raise HTTPException(404)
+        job = _finished_job(job_id)
+        if job.status != "done":
+            raise HTTPException(404)
+        path = _resolve_media(job, header)
+        if path is None:
+            raise HTTPException(404)
+        return FileResponse(path)
+
+    @app.get("/api/jobs/{job_id}/review")
+    def get_review(job_id: str):
+        job = _finished_job(job_id)
+        if job.status != "done":
+            raise HTTPException(404)
+        work = cfg.work_dir / song_slug(job.inp)
+        notes_file = work / "notes_sec.json"
+        if not notes_file.exists():
+            raise HTTPException(404)
+        notes_data = json.loads(notes_file.read_text())
+        meta_file = work / "align_meta.json"
+        meta = json.loads(meta_file.read_text()) if meta_file.exists() else {}
+        dropped = set(meta.get("dropped_lines", []))
+        missing_spans = [{"start": s, "end": e}
+                         for s, e in meta.get("missing_spans", [])]
+        align_file = work / "alignment.json"
+        align_rows = json.loads(align_file.read_text()) if align_file.exists() else []
+        words_by_line: dict[int, list] = {}
+        for r in align_rows:
+            words_by_line.setdefault(r["line_index"], []).append(
+                {"text": r["word"], "start": r["start"], "end": r["end"]})
+        ref = normalize_lyrics(job.inp.lyrics_text)
+        by_line: dict[int, list] = {}
+        for n in notes_data["notes"]:
+            by_line.setdefault(n["line_index"], []).append({
+                "start": n["start"], "end": n["start"] + n["duration"],
+                "pitch": n["pitch"], "low_confidence": n["low_confidence"]})
+        lines = [{"index": i, "text": " ".join(words), "dropped": i in dropped,
+                  "notes": by_line.get(i, []), "words": words_by_line.get(i, [])}
+                 for i, words in enumerate(ref.lines)]
+        media = {kind: _resolve_media(job, header) is not None
+                 for kind, header in MEDIA_HEADERS.items()}
+        return {"lines": lines, "missing_spans": missing_spans, "media": media}
+
     return app
 
 

src/songtrace/ytdlp.py

@@ -0,0 +1,185 @@
+"""The one place songtrace touches yt-dlp.
+
+YouTube breaks old yt-dlp releases faster than songtrace is released, so
+besides the copy installed with songtrace (the bundled one), newer stable
+releases are fetched from PyPI into a cache dir at runtime and tried first,
+with the bundled copy as the fallback. yt-dlp runs in a subprocess and is
+driven through its command line, its most stable interface, so a cached
+release never mixes with anything songtrace has imported.
+"""
+import importlib.metadata
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from .config import Config
+from .pipeline import PipelineError
+
+# The extras are what make YouTube work; see pyproject.toml.
+REQUIREMENT = "yt-dlp[default,curl-cffi,deno]"
+CHECK_INTERVAL = 24 * 3600
+_lock = threading.Lock()
+
+
+class YtDlpError(PipelineError):
+    pass
+
+
+def _key(version: str) -> tuple[int, ...]:
+    return tuple(int(p) for p in version.split("."))
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    # Installs hold compiled wheels, so they are only good for one Python.
+    return Path(base) / "songtrace" / f"yt-dlp-py{sys.version_info[0]}{sys.version_info[1]}"
+
+
+@dataclass(frozen=True)
+class YtDlp:
+    version: str
+    path: Path | None = None  # None for the bundled copy
+
+    def _env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        if self.path:
+            env["PYTHONPATH"] = os.pathsep.join(
+                filter(None, [str(self.path), env.get("PYTHONPATH")]))
+            env["PATH"] = os.pathsep.join(
+                [str(self.path / "bin"), env.get("PATH", "")])
+        return env
+
+    def run(self, args: list[str], log) -> None:
+        """Runs yt-dlp with `args`, passing each line it prints to `log`."""
+        proc = subprocess.Popen(
+            [sys.executable, "-P", "-m", "yt_dlp", "--ignore-config", *args],
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+            errors="replace", env=self._env())
+        last = error = ""
+        for line in proc.stdout:
+            last = line.rstrip()
+            log(last)
+            if last.startswith("ERROR:"):
+                error = last
+        if proc.wait() == 0:
+            return
+        if proc.returncode == 2:
+            raise YtDlpError(f"yt-dlp {self.version} rejected songtrace's "
+                             f"options, so it may be incompatible: {last}")
+        raise YtDlpError(error or f"yt-dlp exited with status {proc.returncode}")
+
+
+def bundled() -> YtDlp:
+    return YtDlp(importlib.metadata.version("yt-dlp"))
+
+
+def _latest_release() -> str:
+    r = httpx.get("https://pypi.org/pypi/yt-dlp/json", timeout=15,
+                  follow_redirects=True)
+    r.raise_for_status()
+    return r.json()["info"]["version"]
+
+
+def _pip_install(target: Path, version: str) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--quiet", "--no-input",
+         "--disable-pip-version-check", "--target", str(target),
+         f"{REQUIREMENT}=={version}"],
+        capture_output=True, text=True)
+    if proc.returncode:
+        raise YtDlpError(f"pip could not install yt-dlp {version}: "
+                         f"{proc.stderr.strip()[-500:]}")
+
+
+def _install(version: str, log) -> YtDlp:
+    """Installs `version` into the cache unless it is already there.
+
+    The install is checked to run before it is moved into place, so a
+    directory in the cache is always a usable yt-dlp."""
+    dest = cache_dir() / version
+    if dest.is_dir():
+        return YtDlp(version, dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    log(f"installing yt-dlp {version}")
+    tmp = Path(tempfile.mkdtemp(dir=dest.parent, prefix=".tmp-"))
+    try:
+        _pip_install(tmp, version)
+        proc = subprocess.run(
+            [sys.executable, "-P", "-m", "yt_dlp", "--version"],
+            capture_output=True, text=True, env=YtDlp(version, tmp)._env())
+        got = proc.stdout.strip()
+        if proc.returncode or _key(got) != _key(version):
+            raise YtDlpError(f"yt-dlp {version} failed its check after install: "
+                             f"{(got or proc.stderr.strip())[-500:]}")
+        try:
+            tmp.rename(dest)
+        except OSError:
+            if not dest.is_dir():
+                raise
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return YtDlp(version, dest)
+
+
+def _cached() -> list[YtDlp]:
+    root = cache_dir()
+    if not root.is_dir():
+        return []
+    found = [YtDlp(p.name, p) for p in root.iterdir()
+             if p.is_dir() and re.fullmatch(r"\d+(\.\d+)*", p.name)]
+    return sorted(found, key=lambda y: _key(y.version))
+
+
+def _newest(base: YtDlp, refresh: bool, log) -> YtDlp | None:
+    """The newest cached release newer than `base`, checking PyPI for a newer
+    one first if that has not been done for a day or `refresh` is set."""
+    marker = cache_dir() / ".checked"
+    if (refresh or not marker.exists()
+            or time.time() - marker.stat().st_mtime > CHECK_INTERVAL):
+        # Recorded even on failure, so a broken release is not reinstalled
+        # for every job; a failed download refreshes regardless.
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()
+        try:
+            latest = _latest_release()
+            if _key(latest) > _key(base.version):
+                _install(latest, log)
+        except Exception as e:
+            log(f"could not update yt-dlp: {e}")
+    newer = [y for y in _cached() if _key(y.version) > _key(base.version)]
+    for old in newer[:-1]:
+        shutil.rmtree(old.path, ignore_errors=True)
+    return newer[-1] if newer else None
+
+
+def candidates(cfg: Config, log, refresh: bool = False) -> list[YtDlp]:
+    """The yt-dlp copies to try, in order: the newest release (or the one
+    `cfg.ytdlp_version` pins), then the bundled copy."""
+    base = bundled()
+    want = cfg.ytdlp_version
+    if want == "bundled":
+        return [base]
+    with _lock:
+        if want == "auto":
+            first = _newest(base, refresh, log)
+        elif not re.fullmatch(r"\d+(\.\d+)*", want):
+            raise YtDlpError(f"ytdlp_version must be \"auto\", \"bundled\" or a "
+                             f"release such as \"2026.08.19\", not {want!r}")
+        elif _key(want) == _key(base.version):
+            first = None
+        else:
+            try:
+                first = _install(want, log)
+            except Exception as e:
+                log(f"could not install the pinned yt-dlp {want}: {e}")
+                first = None
+    return [first, base] if first else [base]

tests/fixtures/chart_crlf.txt

@@ -0,0 +1,36 @@
+#TITLE:Placeholder Chart
+#ARTIST:Test Artist
+#LANGUAGE:English
+#YEAR:2000
+#CREATOR:songtrace tests
+#GENRE:Test
+#COVER:Test Artist - Placeholder Chart [CO].jpg
+#MP3:Test Artist - Placeholder Chart.mp3
+#VIDEO:Test Artist - Placeholder Chart.mp4
+#BPM:217,98
+#GAP:4880
+#MEDLEYSTARTBEAT:113
+#MEDLEYENDBEAT:240
+: 0 3 16 ah
+: 5 3 20  ah
+: 11 3 23  la
+: 17 3 16  la
+: 22 28 15  ah
+: 51 2 16  doo
+: 54 31 16 ~
+- 95  
+F 113 3 18 la
+F 117 3 21  la
+F 121 3 21  la
+* 125 3 21  doo
+* 129 12 19 ~
+- 150
+: 155 4 12 Na
+R 160 4 0  na
+G 165 4 0  na
+: 170 6 14  la
+- 190
+: 194 3 16 La
+: 198 3 18  la
+* 202 10 20  ah
+E

tests/fixtures/chart_latin1.txt

@@ -0,0 +1,21 @@
+#TITLE:Café Placeholder
+#ARTIST:Tést Artist
+#LANGUAGE:English
+#GENRE:Test
+#YEAR:2000
+#MP3:Tést Artist - Café Placeholder.mp3
+#CREATOR:songtrace tests
+#BPM:256
+#GAP:49673
+: 0 4 2 Doo
+: 6 4 4  doo
+: 12 8 5  laé
+- 28 30
+: 32 4 0 Na
+: 38 4 -2  na
+* 44 12 -9  ah
+- 64
+F 70 4 3 La
+: 76 6 -5  la
+: 84 10 -9 ~
+E

tests/fixtures/sanctuary.txt

@@ -1,472 +0,0 @@
-#TITLE:Sanctuary
-#ARTIST:Utada Hikaru
-#LANGUAGE:English
-#YEAR:2009
-#CREATOR:Subkei
-#GENRE:J-Pop
-#COVER:Utada Hikaru - Sanctuary [CO].jpg
-#MP3:Utada Hikaru - Sanctuary.mp3
-#VIDEO:Utada Hikaru - Sanctuary.mp4
-#BPM:217,98
-#GAP:4880
-#MEDLEYSTARTBEAT:2471
-#MEDLEYENDBEAT:2990
-: 0 3 16 ah
-: 5 3 20  ah
-: 11 3 23  ah
-: 17 3 16  ah
-: 22 28 15  ah
-: 51 2 16  ah
-: 54 31 16 ~
-- 95
-F 113 3 18 wonk
-F 117 3 21  uoy
-F 121 3 21  naht
-F 125 3 21  snoit
-F 129 3 21 cef
-F 133 3 18 fa
-F 137 3 18  erom
-F 144 2 18  deen
-F 147 4 18  I
-- 180
-: 425 3 16 In
-: 429 3 21  you
-: 433 2 20 ~
-: 436 4 16 ~
-: 441 2 18  and
-: 445 4 20  I
-: 451 4 18 ~
-- 459
-: 461 3 16 there's
-: 465 3 16  a
-: 469 5 20  new
-: 475 4 23  land
-: 481 4 16 ~
-: 487 27 15 ~
-: 515 4 16 ~
-: 521 17 16 ~
-: 539 1 18 ~
-: 541 3 20 ~
-- 547
-: 549 1 16 An
-: 551 2 18 ~
-: 556 3 18 gels
-: 560 4 18  in
-: 565 7 20  flight
-: 573 2 18 ~
-- 576
-F 578 2 18 wonk
-F 581 3 21  uoy
-F 585 3 21  naht
-F 589 3 21  snoit
-F 593 3 21 cef
-F 597 3 18 fa
-F 601 3 18  erom
-F 608 2 18  deen
-F 611 3 18  I
-- 615
-: 617 1 16 My
-: 620 1 21  sanc
-: 624 2 20 tu
-: 628 4 16 a
-: 634 8 18 ry
-- 646
-: 648 3 16 my
-: 653 1 21  sanc
-: 657 2 20 tu
-: 661 3 16 a
-: 665 4 16 ry
-: 670 2 18 ~
-F 674 4 13  yeah
-- 680
-: 682 2 16 Where
-: 686 1 21  fears
-: 689 1 20 ~
-: 691 5 16 ~
-: 697 1 18  and
-* 701 4 20  lies
-* 707 4 18 ~
-- 715
-: 717 3 16 melt
-: 721 3 16  a
-: 725 4 20 way
-: 732 4 23 ~
-: 737 3 16 ~
-: 742 28 15 ~
-: 771 3 16 ~
-: 775 19 16 ~
-: 795 1 18 ~
-: 797 3 20 ~
-- 804
-: 806 1 16 Mu
-: 808 2 18 ~
-: 812 3 18 sic
-: 817 3 18  will
-: 822 7 20  tie
-: 830 2 18 ~
-- 833
-F 835 1 18 wonk
-F 837 3 21  uoy
-F 841 3 21  naht
-F 845 3 21  snoit
-F 849 3 21 cef
-F 853 3 18 fa
-F 857 3 18  erom
-F 864 2 18  deen
-F 867 3 18  I
-- 871
-: 873 2 16 What's
-: 877 1 21  left
-: 881 1 20  of
-: 884 3 16  me
-: 888 1 16 ~
-: 890 7 18 ~
-- 903
-: 905 2 16 What's
-: 909 1 21  left
-: 913 1 20  of
-: 916 3 16  me
-: 921 2 16 ~
-: 925 3 18 ~
-: 933 24 13 now?
-- 986
-: 1069 3 13 I
-: 1074 6 16  watch
-: 1082 3 16  you
-: 1087 9 18 ~
-- 1102
-: 1105 3 18 fast
-: 1109 3 20 ~
-* 1117 2 13  a
-* 1122 5 16 sleep
-: 1129 3 18 ~
-: 1133 15 16 ~
-- 1162
-: 1189 3 20 All
-: 1193 6 21 ~
-: 1201 3 18  I
-: 1205 6 20 ~
-: 1213 5 16  fear
-: 1220 20 13 ~
-- 1246
-: 1249 2 11 means
-: 1255 7 13  no
-: 1266 5 18 thing
-: 1273 41 20 ~
-- 1319
-: 1321 2 16 In
-: 1325 2 21  you
-: 1328 2 20 ~
-: 1332 3 16 ~
-: 1337 2 18  and
-: 1341 4 20  I
-: 1347 4 18 ~
-- 1355
-: 1357 3 16 there's
-: 1361 3 16  a
-* 1365 5 20  new
-: 1371 4 23  land
-: 1377 4 16 ~
-: 1383 27 15 ~
-: 1411 4 16 ~
-: 1417 17 16 ~
-: 1435 1 18 ~
-: 1437 3 20 ~
-- 1442
-: 1444 1 16 An
-: 1446 2 18 ~
-: 1452 3 18 gels
-: 1457 3 18  in
-: 1462 6 20  flight
-: 1469 2 18 ~
-- 1472
-F 1474 1 18 wonk
-F 1476 3 21  uoy
-F 1480 3 21  naht
-F 1484 3 21  snoit
-F 1488 3 21 cef
-F 1492 3 18 fa
-F 1496 3 18  erom
-F 1503 2 18  deen
-F 1506 3 18  I
-- 1511
-: 1513 1 16 My
-: 1516 1 21  sanc
-: 1520 2 20 tu
-: 1524 4 16 a
-: 1530 8 18 ry
-- 1541
-: 1543 3 16 my
-: 1548 1 21  sanc
-: 1552 2 20 tu
-: 1556 3 16 a
-: 1560 4 16 ry
-: 1565 2 18 ~
-F 1570 3 13  yeah
-- 1575
-: 1577 2 16 Where
-* 1581 1 21  fears
-* 1584 1 20 ~
-: 1586 5 16 ~
-: 1592 1 18  and
-: 1596 4 20  lies
-: 1602 4 18 ~
-- 1611
-: 1613 3 16 melt
-: 1617 3 16  a
-: 1621 4 20 way
-: 1628 4 23 ~
-: 1633 3 16 ~
-: 1638 27 15 ~
-: 1666 4 16 ~
-: 1672 18 16 ~
-: 1691 1 18 ~
-: 1693 3 20 ~
-- 1699
-: 1701 1 16 Mu
-: 1703 2 18 ~
-: 1707 3 18 sic
-: 1712 3 18  will
-: 1717 7 20  tie
-: 1725 2 18 ~
-- 1728
-F 1730 2 18 wonk
-F 1733 3 21  uoy
-F 1737 3 21  naht
-F 1741 3 21  snoit
-F 1745 3 21 cef
-F 1749 3 18 fa
-F 1753 3 18  erom
-F 1760 2 18  deen
-F 1763 3 18  I
-- 1767
-: 1769 2 16 What's
-: 1773 1 21  left
-: 1777 1 20  of
-: 1780 3 16  me
-: 1785 1 16 ~
-: 1787 7 18 ~
-- 1798
-: 1800 2 16 What's
-: 1804 1 21  left
-* 1808 1 20  of
-* 1811 3 16  me
-: 1815 1 16 ~
-: 1817 7 18 ~
-- 1831
-F 1834 2 21 snwod
-F 1837 2 20  dna
-F 1841 3 18  spu
-F 1845 3 20  y
-F 1849 3 20 nam
-F 1853 3 18  os
-- 1870
-: 1897 3 20 My
-* 1901 2 20  heart's
-: 1904 1 18  a
-: 1906 3 20  bat
-: 1910 3 21 tle
-: 1914 5 21 ground
-- 1926
-F 1929 2 16 snoit
-F 1932 6 16 om
-F 1941 2 18 e
-F 1945 2 18 ~
-F 1948 2 18  eurt
-F 1952 2 18  deen
-F 1955 2 16  I
-- 1971
-F 1987 3 18 wonk
-F 1991 3 21  uoy
-F 1995 3 21  naht
-F 1999 3 21  snoit
-F 2003 3 21 cef
-F 2007 3 18 fa
-F 2011 3 18  erom
-F 2018 2 18  deen
-F 2021 3 18  I
-- 2038
-F 2059 2 16 snoit
-F 2062 6 16 om
-F 2070 3 18 e
-F 2075 2 18 ~
-F 2078 2 18  eurt
-F 2082 2 18  deen
-F 2085 2 16 I
-- 2116
-: 2219 3 13 You
-: 2224 6 16  show
-: 2232 3 16  me
-: 2237 7 18 ~
-- 2252
-: 2255 3 18 how
-: 2259 3 20 ~
-: 2267 2 13  to
-: 2272 5 16  see
-- 2282
-* 2284 3 13 That
-* 2289 6 16  no
-* 2297 3 16 thing
-* 2302 5 18 ~
-- 2313
-: 2316 3 13 is
-: 2321 3 16  whole
-: 2325 2 15 ~
-: 2328 2 13  and
-: 2331 1 13 ~
-: 2333 2 15 ~
-- 2338
-: 2340 3 20 no
-: 2344 6 21 ~
-: 2352 3 18 ~
-: 2356 6 20 ~
-: 2364 5 16 thing
-: 2371 12 13 ~
-- 2395
-: 2399 2 11 is
-: 2403 9 13  bro
-: 2416 5 18 ken
-: 2423 41 20 ~
-- 2470
-: 2472 2 16 In
-* 2476 2 21  you
-* 2479 2 20 ~
-* 2483 3 16 ~
-: 2488 2 18  and
-: 2492 4 20  I
-: 2499 3 18 ~
-- 2506
-: 2508 3 16 There's
-: 2512 3 16  a
-: 2516 5 20  new
-: 2522 4 23  land
-: 2528 4 16 ~
-: 2534 27 15 ~
-: 2562 4 16 ~
-: 2568 17 16 ~
-: 2586 1 18 ~
-: 2588 3 20 ~
-- 2593
-: 2595 1 16 An
-: 2597 2 18 ~
-: 2603 3 18 gels
-: 2608 3 18  in
-: 2613 6 20  flight
-: 2620 2 18 ~
-- 2623
-F 2625 2 18 wonk
-F 2628 3 21  uoy
-F 2632 3 21  naht
-F 2636 3 21  snoit
-F 2640 3 21 cef
-F 2644 3 18 fa
-F 2648 3 18  erom
-F 2655 2 18  deen
-F 2658 2 18  I
-- 2661
-: 2663 2 16 My
-: 2668 1 21  sanc
-: 2672 1 20 tu
-: 2675 4 16 a
-: 2681 7 18 ry
-- 2693
-: 2695 3 16 My
-: 2700 1 21  sanc
-: 2704 2 20 tu
-: 2708 3 16 a
-: 2712 4 16 ry
-: 2717 2 18 ~
-F 2721 4 13  yeah
-- 2726
-: 2728 2 16 Where
-: 2732 1 21  fears
-: 2735 1 20 ~
-: 2737 5 16 ~
-: 2743 1 18  and
-: 2747 4 20  lies
-: 2754 3 18 ~
-- 2761
-: 2763 3 16 melt
-: 2767 3 16  a
-: 2771 4 20 way
-: 2778 4 23 ~
-: 2783 4 16 ~
-: 2789 27 15 ~
-: 2817 4 16 ~
-: 2823 17 16 ~
-: 2841 1 18 ~
-: 2843 3 20 ~
-- 2849
-: 2851 1 16 Mu
-: 2853 2 18 ~
-: 2857 3 18 sic
-* 2862 3 18  will
-* 2868 7 20  tie
-: 2877 2 18 ~
-- 2880
-F 2882 1 18 wonk
-F 2884 3 21  uoy
-F 2888 3 21  naht
-F 2892 3 21  snoit
-F 2896 3 21 cef
-F 2900 3 18 fa
-F 2904 3 18  erom
-F 2911 2 18  deen
-F 2914 2 18  I
-- 2917
-: 2919 2 16 What's
-: 2923 1 21  left
-: 2927 1 20  of
-: 2930 3 16  me
-: 2935 1 16 ~
-: 2937 7 18 ~
-- 2949
-: 2951 2 16 What's
-: 2955 1 21  left
-* 2959 1 20  of
-* 2962 3 16  me
-* 2967 2 16 ~
-: 2971 3 18 ~
-: 2979 12 13  now?
-- 3005
-: 3026 2 11 uh
-: 3029 2 13 ~
-: 3032 3 16 ~
-: 3036 8 15 ~
-: 3045 4 18 ~
-: 3051 4 16 ~
-: 3056 3 15 ~
-: 3060 3 13 ~
-- 3066
-: 3068 1 16 My
-: 3070 2 18 ~
-: 3074 12 18  fears
-- 3096
-: 3100 1 16 my
-: 3102 2 18 ~
-: 3107 3 18  lies
-: 3111 2 16 ~
-: 3114 1 13 ~
-- 3129
-* 3164 3 16 melt
-* 3169 3 16  a
-* 3173 4 20 way
-* 3179 4 23 ~
-* 3185 3 16 ~
-* 3190 27 15 ~
-* 3218 3 16 ~
-* 3223 19 16 ~
-- 3248
-: 3250 4 18 ah
-: 3256 126 20 ~
-- 3392
-F 3410 1 18 wonk
-F 3412 3 21  uoy
-F 3416 3 21  naht
-F 3420 3 21  snoit
-F 3424 3 21 cef
-F 3428 3 18 fa
-F 3432 3 18  erom
-F 3439 2 18  deen
-F 3442 3 18  I
-E

tests/fixtures/sweet_child.txt

@@ -1,494 +0,0 @@
-#TITLE:Sweet Child O´Mine
-#ARTIST:Guns N' Roses
-#LANGUAGE:English
-#GENRE:Rock
-#YEAR:1987
-#MP3:Guns N' Roses - Sweet Child O´Mine.mp3
-#COVER:Guns N' Roses - Sweet Child O´Mine.jpg
-#VIDEO:Guns N' Roses - Sweet Child O´Mine.webm
-#CREATOR:sanicsip
-#FIXER:Pacayaka
-#BPM:256
-#GAP:49673
-#VIDEOGAP:0,3
-#START:13
-#MEDLEYSTARTBEAT:1564
-#MEDLEYENDBEAT:2057
-: 0 3 8 She's
-: 5 2 8  got
-: 8 1 8  a
-: 13 2 6  smile
-: 16 8 8 ~
-: 25 1 6  that
-: 27 2 5  it
-: 32 7 6  seems
-: 41 1 8  to
-: 45 1 5  me
-: 47 5 4 ~
-: 53 1 3 ~
-- 55
-: 57 1 1 re
-: 60 7 6 minds
-: 69 2 5  me
-: 73 1 1  of
-: 76 1 1  child
-: 79 9 6 ~
-: 91 5 6 hood
-- 99
-: 101 3 6 mem
-: 105 4 5 o
-: 111 6 3 ries
-: 118 1 1 ~
-- 120
-: 122 3 1 where
-: 126 2 4  eve
-: 129 5 6 ~
-: 135 2 5 ~
-: 138 1 1 ry
-: 142 2 4 thing
-: 145 4 6 ~
-: 150 2 5  was
-: 154 1 1  as
-: 158 2 5  fresh
-: 161 4 6 ~
-: 166 3 5  as
-: 171 1 1  the
-: 174 5 6  bright
-: 181 5 6  blue
-: 190 8 6  sky
-: 200 5 5 ~
-- 222
-: 258 4 8 Now
-: 264 4 8  and
-: 271 10 8  then
-: 283 2 6  when
-: 287 2 5  I
-: 291 3 6  see
-: 295 1 5  her
-: 297 1 6 ~
-: 299 2 8 ~
-: 304 8 5  face
-- 313
-: 315 3 6 she
-: 319 3 8 ~
-: 324 3 6  takes
-: 330 2 5  me
-: 334 1 1  a
-: 338 2 3 way
-: 341 3 6 ~
-: 345 2 5  to
-: 349 3 1  that
-- 354
-: 356 3 6 spe
-: 360 3 6 cial
-: 364 2 8 ~
-: 369 1 6  place
-: 371 4 5 ~
-: 377 2 5  and
-: 381 1 6  if
-: 384 2 5  I
-: 389 3 6  stare
-: 393 2 5 ~
-: 398 3 6  too
-: 402 2 5 ~
-: 405 4 6  long
-: 410 1 5 ~
-- 415
-: 417 1 1 I'd
-: 420 1 1  prob
-: 423 1 6 a
-: 425 2 6 bly
-: 429 5 6  break
-: 436 5 6  down
-: 442 2 6  and
-* 445 1 8 ~
-: 450 7 6  cry
-: 458 8 5 ~
-- 483
-: 512 3 6 Whoah
-: 517 24 8 ~
-: 543 3 10  oh
-: 548 2 8  ooh
-: 551 3 8  whoah
-: 555 1 6 ~
-: 559 3 6  sweet
-: 563 1 5 ~
-: 567 2 5  child
-: 570 3 6 ~
-: 575 1 6  o'
-: 578 8 6  mine
-: 587 12 5 ~
-- 616
-: 643 1 6 Whoah
-: 645 11 8 ~
-: 659 7 6  oh
-: 668 7 5  oh
-: 677 2 5  oh
-: 680 3 6 ~
-: 684 3 5 ~
-: 689 5 1  sweet
-: 697 7 3  love
-: 706 2 5  of
-: 711 26 1  mine
-- 771
-: 1041 5 8 She's
-: 1048 6 8  got
-: 1056 2 6  eyes
-: 1059 7 8 ~
-: 1068 3 6  of
-: 1073 1 5  the
-: 1076 3 6  blu
-: 1080 3 6 est
-: 1084 2 8 ~
-: 1089 11 3  skies
-: 1102 5 1  as
-: 1110 5 6  if
-: 1118 7 6  they
-- 1128
-: 1130 4 6 thought
-: 1135 2 5  of
-: 1140 2 5  rain
-: 1143 4 6 ~
-: 1148 4 5 ~
-- 1162
-* 1171 4 8 I
-: 1176 2 5  hate
-: 1179 3 6 ~
-: 1184 2 6  to
-: 1187 3 5 ~
-: 1192 2 6  look
-: 1196 10 6  in
-: 1208 3 6 to
-: 1213 6 5  those
-: 1221 2 5  eyes
-: 1224 7 6 ~
-: 1233 4 6  and
-- 1239
-: 1241 4 6 see
-: 1246 1 5 ~
-: 1249 3 1  an
-: 1253 1 3  ounce
-: 1256 5 6 ~
-: 1262 1 5 ~
-: 1265 2 1  of
-: 1269 15 1  pain
-- 1294
-: 1301 3 6 Her
-: 1305 2 6  hair
-: 1308 5 8 ~
-: 1314 2 8  re
-: 1318 6 8 minds
-: 1326 4 8  me
-: 1331 3 6  of
-: 1335 2 5  a
-: 1339 6 6  warm
-: 1347 2 6  safe
-: 1350 3 8 ~
-: 1355 6 5  place
-- 1362
-: 1364 6 1 where
-: 1372 3 6  as
-: 1376 2 5 ~
-: 1380 2 1  a
-: 1384 2 5  child
-: 1387 7 6 ~
-* 1395 3 8  I'd
-: 1399 5 6  hide
-: 1405 1 5 ~
-: 1408 11 1 ~
-- 1428
-: 1431 1 6 and
-: 1433 2 8 ~
-: 1437 2 5  pray
-: 1440 3 6 ~
-: 1445 3 6  for
-: 1449 2 5  the
-: 1453 7 6  thun
-: 1461 6 6 der
-- 1471
-: 1473 4 6 and
-: 1478 2 5  the
-: 1482 1 5  rain
-: 1484 6 6 ~
-- 1491
-: 1493 1 5 to
-: 1496 8 6  qui
-: 1505 2 5 et
-: 1509 2 1 ly
-: 1514 1 5  pass
-: 1516 6 6 ~
-* 1526 2 8  me
-: 1529 5 6  by
-: 1535 1 5 ~
-: 1538 10 1 ~
-- 1558
-: 1566 3 6 Whoah
-: 1570 19 8 ~
-: 1591 3 10  oh
-: 1595 3 8  ooh
-: 1600 2 8  whoah
-: 1603 1 6 ~
-: 1607 4 6  sweet
-: 1612 1 5 ~
-: 1615 3 5  child
-: 1620 2 6 ~
-: 1623 1 6  o'
-: 1629 7 6  mine
-: 1637 11 5 ~
-- 1658
-: 1675 2 12 Whoah
-: 1678 20 13 ~
-: 1699 1 12 ~
-: 1701 5 13 ~
-: 1711 1 8  oh
-: 1713 4 10 ~
-: 1719 7 8  oh
-: 1727 3 8  oh
-: 1731 3 10 ~
-: 1736 1 8 ~
-- 1737
-: 1739 3 6 Sweet
-: 1743 1 5 ~
-: 1748 7 6  love
-* 1757 2 8  of
-: 1761 4 6  mine
-: 1766 1 5 ~
-: 1770 16 1 ~
-- 1803
-* 1829 8 8 Oh
-* 1842 4 10  oh
-* 1850 4 13  oh
-* 1858 2 13  oh
-* 1861 5 15 ~
-* 1867 1 13 ~
-- 1869
-: 1871 3 13 Sweet
-: 1875 1 10 ~
-: 1880 1 10  child
-: 1882 3 13 ~
-: 1886 1 10 ~
-: 1888 2 8  o'
-: 1892 2 8  mine
-: 1895 5 10 ~
-: 1901 2 13 ~
-: 1905 2 10 ~
-: 1909 9 8 ~
-- 1924
-: 1926 2 8 Ooh
-: 1929 4 10 ~
-: 1934 2 8 ~
-: 1937 3 5 ~
-: 1942 3 8  yeah
-: 1951 1 8  yeah
-: 1953 5 10 ~
-: 1959 2 8 ~
-- 1962
-: 1964 1 8 Ooh
-: 1966 7 10 ~
-: 1974 7 8 ~
-: 1982 7 6 ~
-: 1991 2 5  ooh
-: 1994 4 6 ~
-: 1999 1 5 ~
-- 2002
-: 2004 3 1 sweet
-: 2010 9 3  love
-: 2021 1 5  of
-: 2025 1 3  mine
-: 2027 1 5 ~
-: 2029 2 3 ~
-: 2032 25 1 ~
-- 2091
-: 3176 4 3 Where
-: 3181 3 1  do
-: 3185 2 -2  we
-: 3190 8 -4  go?
-- 3204
-: 3207 1 1 Where
-: 3209 4 3 ~
-: 3214 2 1  do
-: 3217 2 -2  we
-: 3221 6 -4  go
-: 3229 8 -6  now?
-- 3239
-: 3241 3 3 Where
-: 3245 3 1  do
-: 3249 2 -2  we
-: 3253 11 -4  go?
-- 3274
-: 3282 1 -4 Ooh
-: 3284 4 -2 ~
-: 3289 3 -4  oh
-: 3293 3 -2 ~
-: 3297 3 -4  oh
-: 3301 1 -6 ~
-- 3304
-: 3306 2 -2 Where
-: 3309 2 -4  do
-: 3312 2 -6  we
-: 3316 4 -2  go
-: 3321 4 -4 ~
-: 3326 6 -2 ~?
-- 3342
-: 3355 5 -4 Oh
-: 3362 7 -2 ~
-: 3370 2 -2  where
-: 3373 2 -2  do
-: 3376 2 -2  we
-: 3380 3 -4  go
-: 3384 1 -6 ~
-: 3387 13 -9  now?
-- 3410
-: 3430 1 -6 Where
-: 3433 1 -2 ~
-: 3435 2 -2  do
-: 3439 2 1  we
-: 3443 3 -4  go
-: 3447 8 -2 ~?
-- 3465
-: 3474 7 3 Ooh
-: 3483 12 1  oh
-: 3497 2 3  where
-: 3500 2 1  do
-: 3503 2 -2  we
-: 3507 6 -4  go
-: 3514 13 -6  now?
-- 3537
-: 3558 1 -4 ay
-: 3560 6 -2 ~
-: 3567 1 -4  ay
-: 3569 5 -2 ~
-: 3575 1 -4  ay
-: 3577 5 -2 ~
-: 3583 1 -4  ay
-: 3585 5 -2 ~
-: 3591 1 -4  ay
-: 3593 6 -2 ~
-: 3600 1 -4  ay
-: 3602 5 -2 ~
-: 3608 2 -4  ay
-: 3611 2 -2 ~
-- 3614
-: 3616 4 10 Oh
-: 3623 1 13  where
-: 3625 1 15 ~
-: 3627 3 13  do
-: 3631 3 10  we
-: 3635 6 8  go
-: 3643 5 6  now?
-- 3649
-* 3651 2 6 ah
-* 3655 2 10  ah
-* 3659 2 13  ah
-* 3663 2 10  ah
-* 3666 1 8  ah
-* 3668 2 10  ah
-* 3673 2 8  ah
-* 3676 2 6  oh
-* 3680 2 8  ah
-* 3683 1 6  oh
-- 3684
-: 3686 1 8 where
-: 3688 2 10 ~
-: 3691 2 8  do
-: 3695 2 6  we
-: 3699 1 8  go
-: 3701 11 10 ~?
-- 3719
-* 3722 2 13 ah
-* 3725 12 15 ~
-* 3738 8 13 ~
-* 3748 1 10  oh
-* 3752 2 15  where
-* 3756 2 13  do
-* 3760 2 10  we
-* 3764 7 8  go
-* 3772 10 6  now?
-- 3792
-: 3816 3 10 Where
-: 3821 2 10  do
-: 3825 2 13  we
-: 3829 1 8  go
-: 3831 4 10 ~
-: 3837 1 13 ~
-: 3841 2 10 ~
-: 3845 1 13 ~
-: 3849 1 10 ~
-: 3851 1 8 ~
-: 3853 1 10 ~
-: 3855 1 8 ~
-: 3857 1 10 ~
-: 3859 1 8 ~
-: 3861 2 10 ~
-: 3865 2 8 ~
-: 3868 3 6 ~
-: 3872 3 8 ~
-: 3876 2 6 ~?
-- 3879
-: 3881 2 10 where
-: 3884 1 8  do
-: 3886 1 10 ~
-: 3888 2 10  we
-: 3892 3 8  go
-: 3897 1 6 ~
-: 3901 11 3  now?
-- 3922
-: 3943 1 8 Where
-: 3945 2 10 ~
-: 3949 2 8  do
-: 3953 2 6  we
-: 3957 2 10  go
-: 3960 2 8 ~
-: 3963 10 10 ~?
-- 3983
-: 3990 8 10 Whoah
-: 4000 3 13 ~
-: 4004 3 10 ~
-: 4008 3 10  where
-: 4012 3 13  do
-: 4017 2 10  we
-: 4021 5 8  go
-: 4028 10 6  now?
-- 4039
-* 4041 3 15 no
-* 4046 3 13  no
-* 4051 4 10  no
-* 4057 3 9  no
-* 4062 3 8  no
-* 4067 3 6  no
-* 4072 9 3  no
-- 4087
-: 4090 3 8 sweet
-: 4094 2 10 ~
-: 4101 3 8  child
-: 4105 2 6 ~
-: 4109 7 3 ~
-- 4122
-: 4124 3 10 sweet
-: 4128 1 8 ~
-: 4130 3 10 ~
-: 4137 3 10  child
-: 4142 2 13 ~
-: 4145 4 10 ~
-: 4150 2 13 ~
-: 4153 4 10 ~
-: 4158 1 8 ~
-: 4160 2 10 ~
-: 4163 2 8 ~
-: 4166 3 6 ~
-: 4171 2 10 ~
-: 4175 2 13 ~
-: 4179 3 10 ~
-: 4183 4 13 ~
-: 4188 4 15 ~
-: 4194 2 13 ~
-: 4199 1 10 ~
-- 4200
-: 4202 1 8 o'
-: 4204 2 10 ~
-: 4208 2 8  mine
-: 4211 2 6 ~
-: 4214 46 3 ~
-: 4262 33 1 ~
-: 4297 49 3 ~
-E

tests/test_acquire.py

@@ -24,7 +24,7 @@ def test_local_video(tmp_path, monkeypatch):
     assert any("audio.wav" in str(a[-1]) for a in calls)
 
 def test_youtube(tmp_path, monkeypatch):
-    def fake_dl(url, dest):
+    def fake_dl(url, dest, cfg, log):
         video = dest / "source_video.webm"
         video.write_bytes(b"v")
         thumb = dest / "source_video.jpg"
@@ -83,3 +83,120 @@ def test_classify_picks_largest_video_when_multiple(tmp_path):
     (tmp_path / "source_video.mp4").write_bytes(b"much larger contents here")
     video, _ = acquire._classify_downloads(tmp_path)
     assert video.name == "source_video.mp4"
+
+def test_classify_ignores_partials_left_by_a_failed_attempt(tmp_path):
+    (tmp_path / "source_video.webm").write_bytes(b"v")
+    (tmp_path / "source_video.f137.mp4.part").write_bytes(b"a much bigger partial")
+    (tmp_path / "source_video.f251.webm.ytdl").write_bytes(b"resume state")
+    video, _ = acquire._classify_downloads(tmp_path)
+    assert video.name == "source_video.webm"
+
+def test_ydl_args_default_client_adds_no_player_client(tmp_path):
+    cfg = Config(whisper_url="http://x/v1")
+    args = acquire._ydl_args(cfg, tmp_path, "default", "https://yt/x")
+    assert "--extractor-args" not in args
+    assert "--retries" in args and "--fragment-retries" in args
+    assert args[-2:] == ["--", "https://yt/x"]
+
+def test_ydl_args_named_client_pot_provider_and_cookies(tmp_path):
+    cfg = Config(whisper_url="http://x/v1",
+                 ytdlp_pot_provider_url="http://pot:4416",
+                 ytdlp_cookies=tmp_path / "cookies.txt",
+                 ytdlp_impersonate="chrome")
+    args = acquire._ydl_args(cfg, tmp_path, "tv", "https://yt/x")
+    joined = " ".join(args)
+    assert "--extractor-args youtube:player_client=tv" in joined
+    assert ("--extractor-args youtubepot-bgutilhttp:base_url=http://pot:4416"
+            in joined)
+    assert f"--cookies {tmp_path / 'cookies.txt'}" in joined
+    assert "--impersonate chrome" in joined
+
+def test_ydl_args_parse_with_real_yt_dlp(tmp_path):
+    """Every option songtrace passes must exist in the bundled yt-dlp."""
+    import pytest
+    pytest.importorskip("yt_dlp")
+    from yt_dlp import parse_options
+    cfg = Config(whisper_url="http://x/v1", ytdlp_pot_provider_url="http://p:1",
+                 ytdlp_cookies=tmp_path / "c.txt")
+    parse_options(acquire._ydl_args(cfg, tmp_path, "tv", "https://yt/x"))
+
+class FakeYtDlp:
+    def __init__(self, version, behaviour, seen):
+        self.version, self._behaviour, self._seen = version, behaviour, seen
+    def run(self, args, log):
+        client = next((a for a in args if a.startswith("youtube:")), None)
+        self._seen.append((self.version, client))
+        self._behaviour(self.version, client)
+
+def _fake_candidates(monkeypatch, behaviour, versions=("2026.09.01", "2026.08.19"),
+                     refreshed=None):
+    """Stub ytdlp.candidates; `refreshed` is what a refresh turns up."""
+    seen = []
+    def candidates(cfg, log, refresh=False):
+        vs = refreshed if refresh and refreshed else versions
+        return [FakeYtDlp(v, behaviour, seen) for v in vs]
+    monkeypatch.setattr(acquire.ytdlp, "candidates", candidates)
+    return seen
+
+def test_download_falls_through_to_the_next_client(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if client is None:
+            raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default", "tv"])
+    logged = []
+    video, thumb = acquire.download_youtube("https://yt/x", tmp_path, cfg,
+                                            logged.append)
+    assert video.name == "source_video.webm"
+    assert thumb is None
+    assert seen == [("2026.09.01", None),
+                    ("2026.09.01", "youtube:player_client=tv")]
+    assert any("403" in m for m in logged)
+
+def test_download_falls_back_to_the_bundled_copy(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if version == "2026.09.01":
+            raise YtDlpError("rejected songtrace's options")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default"])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert [v for v, _ in seen] == ["2026.09.01", "2026.08.19"]
+
+def test_download_retries_with_a_release_found_after_failing(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if version != "2026.10.01":
+            raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour,
+                            refreshed=("2026.10.01", "2026.08.19"))
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default"])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert [v for v, _ in seen] == ["2026.09.01", "2026.08.19", "2026.10.01"]
+
+def test_download_reports_versions_and_clients_when_all_fail(tmp_path, monkeypatch):
+    import pytest
+    from songtrace.pipeline import PipelineError
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default", "tv"])
+    with pytest.raises(PipelineError) as e:
+        acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert "2026.09.01, 2026.08.19" in str(e.value)
+    assert "default, tv" in str(e.value)
+    assert "403" in str(e.value)
+    assert len(seen) == 4
+
+def test_download_with_no_configured_clients_still_tries_default(tmp_path, monkeypatch):
+    seen = _fake_candidates(
+        monkeypatch,
+        lambda v, c: (tmp_path / "source_video.mp4").write_bytes(b"v"))
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=[])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert seen == [("2026.09.01", None)]

tests/test_align.py

@@ -1,13 +1,25 @@
 import json
 
+import numpy as np
 import pytest
+import soundfile as sf
 
 from songtrace.config import Config
 from songtrace.lyrics import normalize_lyrics
 from songtrace.pipeline import Ctx, PipelineError, SongInput
 from songtrace.stages import align
+from songtrace.whisper_client import TranscriptSegment
 
-LYRICS = "she's got a smile\nthat it seems to me"
+REAL_UNTRANSCRIBED_SINGING = align.untranscribed_singing
+
+
+@pytest.fixture(autouse=True)
+def no_untranscribed_singing(monkeypatch):
+    """The tests have no vocals.wav; those about missed singing set their own."""
+    monkeypatch.setattr(align, "untranscribed_singing", lambda vocals, segments: [])
+
+
+LYRICS = "it's one two three\nfour five six seven eight"
 
 
 def make_ctx(tmp_path, lyrics=LYRICS, transcript=None):
@@ -15,7 +27,7 @@ def make_ctx(tmp_path, lyrics=LYRICS, transcript=None):
     work.mkdir(exist_ok=True)
     if transcript is None:
         transcript = [{"start": 1.0, "end": 4.0,
-                       "text": "she's got a smile that it seems to me"}]
+                       "text": "it's one two three four five six seven eight"}]
     (work / "transcript.json").write_text(json.dumps(transcript))
     inp = SongInput(title="T", artist="A", lyrics_text=lyrics)
     return Ctx(inp=inp, cfg=Config(whisper_url="u", device="cpu"),
@@ -49,7 +61,7 @@ def check_invariants(rows, lyrics):
 def test_alignment_covers_all_words(tmp_path, monkeypatch):
     rows = run_align(tmp_path, monkeypatch)
     assert [r["word"] for r in rows] == \
-        ["she's", "got", "a", "smile", "that", "it", "seems", "to", "me"]
+        ["it's", "one", "two", "three", "four", "five", "six", "seven", "eight"]
     assert rows[0]["line_index"] == 0 and rows[-1]["line_index"] == 1
     starts = [r["start"] for r in rows]
     assert starts == sorted(starts)
@@ -63,18 +75,18 @@ def test_mismatched_lyrics_fail(tmp_path, monkeypatch):
 
 
 def test_unalignable_word_interpolated(tmp_path, monkeypatch):
-    lyrics = "she's got ... smile\nthat it seems to me"
+    lyrics = "it's one ... three\nfour five six seven eight"
     rows = run_align(tmp_path, monkeypatch, lyrics)
     dots = next(r for r in rows if r["word"] == "...")
     assert dots["score"] == 0.0
-    prev = next(r for r in rows if r["word"] == "got")
-    nxt = next(r for r in rows if r["word"] == "smile")
+    prev = next(r for r in rows if r["word"] == "one")
+    nxt = next(r for r in rows if r["word"] == "three")
     assert prev["end"] <= dots["start"] <= dots["end"] <= nxt["start"] + 1e-6
     check_invariants(rows, lyrics)
 
 
 def test_leading_unalignable_word(tmp_path, monkeypatch):
-    lyrics = "... got a smile\nthat it seems to me"
+    lyrics = "... one two three\nfour five six seven eight"
     rows = run_align(tmp_path, monkeypatch, lyrics)
     assert rows[0]["word"] == "..." and rows[0]["score"] == 0.0
     assert rows[0]["start"] >= 0.0
@@ -83,7 +95,7 @@ def test_leading_unalignable_word(tmp_path, monkeypatch):
 
 
 def test_trailing_unalignable_word(tmp_path, monkeypatch):
-    lyrics = "she's got a smile\nthat it seems to ..."
+    lyrics = "it's one two three\nfour five six seven ..."
     rows = run_align(tmp_path, monkeypatch, lyrics)
     assert rows[-1]["word"] == "..." and rows[-1]["score"] == 0.0
     assert rows[-2]["end"] <= rows[-1]["start"]
@@ -91,7 +103,7 @@ def test_trailing_unalignable_word(tmp_path, monkeypatch):
 
 
 def test_consecutive_unalignable_words(tmp_path, monkeypatch):
-    lyrics = "she's got ... ... smile\nthat it seems to me"
+    lyrics = "it's one ... ... three\nfour five six seven eight"
     rows = run_align(tmp_path, monkeypatch, lyrics)
     dots = [r for r in rows if r["word"] == "..."]
     assert len(dots) == 2
@@ -113,8 +125,8 @@ def test_all_words_unalignable_in_section(tmp_path, monkeypatch):
 
 
 def test_non_chronological_transcript(tmp_path, monkeypatch):
-    transcript = [{"start": 30.0, "end": 33.0, "text": "that it seems to me"},
-                  {"start": 1.0, "end": 4.0, "text": "she's got a smile"}]
+    transcript = [{"start": 30.0, "end": 33.0, "text": "four five six seven eight"},
+                  {"start": 1.0, "end": 4.0, "text": "it's one two three"}]
     rows = run_align(tmp_path, monkeypatch, transcript=transcript)
     check_invariants(rows, LYRICS)
     assert len({r["start"] for r in rows}) == len(rows)
@@ -131,9 +143,95 @@ def test_inverted_section_does_not_collapse(tmp_path, monkeypatch):
 
 
 def test_words_split_across_sections(tmp_path, monkeypatch):
-    transcript = [{"start": 1.0, "end": 4.0, "text": "she's got a smile"},
-                  {"start": 30.0, "end": 33.0, "text": "that it seems to me"}]
+    transcript = [{"start": 1.0, "end": 4.0, "text": "it's one two three"},
+                  {"start": 30.0, "end": 33.0, "text": "four five six seven eight"}]
     rows = run_align(tmp_path, monkeypatch, transcript=transcript)
     check_invariants(rows, LYRICS)
     assert rows[3]["end"] <= 5.0
     assert rows[4]["start"] >= 29.0
+
+
+def test_align_drops_lines_never_sung(tmp_path, monkeypatch):
+    lyrics = "it's one two three\nfour five six seven eight\nnine ten eleven twelve"
+    transcript = [{"start": 1.0, "end": 4.0,
+                   "text": "it's one two three four five six seven eight"}]
+    rows = run_align(tmp_path, monkeypatch, lyrics, transcript)
+    assert {r["line_index"] for r in rows} == {0, 1}
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == [2]
+    assert meta["missing_spans"] == []
+
+
+def test_align_flags_missing_span_for_unmatched_singing(tmp_path, monkeypatch):
+    lyrics = "it's one two three\nfour five six seven eight"
+    transcript = [
+        {"start": 1.0, "end": 4.0, "text": "it's one two three four five six seven eight"},
+        {"start": 20.0, "end": 23.0, "text": "completely unrelated ad lib bridge"},
+    ]
+    run_align(tmp_path, monkeypatch, lyrics, transcript)
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == []
+    assert meta["missing_spans"] == [[19.0, 24.0]]
+
+
+def _tone(seconds, sr, level):
+    t = np.arange(int(seconds * sr)) / sr
+    return level * np.sin(2 * np.pi * 220 * t)
+
+
+def test_untranscribed_singing_finds_sung_audio_the_transcript_skips(
+        tmp_path):
+    sr = 16000
+    rng = np.random.default_rng(0)
+    audio = np.concatenate([
+        _tone(2, sr, 0.3),           # 0-2s: sung and transcribed
+        np.zeros(2 * sr),            # 2-4s: silence
+        _tone(5, sr, 0.3),           # 4-9s: sung, never transcribed
+        np.zeros(3 * sr),            # 9-12s: silence
+        _tone(1, sr, 0.3),           # 12-13s: too short to count
+        np.zeros(3 * sr),
+    ]) + 0.001 * rng.standard_normal(16 * sr)   # separation bleed
+    path = tmp_path / "vocals.wav"
+    sf.write(path, audio.astype(np.float32), sr)
+    segments = [TranscriptSegment(0.0, 2.0, "one two")]
+    spans = REAL_UNTRANSCRIBED_SINGING(path, segments)
+    assert len(spans) == 1
+    assert spans[0][0] == pytest.approx(4.0, abs=0.1)
+    assert spans[0][1] == pytest.approx(9.0, abs=0.1)
+
+
+def test_lines_whisper_missed_are_aligned_in_the_untranscribed_singing(
+        tmp_path, monkeypatch):
+    lyrics = "one two three\nfour five six\nseven eight nine"
+    transcript = [{"start": 1.0, "end": 3.0, "text": "one two three"},
+                  {"start": 40.0, "end": 42.0, "text": "seven eight nine"}]
+    monkeypatch.setattr(align, "untranscribed_singing",
+                        lambda vocals, segments: [(20.0, 26.0)])
+    rows = run_align(tmp_path, monkeypatch, lyrics, transcript)
+    check_invariants(rows, lyrics)
+    middle = [r for r in rows if r["line_index"] == 1]
+    assert all(19.0 <= r["start"] and r["end"] <= 27.0 for r in middle)
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == []
+
+
+def test_stars_bracket_each_line_and_take_no_words(tmp_path, monkeypatch):
+    lyrics = "one two\n...\nthree four"
+    transcript = [{"start": 0.0, "end": 10.0, "text": "one two three four"}]
+    seen = []
+
+    def spy(vocals_path, start, end, tokens, device):
+        seen.append(tokens)
+        # each star claims a long stretch, so a word given a star's span shows
+        spans = [(start + i, start + i + (5.0 if t == "*" else 0.5), 0.9)
+                 for i, t in enumerate(tokens)]
+        return spans
+
+    monkeypatch.setattr(align, "force_align_section", spy)
+    ctx = make_ctx(tmp_path, lyrics, transcript)
+    align.align_stage().run(ctx)
+    rows = json.loads((ctx.work / "alignment.json").read_text())
+    assert seen == [["*", "one", "two", "*", "three", "four", "*"]]
+    timed = [r for r in rows if r["word"] != "..."]
+    assert all(r["end"] - r["start"] == pytest.approx(0.5) for r in timed)
+    check_invariants(rows, lyrics)

tests/test_lyrics.py

@@ -1,22 +1,22 @@
 from songtrace.lyrics import normalize_lyrics, alignment_token
 
 RAW = """[Verse 1]
-She's got a smile
+It's one two three
 
 [Chorus]
-Whoa, sweet child o' mine
-Take me down to 7 streets
+Whoa, la la o' la
+Count me up to 7 times
 """
 
 
 def test_normalize_strips_sections_and_blanks():
     ref = normalize_lyrics(RAW)
     assert ref.lines == [
-        ["She's", "got", "a", "smile"],
-        ["Whoa,", "sweet", "child", "o'", "mine"],
-        ["Take", "me", "down", "to", "7", "streets"],
+        ["It's", "one", "two", "three"],
+        ["Whoa,", "la", "la", "o'", "la"],
+        ["Count", "me", "up", "to", "7", "times"],
     ]
-    assert ref.words[0] == "She's"
+    assert ref.words[0] == "It's"
     assert ref.word_line_index == [0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2]
 
 

tests/test_models.py

@@ -0,0 +1,129 @@
+import sys
+import types
+
+import pytest
+
+from songtrace import models
+from songtrace.stages import align, pitch
+
+
+@pytest.fixture
+def isolated_callbacks(monkeypatch):
+    """release() with only the callbacks a test registers."""
+    monkeypatch.setattr(models, "_callbacks", [])
+    return models._callbacks
+
+
+def fake_torch(available=True, initialised=True, emptied=None, reserved=None):
+    """A torch whose allocator reports `reserved` bytes, then 0 once emptied."""
+    state = {"reserved": 4 * 2 ** 20 if reserved is None else reserved}
+
+    def empty_cache():
+        emptied.append(True)
+        state["reserved"] = 0
+
+    mod = types.ModuleType("torch")
+    mod.cuda = types.SimpleNamespace(
+        is_available=lambda: available,
+        is_initialized=lambda: initialised,
+        memory_reserved=lambda: state["reserved"],
+        empty_cache=empty_cache)
+    return mod
+
+
+def test_release_without_torch_or_callbacks_does_nothing(monkeypatch,
+                                                         isolated_callbacks):
+    monkeypatch.delitem(sys.modules, "torch", raising=False)
+    assert models.release() == 0
+
+
+def test_release_runs_every_registered_callback(isolated_callbacks):
+    called = []
+    models.on_release(lambda: called.append("a"))
+    models.on_release(lambda: called.append("b"))
+    models.release()
+    assert called == ["a", "b"]
+
+
+def test_on_release_returns_the_function_so_it_works_as_a_decorator():
+    def drop():
+        pass
+    assert models.on_release(drop) is drop
+    models._callbacks.remove(drop)
+
+
+def test_release_empties_the_allocator_when_cuda_is_in_use(monkeypatch,
+                                                           isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch", fake_torch(emptied=emptied))
+    assert models.release() == 4 * 2 ** 20
+    assert emptied == [True]
+
+
+def test_release_leaves_the_allocator_alone_without_a_gpu(monkeypatch,
+                                                          isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(available=False, emptied=emptied))
+    assert models.release() == 0
+    assert emptied == []
+
+
+def test_release_does_not_initialise_cuda_just_to_clean_up(monkeypatch,
+                                                           isolated_callbacks):
+    """A run that never touched the GPU must not create a context on the way out."""
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(initialised=False, emptied=emptied))
+    assert models.release() == 0
+    assert emptied == []
+
+
+def test_align_drops_its_cached_model():
+    align._model_cache["cuda"] = object()
+    align.unload_model()
+    assert align._model_cache == {}
+
+
+def test_align_registers_its_unload():
+    assert align.unload_model in models._callbacks
+
+
+def test_pitch_drops_the_model_torchcrepe_cached(monkeypatch):
+    torchcrepe = types.ModuleType("torchcrepe")
+
+    def infer():
+        pass
+
+    infer.model = object()
+    infer.capacity = "full"
+    torchcrepe.infer = infer
+    monkeypatch.setitem(sys.modules, "torchcrepe", torchcrepe)
+    pitch.unload_model()
+    assert not hasattr(infer, "model")
+    assert not hasattr(infer, "capacity")
+
+
+def test_pitch_unload_is_fine_when_torchcrepe_was_never_imported(monkeypatch):
+    monkeypatch.delitem(sys.modules, "torchcrepe", raising=False)
+    pitch.unload_model()
+
+
+def test_pitch_unload_is_fine_when_no_model_was_cached(monkeypatch):
+    torchcrepe = types.ModuleType("torchcrepe")
+    torchcrepe.infer = lambda: None
+    monkeypatch.setitem(sys.modules, "torchcrepe", torchcrepe)
+    pitch.unload_model()
+
+
+def test_pitch_registers_its_unload():
+    assert pitch.unload_model in models._callbacks
+
+
+def test_release_reports_nothing_freed_when_the_allocator_was_already_empty(
+        monkeypatch, isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(emptied=emptied, reserved=0))
+    assert models.release() == 0
+    assert emptied == [True]

tests/test_notes.py

@@ -78,7 +78,7 @@ def test_syllabify():
     assert syllabify("reminds", "English") == ["re", "minds"]
     assert syllabify("a", "English") == ["a"]
     assert syllabify("xyzzy", None) == ["xyzzy"]
-    assert syllabify("She's", "English") == ["She's"]
+    assert syllabify("It's", "English") == ["It's"]
 
 
 def test_syllabify_preserves_word_characters():
@@ -96,12 +96,12 @@ def test_syllabify_language_without_pyphen_dict_is_not_mishandled_as_english():
 def test_build_notes_basic_line():
     times, f0, conf = flat_pitch()
     rows = [
-        {"word": "She's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
+        {"word": "It's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
         {"word": "got", "start": 1.6, "end": 2.0, "score": 0.9, "line_index": 0},
         {"word": "Now", "start": 5.0, "end": 5.5, "score": 0.9, "line_index": 1},
     ]
     notes, breaks, warnings = build_notes(rows, times, f0, conf, "English")
-    assert notes[0].text == "She's"          # line-initial: no leading space
+    assert notes[0].text == "It's"          # line-initial: no leading space
     assert notes[1].text == " got"           # mid-line: leading space
     assert notes[2].text == "Now"            # new line: no leading space
     assert len(breaks) == 1 and 2.0 <= breaks[0] <= 5.0
@@ -225,8 +225,8 @@ def test_build_notes_short_multisyllable_word_does_not_overlap():
 def test_build_notes_never_overlaps_on_dense_input():
     rng = np.random.default_rng(11)
     times = np.arange(0, 40.0, 0.01)
-    words = ["She's", "got", "a", "beautiful", "smile", "reminds", "me",
-             "everything", "I", "lost", "yesterday", "oh"]
+    words = ["We", "count", "a", "beautiful", "number", "reminds", "us",
+             "everything", "we", "listed", "yesterday", "oh"]
     for _ in range(8):
         f0 = 220.0 * 2 ** (rng.integers(0, 12, len(times)) // 3 / 12.0)
         conf = np.where(rng.random(len(times)) < 0.9, 0.9, 0.1)
@@ -244,8 +244,8 @@ def test_build_notes_starts_are_non_decreasing():
     times = np.arange(0, 12.0, 0.01)
     f0 = 220.0 * 2 ** (np.floor(times * 2) % 5 / 12.0)   # stepped melody
     conf = np.where((times % 3.0) < 2.6, 0.9, 0.1)       # unvoiced gaps
-    words = ["She's", "got", "a", "beautiful", "smile", "that",
-             "reminds", "me", "of", "everything", "I", "lost"]
+    words = ["We", "count", "a", "beautiful", "number", "that",
+             "reminds", "us", "of", "everything", "we", "list"]
     rows = []
     for i, w in enumerate(words):
         dur = 0.8 if i % 3 else 0.07       # every third word sung very fast
@@ -278,7 +278,7 @@ def test_notes_stage_writes_json(tmp_path):
     times, f0, conf = flat_pitch()
     np.savez(work / "pitch.npz", times=times, f0=f0, conf=conf)
     (work / "alignment.json").write_text(json.dumps([
-        {"word": "She's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
+        {"word": "It's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
         {"word": "gone", "start": 3.0, "end": 3.5, "score": 0.9, "line_index": 1},
     ]))
     ctx = Ctx(inp=SongInput(title="T", artist="A", lyrics_text="x", language="English"),
@@ -287,7 +287,7 @@ def test_notes_stage_writes_json(tmp_path):
     assert stage.outputs(ctx) == [work / "notes_sec.json"]
     stage.run(ctx)
     data = json.loads((work / "notes_sec.json").read_text())
-    assert [n["text"] for n in data["notes"]] == ["She's", "gone"]
+    assert [n["text"] for n in data["notes"]] == ["It's", "gone"]
     assert data["breaks"] == [2.25]
     assert data["warnings"] == []
     assert TimedNote(**data["notes"][0]).pitch == 0
@@ -295,3 +295,42 @@ def test_notes_stage_writes_json(tmp_path):
 
 def test_notes_stage_registered():
     assert "notes" in [s.name for s in all_stages()]
+
+
+def test_build_notes_keeps_matched_words_within_missing_span():
+    # A missing span covers whole Whisper segments, so it can hold matched
+    # lines alongside the unmatched singing; those lines must keep their notes.
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0},
+        {"word": "held", "start": 5.0, "end": 5.4, "score": 0.9, "line_index": 1},
+    ]
+    notes, breaks, warnings = build_notes(rows, times, f0, conf, "English",
+                                          missing_spans=[(4.5, 6.0)])
+    assert [n.text for n in notes] == ["keep", "held"]
+    assert breaks == [(1.4 + 5.0) / 2]
+    assert warnings == ["missing lyrics near 0:04–0:06"]
+
+
+def test_warnings_report_dropped_lines():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    ref_lines = [["keep"], ["the", "outro"]]
+    _, _, warnings = build_notes(rows, times, f0, conf, "English",
+                                 dropped_lines=[1], ref_lines=ref_lines)
+    assert warnings == ['1 line dropped (not sung) near "the outro"']
+
+
+def test_warnings_report_missing_spans():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    _, _, warnings = build_notes(rows, times, f0, conf, "English",
+                                 missing_spans=[(81.0, 89.5)])
+    assert warnings == ["missing lyrics near 1:21–1:29"]
+
+
+def test_notes_carry_line_index():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "hey", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 3}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert notes[0].line_index == 3

tests/test_package.py

@@ -49,19 +49,37 @@ def make_pipeline_inputs(tmp_path, cover=None):
     return inp, cfg
 
 
-def test_package_copies_compatible_video(tmp_path, monkeypatch):
-    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+def test_package_remuxes_compatible_video_without_reencoding(tmp_path, monkeypatch):
+    calls = []
+    monkeypatch.setattr(package, "ffmpeg",
+                        lambda *a: (calls.append(a), Path(a[-1]).write_bytes(b"m")))
     monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
     ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
     package.package_stage().run(ctx)
     out = tmp_path / "out" / "A - T"
     assert (out / "A - T.txt").exists()
     assert (out / "A - T.mp3").exists()
-    assert (out / "A - T.webm").read_bytes() == b"v"
+    assert (out / "A - T.webm").exists()
+    video_call = next(c for c in calls if c[-1].endswith("A - T.webm"))
+    assert "-c" in video_call and "copy" in video_call, "the video was re-encoded"
     img = Image.open(out / "A - T.jpg")
     assert img.width == img.height
 
 
+@pytest.mark.parametrize("probe,name", [(("webm", "vp9"), "A - T.webm"),
+                                        (("avi", "mpeg4"), "A - T.mp4")])
+def test_package_strips_the_videos_audio_track(tmp_path, monkeypatch, probe, name):
+    """#MP3 is the song's audio; a video that keeps its own plays as an echo."""
+    calls = []
+    monkeypatch.setattr(package, "ffmpeg",
+                        lambda *a: (calls.append(a), Path(a[-1]).write_bytes(b"m")))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: probe)
+    ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
+    package.package_stage().run(ctx)
+    video_call = next(c for c in calls if c[-1].endswith(name))
+    assert "-an" in video_call
+
+
 def test_package_reencodes_and_rewrites_video_header(tmp_path, monkeypatch):
     monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
     monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("avi", "mpeg4"))

tests/test_pipeline.py

@@ -53,3 +53,49 @@ def test_read_warnings_is_empty_without_a_notes_file(tmp_path):
 def test_read_warnings_reads_the_notes_file(tmp_path):
     (tmp_path / "notes_sec.json").write_text(json.dumps({"warnings": ["w1", "w2"]}))
     assert read_warnings(tmp_path) == ["w1", "w2"]
+
+def test_gpu_is_released_after_every_stage(tmp_path, monkeypatch):
+    """Not just at the end: a later stage may wait minutes on the Whisper server."""
+    from songtrace import models
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    stages = [fake_stage("s1", calls), fake_stage("s2", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["s1", "release", "s2", "release"]
+
+def test_gpu_is_released_when_a_stage_fails(tmp_path, monkeypatch):
+    import pytest
+    from songtrace import models
+    from songtrace.pipeline import PipelineError
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    def boom(ctx):
+        raise PipelineError("boom")
+    stages = [Stage(name="s1", outputs=lambda ctx: [ctx.work / "s1.done"], run=boom)]
+    with pytest.raises(PipelineError):
+        run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["release"]
+
+def test_a_cached_stage_does_not_pay_for_a_release(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    stages = [fake_stage("s1", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    calls.clear()
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == []
+
+def test_a_release_that_freed_memory_is_reported_in_the_log(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, lines = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: 512 * 2 ** 20)
+    run_pipeline(inp, cfg, log=lines.append, stages=[fake_stage("s1", [])])
+    assert "[s1] released 512 MiB of GPU memory" in lines
+
+def test_a_release_that_freed_nothing_stays_out_of_the_log(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, lines = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: 0)
+    run_pipeline(inp, cfg, log=lines.append, stages=[fake_stage("s1", [])])
+    assert not any("released" in line for line in lines)

tests/test_pitch.py

@@ -17,3 +17,21 @@ def test_pitch_stage_writes_npz(tmp_path, monkeypatch):
     data = np.load(work / "pitch.npz")
     assert np.allclose(data["f0"], 220.0)
     assert data["times"].shape == data["conf"].shape
+
+
+def test_mute_silence_drops_bleed_but_keeps_quiet_singing():
+    # 60 frames of singing around -30 dB, one quiet sung frame at -50 dB, and
+    # 40 frames of bleed at -60 dB: only the bleed is more than 25 dB below
+    # the song's loud level.
+    loudness = np.array([-30.0] * 60 + [-50.0] + [-60.0] * 40)
+    conf = np.full_like(loudness, 0.8)
+    pitch.mute_silence(conf, loudness)
+    assert (conf[:61] == 0.8).all()
+    assert (conf[61:] == 0.0).all()
+
+
+def test_mute_silence_is_relative_to_the_songs_level():
+    loudness = np.array([-45.0] * 60 + [-75.0] * 40)
+    conf = np.full_like(loudness, 0.8)
+    pitch.mute_silence(conf, loudness)
+    assert (conf[:60] == 0.8).all() and (conf[60:] == 0.0).all()

tests/test_rebuild.py

@@ -5,7 +5,7 @@ import pytest
 
 from songtrace.config import Config
 from songtrace.pipeline import STAGE_ORDER, PipelineError, SongInput
-from songtrace.rebuild import (FIELD_STAGE, changed_fields, plan,
+from songtrace.rebuild import (FIELD_STAGE, changed_fields, earliest, plan,
                                    relocate_work, superseded_output)
 
 
@@ -124,3 +124,14 @@ def test_superseded_output_refuses_a_path_outside_the_output_root(tmp_path):
 def test_superseded_output_refuses_the_output_root_itself(tmp_path):
     root = tmp_path / "out"
     assert superseded_output(str(root), str(root / "A - T"), root) is None
+
+
+def test_earliest_picks_the_earlier_stage():
+    assert earliest("package", "separate") == "separate"
+    assert earliest("separate", "package") == "separate"
+
+
+def test_earliest_ignores_unset_stages():
+    assert earliest(None, "grid") == "grid"
+    assert earliest("grid", None) == "grid"
+    assert earliest(None, None) is None

tests/test_transcribe.py

@@ -1,6 +1,7 @@
 from songtrace.lyrics import normalize_lyrics
 from songtrace.whisper_client import TranscriptSegment
-from songtrace.stages.transcribe import lyrics_similarity, vocal_sections
+from songtrace.stages.transcribe import (classify_lyrics_match, lyrics_similarity,
+                                         recovered_spans, vocal_sections)
 
 def seg(s, e, t=""):
     return TranscriptSegment(start=s, end=e, text=t)
@@ -18,11 +19,77 @@ def test_vocal_sections_keeps_contained_segment():
     assert sections == [(0.0, 11.0)]
 
 def test_similarity_high_for_matching_lyrics():
-    ref = normalize_lyrics("she's got a smile\nthat it seems to me")
-    segs = [seg(0, 2, "She's got a smile"), seg(2, 4, "that it seems to me")]
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(0, 2, "It's one two three"), seg(2, 4, "four five six seven eight")]
     assert lyrics_similarity(segs, ref) > 0.9
 
 def test_similarity_low_for_wrong_lyrics():
     ref = normalize_lyrics("completely different words here entirely")
-    segs = [seg(0, 2, "she's got a smile that it seems to me")]
+    segs = [seg(0, 2, "it's one two three four five six seven eight")]
     assert lyrics_similarity(segs, ref) < 0.4
+
+def test_classify_lyrics_match_flags_extra_reference_line():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight\nnine ten eleven")
+    segs = [seg(1, 4, "it's one two three four five six seven eight")]
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == [2]
+    assert missing == []
+
+def test_classify_lyrics_match_flags_unmatched_singing():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(1, 4, "it's one two three four five six seven eight"),
+            seg(20, 23, "completely unrelated ad lib bridge")]
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == []
+    assert missing == [(19.0, 24.0)]
+
+def test_classify_lyrics_match_keeps_partially_matched_lines():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    # line 1 heard with one word garbled ("five" -> "fife"): still a replace/equal
+    # match, so the line stays matched rather than dropped
+    segs = [seg(1, 4, "it's one two three four fife six seven eight")]
+    dropped, _ = classify_lyrics_match(segs, ref)
+    assert dropped == []
+
+def test_classify_lyrics_match_scopes_missing_span_to_adlib_not_whole_section():
+    # matched line and an unmatched ad-lib close enough together that
+    # vocal_sections would merge them into one section; missing_spans must
+    # stay tight around the ad-lib so the review marks the right place.
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(1, 4, "it's one two three four five six seven eight"),
+            seg(6, 8, "completely unrelated ad lib")]
+    sections = vocal_sections(segs)
+    assert sections == [(0.0, 9.0)]      # confirms the two segments do merge
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == []
+    assert missing == [(5.0, 9.0)]
+    for a, b in missing:
+        assert not (a <= 1.0 < b)        # matched line's start (1.0) untouched
+
+
+THREE_LINES = "one two three\nfour five six\nseven eight nine"
+
+
+def test_lines_whisper_missed_are_kept_when_singing_went_untranscribed():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(0, 2, "one two three"), seg(20, 22, "seven eight nine")]
+    assert classify_lyrics_match(segs, ref)[0] == [1]
+    dropped, _ = classify_lyrics_match(segs, ref, unheard=[(8.0, 14.0)])
+    assert dropped == []
+
+
+def test_untranscribed_singing_elsewhere_does_not_keep_a_line():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(0, 2, "one two three"), seg(20, 22, "seven eight nine")]
+    dropped, _ = classify_lyrics_match(segs, ref, unheard=[(30.0, 35.0)])
+    assert dropped == [1]
+
+
+def test_recovered_spans_are_the_singing_between_heard_neighbours():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(10, 12, "four five six"), seg(20, 22, "seven eight nine")]
+    unheard = [(3.0, 9.0), (14.0, 18.0), (30.0, 35.0)]
+    # line 0 comes before anything heard, so only the singing before line 1
+    # can stand in for it; the other spans have no missing line around them
+    assert recovered_spans(segs, ref, unheard) == [(3.0, 9.0)]
+    assert classify_lyrics_match(segs, ref, unheard=unheard)[0] == []

tests/test_ultrastar.py

@@ -10,8 +10,8 @@ def load(name):
     return (FIXTURES / name).read_text(encoding="utf-8", errors="replace")
 
 def test_parse_headers_and_notes():
-    song = parse_ultrastar(load("sanctuary.txt"))
-    assert get_header(song, "artist") == "Utada Hikaru"
+    song = parse_ultrastar(load("chart_crlf.txt"))
+    assert get_header(song, "artist") == "Test Artist"
     assert parse_bpm(get_header(song, "BPM")) == 217.98
     first = song.body[0]
     assert first == Note(kind=":", beat=0, length=3, pitch=16, text="ah")
@@ -19,16 +19,16 @@ def test_parse_headers_and_notes():
     assert any(n.kind == "F" for n in song.body if isinstance(n, Note))
 
 def test_note_text_keeps_leading_space():
-    song = parse_ultrastar(load("sanctuary.txt"))
+    song = parse_ultrastar(load("chart_crlf.txt"))
     notes = [n for n in song.body if isinstance(n, Note)]
     assert notes[1].text == " ah"
 
 def test_negative_pitch():
-    song = parse_ultrastar(load("sweet_child.txt"))
+    song = parse_ultrastar(load("chart_latin1.txt"))
     assert any(n.pitch == -9 for n in song.body if isinstance(n, Note))
 
 def test_round_trip():
-    for name in ("sweet_child.txt", "sanctuary.txt"):
+    for name in ("chart_latin1.txt", "chart_crlf.txt"):
         song = parse_ultrastar(load(name))
         again = parse_ultrastar(serialize_ultrastar(song))
         assert again == song

tests/test_web.py

@@ -1,4 +1,5 @@
 import io
+import json
 import re
 import shutil
 import threading
@@ -360,6 +361,32 @@ def test_index_has_required_hooks():
         assert f'name="{name}"' in html, name
 
 
+def test_video_source_fields_are_outside_advanced_details():
+    html = _index_html()
+    form_start = html.index('id="song-form"')
+    details_start = html.index("<details>", form_start)
+    before = html[form_start:details_start]
+    assert 'name="youtube_url"' in before
+    assert 'name="video"' in before
+    after = html[details_start:]
+    for name in ("genre", "year", "language", "bpm", "cover"):
+        assert f'name="{name}"' in after
+
+
+def test_song_form_lyrics_uses_a_two_column_grid():
+    css = _page_css(_index_html())
+    assert re.search(r"\.song-form-grid\s*\{[^}]*grid-template-columns:\s*1fr 1fr",
+                     css, re.S)
+
+
+def test_song_form_grid_stacks_on_narrow_screens():
+    css = _page_css(_index_html())
+    assert re.search(
+        r"@media \(max-width: 720px\)\s*\{[^}]*\.song-form-grid\s*\{[^}]*"
+        r"grid-template-columns:\s*1fr\s*;",
+        css, re.S)
+
+
 def test_index_makes_no_external_requests():
     import re as _re
     html = _index_html()
@@ -384,10 +411,53 @@ def test_index_respects_reduced_motion():
     assert "prefers-reduced-motion" in _index_html()
 
 
-def test_index_parses_warnings_with_endash():
+def test_index_has_lyrics_review_hook():
     html = _index_html()
-    assert "–" in html, "warning parser must handle the en-dash separator"
-    assert "data-start" in html and "data-end" in html
+    assert 'id="lyrics-review"' in html
+    assert 'id="warnings"' not in html
+
+
+def test_index_review_uses_svg_not_canvas():
+    html = _index_html()
+    assert "createElementNS" in html
+    assert "<canvas" not in html
+
+
+def test_index_review_fetches_review_endpoint():
+    html = _index_html()
+    assert "/review" in html
+
+
+def test_index_lyrics_review_uses_endash_for_time_ranges():
+    html = _index_html()
+    body = _fn_body(html, "missingSpanNode")
+    assert "–" in body
+
+
+def test_index_review_lays_out_words_in_time():
+    """Words must be positioned by their sung timing (percentage-based), not
+    packed as plain flow text, so notes can line up under their own word."""
+    html = _index_html()
+    body = _fn_body(html, "lineTimeline")
+    assert "review-word" in body
+    assert "style.left" in body
+
+
+def test_lyrics_review_cache_clears_on_job_status_change():
+    """Regression: switching between done/failed/running jobs must clear the
+    cache so a previously-viewed done job re-fetches when re-selected."""
+    html = _index_html()
+    body = _fn_body(html, "renderLyricsReview")
+    # The "failed" branch must clear the cache before rendering the placeholder
+    assert re.search(
+        r'if\s*\(\s*job\.status\s*===\s*"failed"\s*\)\s*\{[^}]*'
+        r'delete\s+box\.dataset\.jobId',
+        body, re.S), "failed branch must delete cache key"
+    # The "not done" (queued/running) branch must clear the cache before rendering
+    assert re.search(
+        r'if\s*\(\s*job\.status\s*!==\s*"done"\s*\)\s*\{[^}]*'
+        r'delete\s+box\.dataset\.jobId',
+        body, re.S), "not done branch must delete cache key"
 
 
 def test_index_has_copy_path_control():
@@ -514,11 +584,19 @@ def _submit_body(html):
     return html[start:html.index("\n});\n", start)]
 
 
+def _listener_body(html, prefix):
+    start = html.index(prefix)
+    return html[start:html.index("\n});\n", start)]
+
+
 def _rebuild_flaws(html):
     """Ways rebuild mode could quietly stop working."""
     flaws, submit = [], _submit_body(html)
     if "rebuildOf ?" not in submit or "/rebuild" not in submit:
         flaws.append("the form always posts to /api/jobs, so edits create a new song")
+    if "form.reset()" in submit or "exitRebuild()" in submit:
+        flaws.append("a successful submission empties the form, so correcting "
+                     "or varying the song just sent means retyping it")
 
     actions = _fn_body(html, "renderActions")
     if not re.search(r"if \(.*dataset\.jobId === job\.id.*\) return;", actions):
@@ -526,9 +604,39 @@ def _rebuild_flaws(html):
     if '"failed"' not in actions or '"done"' not in actions:
         flaws.append("the action row does not key off the job status")
 
-    start = _fn_body(html, "startRebuild")
-    if "/input" not in start or "form.elements[" not in start:
+    load = _fn_body(html, "loadInputs")
+    if "/input" not in load or "form.elements[" not in load:
         flaws.append("rebuild mode does not prefill the form from the job's input")
+
+    select = _fn_body(html, "selectJob")
+    if "loadInputs(" not in select:
+        flaws.append("selecting a queue entry does not bring its inputs back up")
+    if "formDirty" not in select or "confirm(" not in select:
+        flaws.append("selecting a queue entry discards unsaved edits without asking")
+
+    if "if (rebuildOf === id) exitRebuild();" not in _fn_body(html, "deleteJob"):
+        flaws.append("deleting the loaded job leaves the form pointed at it")
+
+    # selecting a queue entry loads it, so the sidebar button is now the only
+    # way back to a blank form
+    create = _listener_body(html, 'createSong.addEventListener("click"')
+    if "exitRebuild()" not in create:
+        flaws.append("the queue's CREATE SONG button does not clear the form")
+    if "formDirty" not in create or "confirm(" not in create:
+        flaws.append("the queue's CREATE SONG button discards edits without asking")
+    if "clearDetail(" not in create:
+        flaws.append("CREATE SONG empties the form but leaves the previous "
+                     "song's review and player sitting under it")
+    if "composing" not in create or "composing" not in _fn_body(html, "refreshJobs"):
+        flaws.append("the blank page CREATE SONG made is selected back over by "
+                     "the next poll of the queue")
+
+    mode = _fn_body(html, "setFormMode")
+    if 'querySelector("details").open' not in mode:
+        flaws.append("prefilled genre/year/language/bpm stay hidden behind the "
+                     "closed Advanced summary, so they rebuild unseen")
+    if "submitButton.disabled" not in _fn_body(html, "setSubmitLock"):
+        flaws.append("the form lets you submit a rebuild the API will answer 409")
     return flaws
 
 
@@ -561,7 +669,7 @@ def test_rebuild_full_and_delete_controls_are_wired_up():
 
 def _empty_state_flaws(html):
     refresh = _fn_body(html, "refreshJobs")
-    if "clearDetail()" not in refresh:
+    if "clearDetail(" not in refresh:
         return ["refreshJobs never resets the panel when no job is selected"]
     return []
 
@@ -570,6 +678,54 @@ def test_review_panel_resets_when_no_job_is_selected():
     assert _empty_state_flaws(_index_html()) == []
 
 
+def _playback_flaws(html):
+    """Ways the review could stop tracking the media element."""
+    flaws = []
+    source = _fn_body(html, "setPlayerSource")
+    if "media/audio" not in source:
+        flaws.append("the player is not pointed at the job's packaged audio, "
+                     "which is the file the game plays and the notes track")
+    if "media/video" not in source:
+        flaws.append("the packaged video is never shown alongside the audio")
+
+    # the mp3 and the video carry the same recording; playing both is an echo
+    if not re.search(r"<video[^>]*\bmuted\b", html):
+        flaws.append("the background video is not muted, so its own audio "
+                     "plays on top of the mp3")
+    pump = _fn_body(html, "pumpPlayback")
+    if "slaveVideo(" not in pump:
+        flaws.append("the picture is never pulled back onto the audio clock, "
+                     "so it drifts out of sync over a long song")
+
+    if "requestAnimationFrame" not in _fn_body(html, "pumpPlayback"):
+        flaws.append("sync is not driven by the frame loop, so the playhead "
+                     "steps at timeupdate's ~4Hz instead of following the audio")
+
+    if "media.paused" not in _fn_body(html, "focusActive"):
+        flaws.append("the view is scrolled even while paused, fighting a reader "
+                     "who scrolled away to look at something else")
+
+    sync = _fn_body(html, "syncPlayback")
+    if "clearEntry(" not in sync:
+        flaws.append("the line the playhead left keeps its highlight")
+    clear = _fn_body(html, "clearEntry")
+    for name in ("review-word-sung", "review-word-active", "review-line-active"):
+        if name not in clear:
+            flaws.append(f"{name} is never taken off a line the playhead left")
+
+    # every branch that gives up on rendering a review has to unload the media
+    # too, or the previous song stays loaded and playable under the new one
+    render = _fn_body(html, "renderLyricsReview")
+    if render.count("resetPlayer()") < render.count("emptyNote("):
+        flaws.append("a review the page cannot render leaves the previous "
+                     "song's media loaded in the player")
+    return flaws
+
+
+def test_review_playback_tracks_the_media_element():
+    assert _playback_flaws(_index_html()) == []
+
+
 # each mutation is a plausible regression; the checker above must reject all of them
 MUTATIONS = [
     (_focus_flaws, "queue: card moved unconditionally",
@@ -602,9 +758,52 @@ MUTATIONS = [
      'if (!confirm("Delete this song? This removes all its files and cannot be undone.")) return;',
      ""),
     (_rebuild_full_and_delete_flaws, "rebuild-full: no longer offered on a done job",
-     '["edit", "rebuild-full", "delete"]', '["edit", "delete"]'),
+     '["rebuild-full", "delete"]', '["delete"]'),
+    (_rebuild_flaws, "prefill: selecting a queue entry no longer loads its inputs",
+     "  if (reload) await loadInputs(id, JOBS.find(j => j.id === id)?.status);\n", ""),
+    (_rebuild_flaws, "prefill: unsaved edits discarded without asking",
+     '  if (reload && formDirty && !confirm("Discard your unsaved edits to this form?")) return;\n',
+     ""),
+    (_rebuild_flaws, "prefill: deleting the loaded job leaves the form pointed at it",
+     "  if (rebuildOf === id) exitRebuild();\n", ""),
+    (_rebuild_flaws, "prefill: advanced fields stay hidden behind a closed summary",
+     'form.querySelector("details").open =', "const unusedAdvancedOpen ="),
+    (_rebuild_flaws, "prefill: an in-progress job can be submitted for rebuild anyway",
+     "submitButton.disabled = locked;", ""),
+    (_rebuild_flaws, "submit: a successful submission empties the form again",
+     "  rebuildOf = null;\n  formDirty = false;\n  setFormMode(null, null);\n  refreshJobs();",
+     "  exitRebuild();\n  refreshJobs();"),
+    (_rebuild_flaws, "create: the queue button no longer clears the form",
+     "  exitRebuild();\n  clearDetail(\"nothing selected\");\n", ""),
+    (_rebuild_flaws, "create: the review is left behind under a blank form",
+     '  clearDetail("nothing selected");\n', ""),
+    (_rebuild_flaws, "create: the next poll selects a song back into the blank page",
+     "  composing = true;\n", ""),
+    (_rebuild_flaws, "create: the queue button discards edits without asking",
+     '  if (formDirty && !confirm("Discard your unsaved edits to this form?")) return;\n  composing = true;',
+     "  composing = true;"),
+    (_playback_flaws, "playback: sync falls back to the timeupdate event's ~4Hz",
+     "syncFrame = media.paused ? null : requestAnimationFrame(pumpPlayback);",
+     "syncFrame = null;"),
+    (_playback_flaws, "playback: the view is scrolled even while paused",
+     "if (!activeEntry || media.paused) return;", "if (!activeEntry) return;"),
+    (_playback_flaws, "playback: the line the playhead left keeps its highlight",
+     "    if (activeEntry) clearEntry(activeEntry);\n", ""),
+    (_playback_flaws, "playback: a word stays lit after the playhead moves on",
+     'w.el.classList.remove("review-word-sung", "review-word-active");',
+     'w.el.classList.remove("review-word-sung");'),
+    (_playback_flaws, "playback: an unrenderable review leaves the old song loaded",
+     "    resetPlayer();\n", ""),
+    (_playback_flaws, "playback: the player is not pointed at the packaged audio",
+     'const src = available?.audio ? `/api/jobs/${job.id}/media/audio` : "";',
+     'const src = "";'),
+    (_playback_flaws, "playback: the background video plays its own audio too",
+     '<video id="player-video" muted playsinline',
+     '<video id="player-video" playsinline'),
+    (_playback_flaws, "playback: the picture is never re-synced to the audio",
+     "  slaveVideo(false);\n", ""),
     (_empty_state_flaws, "empty state: clearDetail no longer wired into refreshJobs",
-     "if (selectedId) refreshDetail();\n  else clearDetail();",
+     "if (selectedId) refreshDetail();\n  else clearDetail(composing ? \"nothing selected\" : undefined);",
      "if (selectedId) refreshDetail();"),
 ]
 
@@ -635,13 +834,13 @@ def test_narrow_stage_labels_stay_in_the_accessibility_tree():
 
 def test_rebuild_mode_reuses_the_one_form():
     html = _index_html()
-    assert html.count("<form") == 1
+    assert html.count('name="lyrics"') == 1    # one song form, not a rebuild copy
     assert _rebuild_flaws(html) == []
 
 
 def test_index_has_rebuild_hooks():
     html = _index_html()
-    for hook in ("review-actions", "review-lineage", "cancel-rebuild",
+    for hook in ("review-actions", "review-lineage", "create-song",
                  'data-keep="video"', 'data-keep="cover"'):
         assert hook in html, hook
 
@@ -1176,3 +1375,480 @@ def test_discovered_jobs_are_visible_from_a_fresh_app(tmp_path):
     jobs = client2.get("/api/jobs").json()
     assert len(jobs) == 1
     assert jobs[0]["title"] == "T" and jobs[0]["status"] == "done"
+
+
+def review_runner_factory(notes, dropped_lines=None, missing_spans=None, warnings=None,
+                          words=None):
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        work = cfg.work_dir / song_slug(inp)
+        work.mkdir(parents=True, exist_ok=True)
+        (work / "notes_sec.json").write_text(json.dumps({
+            "notes": notes, "breaks": [], "warnings": warnings or []}))
+        if dropped_lines is not None or missing_spans is not None:
+            (work / "align_meta.json").write_text(json.dumps({
+                "dropped_lines": dropped_lines or [],
+                "missing_spans": missing_spans or []}))
+        if words is not None:
+            (work / "alignment.json").write_text(json.dumps(words))
+        out = cfg.output_dir / song_slug(inp)
+        out.mkdir(parents=True, exist_ok=True)
+        return PipelineResult(output_dir=out, warnings=warnings or [])
+    return runner
+
+
+def test_review_endpoint_groups_notes_by_line(tmp_path):
+    notes = [
+        {"start": 1.0, "duration": 0.4, "pitch": 0, "text": "hi",
+         "low_confidence": False, "line_index": 0},
+        {"start": 5.0, "duration": 0.3, "pitch": 2, "text": "there",
+         "low_confidence": True, "line_index": 1},
+    ]
+    client, _ = make_client(tmp_path, review_runner_factory(
+        notes, dropped_lines=[2], missing_spans=[[8.0, 9.5]]))
+    resp = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "hi\nthere\ngone",
+        "youtube_url": "http://y"})
+    job_id = resp.json()["id"]
+    wait_status(client, job_id, "done")
+    body = client.get(f"/api/jobs/{job_id}/review").json()
+    assert body["lines"] == [
+        {"index": 0, "text": "hi", "dropped": False,
+         "notes": [{"start": 1.0, "end": 1.4, "pitch": 0, "low_confidence": False}],
+         "words": []},
+        {"index": 1, "text": "there", "dropped": False,
+         "notes": [{"start": 5.0, "end": 5.3, "pitch": 2, "low_confidence": True}],
+         "words": []},
+        {"index": 2, "text": "gone", "dropped": True, "notes": [], "words": []},
+    ]
+    assert body["missing_spans"] == [{"start": 8.0, "end": 9.5}]
+
+
+def test_review_endpoint_includes_per_word_timing(tmp_path):
+    notes = [
+        {"start": 1.0, "duration": 0.4, "pitch": 0, "text": "hi",
+         "low_confidence": False, "line_index": 0},
+        {"start": 5.0, "duration": 0.3, "pitch": 2, "text": "there",
+         "low_confidence": True, "line_index": 1},
+    ]
+    words = [
+        {"word": "hi", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0},
+        {"word": "there", "start": 5.0, "end": 5.3, "score": 0.9, "line_index": 1},
+    ]
+    client, _ = make_client(tmp_path, review_runner_factory(
+        notes, dropped_lines=[2], missing_spans=[[8.0, 9.5]], words=words))
+    resp = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "hi\nthere\ngone",
+        "youtube_url": "http://y"})
+    job_id = resp.json()["id"]
+    wait_status(client, job_id, "done")
+    body = client.get(f"/api/jobs/{job_id}/review").json()
+    assert body["lines"][0]["words"] == [{"text": "hi", "start": 1.0, "end": 1.4}]
+    assert body["lines"][1]["words"] == [{"text": "there", "start": 5.0, "end": 5.3}]
+    assert body["lines"][2]["dropped"] is True
+    assert body["lines"][2]["words"] == []
+
+
+def test_review_of_a_failed_job_is_404(tmp_path):
+    def bad_runner(*a, **kw):
+        raise PipelineError("boom")
+    client, _ = make_client(tmp_path, bad_runner)
+    resp = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"})
+    job_id = resp.json()["id"]
+    wait_status(client, job_id, "failed")
+    assert client.get(f"/api/jobs/{job_id}/review").status_code == 404
+
+
+def test_review_of_a_running_job_is_409(tmp_path):
+    release = threading.Event()
+
+    def blocking(inp, cfg, log=print, force_from=None, stages=None):
+        release.wait(5)
+        return PipelineResult(output_dir=cfg.output_dir / "X")
+
+    client, _ = make_client(tmp_path, blocking)
+    resp = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"})
+    job_id = resp.json()["id"]
+    try:
+        wait_status(client, job_id, "running")
+        assert client.get(f"/api/jobs/{job_id}/review").status_code == 409
+    finally:
+        release.set()
+    wait_status(client, job_id, "done")
+
+
+def test_review_of_an_unknown_job_is_404(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    assert client.get("/api/jobs/nope/review").status_code == 404
+
+
+def test_review_missing_when_pipeline_never_wrote_notes(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/review").status_code == 404
+
+
+# --- review playback -------------------------------------------------------
+
+MEDIA_FILES = {"A - T.mp3": b"ID3audio", "A - T.mp4": b"\0\0\0\x18ftypvideo",
+               "A - T.jpg": b"\xff\xd8cover"}
+MEDIA_HEADERS = [("TITLE", "T"), ("ARTIST", "A"), ("MP3", "A - T.mp3"),
+                 ("COVER", "A - T.jpg"), ("VIDEO", "A - T.mp4")]
+
+
+def media_runner_factory(files=None, headers=None, write_txt=True):
+    """A run that leaves behind a song folder, the way package does."""
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        slug = song_slug(inp)
+        out = cfg.output_dir / slug
+        out.mkdir(parents=True, exist_ok=True)
+        for name, body in (MEDIA_FILES if files is None else files).items():
+            (out / name).write_bytes(body)
+        if write_txt:
+            rows = [f"#{k}:{v}" for k, v in
+                    (MEDIA_HEADERS if headers is None else headers)]
+            (out / f"{slug}.txt").write_text("\n".join(rows) + "\n: 0 4 0 la\nE\n",
+                                             encoding="utf-8")
+        return PipelineResult(output_dir=out)
+    return runner
+
+
+def test_media_serves_the_files_the_song_txt_names(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    for kind, name in (("audio", "A - T.mp3"), ("video", "A - T.mp4"),
+                       ("cover", "A - T.jpg")):
+        resp = client.get(f"/api/jobs/{job_id}/media/{kind}")
+        assert resp.status_code == 200, kind
+        assert resp.content == MEDIA_FILES[name], kind
+
+
+def test_media_serves_whatever_the_header_was_rewritten_to(tmp_path):
+    """package transcodes to .mp4 and rewrites #VIDEO; the extension is not fixed."""
+    files = {**MEDIA_FILES, "A - T.webm": b"transcoded"}
+    headers = [(k, "A - T.webm" if k == "VIDEO" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(files, headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/video").content == b"transcoded"
+
+
+def test_media_supports_range_requests(tmp_path):
+    """Without 206 the browser cannot seek, which is the point of the player."""
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    resp = client.get(f"/api/jobs/{job_id}/media/video", headers={"Range": "bytes=0-3"})
+    assert resp.status_code == 206
+    assert resp.headers["content-range"] == f"bytes 0-3/{len(MEDIA_FILES['A - T.mp4'])}"
+    assert resp.content == MEDIA_FILES["A - T.mp4"][:4]
+
+
+def test_media_of_an_unknown_kind_is_404(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/instrumental").status_code == 404
+
+
+def test_media_refuses_a_header_pointing_outside_the_song_folder(tmp_path):
+    secret = tmp_path / "secret.txt"
+    secret.write_text("not yours")
+    headers = [(k, "../../secret.txt" if k == "MP3" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_refuses_an_absolute_header_path(tmp_path):
+    secret = tmp_path / "secret.txt"
+    secret.write_text("not yours")
+    headers = [(k, str(secret) if k == "MP3" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_404s_when_the_named_file_is_missing(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory(files={}))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_404s_when_the_header_was_dropped(tmp_path):
+    """package strips #COVER when there is no usable cover image."""
+    headers = [(k, v) for k, v in MEDIA_HEADERS if k != "COVER"]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/cover").status_code == 404
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 200
+
+
+def test_media_404s_when_there_is_no_song_txt(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory(write_txt=False))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_of_a_failed_job_is_404(tmp_path):
+    def bad_runner(*a, **kw):
+        raise PipelineError("boom")
+    client, _ = make_client(tmp_path, bad_runner)
+    job_id = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}).json()["id"]
+    wait_status(client, job_id, "failed")
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_of_a_running_job_is_409(tmp_path):
+    release = threading.Event()
+
+    def blocking(inp, cfg, log=print, force_from=None, stages=None):
+        release.wait(5)
+        return PipelineResult(output_dir=cfg.output_dir / "X")
+
+    client, _ = make_client(tmp_path, blocking)
+    job_id = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}).json()["id"]
+    try:
+        wait_status(client, job_id, "running")
+        assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 409
+    finally:
+        release.set()
+    wait_status(client, job_id, "done")
+
+
+def test_media_of_an_unknown_job_is_404(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    assert client.get("/api/jobs/nope/media/audio").status_code == 404
+
+
+def test_review_reports_which_media_the_player_can_load(tmp_path):
+    notes = [{"start": 1.0, "duration": 0.4, "pitch": 0, "text": "hi",
+              "low_confidence": False, "line_index": 0}]
+    review = review_runner_factory(notes)
+    media = media_runner_factory(headers=[(k, v) for k, v in MEDIA_HEADERS
+                                          if k != "COVER"])
+
+    def runner(inp, cfg, **kw):
+        media(inp, cfg, **kw)
+        return review(inp, cfg, **kw)
+
+    client, _ = make_client(tmp_path, runner)
+    job_id = make_done_job(client, lyrics="hi")
+    body = client.get(f"/api/jobs/{job_id}/review").json()
+    assert body["media"] == {"audio": True, "video": True, "cover": False}
+
+
+# --- restarting a rebuild from a chosen stage ------------------------------
+
+def force_from_runner_factory(seen):
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        seen.append(force_from)
+        out = cfg.output_dir / song_slug(inp)
+        out.mkdir(parents=True, exist_ok=True)
+        return PipelineResult(output_dir=out)
+    return runner
+
+
+def rebuild_with(client, job_id, **extra):
+    data = {"title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}
+    data.update(extra)
+    return client.post(f"/api/jobs/{job_id}/rebuild", data=data)
+
+
+def test_rebuild_without_edits_restarts_from_the_stage_asked_for(tmp_path):
+    """The point of the control: a change in songtrace invalidates no field."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="package")
+    assert resp.status_code == 201
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "package"
+
+
+def test_rebuild_without_a_stage_still_plans_from_the_edit(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, lyrics="different words")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "align"
+
+
+def test_an_edit_wins_when_it_invalidates_more_than_the_stage_asked_for(tmp_path):
+    """A choice may widen what is redone, never narrow it below correctness."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, lyrics="different words",
+                        force_from="package")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "align"
+
+
+def test_the_stage_asked_for_wins_when_it_is_earlier_than_the_edit(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, title="Renamed", force_from="separate")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "separate"
+
+
+def test_rebuild_rejects_a_stage_that_is_not_in_the_pipeline(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="deechoing")
+    assert resp.status_code == 400
+    assert "deechoing" in resp.json()["detail"]
+
+
+def test_a_blank_stage_is_the_same_as_not_asking(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] is None
+
+
+def test_rebuild_from_scratch_still_restarts_at_the_first_stage(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = client.post(f"/api/jobs/{parent}/rebuild-full")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == STAGE_ORDER[0]
+
+
+def test_the_restart_control_offers_every_stage():
+    html = _index_html()
+    assert 'name="force_from"' in html
+    stages = _fn_body(html, "loadStages")
+    assert "force_from" in stages and "STAGES.map" in stages
+    mode = _fn_body(html, "setFormMode")
+    assert "restart-field" in mode, "the control is shown outside rebuild mode"
+
+
+def test_a_textareas_crlf_does_not_read_as_a_lyrics_edit(tmp_path):
+    """Browsers submit textareas with CRLF; the stored lyrics use LF."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client, lyrics="one\ntwo")
+    resp = rebuild_with(client, parent, lyrics="one\r\ntwo")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] is None, "the rebuild redid the alignment for nothing"
+    body = client.get(f"/api/jobs/{resp.json()['id']}/input").json()
+    assert body["lyrics"] == "one\ntwo"
+
+
+def test_submitting_crlf_lyrics_stores_them_with_lf(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    job_id = make_done_job(client, lyrics="one\r\ntwo")
+    assert client.get(f"/api/jobs/{job_id}/input").json()["lyrics"] == "one\ntwo"
+
+
+def test_rebuild_all_rebuilds_every_song_from_the_stage(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, capture_runner_factory(seen))
+    first = make_done_job(client, title="One")
+    second = make_done_job(client, title="Two")
+    resp = client.post("/api/rebuild-all", data={"force_from": "pitch"})
+    assert resp.status_code == 201
+    body = resp.json()
+    assert len(body["ids"]) == 2 and body["skipped"] == []
+    jobs = [wait_status(client, i, "done") for i in body["ids"]]
+    assert {j["rebuilt_from"] for j in jobs} == {first, second}
+    assert [s["force_from"] for s in seen[2:]] == ["pitch", "pitch"]
+    by_title = lambda runs: sorted((r["inp"] for r in runs), key=lambda i: i.title)
+    assert by_title(seen[2:]) == by_title(seen[:2])
+
+
+def test_rebuild_all_skips_jobs_that_were_already_rebuilt(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    parent = make_done_job(client)
+    renamed = client.post(f"/api/jobs/{parent}/rebuild",
+                          data=rebuild_form(title="Renamed")).json()["id"]
+    wait_status(client, renamed, "done")
+    body = client.post("/api/rebuild-all", data={"force_from": "notes"}).json()
+    assert len(body["ids"]) == 1
+    job = wait_status(client, body["ids"][0], "done")
+    assert job["rebuilt_from"] == renamed
+
+
+def test_rebuild_all_takes_the_latest_job_for_a_song(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    make_done_job(client)
+    latest = make_done_job(client)
+    body = client.post("/api/rebuild-all", data={"force_from": "grid"}).json()
+    assert len(body["ids"]) == 1
+    assert wait_status(client, body["ids"][0], "done")["rebuilt_from"] == latest
+
+
+def test_rebuild_all_skips_songs_in_progress(tmp_path):
+    gate = threading.Event()
+
+    def blocking_runner(inp, cfg, log=print, force_from=None, stages=None):
+        gate.wait(timeout=5)
+        return PipelineResult(output_dir=cfg.output_dir / song_slug(inp))
+
+    client, _ = make_client(tmp_path, blocking_runner)
+    try:
+        busy = client.post("/api/jobs", data={
+            "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}).json()["id"]
+        body = client.post("/api/rebuild-all", data={"force_from": "pitch"}).json()
+        assert body == {"ids": [], "skipped": [{"id": busy, "reason": "still in progress"}]}
+    finally:
+        gate.set()
+
+
+def test_rebuild_all_from_acquire_skips_a_song_whose_upload_is_gone(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    job_id = client.post("/api/jobs", data={"title": "T", "artist": "A", "lyrics": "x"},
+                         files={"video": ("v.mp4", io.BytesIO(b"data"), "video/mp4")}
+                         ).json()["id"]
+    wait_status(client, job_id, "done")
+    shutil.rmtree(tmp_path / "work" / "uploads", ignore_errors=True)
+    body = client.post("/api/rebuild-all", data={"force_from": "acquire"}).json()
+    assert body["ids"] == []
+    assert body["skipped"][0]["id"] == job_id
+    assert "upload" in body["skipped"][0]["reason"]
+
+
+def test_rebuild_all_rejects_an_unknown_stage(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    make_done_job(client)
+    assert client.post("/api/rebuild-all", data={"force_from": "nope"}).status_code == 400
+    assert client.post("/api/rebuild-all", data={}).status_code == 422
+
+
+def test_rebuild_all_lists_the_current_job_of_each_song(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    one = make_done_job(client, title="One")
+    two = make_done_job(client, title="Two")
+    rerun = client.post(f"/api/jobs/{one}/rerun").json()["id"]
+    wait_status(client, rerun, "done")
+    songs = client.get("/api/rebuild-all").json()
+    assert [(s["id"], s["title"], s["rebuilt_from"]) for s in songs] == [
+        (rerun, "One", one), (two, "Two", None)]
+    assert all(s["status"] == "done" and s["finished_at"] for s in songs)
+
+
+def test_rebuild_all_rebuilds_only_the_songs_selected(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    make_done_job(client, title="One")
+    two = make_done_job(client, title="Two")
+    resp = client.post("/api/rebuild-all", data={"force_from": "pitch", "ids": [two]})
+    body = resp.json()
+    assert len(body["ids"]) == 1 and body["skipped"] == []
+    assert wait_status(client, body["ids"][0], "done")["rebuilt_from"] == two
+
+
+def test_rebuild_all_reports_a_selected_job_that_was_since_rebuilt(tmp_path):
+    client, _ = make_client(tmp_path, capture_runner_factory([]))
+    old = make_done_job(client)
+    rerun = client.post(f"/api/jobs/{old}/rerun").json()["id"]
+    wait_status(client, rerun, "done")
+    body = client.post("/api/rebuild-all", data={"force_from": "pitch", "ids": [old]}).json()
+    assert body == {"ids": [], "skipped": [
+        {"id": old, "reason": "no longer the current job for its song"}]}

tests/test_ytdlp.py

@@ -0,0 +1,139 @@
+import os
+import time
+
+import pytest
+
+from songtrace import ytdlp
+from songtrace.config import Config
+from songtrace.ytdlp import YtDlp, YtDlpError
+
+
+def fake_package(path, version="2026.09.01", body=""):
+    """A stand-in yt_dlp that answers --version and otherwise runs `body`."""
+    pkg = path / "yt_dlp"
+    pkg.mkdir(parents=True)
+    (pkg / "__init__.py").touch()
+    (pkg / "__main__.py").write_text(
+        "import sys\n"
+        f"if '--version' in sys.argv: print({version!r}); sys.exit()\n"
+        + body)
+    return path
+
+
+@pytest.fixture
+def cache(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
+    monkeypatch.setattr(ytdlp, "bundled", lambda: YtDlp("2026.8.19"))
+    return ytdlp.cache_dir()
+
+
+@pytest.fixture
+def pypi(monkeypatch):
+    """Stubs PyPI and pip: `latest` is the newest release, `installs` logs pip."""
+    state = {"latest": "2026.9.1", "installs": []}
+    monkeypatch.setattr(ytdlp, "_latest_release", lambda: state["latest"])
+    def pip_install(target, version):
+        state["installs"].append(version)
+        fake_package(target, version)
+    monkeypatch.setattr(ytdlp, "_pip_install", pip_install)
+    return state
+
+
+def cfg(version="auto"):
+    return Config(whisper_url="http://x/v1", ytdlp_version=version)
+
+
+def test_run_uses_the_install_on_its_path_and_logs_its_output(tmp_path):
+    path = fake_package(tmp_path, body="print('[youtube] hello', sys.argv[1:])\n")
+    logged = []
+    YtDlp("2026.09.01", path).run(["--", "https://yt/x"], logged.append)
+    assert logged == ["[youtube] hello ['--ignore-config', '--', 'https://yt/x']"]
+
+
+def test_run_raises_the_error_line(tmp_path):
+    path = fake_package(tmp_path, body=(
+        "print('ERROR: HTTP Error 403: Forbidden', file=sys.stderr)\n"
+        "print('trailing noise')\nsys.exit(1)\n"))
+    with pytest.raises(YtDlpError, match="^ERROR: HTTP Error 403"):
+        YtDlp("2026.09.01", path).run([], lambda m: None)
+
+
+def test_run_flags_a_usage_error_as_incompatible(tmp_path):
+    path = fake_package(tmp_path, body=(
+        "print('error: no such option: --retries', file=sys.stderr)\n"
+        "sys.exit(2)\n"))
+    with pytest.raises(YtDlpError, match="2026.09.01 rejected.*--retries"):
+        YtDlp("2026.09.01", path).run([], lambda m: None)
+
+
+def test_auto_installs_a_newer_release_and_tries_it_first(cache, pypi):
+    found = ytdlp.candidates(cfg(), lambda m: None)
+    assert [y.version for y in found] == ["2026.9.1", "2026.8.19"]
+    assert found[0].path == cache / "2026.9.1"
+    assert not [p for p in cache.iterdir() if p.name.startswith(".tmp-")]
+
+
+def test_auto_checks_pypi_once_a_day(cache, pypi):
+    ytdlp.candidates(cfg(), lambda m: None)
+    pypi["latest"] = "2026.10.1"
+    found = ytdlp.candidates(cfg(), lambda m: None)
+    assert found[0].version == "2026.9.1"
+    found = ytdlp.candidates(cfg(), lambda m: None, refresh=True)
+    assert found[0].version == "2026.10.1"
+    assert not (cache / "2026.9.1").exists()
+    old = time.time() - ytdlp.CHECK_INTERVAL - 1
+    os.utime(cache / ".checked", (old, old))
+    pypi["latest"] = "2026.11.1"
+    assert ytdlp.candidates(cfg(), lambda m: None)[0].version == "2026.11.1"
+
+
+def test_auto_uses_only_bundled_when_it_is_newest(cache, pypi):
+    pypi["latest"] = "2026.8.19"
+    assert [y.version for y in ytdlp.candidates(cfg(), lambda m: None)] == [
+        "2026.8.19"]
+    assert pypi["installs"] == []
+
+
+def test_auto_survives_pypi_being_unreachable(cache, pypi, monkeypatch):
+    ytdlp.candidates(cfg(), lambda m: None)
+    def down():
+        raise OSError("network unreachable")
+    monkeypatch.setattr(ytdlp, "_latest_release", down)
+    logged = []
+    found = ytdlp.candidates(cfg(), logged.append, refresh=True)
+    assert [y.version for y in found] == ["2026.9.1", "2026.8.19"]
+    assert any("network unreachable" in m for m in logged)
+
+
+def test_an_install_that_fails_its_check_is_discarded(cache, pypi, monkeypatch):
+    monkeypatch.setattr(ytdlp, "_pip_install",
+                        lambda target, v: fake_package(target, "2026.1.1"))
+    logged = []
+    assert [y.version for y in ytdlp.candidates(cfg(), logged.append)] == [
+        "2026.8.19"]
+    assert any("failed its check" in m for m in logged)
+    assert list(cache.iterdir()) == [cache / ".checked"]
+
+
+def test_bundled_never_touches_pypi(cache, pypi):
+    pypi["latest"] = None
+    assert [y.version for y in ytdlp.candidates(cfg("bundled"), print)] == [
+        "2026.8.19"]
+    assert not cache.exists()
+
+
+def test_pin_installs_that_release_even_if_older(cache, pypi):
+    found = ytdlp.candidates(cfg("2026.07.01"), lambda m: None)
+    assert [y.version for y in found] == ["2026.07.01", "2026.8.19"]
+    assert pypi["installs"] == ["2026.07.01"]
+
+
+def test_pin_matching_bundled_installs_nothing(cache, pypi):
+    found = ytdlp.candidates(cfg("2026.08.19"), lambda m: None)
+    assert [y.version for y in found] == ["2026.8.19"]
+    assert pypi["installs"] == []
+
+
+def test_pin_must_be_a_release_number(cache, pypi):
+    with pytest.raises(YtDlpError, match="ytdlp_version"):
+        ytdlp.candidates(cfg("latest; rm -rf /"), lambda m: None)