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

@@ -4,8 +4,10 @@ Turn a song and its lyrics into a playable UltraStar chart.
 
 A CLI and minimal web UI that turns a song — title, artist, lyrics you supply,
 and a YouTube URL or local video file — into a playable
-[UltraStar](https://usdx.eu/format/)-format song folder for
-[Melody Mania](https://melodymania.net/), a commercial UltraStar Deluxe fork.
+[UltraStar](https://usdx.eu/format/)-format song folder. Also compatible with
+[Melody Mania](https://melodymania.org/).
+
+![Web UI](docs/images/webui.png)
 
 The pipeline:
 
@@ -29,9 +31,30 @@ output.
 **The output is a best-effort draft**, not a finished song. Every run ends by
 printing the low-confidence regions it found (e.g.
 `3 low-confidence notes near 0:42–0:47`) — open the result in an UltraStar
-editor such as [Yass](http://www.yass-hq.de/) or
+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:
@@ -40,19 +63,6 @@ Config is TOML. Resolution order:
 2. the `SONGTRACE_CONFIG` environment variable
 3. `~/.config/songtrace/config.toml`
 
-If you used this project under its former name, move your existing config once:
-
-```sh
-pip uninstall karaoke-maker    # removes the old console script
-mv ~/.config/karaoke-maker ~/.config/songtrace
-```
-
-The Docker deployment needs no config migration — the image sets
-`SONGTRACE_CONFIG` itself and the config is bind-mounted to a fixed path.
-Run `docker compose down` before upgrading (or `docker compose up -d
---remove-orphans`) since the service key changed and Compose won't replace
-the old container in place.
-
 Copy the example and fill in your Whisper server:
 
 ```sh
@@ -62,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"`
@@ -83,8 +95,6 @@ The web UI is then at `http://localhost:8000`. Downloaded model weights
 (Demucs, wav2vec2, ...) are cached under `./data` on the host so they survive
 container recreation.
 
-![Web UI](docs/images/webui.png)
-
 Run the CLI inside the container instead of the web UI:
 
 ```sh
@@ -98,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
@@ -130,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):
@@ -45,6 +46,12 @@ def song_slug(inp: SongInput) -> str:
     name = f"{inp.artist} - {inp.title}"
     return name.replace("/", "").replace("\0", "")
 
+def read_warnings(work: Path) -> list[str]:
+    notes_file = work / "notes_sec.json"
+    if not notes_file.exists():
+        return []
+    return json.loads(notes_file.read_text()).get("warnings", [])
+
 def _real_stages() -> list[Stage]:
     from . import stages
     return stages.all_stages()
@@ -68,9 +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)
-    warnings = []
-    notes_file = work / "notes_sec.json"
-    if notes_file.exists():
-        warnings = json.loads(notes_file.read_text()).get("warnings", [])
-    return PipelineResult(output_dir=cfg.output_dir / song_slug(inp), warnings=warnings)
+        # 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/web.py

@@ -1,3 +1,4 @@
+import json
 import math
 import queue
 import re
@@ -5,7 +6,7 @@ import shutil
 import threading
 import time
 import uuid
-from dataclasses import dataclass, field
+from dataclasses import asdict, dataclass, field
 from pathlib import Path
 
 from fastapi import FastAPI, File, Form, HTTPException, UploadFile
@@ -15,11 +16,15 @@ from fastapi.staticfiles import StaticFiles
 
 from . import rebuild as rebuild_policy
 from .config import Config
-from .pipeline import (STAGE_ORDER, PipelineError, SongInput, run_pipeline,
-                       song_slug)
+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
@@ -35,6 +40,7 @@ class Job:
     error: str | None = None
     inp: SongInput | None = None
     rebuilt_from: str | None = None
+    force_stage: str | None = None
     created_at: float = field(default_factory=time.time)
     started_at: float | None = None
     finished_at: float | None = None
@@ -91,6 +97,35 @@ def _cleanup_uploads(cfg: Config, job_id: str, video_path: Path | None) -> None:
             pass
 
 
+def _discover_jobs(cfg: Config) -> list[Job]:
+    discovered = []
+    if not cfg.work_dir.exists():
+        return discovered
+    for sidecar in cfg.work_dir.glob("*/input.json"):
+        try:
+            data = json.loads(sidecar.read_text())
+            for key in ("video_path", "cover_path"):
+                if data.get(key) is not None:
+                    data[key] = Path(data[key])
+            inp = SongInput(**data)
+            slug = song_slug(inp)
+            out = cfg.output_dir / slug
+            done = out.exists() and any(out.iterdir())
+            mtime = sidecar.stat().st_mtime
+            warnings = read_warnings(sidecar.parent) if done else []
+        except (OSError, ValueError, TypeError):
+            continue
+        discovered.append(Job(
+            id=uuid.uuid4().hex, title=inp.title, artist=inp.artist, inp=inp,
+            status="done" if done else "failed",
+            output_dir=str(out) if done else None,
+            warnings=warnings,
+            error=None if done else "interrupted before completion",
+            created_at=mtime, finished_at=mtime))
+    discovered.sort(key=lambda j: j.created_at)
+    return discovered
+
+
 def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
     app = FastAPI()
     app.mount("/static", StaticFiles(directory=STATIC), name="static")
@@ -99,17 +134,24 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
     lock = threading.Lock()
     todo: queue.Queue[str] = queue.Queue()
 
+    for job in _discover_jobs(cfg):
+        jobs[job.id] = job
+        order.append(job.id)
+
     def _prepare_rebuild(job: Job, log) -> str | None:
         """Relocate cached work and report the stage this rebuild restarts from."""
         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
@@ -128,6 +170,15 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
         shutil.rmtree(old, ignore_errors=True)
         log(f"[rebuild] removed superseded {old.name}")
 
+    def _write_sidecar(job: Job) -> None:
+        work = cfg.work_dir / song_slug(job.inp)
+        work.mkdir(parents=True, exist_ok=True)
+        data = asdict(job.inp)
+        for key in ("video_path", "cover_path"):
+            if data[key] is not None:
+                data[key] = str(data[key])
+        (work / "input.json").write_text(json.dumps(data))
+
     def worker():
         while True:
             job_id = todo.get()
@@ -144,6 +195,7 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
 
             try:
                 force_from = _prepare_rebuild(job, log)
+                _write_sidecar(job)
                 result = runner(job.inp, cfg, log=log, force_from=force_from)
                 with lock:
                     job.output_dir = str(result.output_dir)
@@ -164,10 +216,10 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
 
     threading.Thread(target=worker, daemon=True).start()
 
-    def _enqueue(job_id: str, inp: SongInput,
-                 rebuilt_from: str | None = None) -> dict:
+    def _enqueue(job_id: str, inp: SongInput, rebuilt_from: str | None = None,
+                 force_stage: str | None = None) -> dict:
         job = Job(id=job_id, title=inp.title, artist=inp.artist, inp=inp,
-                  rebuilt_from=rebuilt_from)
+                  rebuilt_from=rebuilt_from, force_stage=force_stage)
         with lock:
             jobs[job_id] = job
             order.append(job_id)
@@ -196,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")
@@ -216,6 +269,12 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
         parent = _finished_job(job_id)
         return _enqueue(uuid.uuid4().hex, parent.inp, rebuilt_from=job_id)
 
+    @app.post("/api/jobs/{job_id}/rebuild-full", status_code=201)
+    def rebuild_full(job_id: str):
+        parent = _finished_job(job_id)
+        return _enqueue(uuid.uuid4().hex, parent.inp, rebuilt_from=job_id,
+                        force_stage=STAGE_ORDER[0])
+
     def _require_source(parent_inp: SongInput, inp: SongInput,
                         force_from: str | None) -> None:
         """Refuse a rebuild that will rerun acquire against an upload we no longer have."""
@@ -235,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")
@@ -259,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():
@@ -303,6 +415,87 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
                 "video_filename": inp.video_path.name if inp.video_path else None,
                 "cover_filename": inp.cover_path.name if inp.cover_path else None}
 
+    @app.delete("/api/jobs/{job_id}", status_code=204)
+    def delete_job(job_id: str):
+        with lock:
+            job = jobs.get(job_id)
+            if job is None:
+                raise HTTPException(404)
+            if job.status in ("queued", "running"):
+                raise HTTPException(409, "job is still in progress")
+            slug = song_slug(job.inp)
+            if any(other.status in ("queued", "running") and song_slug(other.inp) == slug
+                   for other_id, other in jobs.items() if other_id != job_id):
+                raise HTTPException(409, "another job for this song is in progress")
+            jobs.pop(job_id, None)
+            if job_id in order:
+                order.remove(job_id)
+        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/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,11 +1,23 @@
 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
+
+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"
 
@@ -137,3 +149,89 @@ def test_words_split_across_sections(tmp_path, monkeypatch):
     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_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
@@ -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

@@ -1,7 +1,7 @@
 import json
 from pathlib import Path
 from songtrace.config import Config
-from songtrace.pipeline import SongInput, Stage, run_pipeline, song_slug
+from songtrace.pipeline import SongInput, Stage, read_warnings, run_pipeline, song_slug
 
 def make_cfg(tmp_path):
     return Config(whisper_url="http://x/v1", output_dir=tmp_path / "out",
@@ -46,3 +46,56 @@ def test_warnings_surfaced(tmp_path):
     st = Stage(name="n", outputs=lambda ctx: [ctx.work / "n.done"], run=run)
     result = run_pipeline(inp, cfg, log=lambda m: None, stages=[st])
     assert result.warnings == ["w1"]
+
+def test_read_warnings_is_empty_without_a_notes_file(tmp_path):
+    assert read_warnings(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)
@@ -26,3 +27,69 @@ def test_similarity_low_for_wrong_lyrics():
     ref = normalize_lyrics("completely different words here entirely")
     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_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)