acquire: keep yt-dlp current at runtime, with the bundled copy as fallback

YouTube breaks old yt-dlp releases faster than songtrace is released.
songtrace now checks PyPI daily, and again after a download fails outright,
installs a newer stable release into its cache dir and tries it before the
bundled copy, which is never modified. yt-dlp runs in a subprocess through
its CLI, all from one module, so a cached release never mixes with the
imported one. ytdlp_version pins a release or turns updating off.

README.md

@@ -34,6 +34,27 @@ printing the low-confidence regions it found (e.g.
 editor such as [Yass](https://www.yass-along.com/) or
 [USDX](https://usdx.eu/) and touch those spots up before playing.
 
+## Reviewing a song
+
+The web UI plays the finished song folder back against the review, so you can
+check the timing without loading it into a game first. Pick a song in the
+queue and the review panel gets the packaged video with a transport above the
+lyrics; as it plays, the line being sung is highlighted, words light up as
+they are reached, and a playhead sweeps each line against its notes. Click any
+line or word to play from there.
+
+Playback is modelled on the game: the `#MP3` is the audio and the clock, and
+the `#VIDEO` is muted background slaved to it. It also uses the same seconds
+the notes were generated from, so a word that lights up late in the browser is
+late in the game too.
+
+The packaged video has its audio track stripped for the same reason. It is the
+same recording as the `#MP3`, so a player that does not mute the video plays
+both at once, a few frames apart, which is heard as an echo. Songs built
+before this change still have it — check with `ffprobe <song>.mp4` for an
+audio stream, and rebuild with **Restart from** set to `package` to clear it
+without re-downloading.
+
 ## Configuration
 
 Config is TOML. Resolution order:
@@ -53,7 +74,7 @@ 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`,
 `ytdlp_clients`, `ytdlp_cookies`, `ytdlp_impersonate`,
-`ytdlp_pot_provider_url`).
+`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"`
@@ -87,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
@@ -122,29 +167,39 @@ Valid stages, in pipeline order: `acquire`, `separate`, `transcribe`,
 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. NEW
-SONG INSTEAD clears the form to start a fresh song.
+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.
 
 ## 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 and the
-   version baked into the image does not. Hotfix a running container, then
-   rebuild so it sticks:
+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.
 
-   ```sh
-   docker compose exec songtrace pip install -U 'yt-dlp[default,curl-cffi,deno]'
-   docker compose restart songtrace
-   docker compose build --pull songtrace   # permanent
-   ```
+   `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. Check with
-   `docker compose exec songtrace yt-dlp -v --simulate <url>` — the debug
+   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
@@ -168,7 +223,9 @@ 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

@@ -18,3 +18,6 @@ bind_host = "0.0.0.0"
 # 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"

scripts/screenshot_webui.py

@@ -7,6 +7,8 @@ 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
@@ -110,6 +112,7 @@ SONGS = [
     ("Vampire in the Corner", "Magdalena Bay", "queued", {}),
 ]
 SELECTED = "Greensleeves"
+REVIEW_HEADING = "REVIEW"
 
 running_event = threading.Event()
 
@@ -157,14 +160,42 @@ 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:
@@ -187,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()
@@ -201,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

@@ -24,6 +24,9 @@ class Config:
     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", "ytdlp_cookies"}

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/pipeline.py

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

src/songtrace/rebuild.py

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

src/songtrace/stages/acquire.py

@@ -2,6 +2,7 @@ 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
@@ -22,67 +23,50 @@ def _classify_downloads(dest: Path) -> tuple[Path, Path | None]:
     return video, thumbs[0] if thumbs else None
 
 
-class _YdlLog:
-    """Routes yt-dlp's own messages into the job log, minus progress noise."""
-
-    def __init__(self, log):
-        self._log = log
-
-    def debug(self, msg: str) -> None:
-        if not msg.startswith("[debug] "):
-            self._log(msg)
-
-    def warning(self, msg: str) -> None:
-        self._log(msg)
-
-    error = warning
-
-
-def _ydl_opts(cfg: Config, dest: Path, client: str, log) -> dict:
-    extractor_args: dict[str, dict[str, list[str]]] = {}
+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":
-        extractor_args["youtube"] = {"player_client": [client]}
+        args += ["--extractor-args", f"youtube:player_client={client}"]
     if cfg.ytdlp_pot_provider_url:
-        extractor_args["youtubepot-bgutilhttp"] = {
-            "base_url": [cfg.ytdlp_pot_provider_url]}
-    opts = {
-        "outtmpl": str(dest / "source_video.%(ext)s"),
-        "format": "bestvideo*+bestaudio/best",
-        "writethumbnail": True,
-        "noplaylist": True,
-        "noprogress": True,
-        "logger": _YdlLog(log),
-        "retries": 10,
-        "fragment_retries": 10,
-        "extractor_retries": 5,
-        "extractor_args": extractor_args,
-    }
+        args += ["--extractor-args",
+                 f"youtubepot-bgutilhttp:base_url={cfg.ytdlp_pot_provider_url}"]
     if cfg.ytdlp_cookies:
-        opts["cookiefile"] = str(cfg.ytdlp_cookies)
+        args += ["--cookies", str(cfg.ytdlp_cookies)]
     if cfg.ytdlp_impersonate:
-        from yt_dlp.networking.impersonate import ImpersonateTarget
-        opts["impersonate"] = ImpersonateTarget.from_str(cfg.ytdlp_impersonate)
-    return opts
+        args += ["--impersonate", cfg.ytdlp_impersonate]
+    return [*args, "--", url]
 
 
 def download_youtube(url: str, dest: Path, cfg: Config,
                      log=print) -> tuple[Path, Path | None]:
-    import yt_dlp
     clients = list(cfg.ytdlp_clients) or ["default"]
+    tried: list[str] = []
     last: Exception | None = None
-    for client in clients:
-        try:
-            with yt_dlp.YoutubeDL(_ydl_opts(cfg, dest, client, log)) as ydl:
-                ydl.extract_info(url, download=True)
-            return _classify_downloads(dest)
-        except Exception as e:
-            last = e
-            log(f"yt-dlp player_client={client} failed: {e}")
+    # 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 {yt_dlp.version.__version__} could not download {url} after "
-        f"trying player_client={', '.join(clients)}. Last error: {last}. "
-        "YouTube blocks change often: upgrade yt-dlp, then see the yt-dlp "
-        "options in config.toml (cookies, impersonation, PO token provider).")
+        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:

src/songtrace/stages/align.py

@@ -2,11 +2,14 @@ import json
 from pathlib import Path
 
 from ..lyrics import alignment_token, normalize_lyrics
+from ..models import on_release
 from ..pipeline import Ctx, PipelineError, Stage
 from .transcribe import classify_lyrics_match, load_transcript, lyrics_similarity, vocal_sections
 
 SIMILARITY_THRESHOLD = 0.4
 
+# 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 +20,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

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,10 +1,23 @@
+import sys
 from pathlib import Path
 
 import numpy as np
 
+from ..models import on_release
 from ..pipeline import Ctx, Stage
 
 
+@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 track_pitch(vocals_path: Path, model: str, device: str):
     import torchaudio
     import torchcrepe

src/songtrace/static/index.html

@@ -111,6 +111,7 @@ body {
 }
 
 #sidebar .eyebrow, #jobs .empty-note { padding: 0 18px; }
+#create-song { display: block; width: calc(100% - 36px); margin: 0 18px 20px; padding: 9px 12px; }
 
 #jobs { display: flex; flex-direction: column; gap: 1px; margin-top: 8px; }
 
@@ -199,6 +200,8 @@ body {
 .song-form-lyrics textarea { height: 100%; flex: 1 1 auto; }
 .pair { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
 .field { display: flex; flex-direction: column; gap: 6px; }
+/* [hidden] is only display:none, which the rule above would otherwise win */
+.field[hidden], .keep-note[hidden] { display: none; }
 .field > span {
   font-family: var(--font-display);
   font-weight: 600;
@@ -320,8 +323,27 @@ button { cursor: pointer; }
 }
 #review h3 span { color: var(--text-muted); font-weight: 400; }
 
+/* sticks to the top of #main so the video stays in frame as the lyrics scroll */
+#player { position: sticky; top: 0; z-index: 2; margin: 0 0 14px; padding: 6px 0 10px; background: var(--bg); }
+#player-video {
+  display: block;
+  width: 100%;
+  max-height: 30vh;
+  background: #000;
+  border: 1px solid var(--border);
+  border-radius: 2px;
+}
+#player-video[hidden] { display: none; }
+/* the native transport renders light otherwise, against everything around it */
+#player-media { display: block; width: 100%; margin-top: 8px; color-scheme: dark; }
+
 #lyrics-review { display: flex; flex-direction: column; gap: 10px; }
 .review-line { padding: 8px 12px; background: var(--panel); border: 1px solid var(--border); }
+.review-line-active { background: var(--panel-raised); border-color: var(--aqua); }
+.review-word-sung { color: var(--text-muted); }
+.review-word-active { color: var(--aqua); font-weight: 600; }
+.review-playhead { position: absolute; top: 0; bottom: 0; width: 2px; margin-left: -1px; background: var(--aqua); }
+.review-seek { cursor: pointer; }
 .review-line-text { display: block; font-size: 0.9rem; }
 .review-line-dropped { opacity: 0.55; }
 .review-line-dropped .review-line-text { text-decoration: line-through; }
@@ -355,7 +377,7 @@ button { cursor: pointer; }
   border: 1px solid var(--border);
 }
 .output-path code { flex: 1; overflow-wrap: anywhere; font-family: var(--font-mono); font-size: 0.82rem; }
-#copy-path, .action, #cancel-rebuild {
+#copy-path, .action {
   flex: none;
   padding: 5px 12px;
   font-family: var(--font-display);
@@ -368,7 +390,7 @@ button { cursor: pointer; }
   border: 1px solid var(--control);
   border-radius: 2px;
 }
-#copy-path:hover, .action:hover, #cancel-rebuild:hover { border-color: var(--text-muted); }
+#copy-path:hover, .action:hover { border-color: var(--text-muted); }
 
 .form-actions { display: flex; align-items: center; gap: 14px; }
 .keep-note { margin: -8px 0 0; font-size: 0.78rem; color: var(--aqua); }
@@ -495,6 +517,7 @@ button { cursor: pointer; }
     <div class="kana" aria-hidden="true">カラオケ</div>
   </div>
   <div>
+    <button type="button" id="create-song" class="primary">CREATE SONG</button>
     <h2 class="eyebrow">QUEUE</h2>
     <div id="jobs"></div>
   </div>
@@ -513,6 +536,10 @@ button { cursor: pointer; }
           <label class="field"><span>YouTube URL</span><input name="youtube_url"></label>
           <label class="field"><span>Video file</span><input type="file" name="video"></label>
           <p class="keep-note" data-keep="video" hidden></p>
+          <label class="field" id="restart-field" hidden>
+            <span>Restart from</span>
+            <select name="force_from"></select>
+          </label>
           <details>
             <summary>Advanced</summary>
             <div class="stack">
@@ -533,7 +560,6 @@ button { cursor: pointer; }
       </div>
       <div class="form-actions">
         <button type="submit" class="primary">CREATE SONG</button>
-        <button type="button" id="cancel-rebuild" hidden>NEW SONG INSTEAD</button>
         <p id="form-lock" hidden></p>
       </div>
     </form>
@@ -545,6 +571,10 @@ button { cursor: pointer; }
     <h3 id="review-title"></h3>
     <p id="review-lineage" hidden></p>
     <p id="review-error" class="review-error" hidden></p>
+    <div id="player" hidden>
+      <video id="player-video" muted playsinline preload="metadata"></video>
+      <audio id="player-media" controls preload="metadata"></audio>
+    </div>
     <div id="lyrics-review"><p class="empty-note">no songs queued yet — nothing to review</p></div>
     <div id="output-path"></div>
     <div id="review-actions"></div>
@@ -575,12 +605,15 @@ const nowTitle = document.getElementById("now-title");
 const stageTrack = document.getElementById("stage-track");
 const reviewActions = document.getElementById("review-actions");
 const reviewLineage = document.getElementById("review-lineage");
-const cancelRebuild = document.getElementById("cancel-rebuild");
+const createSong = document.getElementById("create-song");
 const formLock = document.getElementById("form-lock");
 const formHeading = document.querySelector("#new-song h2");
 const submitButton = form.querySelector("button[type=submit]");
 let rebuildOf = null;
 let formDirty = false;
+// set by CREATE SONG: the page is a blank sheet on purpose, so the poll must
+// not quietly select the newest song back into it
+let composing = false;
 let JOBS = [];
 let selectedId = null;
 let STAGES = [];
@@ -615,10 +648,16 @@ form.addEventListener("submit", async (e) => {
   if (!resp.ok) {
     const body = await resp.json().catch(() => ({}));
     formError.textContent = body.detail || `error: ${resp.status}`;
-    return;  // before the reset below, so a rejected submission is never retyped
+    return;
   }
   selectedId = (await resp.json()).id;
-  exitRebuild();
+  composing = false;
+  // the fields stay as submitted: the song just sent is the obvious starting
+  // point for the next one, and nothing has to be retyped to correct it. The
+  // queue's CREATE SONG button is what empties the form.
+  rebuildOf = null;
+  formDirty = false;
+  setFormMode(null, null);
   refreshJobs();
 });
 
@@ -647,7 +686,21 @@ for (const input of form.querySelectorAll('input[type="file"]')) {
 // anything of the operator's in there worth warning about first
 form.addEventListener("input", () => { formDirty = true; });
 
-cancelRebuild.addEventListener("click", exitRebuild);
+// Always available, and the form is usually holding a selected song by now, so
+// this clears the whole page down to a blank sheet — fields, review, player and
+// queue selection — and brings the form back into view from wherever playback
+// scrolled the panel to. Leaving another song's review under an empty form
+// reads as though the two belong together.
+createSong.addEventListener("click", () => {
+  if (formDirty && !confirm("Discard your unsaved edits to this form?")) return;
+  composing = true;
+  selectedId = null;
+  for (const card of jobsDiv.querySelectorAll(".job")) card.removeAttribute("aria-current");
+  exitRebuild();
+  clearDetail("nothing selected");
+  document.getElementById("new-song").scrollIntoView({ block: "start", behavior: "smooth" });
+  form.elements.title.focus();
+});
 
 function jobCard(job) {
   const card = document.createElement("button");
@@ -722,6 +775,11 @@ function renderJobs(jobs) {
 async function loadStages() {
   const resp = await fetch("/api/stages");
   STAGES = (await resp.json()).stages;
+  // a rebuild redoes only what the edit invalidated, which cannot see a change
+  // in songtrace itself — this is how you redo a stage anyway
+  const select = form.elements.force_from;
+  select.replaceChildren(new Option("only what changed", ""),
+                         ...STAGES.map(s => new Option(s, s)));
 }
 
 function renderStageTrack(job) {
@@ -784,11 +842,11 @@ async function refreshJobs() {
   // deliberately not via selectJob: the auto-selection on load fills the review
   // panel but leaves the form blank, so landing on the page is still the way to
   // start a new song. Clicking a queue entry is what loads its inputs.
-  if (selectedId === null && jobs.length) selectedId = jobs[0].id;
+  if (!composing && selectedId === null && jobs.length) selectedId = jobs[0].id;
   renderJobs(jobs);
   renderNowBar(jobs);
   if (selectedId) refreshDetail();
-  else clearDetail();
+  else clearDetail(composing ? "nothing selected" : undefined);
   schedulePoll(jobs);
 }
 
@@ -796,6 +854,7 @@ async function selectJob(id) {
   // the form already holds this job; reloading it would drop edits in progress
   const reload = id !== rebuildOf;
   if (reload && formDirty && !confirm("Discard your unsaved edits to this form?")) return;
+  composing = false;
   selectedId = id;
   for (const card of jobsDiv.querySelectorAll(".job")) {
     if (card.dataset.id === id) card.setAttribute("aria-current", "true");
@@ -873,6 +932,10 @@ function lineTimeline(words, notes, minPitch, span) {
   }
   box.append(wordsRow);
   if (notes.length) box.append(pianoRoll(notes, minPitch, span, t0, t1));
+  const playhead = document.createElement("div");
+  playhead.className = "review-playhead";
+  playhead.hidden = true;
+  box.append(playhead);
   return box;
 }
 
@@ -906,6 +969,21 @@ function lineNode(line, minPitch, span) {
   return row;
 }
 
+// What playback needs from a rendered line: the time range it was laid out
+// over, the word labels along it, and the bar that sweeps across it.
+function lineEntry(row, line) {
+  const laid = line.words.length ? line.words : line.notes;
+  if (!laid.length || line.dropped) return null;
+  const labels = [...row.querySelectorAll(".review-word")];
+  return {
+    row,
+    t0: laid[0].start,
+    t1: Math.max(...laid.map(x => x.end)),
+    words: line.words.map((w, i) => ({ el: labels[i], start: w.start, end: w.end })),
+    playhead: row.querySelector(".review-playhead"),
+  };
+}
+
 function buildLyricsReview(data) {
   const allNotes = data.lines.flatMap(l => l.notes);
   const pitches = allNotes.map(n => n.pitch);
@@ -914,6 +992,7 @@ function buildLyricsReview(data) {
   const span = Math.max(1, maxPitch - minPitch);
   const spans = [...data.missing_spans].sort((a, b) => a.start - b.start);
   const nodes = [];
+  const entries = [];
   let spanIdx = 0;
   for (const line of data.lines) {
     const lineStart = line.notes.length ? Math.min(...line.notes.map(n => n.start)) : null;
@@ -921,24 +1000,172 @@ function buildLyricsReview(data) {
       nodes.push(missingSpanNode(spans[spanIdx]));
       spanIdx++;
     }
-    nodes.push(lineNode(line, minPitch, span));
+    const row = lineNode(line, minPitch, span);
+    const entry = lineEntry(row, line);
+    if (entry) entries.push(entry);
+    nodes.push(row);
   }
   while (spanIdx < spans.length) {
     nodes.push(missingSpanNode(spans[spanIdx]));
     spanIdx++;
   }
-  return nodes;
+  return { nodes, entries };
+}
+
+// The song folder's own media, played against the same seconds the review was
+// built from, so the highlighted line is the one you are hearing.
+//
+// Modelled on the game: #MP3 is the audio and the clock, the video is muted
+// background slaved to it. Playing the video's own audio alongside the mp3 is
+// the same recording twice, a few frames apart, which is heard as an echo.
+const player = document.getElementById("player");
+const media = document.getElementById("player-media");
+const video = document.getElementById("player-video");
+const DRIFT = 0.25;  // seconds before the picture is worth re-seeking
+
+function slaveVideo(force) {
+  if (video.hidden || !video.getAttribute("src")) return;
+  if (force || Math.abs(video.currentTime - media.currentTime) > DRIFT) {
+    video.currentTime = media.currentTime;
+  }
+}
+
+for (const event of ["seeked", "ratechange"]) {
+  media.addEventListener(event, () => {
+    video.playbackRate = media.playbackRate;
+    slaveVideo(true);
+  });
+}
+media.addEventListener("pause", () => video.pause());
+let timeline = [];
+let activeEntry = null;
+let syncFrame = null;
+
+// the first line that has not finished yet: the one being sung, or the one
+// coming up while the track is between lines
+function entryAt(t) {
+  return timeline.find(e => t <= e.t1) ?? timeline[timeline.length - 1] ?? null;
+}
+
+function paintEntry(entry, t) {
+  for (const w of entry.words) {
+    w.el.classList.toggle("review-word-sung", t >= w.end);
+    w.el.classList.toggle("review-word-active", t >= w.start && t < w.end);
+  }
+  if (!entry.playhead) return;
+  const inside = t >= entry.t0 && t <= entry.t1;
+  entry.playhead.hidden = !inside;
+  if (inside) {
+    const frac = (t - entry.t0) / Math.max(entry.t1 - entry.t0, 0.001);
+    entry.playhead.style.left = `${frac * 100}%`;
+  }
+}
+
+function clearEntry(entry) {
+  entry.row.classList.remove("review-line-active");
+  if (entry.playhead) entry.playhead.hidden = true;
+  for (const w of entry.words) {
+    w.el.classList.remove("review-word-sung", "review-word-active");
+  }
+}
+
+function syncPlayback() {
+  const t = media.currentTime;
+  const entry = entryAt(t);
+  if (entry !== activeEntry) {
+    if (activeEntry) clearEntry(activeEntry);
+    activeEntry = entry;
+    if (entry) {
+      entry.row.classList.add("review-line-active");
+      focusActive();
+    }
+  }
+  if (entry) paintEntry(entry, t);
+}
+
+// centred so there is context either side, like a scrolling lyric sheet; only
+// while running, so it does not fight a reader who has scrolled away to look
+// at something else
+function focusActive() {
+  if (!activeEntry || media.paused) return;
+  activeEntry.row.scrollIntoView({ block: "center", behavior: "smooth" });
+}
+
+function pumpPlayback() {
+  syncPlayback();
+  slaveVideo(false);
+  syncFrame = media.paused ? null : requestAnimationFrame(pumpPlayback);
+}
+
+// timeupdate fires about four times a second, too coarse for a playhead
+media.addEventListener("play", () => {
+  if (syncFrame === null) syncFrame = requestAnimationFrame(pumpPlayback);
+  if (!video.hidden && video.getAttribute("src")) video.play().catch(() => {});
+  focusActive();  // the line may already be active from a seek while paused
+});
+for (const event of ["pause", "seeked", "loadedmetadata"]) {
+  media.addEventListener(event, syncPlayback);
+}
+
+function bindTimeline(entries) {
+  if (activeEntry) clearEntry(activeEntry);
+  activeEntry = null;
+  timeline = entries;
+  for (const entry of entries) {
+    entry.row.classList.add("review-seek");
+    entry.row.title = "click to play from here";
+    entry.row.addEventListener("click", (e) => {
+      const word = entry.words.find(w => w.el === e.target);
+      media.currentTime = word ? word.start : entry.t0;
+      if (media.paused) syncPlayback();
+    });
+  }
+}
+
+// Returns true when the folder gave us something to play. #MP3 is required —
+// it is the audio the game uses, so it is the one the review has to track.
+function setPlayerSource(job, available) {
+  const src = available?.audio ? `/api/jobs/${job.id}/media/audio` : "";
+  player.hidden = !src;
+  if (media.dataset.src === src) return !!src;
+  media.dataset.src = src;
+  if (src) media.src = src;
+  else { media.removeAttribute("src"); media.load(); }
+
+  video.hidden = !(src && available.video);
+  video.poster = available?.cover ? `/api/jobs/${job.id}/media/cover` : "";
+  if (!video.hidden) video.src = `/api/jobs/${job.id}/media/video`;
+  else { video.removeAttribute("src"); video.load(); }
+  return !!src;
+}
+
+function resetPlayer() {
+  // the 3s poll reaches here for every running job; reloading a cleared
+  // element each time would be pure churn
+  if (player.hidden && !timeline.length) return;
+  bindTimeline([]);
+  player.hidden = true;
+  media.pause();
+  video.pause();
+  media.dataset.src = "";
+  for (const el of [media, video]) {
+    el.removeAttribute("src");
+    el.removeAttribute("poster");
+    el.load();
+  }
 }
 
 async function renderLyricsReview(job) {
   const box = document.getElementById("lyrics-review");
   if (job.status === "failed") {
     delete box.dataset.jobId;
+    resetPlayer();
     box.replaceChildren(emptyNote("job failed — nothing to review"));
     return;
   }
   if (job.status !== "done") {
     delete box.dataset.jobId;
+    resetPlayer();
     box.replaceChildren(emptyNote("waiting for this song to finish…"));
     return;
   }
@@ -946,6 +1173,7 @@ async function renderLyricsReview(job) {
   const resp = await fetch(`/api/jobs/${job.id}/review`);
   if (job.id !== selectedId) return;
   if (!resp.ok) {
+    resetPlayer();
     box.replaceChildren(emptyNote("no review data available"));
     return;
   }
@@ -953,10 +1181,17 @@ async function renderLyricsReview(job) {
   if (job.id !== selectedId) return;
   box.dataset.jobId = job.id;
   if (!data.lines.length) {
+    resetPlayer();
     box.replaceChildren(emptyNote("no lyrics to review"));
     return;
   }
-  box.replaceChildren(...buildLyricsReview(data));
+  const { nodes, entries } = buildLyricsReview(data);
+  box.replaceChildren(...nodes);
+  // with nothing to play, a highlighted line and a click-to-seek cursor would
+  // both be promising something the song folder cannot deliver
+  const playable = setPlayerSource(job, data.media);
+  bindTimeline(playable ? entries : []);
+  if (playable) syncPlayback();
 }
 
 async function copyPath(path, button) {
@@ -1016,19 +1251,23 @@ function renderOutputPath(job) {
   outputPathDiv.replaceChildren(wrap);
 }
 
-function clearDetail() {
+function clearDetail(why = "no songs queued yet") {
   reviewTitle.replaceChildren();
   reviewError.hidden = true;
   reviewError.textContent = "";
-  document.getElementById("warnings").replaceChildren(
-    emptyNote("no songs queued yet — nothing to review"));
+  resetPlayer();
+  // the review box, not an element that no longer exists: getting this wrong
+  // threw partway through and left the rest of the panel showing the old song
+  const box = document.getElementById("lyrics-review");
+  delete box.dataset.jobId;
+  box.replaceChildren(emptyNote(`${why} — nothing to review`));
   outputPathDiv.replaceChildren();
   reviewActions.replaceChildren();
   delete reviewActions.dataset.jobId;
   reviewLineage.replaceChildren();
   reviewLineage.hidden = true;
   delete reviewLineage.dataset.jobId;
-  detail.textContent = "no songs queued yet — nothing to log";
+  detail.textContent = `${why} — nothing to log`;
 }
 
 // a rebuild is refused with 409 until the job settles, so the form says so
@@ -1043,8 +1282,10 @@ function setSubmitLock(status) {
 function setFormMode(inp, status) {
   formHeading.textContent = rebuildOf ? "REBUILD" : "NEW SONG";
   submitButton.textContent = rebuildOf ? "REBUILD SONG" : "CREATE SONG";
-  cancelRebuild.hidden = !rebuildOf;
   setSubmitLock(status);
+  // only a rebuild has stages to restart from; a new song always runs them all
+  document.getElementById("restart-field").hidden = !rebuildOf;
+  if (!rebuildOf) form.elements.force_from.value = "";
   for (const [field, key] of [["video", "video_filename"], ["cover", "cover_filename"]]) {
     const note = form.querySelector(`[data-keep="${field}"]`);
     const kept = rebuildOf && inp ? inp[key] : null;
@@ -1052,9 +1293,9 @@ function setFormMode(inp, status) {
     note.hidden = !kept;
   }
   // the advanced fields carry into a rebuild whether or not the section is open,
-  // so a job that has any must not hide them behind a closed summary
-  form.querySelector("details").open = !!inp && (!!inp.cover_filename ||
-    ["genre", "year", "language", "bpm"].some(n => form.elements[n].value));
+  // so anything actually set must not sit hidden behind a closed summary
+  form.querySelector("details").open = !!inp?.cover_filename ||
+    ["genre", "year", "language", "bpm"].some(n => form.elements[n].value);
 }
 
 function exitRebuild() {

src/songtrace/web.py

@@ -19,9 +19,12 @@ from .config import Config
 from .lyrics import normalize_lyrics
 from .pipeline import (STAGE_ORDER, PipelineError, SongInput, read_warnings,
                        run_pipeline, song_slug)
+from .ultrastar import get_header, parse_ultrastar
 
 STATIC = Path(__file__).parent / "static"
 STAGE_LINE = re.compile(r"^\[(\w+)\] (?:running|cached, skipping)")
+# the song folder names its own media, exactly as the game reads it
+MEDIA_HEADERS = {"audio": "MP3", "video": "VIDEO", "cover": "COVER"}
 
 
 @dataclass
@@ -137,18 +140,18 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
 
     def _prepare_rebuild(job: Job, log) -> str | None:
         """Relocate cached work and report the stage this rebuild restarts from."""
-        if job.force_stage:
-            log(f"[rebuild] restarting from {job.force_stage} (forced rebuild from scratch)")
-            return job.force_stage
         if not job.rebuilt_from:
-            return None
+            return job.force_stage
         with lock:
             parent = jobs.get(job.rebuilt_from)
         if parent is None:
-            return None
-        force_from = rebuild_policy.plan(parent.inp, job.inp)
+            return job.force_stage
+        planned = rebuild_policy.plan(parent.inp, job.inp)
         changed = rebuild_policy.changed_fields(parent.inp, job.inp)
         rebuild_policy.relocate_work(parent.inp, job.inp, cfg)
+        # a stage the operator asked for can only widen what plan() decided,
+        # which is how "redo the packaging" reaches work nothing invalidated
+        force_from = rebuild_policy.earliest(planned, job.force_stage)
         log(f"[rebuild] restarting from {force_from or 'the first incomplete stage'}"
             f" ({', '.join(changed) if changed else 'nothing'} changed)")
         return force_from
@@ -245,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")
@@ -290,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")
@@ -314,8 +325,9 @@ 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)
 
     @app.get("/api/stages")
     def list_stages():
@@ -376,6 +388,35 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
         shutil.rmtree(cfg.work_dir / slug, ignore_errors=True)
         shutil.rmtree(cfg.output_dir / slug, ignore_errors=True)
 
+    def _resolve_media(job: Job, header: str) -> Path | None:
+        """The file a song folder's #MP3/#VIDEO/#COVER header points at."""
+        slug = song_slug(job.inp)
+        out = (cfg.output_dir / slug).resolve()
+        txt = out / f"{slug}.txt"
+        if not txt.exists():
+            return None
+        name = get_header(parse_ultrastar(txt.read_text(encoding="utf-8")), header)
+        if not name:
+            return None
+        # a header names a file in the song folder and nothing else
+        path = (out / name).resolve()
+        if path.parent != out or not path.is_file():
+            return None
+        return path
+
+    @app.get("/api/jobs/{job_id}/media/{kind}")
+    def get_media(job_id: str, kind: str):
+        header = MEDIA_HEADERS.get(kind)
+        if header is None:
+            raise HTTPException(404)
+        job = _finished_job(job_id)
+        if job.status != "done":
+            raise HTTPException(404)
+        path = _resolve_media(job, header)
+        if path is None:
+            raise HTTPException(404)
+        return FileResponse(path)
+
     @app.get("/api/jobs/{job_id}/review")
     def get_review(job_id: str):
         job = _finished_job(job_id)
@@ -406,7 +447,9 @@ def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
         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)]
-        return {"lines": lines, "missing_spans": missing_spans}
+        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/test_acquire.py

@@ -91,87 +91,112 @@ def test_classify_ignores_partials_left_by_a_failed_attempt(tmp_path):
     video, _ = acquire._classify_downloads(tmp_path)
     assert video.name == "source_video.webm"
 
-def test_ydl_opts_default_client_adds_no_player_client(tmp_path):
+def test_ydl_args_default_client_adds_no_player_client(tmp_path):
     cfg = Config(whisper_url="http://x/v1")
-    opts = acquire._ydl_opts(cfg, tmp_path, "default", print)
-    assert "youtube" not in opts["extractor_args"]
-    assert opts["retries"] and opts["fragment_retries"] and opts["extractor_retries"]
+    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_opts_named_client_and_pot_provider(tmp_path):
+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")
-    opts = acquire._ydl_opts(cfg, tmp_path, "tv", print)
-    assert opts["extractor_args"]["youtube"] == {"player_client": ["tv"]}
-    assert opts["extractor_args"]["youtubepot-bgutilhttp"] == {
-        "base_url": ["http://pot:4416"]}
-    assert opts["cookiefile"] == str(tmp_path / "cookies.txt")
+                 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 _fake_yt_dlp(monkeypatch, behaviour):
-    """Install a stub yt_dlp whose download calls `behaviour(opts)`."""
-    import sys
-    import types
+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 = []
-
-    class FakeYoutubeDL:
-        def __init__(self, opts):
-            self.opts = opts
-        def __enter__(self):
-            return self
-        def __exit__(self, *exc):
-            return False
-        def extract_info(self, url, download):
-            seen.append(self.opts["extractor_args"].get("youtube"))
-            behaviour(self.opts)
-
-    mod = types.ModuleType("yt_dlp")
-    mod.YoutubeDL = FakeYoutubeDL
-    mod.version = types.SimpleNamespace(__version__="2026.08.19")
-    monkeypatch.setitem(sys.modules, "yt_dlp", mod)
+    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):
-    def behaviour(opts):
-        client = opts["extractor_args"].get("youtube")
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
         if client is None:
-            raise RuntimeError("HTTP Error 403: Forbidden")
+            raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
         (tmp_path / "source_video.webm").write_bytes(b"v")
-    seen = _fake_yt_dlp(monkeypatch, behaviour)
+    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 == [None, {"player_client": ["tv"]}]
+    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_reports_version_and_clients_when_all_fail(tmp_path, monkeypatch):
+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
-    def behaviour(opts):
-        raise RuntimeError("HTTP Error 403: Forbidden")
-    _fake_yt_dlp(monkeypatch, behaviour)
+    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.08.19" in str(e.value)
+    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_yt_dlp(
-        monkeypatch, lambda opts: (tmp_path / "source_video.mp4").write_bytes(b"v"))
+    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 == [None]
-
-def test_ydl_log_drops_debug_lines():
-    logged = []
-    log = acquire._YdlLog(logged.append)
-    log.debug("[debug] internal detail")
-    log.debug("[youtube] Extracting URL")
-    log.warning("nsig extraction failed")
-    log.error("HTTP Error 403: Forbidden")
-    assert logged == ["[youtube] Extracting URL", "nsig extraction failed",
-                      "HTTP Error 403: Forbidden"]
+    assert seen == [("2026.09.01", None)]

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_package.py

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

tests/test_pipeline.py

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

tests/test_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_web.py

@@ -584,11 +584,19 @@ def _submit_body(html):
     return html[start:html.index("\n});\n", start)]
 
 
+def _listener_body(html, prefix):
+    start = html.index(prefix)
+    return html[start:html.index("\n});\n", start)]
+
+
 def _rebuild_flaws(html):
     """Ways rebuild mode could quietly stop working."""
     flaws, submit = [], _submit_body(html)
     if "rebuildOf ?" not in submit or "/rebuild" not in submit:
         flaws.append("the form always posts to /api/jobs, so edits create a new song")
+    if "form.reset()" in submit or "exitRebuild()" in submit:
+        flaws.append("a successful submission empties the form, so correcting "
+                     "or varying the song just sent means retyping it")
 
     actions = _fn_body(html, "renderActions")
     if not re.search(r"if \(.*dataset\.jobId === job\.id.*\) return;", actions):
@@ -609,6 +617,20 @@ def _rebuild_flaws(html):
     if "if (rebuildOf === id) exitRebuild();" not in _fn_body(html, "deleteJob"):
         flaws.append("deleting the loaded job leaves the form pointed at it")
 
+    # selecting a queue entry loads it, so the sidebar button is now the only
+    # way back to a blank form
+    create = _listener_body(html, 'createSong.addEventListener("click"')
+    if "exitRebuild()" not in create:
+        flaws.append("the queue's CREATE SONG button does not clear the form")
+    if "formDirty" not in create or "confirm(" not in create:
+        flaws.append("the queue's CREATE SONG button discards edits without asking")
+    if "clearDetail(" not in create:
+        flaws.append("CREATE SONG empties the form but leaves the previous "
+                     "song's review and player sitting under it")
+    if "composing" not in create or "composing" not in _fn_body(html, "refreshJobs"):
+        flaws.append("the blank page CREATE SONG made is selected back over by "
+                     "the next poll of the queue")
+
     mode = _fn_body(html, "setFormMode")
     if 'querySelector("details").open' not in mode:
         flaws.append("prefilled genre/year/language/bpm stay hidden behind the "
@@ -647,7 +669,7 @@ def test_rebuild_full_and_delete_controls_are_wired_up():
 
 def _empty_state_flaws(html):
     refresh = _fn_body(html, "refreshJobs")
-    if "clearDetail()" not in refresh:
+    if "clearDetail(" not in refresh:
         return ["refreshJobs never resets the panel when no job is selected"]
     return []
 
@@ -656,6 +678,54 @@ def test_review_panel_resets_when_no_job_is_selected():
     assert _empty_state_flaws(_index_html()) == []
 
 
+def _playback_flaws(html):
+    """Ways the review could stop tracking the media element."""
+    flaws = []
+    source = _fn_body(html, "setPlayerSource")
+    if "media/audio" not in source:
+        flaws.append("the player is not pointed at the job's packaged audio, "
+                     "which is the file the game plays and the notes track")
+    if "media/video" not in source:
+        flaws.append("the packaged video is never shown alongside the audio")
+
+    # the mp3 and the video carry the same recording; playing both is an echo
+    if not re.search(r"<video[^>]*\bmuted\b", html):
+        flaws.append("the background video is not muted, so its own audio "
+                     "plays on top of the mp3")
+    pump = _fn_body(html, "pumpPlayback")
+    if "slaveVideo(" not in pump:
+        flaws.append("the picture is never pulled back onto the audio clock, "
+                     "so it drifts out of sync over a long song")
+
+    if "requestAnimationFrame" not in _fn_body(html, "pumpPlayback"):
+        flaws.append("sync is not driven by the frame loop, so the playhead "
+                     "steps at timeupdate's ~4Hz instead of following the audio")
+
+    if "media.paused" not in _fn_body(html, "focusActive"):
+        flaws.append("the view is scrolled even while paused, fighting a reader "
+                     "who scrolled away to look at something else")
+
+    sync = _fn_body(html, "syncPlayback")
+    if "clearEntry(" not in sync:
+        flaws.append("the line the playhead left keeps its highlight")
+    clear = _fn_body(html, "clearEntry")
+    for name in ("review-word-sung", "review-word-active", "review-line-active"):
+        if name not in clear:
+            flaws.append(f"{name} is never taken off a line the playhead left")
+
+    # every branch that gives up on rendering a review has to unload the media
+    # too, or the previous song stays loaded and playable under the new one
+    render = _fn_body(html, "renderLyricsReview")
+    if render.count("resetPlayer()") < render.count("emptyNote("):
+        flaws.append("a review the page cannot render leaves the previous "
+                     "song's media loaded in the player")
+    return flaws
+
+
+def test_review_playback_tracks_the_media_element():
+    assert _playback_flaws(_index_html()) == []
+
+
 # each mutation is a plausible regression; the checker above must reject all of them
 MUTATIONS = [
     (_focus_flaws, "queue: card moved unconditionally",
@@ -700,8 +770,40 @@ MUTATIONS = [
      'form.querySelector("details").open =', "const unusedAdvancedOpen ="),
     (_rebuild_flaws, "prefill: an in-progress job can be submitted for rebuild anyway",
      "submitButton.disabled = locked;", ""),
+    (_rebuild_flaws, "submit: a successful submission empties the form again",
+     "  rebuildOf = null;\n  formDirty = false;\n  setFormMode(null, null);\n  refreshJobs();",
+     "  exitRebuild();\n  refreshJobs();"),
+    (_rebuild_flaws, "create: the queue button no longer clears the form",
+     "  exitRebuild();\n  clearDetail(\"nothing selected\");\n", ""),
+    (_rebuild_flaws, "create: the review is left behind under a blank form",
+     '  clearDetail("nothing selected");\n', ""),
+    (_rebuild_flaws, "create: the next poll selects a song back into the blank page",
+     "  composing = true;\n", ""),
+    (_rebuild_flaws, "create: the queue button discards edits without asking",
+     '  if (formDirty && !confirm("Discard your unsaved edits to this form?")) return;\n  composing = true;',
+     "  composing = true;"),
+    (_playback_flaws, "playback: sync falls back to the timeupdate event's ~4Hz",
+     "syncFrame = media.paused ? null : requestAnimationFrame(pumpPlayback);",
+     "syncFrame = null;"),
+    (_playback_flaws, "playback: the view is scrolled even while paused",
+     "if (!activeEntry || media.paused) return;", "if (!activeEntry) return;"),
+    (_playback_flaws, "playback: the line the playhead left keeps its highlight",
+     "    if (activeEntry) clearEntry(activeEntry);\n", ""),
+    (_playback_flaws, "playback: a word stays lit after the playhead moves on",
+     'w.el.classList.remove("review-word-sung", "review-word-active");',
+     'w.el.classList.remove("review-word-sung");'),
+    (_playback_flaws, "playback: an unrenderable review leaves the old song loaded",
+     "    resetPlayer();\n", ""),
+    (_playback_flaws, "playback: the player is not pointed at the packaged audio",
+     'const src = available?.audio ? `/api/jobs/${job.id}/media/audio` : "";',
+     'const src = "";'),
+    (_playback_flaws, "playback: the background video plays its own audio too",
+     '<video id="player-video" muted playsinline',
+     '<video id="player-video" playsinline'),
+    (_playback_flaws, "playback: the picture is never re-synced to the audio",
+     "  slaveVideo(false);\n", ""),
     (_empty_state_flaws, "empty state: clearDetail no longer wired into refreshJobs",
-     "if (selectedId) refreshDetail();\n  else clearDetail();",
+     "if (selectedId) refreshDetail();\n  else clearDetail(composing ? \"nothing selected\" : undefined);",
      "if (selectedId) refreshDetail();"),
 ]
 
@@ -738,7 +840,7 @@ def test_rebuild_mode_reuses_the_one_form():
 
 def test_index_has_rebuild_hooks():
     html = _index_html()
-    for hook in ("review-actions", "review-lineage", "cancel-rebuild",
+    for hook in ("review-actions", "review-lineage", "create-song",
                  'data-keep="video"', 'data-keep="cover"'):
         assert hook in html, hook
 
@@ -1385,3 +1487,262 @@ def test_review_missing_when_pipeline_never_wrote_notes(tmp_path):
     client, _ = make_client(tmp_path, ok_runner)
     job_id = make_done_job(client)
     assert client.get(f"/api/jobs/{job_id}/review").status_code == 404
+
+
+# --- review playback -------------------------------------------------------
+
+MEDIA_FILES = {"A - T.mp3": b"ID3audio", "A - T.mp4": b"\0\0\0\x18ftypvideo",
+               "A - T.jpg": b"\xff\xd8cover"}
+MEDIA_HEADERS = [("TITLE", "T"), ("ARTIST", "A"), ("MP3", "A - T.mp3"),
+                 ("COVER", "A - T.jpg"), ("VIDEO", "A - T.mp4")]
+
+
+def media_runner_factory(files=None, headers=None, write_txt=True):
+    """A run that leaves behind a song folder, the way package does."""
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        slug = song_slug(inp)
+        out = cfg.output_dir / slug
+        out.mkdir(parents=True, exist_ok=True)
+        for name, body in (MEDIA_FILES if files is None else files).items():
+            (out / name).write_bytes(body)
+        if write_txt:
+            rows = [f"#{k}:{v}" for k, v in
+                    (MEDIA_HEADERS if headers is None else headers)]
+            (out / f"{slug}.txt").write_text("\n".join(rows) + "\n: 0 4 0 la\nE\n",
+                                             encoding="utf-8")
+        return PipelineResult(output_dir=out)
+    return runner
+
+
+def test_media_serves_the_files_the_song_txt_names(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    for kind, name in (("audio", "A - T.mp3"), ("video", "A - T.mp4"),
+                       ("cover", "A - T.jpg")):
+        resp = client.get(f"/api/jobs/{job_id}/media/{kind}")
+        assert resp.status_code == 200, kind
+        assert resp.content == MEDIA_FILES[name], kind
+
+
+def test_media_serves_whatever_the_header_was_rewritten_to(tmp_path):
+    """package transcodes to .mp4 and rewrites #VIDEO; the extension is not fixed."""
+    files = {**MEDIA_FILES, "A - T.webm": b"transcoded"}
+    headers = [(k, "A - T.webm" if k == "VIDEO" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(files, headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/video").content == b"transcoded"
+
+
+def test_media_supports_range_requests(tmp_path):
+    """Without 206 the browser cannot seek, which is the point of the player."""
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    resp = client.get(f"/api/jobs/{job_id}/media/video", headers={"Range": "bytes=0-3"})
+    assert resp.status_code == 206
+    assert resp.headers["content-range"] == f"bytes 0-3/{len(MEDIA_FILES['A - T.mp4'])}"
+    assert resp.content == MEDIA_FILES["A - T.mp4"][:4]
+
+
+def test_media_of_an_unknown_kind_is_404(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/instrumental").status_code == 404
+
+
+def test_media_refuses_a_header_pointing_outside_the_song_folder(tmp_path):
+    secret = tmp_path / "secret.txt"
+    secret.write_text("not yours")
+    headers = [(k, "../../secret.txt" if k == "MP3" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_refuses_an_absolute_header_path(tmp_path):
+    secret = tmp_path / "secret.txt"
+    secret.write_text("not yours")
+    headers = [(k, str(secret) if k == "MP3" else v) for k, v in MEDIA_HEADERS]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_404s_when_the_named_file_is_missing(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory(files={}))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_404s_when_the_header_was_dropped(tmp_path):
+    """package strips #COVER when there is no usable cover image."""
+    headers = [(k, v) for k, v in MEDIA_HEADERS if k != "COVER"]
+    client, _ = make_client(tmp_path, media_runner_factory(headers=headers))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/cover").status_code == 404
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 200
+
+
+def test_media_404s_when_there_is_no_song_txt(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory(write_txt=False))
+    job_id = make_done_job(client)
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_of_a_failed_job_is_404(tmp_path):
+    def bad_runner(*a, **kw):
+        raise PipelineError("boom")
+    client, _ = make_client(tmp_path, bad_runner)
+    job_id = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}).json()["id"]
+    wait_status(client, job_id, "failed")
+    assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 404
+
+
+def test_media_of_a_running_job_is_409(tmp_path):
+    release = threading.Event()
+
+    def blocking(inp, cfg, log=print, force_from=None, stages=None):
+        release.wait(5)
+        return PipelineResult(output_dir=cfg.output_dir / "X")
+
+    client, _ = make_client(tmp_path, blocking)
+    job_id = client.post("/api/jobs", data={
+        "title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}).json()["id"]
+    try:
+        wait_status(client, job_id, "running")
+        assert client.get(f"/api/jobs/{job_id}/media/audio").status_code == 409
+    finally:
+        release.set()
+    wait_status(client, job_id, "done")
+
+
+def test_media_of_an_unknown_job_is_404(tmp_path):
+    client, _ = make_client(tmp_path, media_runner_factory())
+    assert client.get("/api/jobs/nope/media/audio").status_code == 404
+
+
+def test_review_reports_which_media_the_player_can_load(tmp_path):
+    notes = [{"start": 1.0, "duration": 0.4, "pitch": 0, "text": "hi",
+              "low_confidence": False, "line_index": 0}]
+    review = review_runner_factory(notes)
+    media = media_runner_factory(headers=[(k, v) for k, v in MEDIA_HEADERS
+                                          if k != "COVER"])
+
+    def runner(inp, cfg, **kw):
+        media(inp, cfg, **kw)
+        return review(inp, cfg, **kw)
+
+    client, _ = make_client(tmp_path, runner)
+    job_id = make_done_job(client, lyrics="hi")
+    body = client.get(f"/api/jobs/{job_id}/review").json()
+    assert body["media"] == {"audio": True, "video": True, "cover": False}
+
+
+# --- restarting a rebuild from a chosen stage ------------------------------
+
+def force_from_runner_factory(seen):
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        seen.append(force_from)
+        out = cfg.output_dir / song_slug(inp)
+        out.mkdir(parents=True, exist_ok=True)
+        return PipelineResult(output_dir=out)
+    return runner
+
+
+def rebuild_with(client, job_id, **extra):
+    data = {"title": "T", "artist": "A", "lyrics": "x", "youtube_url": "http://y"}
+    data.update(extra)
+    return client.post(f"/api/jobs/{job_id}/rebuild", data=data)
+
+
+def test_rebuild_without_edits_restarts_from_the_stage_asked_for(tmp_path):
+    """The point of the control: a change in songtrace invalidates no field."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="package")
+    assert resp.status_code == 201
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "package"
+
+
+def test_rebuild_without_a_stage_still_plans_from_the_edit(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, lyrics="different words")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "align"
+
+
+def test_an_edit_wins_when_it_invalidates_more_than_the_stage_asked_for(tmp_path):
+    """A choice may widen what is redone, never narrow it below correctness."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, lyrics="different words",
+                        force_from="package")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "align"
+
+
+def test_the_stage_asked_for_wins_when_it_is_earlier_than_the_edit(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, title="Renamed", force_from="separate")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == "separate"
+
+
+def test_rebuild_rejects_a_stage_that_is_not_in_the_pipeline(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="deechoing")
+    assert resp.status_code == 400
+    assert "deechoing" in resp.json()["detail"]
+
+
+def test_a_blank_stage_is_the_same_as_not_asking(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = rebuild_with(client, parent, force_from="")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] is None
+
+
+def test_rebuild_from_scratch_still_restarts_at_the_first_stage(tmp_path):
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client)
+    resp = client.post(f"/api/jobs/{parent}/rebuild-full")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] == STAGE_ORDER[0]
+
+
+def test_the_restart_control_offers_every_stage():
+    html = _index_html()
+    assert 'name="force_from"' in html
+    stages = _fn_body(html, "loadStages")
+    assert "force_from" in stages and "STAGES.map" in stages
+    mode = _fn_body(html, "setFormMode")
+    assert "restart-field" in mode, "the control is shown outside rebuild mode"
+
+
+def test_a_textareas_crlf_does_not_read_as_a_lyrics_edit(tmp_path):
+    """Browsers submit textareas with CRLF; the stored lyrics use LF."""
+    seen = []
+    client, _ = make_client(tmp_path, force_from_runner_factory(seen))
+    parent = make_done_job(client, lyrics="one\ntwo")
+    resp = rebuild_with(client, parent, lyrics="one\r\ntwo")
+    wait_status(client, resp.json()["id"], "done")
+    assert seen[-1] is None, "the rebuild redid the alignment for nothing"
+    body = client.get(f"/api/jobs/{resp.json()['id']}/input").json()
+    assert body["lyrics"] == "one\ntwo"
+
+
+def test_submitting_crlf_lyrics_stores_them_with_lf(tmp_path):
+    client, _ = make_client(tmp_path, ok_runner)
+    job_id = make_done_job(client, lyrics="one\r\ntwo")
+    assert client.get(f"/api/jobs/{job_id}/input").json()["lyrics"] == "one\ntwo"

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)