From 332758c614da7714c7a4d8897801c6ca4da286bf Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:03:06 +0100
Subject: [PATCH 01/11] A byte we cannot decode is not a reason to fail a
 separation

Reported against a real import:

    'charmap' codec can't decode byte 0x8f in position 20

text=True on its own decodes a child's output with the locale encoding. On
Windows that is cp1252, so one byte outside it in Demucs' progress output
killed the whole job. The output in question is a progress bar and some
echoed metadata. Diagnostic text, never worth failing a separation over.

Both halves have to agree or the mismatch just moves, so the parents now
read utf-8 with errors=replace and the children are told to write utf-8.
Three call sites: the Demucs worker, the vocal-split worker, and ffprobe on
upload, where the same trap would have failed an upload rather than a
separation.

Pre-existing and unrelated to any feature work. It surfaced now only because
error_detail started carrying the message (#434) instead of the bare word
'unknown'.
---
 app/api/jobs.py                   |  5 +++
 app/pipeline/separate.py          | 13 ++++++
 app/pipeline/vocal_split.py       | 13 ++++++
 tests/test_subprocess_encoding.py | 68 +++++++++++++++++++++++++++++++
 4 files changed, 99 insertions(+)
 create mode 100644 tests/test_subprocess_encoding.py

diff --git a/app/api/jobs.py b/app/api/jobs.py
index 247c68f0..bc68918f 100644
--- a/app/api/jobs.py
+++ b/app/api/jobs.py
@@ -76,7 +76,12 @@ def _probe_duration(path: Path) -> float:
             str(path),
         ],
         capture_output=True,
+        # See the note in pipeline/separate.py: text=True alone decodes with the
+        # Windows locale encoding and a stray byte in ffprobe's output would
+        # fail the upload outright.
         text=True,
+        encoding="utf-8",
+        errors="replace",
         timeout=30,
     )
     if result.returncode != 0:
diff --git a/app/pipeline/separate.py b/app/pipeline/separate.py
index b086643b..609ff3d0 100644
--- a/app/pipeline/separate.py
+++ b/app/pipeline/separate.py
@@ -64,6 +64,12 @@ def _get_worker(device: str) -> subprocess.Popen:
     # exits when we are gone, so it cannot be left holding a GPU after a kill
     # that ran no cleanup (SIGKILL, Force Quit, Task Manager, a crash).
     env["STEMDECK_PARENT_PID"] = str(os.getpid())
+    # Pin the child's stdio encoding to match what the parent now decodes with.
+    # Without it a Windows child writes cp1252 while the parent reads utf-8, so
+    # the mismatch simply moves rather than being fixed. Demucs and audio-
+    # separator both emit progress bars and can echo track metadata, neither of
+    # which is guaranteed to be cp1252-safe.
+    env["PYTHONIOENCODING"] = "utf-8:replace"
     try:
         import certifi
 
@@ -77,7 +83,14 @@ def _get_worker(device: str) -> subprocess.Popen:
         stdin=subprocess.PIPE,
         stdout=subprocess.DEVNULL,
         stderr=subprocess.PIPE,
+        # utf-8/replace explicitly. text=True alone decodes with the locale
+        # encoding, which on Windows is cp1252, and a single byte outside it
+        # in a child's output kills the whole job with a UnicodeDecodeError
+        # ("'charmap' codec can't decode byte 0x8f"). This is diagnostic text:
+        # a byte we cannot read is never a reason to fail a separation.
         text=True,
+        encoding="utf-8",
+        errors="replace",
         bufsize=1,
         env=env,
     )
diff --git a/app/pipeline/vocal_split.py b/app/pipeline/vocal_split.py
index e007a274..65cb224e 100644
--- a/app/pipeline/vocal_split.py
+++ b/app/pipeline/vocal_split.py
@@ -56,6 +56,12 @@ def split_vocals(job: Job, stems_dir: Path) -> list[str]:
 
     device = get_demucs_device()
     env = os.environ.copy()
+    # Pin the child's stdio encoding to match what the parent now decodes with.
+    # Without it a Windows child writes cp1252 while the parent reads utf-8, so
+    # the mismatch simply moves rather than being fixed. Demucs and audio-
+    # separator both emit progress bars and can echo track metadata, neither of
+    # which is guaranteed to be cp1252-safe.
+    env["PYTHONIOENCODING"] = "utf-8:replace"
     try:
         import certifi
 
@@ -68,7 +74,14 @@ def split_vocals(job: Job, stems_dir: Path) -> list[str]:
         _spawn_cmd(device, vocals_path, stems_dir),
         stdout=subprocess.DEVNULL,
         stderr=subprocess.PIPE,
+        # utf-8/replace explicitly. text=True alone decodes with the locale
+        # encoding, which on Windows is cp1252, and a single byte outside it
+        # in a child's output kills the whole job with a UnicodeDecodeError
+        # ("'charmap' codec can't decode byte 0x8f"). This is diagnostic text:
+        # a byte we cannot read is never a reason to fail a separation.
         text=True,
+        encoding="utf-8",
+        errors="replace",
         bufsize=1,
         env=env,
     )
diff --git a/tests/test_subprocess_encoding.py b/tests/test_subprocess_encoding.py
new file mode 100644
index 00000000..f0806e4d
--- /dev/null
+++ b/tests/test_subprocess_encoding.py
@@ -0,0 +1,68 @@
+"""Child process output must never be able to fail a job by being unreadable.
+
+`text=True` on its own decodes with the locale encoding. On Windows that is
+cp1252, so a single byte outside it in Demucs' or ffprobe's output raised
+
+    'charmap' codec can't decode byte 0x8f in position 20
+
+and killed the whole separation. The output in question is a progress bar and
+some echoed metadata: diagnostic text that is never worth failing a job over.
+
+Both halves have to agree. The parent reads utf-8 with errors="replace", and
+the child is told to write utf-8, or the mismatch just moves.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+SITES = [
+    ("app/pipeline/separate.py", "the Demucs worker"),
+    ("app/pipeline/vocal_split.py", "the vocal-split worker"),
+    ("app/api/jobs.py", "ffprobe on upload"),
+]
+
+
+@pytest.mark.parametrize(("path", "what"), SITES)
+def test_decoding_is_pinned_not_left_to_the_locale(path: str, what: str):
+    src = Path(path).read_text(encoding="utf-8")
+    assert "text=True" in src, f"{path} no longer spawns a text-mode child; update this test"
+    assert 'encoding="utf-8"' in src, f"{what} decodes with the locale encoding, not utf-8"
+    assert 'errors="replace"' in src, f"{what} would still raise on an undecodable byte"
+
+
+@pytest.mark.parametrize("path", ["app/pipeline/separate.py", "app/pipeline/vocal_split.py"])
+def test_children_are_told_to_write_utf8(path: str):
+    """The parent reading utf-8 is only half of it."""
+    src = Path(path).read_text(encoding="utf-8")
+    assert "PYTHONIOENCODING" in src, f"{path} lets the child pick its own stdio encoding"
+
+
+def test_a_byte_outside_cp1252_survives_a_round_trip():
+    """The actual failure, reproduced. 0x8f is undefined in cp1252, so the old
+    configuration raised here instead of returning a string."""
+    payload = b"progress: \x8f\x9d\x81 50%\n"
+
+    with pytest.raises(UnicodeDecodeError):
+        payload.decode("cp1252")
+
+    # What the code does now.
+    assert payload.decode("utf-8", errors="replace")
+
+
+def test_ffprobe_duration_survives_undecodable_output():
+    """A stray byte on stderr must not stop a valid duration being read."""
+    from app.api import jobs as jobs_mod
+
+    def fake_run(cmd, **kwargs):
+        assert kwargs.get("encoding") == "utf-8"
+        assert kwargs.get("errors") == "replace"
+        # Exactly what a text-mode pipe hands back once errors="replace" is on.
+        return subprocess.CompletedProcess(cmd, 0, "212.5\n", "warn ��\n")
+
+    with patch.object(jobs_mod.subprocess, "run", fake_run):
+        assert jobs_mod._probe_duration(Path("whatever.mp3")) == 212.5

From c1001a2dc8802aaed766c2b522209d97c87795b2 Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:03:24 +0100
Subject: [PATCH 02/11] Search YouTube and SoundCloud from the topbar

The box already took a pasted link. Typing anything that is not a link now
searches instead, so finding a track no longer means leaving StemDeck,
finding it in a browser, and coming back with a URL.

Three tabs: YouTube songs, YouTube playlists, SoundCloud songs. SoundCloud
playlists is deliberately absent, because yt-dlp exposes exactly one
SoundCloud search key (scsearch, tracks only) and a tab that can only ever
be empty is worse than no tab.

Cost, measured rather than assumed. A search is one flat extraction, about
1.1 s for YouTube and 2.0 s for SoundCloud, and it returns titles,
durations, uploaders and thumbnails for the whole page at once. Requests
fire on a word boundary rather than a keystroke, so typing a full phrase
costs one request, not one per character. An AbortController cancels the
superseded request so results cannot land out of order. A 60 s server cache
absorbs the repeats that backspacing produces. A semaphore caps concurrent
yt-dlp searches, because an aborted fetch does not stop a thread that has
already started.

The duration limit is part of the cache key, not just the payload. It
decides each result's too_long verdict and it is a live setting: raising it
has to un-grey the rows now, not once a 60 s entry expires.

Over that limit the pipeline refuses the job outright, so those rows are not
selectable and say so. This reads the user's configured value, which is
anywhere from 1 to 60 minutes, not a hardcoded 20.

The SSRF boundary from #173 is unchanged. Each search gets the narrowest
extractor allowlist that can serve it, generic stays out of all of them, and
every result goes back through validate_youtube_url or validate_playlist_url
before it can reach the pipeline. Anything that fails is dropped rather than
shown. SoundCloud needs webpage_url rather than url for this: its search
returns an api.soundcloud.com endpoint that is not on the allowlisted host
set, so reading url first (as expand_playlist does) drops every result.

Picking a result fills the box and stops there. Extraction is minutes of
work, so it stays behind a deliberate press of Split stems rather than
starting on a click in a list the user may still be reading.

The panel lives on body rather than in the composer, which sets
overflow:hidden for its rounded pill and clipped the dropdown out of
existence. The topbar input is type=text now, since type=url marks a search
query invalid and blocks submission; its styling keys off #url rather than
the type so that cannot silently unstyle it again.
---
 app/api/router.py      |   2 +
 app/api/search.py      | 234 ++++++++++++++++++
 app/pipeline/search.py | 175 +++++++++++++
 static/css/daw.css     | 114 ++++++++-
 static/index.html      |   9 +-
 static/js/i18n.js      | 112 ++++++++-
 static/js/main.js      |  16 ++
 static/js/search.js    | 542 +++++++++++++++++++++++++++++++++++++++++
 tests/test_search.py   | 391 +++++++++++++++++++++++++++++
 9 files changed, 1582 insertions(+), 13 deletions(-)
 create mode 100644 app/api/search.py
 create mode 100644 app/pipeline/search.py
 create mode 100644 static/js/search.js
 create mode 100644 tests/test_search.py

diff --git a/app/api/router.py b/app/api/router.py
index f0d46929..3232a5a6 100644
--- a/app/api/router.py
+++ b/app/api/router.py
@@ -8,6 +8,7 @@
 from app.api.playlist import router as playlist_router
 from app.api.qr import router as qr_router
 from app.api.queue import router as queue_router
+from app.api.search import router as search_router
 from app.api.stems import router as stems_router
 
 router = APIRouter()
@@ -18,3 +19,4 @@
 router.include_router(qr_router, tags=["qr"])
 router.include_router(queue_router, prefix="/queue", tags=["queue"])
 router.include_router(playlist_router, prefix="/playlist", tags=["playlist"])
+router.include_router(search_router, prefix="/search", tags=["search"])
diff --git a/app/api/search.py b/app/api/search.py
new file mode 100644
index 00000000..0ea64890
--- /dev/null
+++ b/app/api/search.py
@@ -0,0 +1,234 @@
+"""Search endpoint for the topbar.
+
+Fired while the user types, so the two things that matter are not spending a
+round trip when an identical one just happened, and not letting a burst of
+typing spawn unbounded work.
+
+  * A short TTL cache absorbs the repeats. Word-boundary triggering means
+    "daft", "daft punk", "daft punk around" are three separate queries, and
+    backspacing walks straight back through them. A 60 s window turns the
+    revisits into cache hits.
+  * A semaphore caps how many yt-dlp searches can be in flight. The client
+    aborts superseded requests, but an abort does not stop a thread that has
+    already started, so the cap is what actually bounds the work.
+
+Neither is a substitute for the client debouncing. Both exist because the
+client cannot be trusted to be the only caller.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+import urllib.error
+import urllib.request
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel, Field
+
+from app.core.settings import get_max_duration_sec
+from app.pipeline.download import InvalidYouTubeURL
+from app.pipeline.preview import PreviewUnavailable
+from app.pipeline.preview import resolve as resolve_preview
+from app.pipeline.search import (
+    DEFAULT_LIMIT,
+    KINDS,
+    MAX_LIMIT,
+    MIN_QUERY_LEN,
+    SOURCES,
+    UnsupportedSearch,
+    search,
+    supported,
+)
+
+logger = logging.getLogger("stemdeck.api")
+
+router = APIRouter(tags=["search"])
+
+# yt-dlp searches are ~1-2 s of blocking network I/O each. Three at once keeps
+# a fast typist responsive without turning the thread pool into a queue of
+# results nobody is waiting for any more.
+_MAX_CONCURRENT = 3
+_semaphore = asyncio.Semaphore(_MAX_CONCURRENT)
+
+_CACHE_TTL_SEC = 60.0
+_CACHE_MAX = 128
+# key -> (expires_at, payload). Plain dict rather than functools.lru_cache: the
+# entries expire on time, not on eviction pressure alone, and search results go
+# stale in a way that a pure LRU would happily serve forever.
+_cache: dict[tuple, tuple[float, dict]] = {}
+
+
+class SearchRequest(BaseModel):
+    query: str = Field(min_length=MIN_QUERY_LEN, max_length=200)
+    source: str = "youtube"
+    kind: str = "track"
+    limit: int = Field(default=DEFAULT_LIMIT, ge=1, le=MAX_LIMIT)
+
+
+def _cache_get(key: tuple) -> dict | None:
+    hit = _cache.get(key)
+    if hit is None:
+        return None
+    expires_at, payload = hit
+    if expires_at < time.monotonic():
+        _cache.pop(key, None)
+        return None
+    return payload
+
+
+def _cache_put(key: tuple, payload: dict) -> None:
+    if len(_cache) >= _CACHE_MAX:
+        # Drop whatever expires soonest. Cheap at this size, and it sheds the
+        # entries closest to being useless rather than an arbitrary one.
+        oldest = min(_cache, key=lambda k: _cache[k][0])
+        _cache.pop(oldest, None)
+    _cache[key] = (time.monotonic() + _CACHE_TTL_SEC, payload)
+
+
+def _clear_cache() -> None:
+    """Test hook. Results are per-process and disposable, so nothing else needs
+    to reach in here."""
+    _cache.clear()
+
+
+@router.post("")
+async def search_sources(request: Request) -> dict:
+    try:
+        body = await request.json()
+    except Exception as e:
+        raise HTTPException(status_code=422, detail=f"Invalid JSON: {e}") from e
+    try:
+        payload = SearchRequest(**body)
+    except Exception as e:
+        raise HTTPException(status_code=422, detail=str(e)) from e
+
+    if payload.source not in SOURCES or payload.kind not in KINDS:
+        raise HTTPException(status_code=422, detail="unknown source or kind")
+    if not supported(payload.source, payload.kind):
+        raise HTTPException(
+            status_code=422,
+            detail=f"{payload.source} has no {payload.kind} search",
+        )
+
+    query = payload.query.strip()
+    # The duration limit is part of the key, not just part of the payload. It
+    # decides each result's too_long verdict, and it is a live setting: raising
+    # it in Settings has to un-grey the rows now, not once a 60 s entry expires.
+    key = (
+        payload.source,
+        payload.kind,
+        query.casefold(),
+        payload.limit,
+        get_max_duration_sec(),
+    )
+    cached = _cache_get(key)
+    if cached is not None:
+        return {**cached, "cached": True}
+
+    try:
+        async with _semaphore:
+            # Re-check: while queued behind the semaphore, an identical search
+            # may have finished and filled the cache. Common when a burst of
+            # keystrokes produces the same query twice.
+            cached = _cache_get(key)
+            if cached is not None:
+                return {**cached, "cached": True}
+            result = await asyncio.to_thread(
+                search, query, payload.source, payload.kind, payload.limit
+            )
+    except UnsupportedSearch as e:
+        raise HTTPException(status_code=422, detail=str(e)) from e
+    except Exception as e:
+        logger.exception("search failed")
+        raise HTTPException(status_code=502, detail="Could not reach that service") from e
+
+    _cache_put(key, result)
+    return {**result, "cached": False}
+
+
+@router.get("/sources")
+def search_sources_available() -> dict:
+    """Which source/kind pairs actually return anything, so the UI does not
+    offer a SoundCloud playlist tab that can only ever be empty."""
+    return {
+        "sources": [{"source": s, "kinds": [k for k in KINDS if supported(s, k)]} for s in SOURCES]
+    }
+
+
+# Preview audio is proxied, never redirected: the CSP allows `media-src 'self'`
+# only, and widening it so an <audio> tag could reach googlevideo.com would let
+# any injected string in the webview pull media from anywhere.
+#
+# Two previews at once is already generous for an audition button, and each one
+# holds a socket open for as long as it plays.
+_PREVIEW_CONCURRENCY = 2
+_preview_semaphore = asyncio.Semaphore(_PREVIEW_CONCURRENCY)
+
+# Big enough that a normal listen is a handful of reads, small enough that
+# abandoning a preview stops promptly.
+_CHUNK = 64 * 1024
+
+_PREVIEW_TIMEOUT_SEC = 20
+
+
+def _proxy(stream: dict, range_header: str | None):
+    """Open the upstream stream and yield it in chunks.
+
+    Range is forwarded rather than swallowed, so seeking the time bar costs one
+    short request instead of pulling the track from the beginning again.
+    """
+    req = urllib.request.Request(stream["url"], headers=dict(stream["headers"]))
+    if range_header:
+        req.add_header("Range", range_header)
+    upstream = urllib.request.urlopen(req, timeout=_PREVIEW_TIMEOUT_SEC)
+
+    def body():
+        try:
+            while True:
+                chunk = upstream.read(_CHUNK)
+                if not chunk:
+                    return
+                yield chunk
+        except (BrokenPipeError, ConnectionResetError, GeneratorExit):
+            # The listener closed the tab or hit pause and seeked away. Normal.
+            return
+        finally:
+            upstream.close()
+
+    return upstream, body
+
+
+@router.get("/preview")
+async def preview(url: str, request: Request):
+    """Stream a search result's audio so it can be auditioned before import."""
+    try:
+        stream = await asyncio.to_thread(resolve_preview, url)
+    except InvalidYouTubeURL as e:
+        raise HTTPException(status_code=422, detail=str(e)) from e
+    except PreviewUnavailable as e:
+        raise HTTPException(status_code=404, detail="No preview available for this track") from e
+    except Exception as e:
+        logger.exception("preview resolve failed")
+        raise HTTPException(status_code=502, detail="Could not load a preview") from e
+
+    range_header = request.headers.get("range")
+    try:
+        async with _preview_semaphore:
+            upstream, body = await asyncio.to_thread(_proxy, stream, range_header)
+    except urllib.error.HTTPError as e:
+        # A signed URL that expired between resolve and play, most often.
+        raise HTTPException(status_code=502, detail="Could not load a preview") from e
+    except Exception as e:
+        logger.exception("preview proxy failed")
+        raise HTTPException(status_code=502, detail="Could not load a preview") from e
+
+    status = upstream.status if upstream.status in (200, 206) else 200
+    headers = {"Accept-Ranges": "bytes", "Cache-Control": "no-store"}
+    for name in ("Content-Range", "Content-Length"):
+        value = upstream.headers.get(name)
+        if value:
+            headers[name] = value
+    return StreamingResponse(body(), status_code=status, media_type=stream["mime"], headers=headers)
diff --git a/app/pipeline/search.py b/app/pipeline/search.py
new file mode 100644
index 00000000..de47b122
--- /dev/null
+++ b/app/pipeline/search.py
@@ -0,0 +1,175 @@
+"""Search YouTube and SoundCloud for something to import.
+
+The topbar already takes a pasted link. This lets it take a query instead, so
+finding a track does not mean leaving StemDeck, finding it in a browser, and
+coming back with a URL.
+
+Two things make this cheap enough to run while the user types:
+
+  * Flat extraction. One request returns titles, durations, uploaders and
+    thumbnails for the whole page of results, with no per-result round trip.
+    Measured at roughly 1.1 s for YouTube and 2.0 s for SoundCloud.
+  * Every result is a URL we already know how to validate, so nothing new has
+    to be trusted. Results go back through validate_youtube_url /
+    validate_playlist_url exactly as playlist entries do (#173), and anything
+    that fails is dropped rather than shown.
+
+The SSRF boundary is unchanged. Each search gets the narrowest extractor
+allowlist that can serve it, and "generic" stays out of all of them.
+"""
+
+from __future__ import annotations
+
+import logging
+import urllib.parse
+
+from yt_dlp import YoutubeDL
+
+from app.core.settings import get_max_duration_sec
+from app.pipeline.download import (
+    InvalidPlaylistURL,
+    InvalidYouTubeURL,
+    _base_ydl_opts,
+    validate_playlist_url,
+    validate_youtube_url,
+)
+
+logger = logging.getLogger("stemdeck.search")
+
+SOURCES = ("youtube", "soundcloud")
+KINDS = ("track", "playlist")
+
+# Enough to fill a dropdown without scrolling forever. Each result costs
+# nothing extra (one request returns all of them), but the JSON and the DOM do.
+DEFAULT_LIMIT = 8
+MAX_LIMIT = 15
+
+# Below this a query is too vague to be worth a round trip to YouTube.
+MIN_QUERY_LEN = 2
+MAX_QUERY_LEN = 200
+
+# YouTube's own "Playlist" search filter, from the sp= parameter on the results
+# page. There is no ytsearch: prefix for playlists, so the search URL extractor
+# is the only route to them.
+_YT_PLAYLIST_FILTER = "EgIQAw%3D%3D"
+
+# One allowlist per (source, kind). Deliberately separate rather than one union:
+# playlist search needs the tab extractor and track search must not have it.
+_EXTRACTORS = {
+    ("youtube", "track"): ["youtube:search", "youtube"],
+    ("youtube", "playlist"): ["youtube:search_url", "youtube:tab", "youtube:playlist", "youtube"],
+    ("soundcloud", "track"): ["soundcloud:search", "soundcloud"],
+}
+
+
+class UnsupportedSearch(ValueError):
+    """The requested source/kind pair has no search behind it."""
+
+
+def supported(source: str, kind: str) -> bool:
+    """SoundCloud has no playlist search: yt-dlp exposes exactly one search key
+    for it (scsearch, tracks only). The UI uses this to not offer a tab that
+    cannot return anything."""
+    return (source, kind) in _EXTRACTORS
+
+
+def _target(source: str, kind: str, query: str, limit: int) -> str:
+    if source == "youtube" and kind == "playlist":
+        q = urllib.parse.quote(query)
+        return f"https://www.youtube.com/results?search_query={q}&sp={_YT_PLAYLIST_FILTER}"
+    prefix = "ytsearch" if source == "youtube" else "scsearch"
+    return f"{prefix}{limit}:{query}"
+
+
+def _entry_url(entry: dict, kind: str) -> str | None:
+    """The importable URL for a result, or None if there is not one.
+
+    Order matters and differs from expand_playlist's. SoundCloud search returns
+    `url` as an api.soundcloud.com endpoint, which is not on the allowlisted
+    host set and is rejected on sight; the real permalink is in `webpage_url`.
+    Reading `url` first, as playlist expansion does, silently drops every
+    SoundCloud result.
+    """
+    for key in ("webpage_url", "url"):
+        raw = entry.get(key)
+        if not isinstance(raw, str) or not raw:
+            continue
+        try:
+            return validate_playlist_url(raw) if kind == "playlist" else validate_youtube_url(raw)
+        except (InvalidYouTubeURL, InvalidPlaylistURL):
+            continue
+    return None
+
+
+def _thumbnail(entry: dict) -> str | None:
+    """Smallest usable thumbnail. The dropdown renders these at ~64px wide, so
+    pulling the 720p variant would cost bandwidth and decode time for nothing."""
+    if isinstance(entry.get("thumbnail"), str):
+        return entry["thumbnail"]
+    thumbs = [t for t in (entry.get("thumbnails") or []) if isinstance(t, dict) and t.get("url")]
+    if not thumbs:
+        return None
+    thumbs.sort(key=lambda t: t.get("width") or 0)
+    for t in thumbs:
+        if (t.get("width") or 0) >= 120:
+            return t["url"]
+    return thumbs[-1]["url"]
+
+
+def search(query: str, source: str, kind: str, limit: int = DEFAULT_LIMIT) -> dict:
+    """Run one search and return normalised results.
+
+    Blocking: yt-dlp does network I/O. Callers must keep this off the event
+    loop (see app/api/search.py).
+    """
+    query = (query or "").strip()
+    if len(query) < MIN_QUERY_LEN:
+        raise UnsupportedSearch("query is too short")
+    query = query[:MAX_QUERY_LEN]
+    if source not in SOURCES or kind not in KINDS:
+        raise UnsupportedSearch("unknown source or kind")
+    if not supported(source, kind):
+        raise UnsupportedSearch(f"{source} has no {kind} search")
+
+    limit = max(1, min(MAX_LIMIT, int(limit)))
+    opts = {
+        **_base_ydl_opts(_EXTRACTORS[(source, kind)]),
+        "extract_flat": "in_playlist",
+        "skip_download": True,
+        "noprogress": True,
+        # Only meaningful for the search-URL route, which has no count in the
+        # target string the way ytsearchN:/scsearchN: do.
+        "playlistend": limit,
+    }
+
+    with YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(_target(source, kind, query, limit), download=False) or {}
+
+    max_duration = get_max_duration_sec()
+    items: list[dict] = []
+    for entry in info.get("entries") or []:
+        if not isinstance(entry, dict):
+            continue
+        url = _entry_url(entry, kind)
+        if not url:
+            continue
+        duration = entry.get("duration")
+        duration = float(duration) if isinstance(duration, int | float) else None
+        items.append(
+            {
+                "url": url,
+                "title": (entry.get("title") or "").strip() or url,
+                "duration": duration,
+                "uploader": (entry.get("uploader") or entry.get("channel") or "").strip() or None,
+                "thumbnail": _thumbnail(entry),
+                # Computed here rather than in the client so the limit is read
+                # from one place. Over it, the pipeline refuses the job outright
+                # (download.py), so the UI has to say "cannot import", not
+                # "this may be slow".
+                "too_long": duration is not None and duration > max_duration,
+            }
+        )
+        if len(items) >= limit:
+            break
+
+    return {"items": items, "max_duration_sec": max_duration}
diff --git a/static/css/daw.css b/static/css/daw.css
index 83c8179e..49b8c9c2 100644
--- a/static/css/daw.css
+++ b/static/css/daw.css
@@ -110,7 +110,10 @@ input, textarea { font-family: inherit; }
 .daw-process-btn > svg { display: none; }
 .daw-url-zone svg { flex-shrink: 0; }
 
-.daw-url-zone input[type="url"] {
+/* Keyed off the id, not the type. This input is type="text" so a search
+   query is not marked invalid; an attribute selector here silently drops
+   every rule the moment that changes. */
+.daw-url-zone #url {
   flex: 1;
   min-width: 0;
   background: none;
@@ -121,7 +124,7 @@ input, textarea { font-family: inherit; }
   font-family: inherit;
   letter-spacing: -0.005em;
 }
-.daw-url-zone input[type="url"]::placeholder { color: var(--muted); }
+.daw-url-zone #url::placeholder { color: var(--muted); }
 
 /* Upload button inside URL zone */
 .daw-upload-btn {
@@ -173,7 +176,7 @@ input, textarea { font-family: inherit; }
   background: rgba(244,183,64,0.06);
   box-shadow: inset 0 0 0 1px rgba(244,183,64,0.3);
 }
-.daw-url-zone.has-file input[type="url"] { display: none; }
+.daw-url-zone.has-file #url { display: none; }
 
 /* Composer vertical divider */
 .daw-composer-sep {
@@ -2612,6 +2615,111 @@ input, textarea { font-family: inherit; }
 .export-click-opt.disabled { opacity: 0.4; cursor: not-allowed; }
 .export-click-opt.disabled:hover { background: none; color: var(--fg-2); }
 
+/* ── Live search dropdown (topbar) ────────────────────────────────
+   Anchored to .url-wrap, which is position:relative already for the drag
+   overlay. contain:layout paint keeps a long result list from forcing the
+   composer above it to re-layout while rows stream in. */
+/* Lives on <body>, not in .url-wrap: the composer clips its children
+   (overflow:hidden for the rounded pill), which made an absolutely positioned
+   panel invisible. JS sets left/top/width from the composer's rect. */
+.search-panel {
+  position: fixed; z-index: 300;
+  background: var(--panel); border: 1px solid var(--border-strong);
+  border-radius: 10px; box-shadow: 0 12px 32px rgba(0,0,0,0.42);
+  overflow: hidden; contain: layout paint;
+}
+.search-panel.hidden { display: none; }
+.search-tabs { display: flex; gap: 2px; padding: 5px; border-bottom: 1px solid var(--border); }
+.search-tab {
+  flex: 1; border: 0; background: transparent; cursor: pointer;
+  padding: 5px 8px; border-radius: 6px; color: var(--muted);
+  font-size: 11px; font-weight: 600; white-space: nowrap;
+  transition: background var(--t-fast), color var(--t-fast);
+}
+.search-tab:hover { background: var(--panel-3); color: var(--fg); }
+.search-tab.active { background: var(--panel-3); color: var(--accent); }
+.search-status { padding: 12px 12px; font-size: 11.5px; color: var(--muted); }
+.search-status.hidden { display: none; }
+.search-list {
+  list-style: none; margin: 0; padding: 4px;
+  max-height: 340px; overflow-y: auto; overscroll-behavior: contain;
+}
+.search-row {
+  display: flex; flex-direction: column;
+  padding: 6px; border-radius: 7px; cursor: pointer;
+}
+.search-row-main { display: flex; align-items: center; gap: 9px; }
+.search-row:hover, .search-row.active { background: var(--panel-3); }
+.search-thumb {
+  flex-shrink: 0; width: 64px; height: 36px; object-fit: cover;
+  border-radius: 4px; background: var(--panel-2);
+}
+.search-thumb-empty { display: block; }
+.search-text { display: flex; flex-direction: column; gap: 1px; min-width: 0; flex: 1; }
+.search-title {
+  font-size: 12px; font-weight: 600; color: var(--fg);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.search-meta {
+  font-size: 10.5px; color: var(--muted);
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+/* Over the duration limit the pipeline refuses the job, so the row is not
+   selectable at all rather than merely warning about it. */
+.search-row.too-long { cursor: not-allowed; opacity: 0.55; }
+.search-row.too-long:hover { background: none; }
+.search-warn {
+  flex-shrink: 0; font-size: 10px; font-weight: 600; color: var(--danger);
+  white-space: nowrap;
+}
+
+/* Audition controls. Hidden until the row is hovered or playing, so a list of
+   eight results is not eight competing buttons. */
+/* A labelled pill, not a bare glyph. An unlabelled circle on a search result
+   reads as "play this result", which is the one thing it does not do: it
+   auditions, it does not select. Always visible for the same reason -- a
+   control you have to hover to discover is not a control most people find. */
+.search-preview-btn {
+  flex-shrink: 0; display: inline-flex; align-items: center; gap: 5px;
+  height: 26px; padding: 0 10px 0 8px;
+  border: 1px solid var(--border-strong); border-radius: 13px;
+  background: var(--panel-2); color: var(--fg-2); cursor: pointer;
+  font-family: inherit; font-size: 10.5px; font-weight: 600;
+  letter-spacing: 0.01em; white-space: nowrap;
+  opacity: 0.75;
+  transition: opacity var(--t-fast), color var(--t-fast),
+              background var(--t-fast), border-color var(--t-fast);
+}
+.search-row:hover .search-preview-btn,
+.search-row.active .search-preview-btn,
+.search-preview-btn:focus-visible { opacity: 1; }
+.search-preview-btn:hover { background: var(--panel-3); color: var(--fg); border-color: var(--fg-2); }
+.search-preview-btn.playing {
+  opacity: 1; color: var(--accent); border-color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 12%, transparent);
+}
+
+.search-player {
+  display: flex; align-items: center; gap: 9px;
+  margin: 7px 2px 1px; padding-left: 73px; cursor: default;
+}
+.search-player.loading .search-seek { opacity: 0.4; }
+.search-player.failed .search-clock { color: var(--danger); }
+.search-play {
+  flex-shrink: 0; width: 24px; height: 24px;
+  display: flex; align-items: center; justify-content: center;
+  border: 0; border-radius: 50%;
+  background: var(--accent); color: #0b1118; cursor: pointer;
+}
+.search-seek {
+  flex: 1; min-width: 0; height: 4px; accent-color: var(--accent);
+  cursor: pointer;
+}
+.search-clock {
+  flex-shrink: 0; font-family: var(--font-mono); font-size: 10px;
+  color: var(--muted); font-variant-numeric: tabular-nums;
+}
+
 .export-fmt-video { display: none; }
 #footer-export-wrap.has-video .export-fmt-video { display: block; flex: 1; }
 
diff --git a/static/index.html b/static/index.html
index e4d1e715..dafd68e6 100644
--- a/static/index.html
+++ b/static/index.html
@@ -36,10 +36,15 @@
             <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="var(--muted)" stroke-width="1.8" style="flex-shrink:0" aria-hidden="true">
               <path d="M10 14a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1 M14 10a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1"/>
             </svg>
+            <!-- type="text", not "url": this box takes a search query as well as a
+                 link, and type="url" marks a query invalid, which blocks form
+                 submission. A pasted link is validated server-side either way
+                 (validate_youtube_url). The topbar styling keys off #url, not
+                 the type, so it survives this. -->
             <input
               id="url"
-              type="url"
-              placeholder="Paste a YouTube or SoundCloud link, or drop an audio file…"
+              type="text"
+              placeholder="Search, or paste a YouTube or SoundCloud link, or drop an audio file…"
               data-i18n-placeholder="topbar.urlPlaceholder"
               spellcheck="false"
               autocomplete="off"
diff --git a/static/js/i18n.js b/static/js/i18n.js
index d463da16..8efa8192 100644
--- a/static/js/i18n.js
+++ b/static/js/i18n.js
@@ -184,7 +184,7 @@ function applyStemRowAriaLabels(scope) {
 const en = {
   "doc.title": "StemDeck — split any track into stems",
 
-  "topbar.urlPlaceholder": "Paste a YouTube or SoundCloud link, or drop an audio file…",
+  "topbar.urlPlaceholder": "Search, or paste a YouTube or SoundCloud link, or drop an audio file…",
   "topbar.removeFile": "Remove file",
   "topbar.uploadFile": "Upload audio file",
   "extract.label": "Extract",
@@ -235,6 +235,18 @@ const en = {
 
   "search.ariaLabel": "Search library",
   "search.placeholder": "Search or #tag…",
+  "search.tab.ytSongs": "YouTube songs",
+  "search.tab.ytPlaylists": "YouTube playlists",
+  "search.tab.scSongs": "SoundCloud songs",
+  "search.searching": "Searching…",
+  "search.noResults": "No results",
+  "search.failed": "Search failed. Check your connection.",
+  "search.tooLong": "Over {mins} min limit",
+  "search.preview": "Preview",
+  "search.play": "Play",
+  "search.pause": "Pause",
+  "search.seek": "Seek",
+  "search.previewFailed": "Preview unavailable",
   "search.tagSuggestions": "Tag suggestions",
   "search.placeholderLibrary": "Search library…",
   "search.placeholderFavorites": "Search favorites…",
@@ -695,7 +707,7 @@ const en = {
 const pl = {
   "doc.title": "StemDeck — rozdziel dowolny utwór na ścieżki",
 
-  "topbar.urlPlaceholder": "Wklej link YouTube lub SoundCloud albo upuść plik audio…",
+  "topbar.urlPlaceholder": "Szukaj albo wklej link YouTube lub SoundCloud, albo upuść plik audio…",
   "topbar.removeFile": "Usuń plik",
   "topbar.uploadFile": "Wgraj plik audio",
   "extract.label": "Wyodrębnij",
@@ -746,6 +758,18 @@ const pl = {
 
   "search.ariaLabel": "Szukaj w bibliotece",
   "search.placeholder": "Szukaj lub #tag…",
+  "search.tab.ytSongs": "Utwory YouTube",
+  "search.tab.ytPlaylists": "Playlisty YouTube",
+  "search.tab.scSongs": "Utwory SoundCloud",
+  "search.searching": "Szukanie…",
+  "search.noResults": "Brak wyników",
+  "search.failed": "Wyszukiwanie nie powiodło się. Sprawdź połączenie.",
+  "search.tooLong": "Ponad limit {mins} min",
+  "search.preview": "Odsłuch",
+  "search.play": "Odtwórz",
+  "search.pause": "Pauza",
+  "search.seek": "Przewiń",
+  "search.previewFailed": "Odsłuch niedostępny",
   "search.tagSuggestions": "Podpowiedzi tagów",
   "search.placeholderLibrary": "Szukaj w bibliotece…",
   "search.placeholderFavorites": "Szukaj w ulubionych…",
@@ -1196,7 +1220,7 @@ const pl = {
 const ja = {
   "doc.title": "StemDeck — トラックをパートごとに分離",
 
-  "topbar.urlPlaceholder": "YouTubeやSoundCloudのリンクを貼り付けるか、音声ファイルをドロップ…",
+  "topbar.urlPlaceholder": "検索するか、YouTube・SoundCloud のリンクを貼り付けるか、音声ファイルをドロップ…",
   "topbar.removeFile": "ファイルを削除",
   "topbar.uploadFile": "音声ファイルをアップロード",
   "extract.label": "抽出",
@@ -1247,6 +1271,18 @@ const ja = {
 
   "search.ariaLabel": "ライブラリを検索",
   "search.placeholder": "検索または#タグ…",
+  "search.tab.ytSongs": "YouTube の曲",
+  "search.tab.ytPlaylists": "YouTube のプレイリスト",
+  "search.tab.scSongs": "SoundCloud の曲",
+  "search.searching": "検索中…",
+  "search.noResults": "結果がありません",
+  "search.failed": "検索に失敗しました。接続を確認してください。",
+  "search.tooLong": "{mins} 分の上限超過",
+  "search.preview": "試聴",
+  "search.play": "再生",
+  "search.pause": "一時停止",
+  "search.seek": "シーク",
+  "search.previewFailed": "試聴できません",
   "search.tagSuggestions": "タグ候補",
   "search.placeholderLibrary": "ライブラリを検索…",
   "search.placeholderFavorites": "お気に入りを検索…",
@@ -1672,7 +1708,7 @@ const ja = {
 const zhHans = {
   "doc.title": "StemDeck — 将任意曲目分离为音轨",
 
-  "topbar.urlPlaceholder": "粘贴 YouTube 或 SoundCloud 链接,或拖放音频文件…",
+  "topbar.urlPlaceholder": "搜索,或粘贴 YouTube 或 SoundCloud 链接,或拖放音频文件…",
   "topbar.removeFile": "移除文件",
   "topbar.uploadFile": "上传音频文件",
   "extract.label": "提取",
@@ -1723,6 +1759,18 @@ const zhHans = {
 
   "search.ariaLabel": "搜索资料库",
   "search.placeholder": "搜索或 #标签…",
+  "search.tab.ytSongs": "YouTube 歌曲",
+  "search.tab.ytPlaylists": "YouTube 播放列表",
+  "search.tab.scSongs": "SoundCloud 歌曲",
+  "search.searching": "搜索中…",
+  "search.noResults": "没有结果",
+  "search.failed": "搜索失败，请检查网络连接。",
+  "search.tooLong": "超过 {mins} 分钟上限",
+  "search.preview": "试听",
+  "search.play": "播放",
+  "search.pause": "暂停",
+  "search.seek": "跳转",
+  "search.previewFailed": "无法试听",
   "search.tagSuggestions": "标签建议",
   "search.placeholderLibrary": "搜索资料库…",
   "search.placeholderFavorites": "搜索收藏…",
@@ -2148,7 +2196,7 @@ const zhHans = {
 const de = {
   "doc.title": "StemDeck — jeden Track in Stems zerlegen",
 
-  "topbar.urlPlaceholder": "YouTube- oder SoundCloud-Link einfügen oder Audiodatei ablegen…",
+  "topbar.urlPlaceholder": "Suchen, einen YouTube- oder SoundCloud-Link einfügen oder eine Audiodatei ablegen…",
   "topbar.removeFile": "Datei entfernen",
   "topbar.uploadFile": "Audiodatei hochladen",
   "extract.label": "Extrahieren",
@@ -2199,6 +2247,18 @@ const de = {
 
   "search.ariaLabel": "Bibliothek durchsuchen",
   "search.placeholder": "Suchen oder #Tag…",
+  "search.tab.ytSongs": "YouTube-Titel",
+  "search.tab.ytPlaylists": "YouTube-Playlists",
+  "search.tab.scSongs": "SoundCloud-Titel",
+  "search.searching": "Suche läuft…",
+  "search.noResults": "Keine Ergebnisse",
+  "search.failed": "Suche fehlgeschlagen. Verbindung prüfen.",
+  "search.tooLong": "Über dem Limit von {mins} Min.",
+  "search.preview": "Vorhören",
+  "search.play": "Abspielen",
+  "search.pause": "Pause",
+  "search.seek": "Springen",
+  "search.previewFailed": "Vorhören nicht möglich",
   "search.tagSuggestions": "Tag-Vorschläge",
   "search.placeholderLibrary": "Bibliothek durchsuchen…",
   "search.placeholderFavorites": "Favoriten durchsuchen…",
@@ -2635,7 +2695,7 @@ const de = {
 const pt = {
   "doc.title": "StemDeck — separe qualquer faixa em stems",
 
-  "topbar.urlPlaceholder": "Cole um link do YouTube ou SoundCloud, ou solte um arquivo de áudio…",
+  "topbar.urlPlaceholder": "Pesquise, ou cole um link do YouTube ou SoundCloud, ou solte um arquivo de áudio…",
   "topbar.removeFile": "Remover arquivo",
   "topbar.uploadFile": "Enviar arquivo de áudio",
   "extract.label": "Extrair",
@@ -2686,6 +2746,18 @@ const pt = {
 
   "search.ariaLabel": "Pesquisar biblioteca",
   "search.placeholder": "Pesquisar ou #tag…",
+  "search.tab.ytSongs": "Músicas do YouTube",
+  "search.tab.ytPlaylists": "Playlists do YouTube",
+  "search.tab.scSongs": "Músicas do SoundCloud",
+  "search.searching": "Pesquisando…",
+  "search.noResults": "Nenhum resultado",
+  "search.failed": "A pesquisa falhou. Verifique sua conexão.",
+  "search.tooLong": "Acima do limite de {mins} min",
+  "search.preview": "Prévia",
+  "search.play": "Reproduzir",
+  "search.pause": "Pausar",
+  "search.seek": "Avançar",
+  "search.previewFailed": "Prévia indisponível",
   "search.tagSuggestions": "Sugestões de tags",
   "search.placeholderLibrary": "Pesquisar biblioteca…",
   "search.placeholderFavorites": "Pesquisar favoritos…",
@@ -3124,7 +3196,7 @@ const pt = {
 const id = {
   "doc.title": "StemDeck — pisahkan trek apa pun menjadi stem",
 
-  "topbar.urlPlaceholder": "Tempel tautan YouTube atau SoundCloud, atau seret file audio…",
+  "topbar.urlPlaceholder": "Cari, atau tempel tautan YouTube atau SoundCloud, atau seret file audio…",
   "topbar.removeFile": "Hapus file",
   "topbar.uploadFile": "Unggah file audio",
   "extract.label": "Ekstrak",
@@ -3175,6 +3247,18 @@ const id = {
 
   "search.ariaLabel": "Cari pustaka",
   "search.placeholder": "Cari atau #tag…",
+  "search.tab.ytSongs": "Lagu YouTube",
+  "search.tab.ytPlaylists": "Playlist YouTube",
+  "search.tab.scSongs": "Lagu SoundCloud",
+  "search.searching": "Mencari…",
+  "search.noResults": "Tidak ada hasil",
+  "search.failed": "Pencarian gagal. Periksa koneksi Anda.",
+  "search.tooLong": "Melebihi batas {mins} mnt",
+  "search.preview": "Pratinjau",
+  "search.play": "Putar",
+  "search.pause": "Jeda",
+  "search.seek": "Geser",
+  "search.previewFailed": "Pratinjau tidak tersedia",
   "search.tagSuggestions": "Saran tag",
   "search.placeholderLibrary": "Cari pustaka…",
   "search.placeholderFavorites": "Cari favorit…",
@@ -3600,7 +3684,7 @@ const id = {
 const fr = {
   "doc.title": "StemDeck — séparez n'importe quel morceau en pistes",
 
-  "topbar.urlPlaceholder": "Collez un lien YouTube ou SoundCloud, ou déposez un fichier audio…",
+  "topbar.urlPlaceholder": "Recherchez, ou collez un lien YouTube ou SoundCloud, ou déposez un fichier audio…",
   "topbar.removeFile": "Retirer le fichier",
   "topbar.uploadFile": "Importer un fichier audio",
   "extract.label": "Extraire",
@@ -3651,6 +3735,18 @@ const fr = {
 
   "search.ariaLabel": "Rechercher dans la bibliothèque",
   "search.placeholder": "Rechercher ou #tag…",
+  "search.tab.ytSongs": "Morceaux YouTube",
+  "search.tab.ytPlaylists": "Playlists YouTube",
+  "search.tab.scSongs": "Morceaux SoundCloud",
+  "search.searching": "Recherche…",
+  "search.noResults": "Aucun résultat",
+  "search.failed": "La recherche a échoué. Vérifiez votre connexion.",
+  "search.tooLong": "Au-delà de la limite de {mins} min",
+  "search.preview": "Écouter",
+  "search.play": "Lecture",
+  "search.pause": "Pause",
+  "search.seek": "Naviguer",
+  "search.previewFailed": "Écoute indisponible",
   "search.tagSuggestions": "Suggestions de tags",
   "search.placeholderLibrary": "Rechercher dans la bibliothèque…",
   "search.placeholderFavorites": "Rechercher dans les favoris…",
diff --git a/static/js/main.js b/static/js/main.js
index 1cdccffb..bd76b188 100644
--- a/static/js/main.js
+++ b/static/js/main.js
@@ -6,6 +6,7 @@ import {
 import { STEM_NAMES, syncStemNamesFromAPI } from "./constants.js";
 import { renderEmptyShell, buildStripStems, downloadCurrentMix, downloadCurrentVideo, downloadAllStemsZip, downloadRegionMix, drawFooterPlaceholder } from "./player.js";
 import { wireJobForm, showError } from "./job.js";
+import { initSearch } from "./search.js";
 import { wireTransportButtons } from "./transport.js";
 import { wireBeatGridUi } from "./beatgridUi.js";
 import { togglePlayPause, updateLoopRegionVisual, toggleMetronome } from "./transport.js";
@@ -134,6 +135,21 @@ const i18nReady = initI18n().then(() => applyTranslations(document));
 
 syncStemNamesFromAPI().then(() => buildStripStems());
 wireJobForm();
+// Live search on the topbar box. Picking a result fills the box and stops
+// there: extraction is minutes of work, so it stays behind the deliberate
+// press of Process rather than starting on a click in a list the user may
+// still be reading. The import flow (single track, playlist, capacity, stems)
+// is untouched, and search never learns about any of it.
+initSearch((item) => {
+  const urlInput = document.getElementById("url");
+  if (!urlInput) return;
+  urlInput.value = item.url;
+  // Fire input so anything listening to the box (the drop zone, the file pill)
+  // sees the new value, then leave the caret where a correction would go.
+  urlInput.dispatchEvent(new Event("input", { bubbles: true }));
+  urlInput.focus();
+  urlInput.setSelectionRange(urlInput.value.length, urlInput.value.length);
+});
 wireTransportButtons();
 wireBeatGridUi();
 wireFooterControls();
diff --git a/static/js/search.js b/static/js/search.js
new file mode 100644
index 00000000..6c256d68
--- /dev/null
+++ b/static/js/search.js
@@ -0,0 +1,542 @@
+// Live search in the topbar.
+//
+// The box already takes a pasted link. Typing anything that is not a link now
+// searches instead, so finding a track does not mean leaving StemDeck.
+//
+// Three things keep this from being expensive:
+//
+//   * Requests fire on a word boundary, not a keystroke. Typing "daft punk
+//     around the world" costs one or two requests, not twenty six. A trailing
+//     space fires sooner than a pause, which is what makes it feel live.
+//   * Every request carries an AbortController, and starting one aborts the
+//     last. A superseded response never lands, so results cannot arrive out of
+//     order and overwrite newer ones.
+//   * Rows are built into a DocumentFragment and attached once, with a single
+//     delegated click listener for the whole list. Thumbnails are lazy and
+//     decode off the main thread.
+//
+// The backend caches for 60 s, so walking backwards through a query (which
+// backspacing does constantly) mostly does not hit the network at all.
+
+import { t, applyTranslations, onLanguageChange } from "./i18n.js";
+
+// A pause long enough to mean "stopped typing".
+const IDLE_MS = 450;
+// A finished word is a much better signal than a pause, so it waits far less.
+const WORD_MS = 120;
+const MIN_QUERY = 2;
+const LIMIT = 8;
+// Wide enough for a long title, narrow enough to scan down.
+const MAX_PANEL_PX = 620;
+
+const ICON_PLAY = '<svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true"><path d="M8 5v14l11-7z" fill="currentColor"/></svg>';
+const ICON_PAUSE = '<svg viewBox="0 0 24 24" width="13" height="13" aria-hidden="true"><path d="M6 5h4v14H6zM14 5h4v14h-4z" fill="currentColor"/></svg>';
+
+// One <audio> for the whole panel, not one per row. preload="none" so nothing
+// is fetched until a preview is actually opened, and reusing the element means
+// opening a second preview releases the first connection immediately.
+// The button carries a word, not just a glyph. An unlabelled circle on a
+// search result reads as "play this result", which is exactly the thing it
+// does not do: it auditions, it does not select.
+function setPreviewButton(btn, playing) {
+  if (!btn) return;
+  btn.innerHTML = playing ? ICON_PAUSE : ICON_PLAY;
+  const label = document.createElement("span");
+  label.textContent = t(playing ? "search.pause" : "search.preview");
+  btn.appendChild(label);
+  btn.classList.toggle("playing", playing);
+  btn.setAttribute("aria-label", label.textContent);
+  btn.title = label.textContent;
+}
+
+let audio = null;
+let previewIndex = -1;
+let rafId = 0;
+
+// Anything that could be a link is left alone: it belongs to the import flow,
+// not to search. Deliberately loose. A false positive here costs one search
+// that would have failed anyway, a false negative sends a URL to YouTube as a
+// search term.
+const LOOKS_LIKE_URL = /^\s*(https?:\/\/|www\.)|\b(youtube\.com|youtu\.be|soundcloud\.com)\b/i;
+
+const TABS = [
+  { source: "youtube", kind: "track", labelKey: "search.tab.ytSongs" },
+  { source: "youtube", kind: "playlist", labelKey: "search.tab.ytPlaylists" },
+  { source: "soundcloud", kind: "track", labelKey: "search.tab.scSongs" },
+];
+
+let panel = null;
+let listEl = null;
+let statusEl = null;
+let tabsEl = null;
+let input = null;
+let onPick = null;
+
+let timerId = null;
+let controller = null;
+let activeTab = 0;
+let items = [];
+let cursor = -1;
+let lastQuery = "";
+
+const fmtDuration = (secs) => {
+  if (typeof secs !== "number" || !isFinite(secs) || secs <= 0) return "";
+  const total = Math.round(secs);
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  return h
+    ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`
+    : `${m}:${String(s).padStart(2, "0")}`;
+};
+
+function position() {
+  // Anchored to the composer, not the input, so the panel lines up with the
+  // pill rather than with the text cursor inside it.
+  const anchor = input.closest(".daw-composer") || input;
+  const r = anchor.getBoundingClientRect();
+  // Capped rather than full composer width. On a wide window the composer is
+  // over 1200px, and a result list that wide leaves the title stranded next to
+  // a 64px thumbnail with a screen of empty space after it.
+  const width = Math.min(r.width, MAX_PANEL_PX);
+  panel.style.left = `${Math.round(r.left)}px`;
+  panel.style.top = `${Math.round(r.bottom + 6)}px`;
+  panel.style.width = `${Math.round(width)}px`;
+}
+
+function open() {
+  position();
+  panel.classList.remove("hidden");
+  input.setAttribute("aria-expanded", "true");
+}
+
+function close() {
+  // Nothing is more jarring than a dropdown that vanishes and keeps playing.
+  stopPreview();
+  if (timerId) { clearTimeout(timerId); timerId = null; }
+  controller?.abort();
+  controller = null;
+  items = [];
+  cursor = -1;
+  lastQuery = "";
+  panel?.classList.add("hidden");
+  input?.setAttribute("aria-expanded", "false");
+  input?.removeAttribute("aria-activedescendant");
+}
+
+function setStatus(text) {
+  stopPreview();
+  listEl.textContent = "";
+  statusEl.textContent = text;
+  statusEl.classList.toggle("hidden", !text);
+}
+
+function render(maxDurationSec) {
+  // The rows about to be destroyed own the running preview.
+  stopPreview();
+  statusEl.classList.add("hidden");
+  listEl.textContent = "";
+  if (!items.length) {
+    setStatus(t("search.noResults"));
+    return;
+  }
+  const mins = Math.round((maxDurationSec || 1200) / 60);
+  // One fragment, one insertion. Appending rows individually would lay out the
+  // panel once per row.
+  const frag = document.createDocumentFragment();
+  items.forEach((item, i) => {
+    const row = document.createElement("li");
+    row.className = "search-row";
+    row.setAttribute("role", "option");
+    row.setAttribute("aria-selected", "false");
+    row.id = `search-row-${i}`;
+    row.dataset.index = String(i);
+    if (item.too_long) row.classList.add("too-long");
+
+    // The clickable part. The expanded player lives beside it in the same <li>
+    // so opening a preview does not move the row.
+    const main = document.createElement("div");
+    main.className = "search-row-main";
+
+    if (item.thumbnail) {
+      const img = document.createElement("img");
+      img.className = "search-thumb";
+      img.src = item.thumbnail;
+      img.alt = "";
+      img.loading = "lazy";
+      img.decoding = "async";
+      main.appendChild(img);
+    } else {
+      const ph = document.createElement("span");
+      ph.className = "search-thumb search-thumb-empty";
+      main.appendChild(ph);
+    }
+
+    const text = document.createElement("span");
+    text.className = "search-text";
+    const title = document.createElement("span");
+    title.className = "search-title";
+    title.textContent = item.title;
+    const meta = document.createElement("span");
+    meta.className = "search-meta";
+    const bits = [];
+    if (item.uploader) bits.push(item.uploader);
+    const dur = fmtDuration(item.duration);
+    if (dur) bits.push(dur);
+    meta.textContent = bits.join(" · ");
+    text.append(title, meta);
+    main.appendChild(text);
+
+    if (item.too_long) {
+      // Over the limit the pipeline refuses the job outright, so this is a
+      // "cannot", not a "may be slow". Saying it here saves the user queueing
+      // something that can only fail.
+      const warn = document.createElement("span");
+      warn.className = "search-warn";
+      warn.textContent = t("search.tooLong", { mins });
+      main.appendChild(warn);
+    }
+
+    // Playlists have no single stream to audition. The kind comes from the
+    // active tab: results do not carry one.
+    if (TABS[activeTab].kind !== "playlist") {
+      const prev = document.createElement("button");
+      prev.type = "button";
+      prev.className = "search-preview-btn";
+      prev.dataset.preview = String(i);
+      setPreviewButton(prev, false);
+      main.appendChild(prev);
+    }
+
+    row.appendChild(main);
+    frag.appendChild(row);
+  });
+  listEl.appendChild(frag);
+  cursor = -1;
+  // Height just changed, and the panel may have been sized while it still held
+  // the "Searching..." line.
+  position();
+}
+
+const fmtClock = (s) => (isFinite(s) && s >= 0 ? fmtDuration(s) || "0:00" : "0:00");
+
+function stopPreview() {
+  if (rafId) { cancelAnimationFrame(rafId); rafId = 0; }
+  if (audio) {
+    audio.pause();
+    // Drop the src as well as pausing: a paused <audio> keeps its connection
+    // and buffer, which for a proxied stream means holding a socket open on
+    // the backend for a preview nobody is listening to.
+    audio.removeAttribute("src");
+    audio.load();
+  }
+  previewIndex = -1;
+  if (!listEl) return;
+  listEl.querySelector(".search-player")?.remove();
+  for (const b of listEl.querySelectorAll(".search-preview-btn")) setPreviewButton(b, false);
+}
+
+function buildPlayer(item) {
+  const wrap = document.createElement("div");
+  wrap.className = "search-player";
+
+  const play = document.createElement("button");
+  play.type = "button";
+  play.className = "search-play";
+  play.innerHTML = ICON_PAUSE;
+  play.setAttribute("aria-label", t("search.pause"));
+
+  const bar = document.createElement("input");
+  bar.type = "range";
+  bar.className = "search-seek";
+  bar.min = "0";
+  bar.max = "1000";
+  bar.value = "0";
+  bar.setAttribute("aria-label", t("search.seek"));
+
+  const clock = document.createElement("span");
+  clock.className = "search-clock";
+  clock.textContent = `0:00 / ${fmtClock(item.duration)}`;
+
+  wrap.append(play, bar, clock);
+  return { wrap, play, bar, clock };
+}
+
+async function startPreview(index) {
+  const item = items[index];
+  const row = listEl.children[index];
+  if (!item || !row) return;
+  if (previewIndex === index) { stopPreview(); return; }
+  stopPreview();
+  previewIndex = index;
+
+  if (!audio) {
+    audio = new Audio();
+    audio.preload = "none";
+  }
+
+  const { wrap, play, bar, clock } = buildPlayer(item);
+  row.appendChild(wrap);
+  const btn = row.querySelector(".search-preview-btn");
+  setPreviewButton(btn, true);
+  wrap.classList.add("loading");
+  position();
+
+  audio.src = `/api/search/preview?url=${encodeURIComponent(item.url)}`;
+
+  let seeking = false;
+  // A single rAF loop while playing, rather than a timeupdate listener: the
+  // bar then moves with the display instead of at the 4/sec timeupdate fires.
+  const tick = () => {
+    if (previewIndex !== index) return;
+    const dur = audio.duration || item.duration || 0;
+    if (!seeking && dur) bar.value = String(Math.round((audio.currentTime / dur) * 1000));
+    clock.textContent = `${fmtClock(audio.currentTime)} / ${fmtClock(dur)}`;
+    rafId = requestAnimationFrame(tick);
+  };
+
+  const setPaused = (paused) => {
+    play.innerHTML = paused ? ICON_PLAY : ICON_PAUSE;
+    play.setAttribute("aria-label", t(paused ? "search.play" : "search.pause"));
+    setPreviewButton(btn, !paused);
+  };
+
+  audio.onplaying = () => { wrap.classList.remove("loading"); setPaused(false); if (!rafId) tick(); };
+  audio.onpause = () => { setPaused(true); if (rafId) { cancelAnimationFrame(rafId); rafId = 0; } };
+  audio.onended = () => { setPaused(true); bar.value = "0"; };
+  audio.onerror = () => {
+    wrap.classList.remove("loading");
+    wrap.classList.add("failed");
+    clock.textContent = t("search.previewFailed");
+  };
+
+  play.addEventListener("click", (e) => {
+    e.stopPropagation();
+    if (audio.paused) audio.play().catch(() => {}); else audio.pause();
+  });
+  bar.addEventListener("pointerdown", () => { seeking = true; });
+  const commit = () => {
+    const dur = audio.duration || item.duration || 0;
+    if (dur) audio.currentTime = (Number(bar.value) / 1000) * dur;
+    seeking = false;
+  };
+  bar.addEventListener("change", commit);
+  bar.addEventListener("pointerup", commit);
+  // The player is inside the row, and the row picks the track on mousedown.
+  wrap.addEventListener("mousedown", (e) => e.stopPropagation());
+  wrap.addEventListener("click", (e) => e.stopPropagation());
+
+  try { await audio.play(); } catch { /* autoplay refused: the play button still works */ }
+}
+
+function highlight(next) {
+  const rows = listEl.children;
+  if (!rows.length) return;
+  if (cursor >= 0 && rows[cursor]) {
+    rows[cursor].classList.remove("active");
+    rows[cursor].setAttribute("aria-selected", "false");
+  }
+  input.removeAttribute("aria-activedescendant");
+  cursor = (next + rows.length) % rows.length;
+  const row = rows[cursor];
+  row.classList.add("active");
+  row.setAttribute("aria-selected", "true");
+  input.setAttribute("aria-activedescendant", row.id);
+  row.scrollIntoView({ block: "nearest" });
+}
+
+function pick(index) {
+  const item = items[index];
+  if (!item || item.too_long) return;
+  close();
+  onPick?.(item);
+}
+
+async function run(query) {
+  const tab = TABS[activeTab];
+  controller?.abort();
+  controller = new AbortController();
+  const mine = controller;
+  setStatus(t("search.searching"));
+  open();
+  try {
+    const r = await fetch("/api/search", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ query, source: tab.source, kind: tab.kind, limit: LIMIT }),
+      signal: mine.signal,
+    });
+    // A newer search started while this was in flight. Its result is the only
+    // one that should reach the DOM.
+    if (mine.signal.aborted || mine !== controller) return;
+    if (!r.ok) { items = []; setStatus(t("search.failed")); lastQuery = ""; return; }
+    const data = await r.json();
+    if (mine !== controller) return;
+    items = Array.isArray(data.items) ? data.items : [];
+    render(data.max_duration_sec);
+  } catch (e) {
+    if (e?.name === "AbortError") return;
+    items = [];
+    setStatus(t("search.failed"));
+    lastQuery = "";
+  }
+}
+
+function schedule(force = false) {
+  const raw = input.value;
+  const query = raw.trim();
+  if (timerId) { clearTimeout(timerId); timerId = null; }
+  if (query.length < MIN_QUERY || LOOKS_LIKE_URL.test(raw)) { close(); return; }
+  if (!force && query === lastQuery) return;
+  // A trailing space means a finished word, which is a far stronger signal
+  // than "has not typed for a moment".
+  const delay = force ? 0 : /\s$/.test(raw) ? WORD_MS : IDLE_MS;
+  timerId = setTimeout(() => {
+    timerId = null;
+    // run() clears lastQuery itself on failure, so an identical retry is
+    // allowed through. Without that a transient error sticks until the user
+    // edits the text, because schedule() short-circuits on an equal query.
+    lastQuery = query;
+    run(query);
+  }, delay);
+}
+
+function buildPanel(wrap) {
+  panel = document.createElement("div");
+  panel.className = "search-panel hidden";
+  panel.id = "search-panel";
+
+  tabsEl = document.createElement("div");
+  tabsEl.className = "search-tabs";
+  tabsEl.setAttribute("role", "tablist");
+  TABS.forEach((tab, i) => {
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = "search-tab" + (i === 0 ? " active" : "");
+    b.setAttribute("role", "tab");
+    b.dataset.index = String(i);
+    b.setAttribute("data-i18n", tab.labelKey);
+    // Set now as well as marking it: this panel is built after the initial
+    // applyTranslations pass, so relying on the attribute alone would render
+    // the raw key until the user changed language.
+    b.textContent = t(tab.labelKey);
+    tabsEl.appendChild(b);
+  });
+
+  listEl = document.createElement("ul");
+  listEl.className = "search-list";
+  listEl.setAttribute("role", "listbox");
+
+  statusEl = document.createElement("div");
+  statusEl.className = "search-status hidden";
+  statusEl.setAttribute("role", "status");
+
+  panel.append(tabsEl, statusEl, listEl);
+  // Deliberately NOT inside .url-wrap. Its ancestor .daw-composer sets
+  // overflow:hidden to clip the rounded pill, which clipped the whole dropdown
+  // out of existence -- it rendered, it was just never visible. Living on
+  // <body> with fixed positioning sidesteps that and any future ancestor that
+  // grows a clip or a transform.
+  document.body.appendChild(panel);
+  // Re-translate the tabs on a language switch. Rows are rebuilt on the next
+  // search, so they need nothing here.
+  onLanguageChange(() => applyTranslations(panel));
+}
+
+/**
+ * Wire live search onto the topbar URL box.
+ * @param {(item: {url: string, title: string}) => void} onSelect
+ *   Called with the chosen result. Filling the box and submitting is the
+ *   caller's job, so this module never has to know about the import flow.
+ */
+export function initSearch(onSelect) {
+  input = document.getElementById("url");
+  const wrap = input?.closest(".url-wrap");
+  if (!input || !wrap) return;
+  onPick = onSelect;
+
+  // The input is already type="text" in the markup. Do NOT set it here: the
+  // topbar styling keys off #url now, but mutating the element's type at
+  // runtime is exactly the kind of thing that silently unstyles it again.
+  input.setAttribute("role", "combobox");
+  input.setAttribute("aria-autocomplete", "list");
+  input.setAttribute("aria-expanded", "false");
+  input.setAttribute("aria-controls", "search-panel");
+
+  buildPanel(wrap);
+
+  input.addEventListener("input", () => schedule());
+  input.addEventListener("focus", () => { if (items.length) open(); });
+
+  // Fixed positioning means the panel does not follow its anchor on its own.
+  // Passive listeners, and only while it is actually open.
+  const reflow = (e) => {
+    if (panel.classList.contains("hidden")) return;
+    // The panel's own list scrolls. Repositioning on that is pure waste: a
+    // forced layout and three style writes per scroll event, on the one
+    // element whose position did not move.
+    if (e && e.target !== document && panel.contains(e.target)) return;
+    position();
+  };
+  window.addEventListener("resize", reflow, { passive: true });
+  window.addEventListener("scroll", reflow, { passive: true, capture: true });
+
+  input.addEventListener("keydown", (e) => {
+    const open = !panel.classList.contains("hidden");
+    if (e.key === "Escape") { close(); return; }
+    if (e.key === "ArrowDown") { if (open) { e.preventDefault(); highlight(cursor + 1); } return; }
+    if (e.key === "ArrowUp") { if (open) { e.preventDefault(); highlight(cursor - 1); } return; }
+    if (e.key === "Enter" && open && cursor >= 0) { e.preventDefault(); pick(cursor); }
+  });
+
+  // One listener for every row, now and later.
+  listEl.addEventListener("mousedown", (e) => {
+    // Auditioning a track is not choosing it. Handled on click below so the
+    // button behaves like a button.
+    if (e.target.closest(".search-preview-btn, .search-player")) { e.preventDefault(); return; }
+    const row = e.target.closest(".search-row");
+    if (!row) return;
+    e.preventDefault(); // keep focus in the input so blur does not race the click
+    pick(Number(row.dataset.index));
+  });
+
+  listEl.addEventListener("click", (e) => {
+    const btn = e.target.closest(".search-preview-btn");
+    if (!btn) return;
+    e.stopPropagation();
+    startPreview(Number(btn.dataset.preview));
+  });
+
+  // Keep focus in the input: a tab is a button, and letting it take focus
+  // would blur the box the user is still typing into.
+  tabsEl.addEventListener("mousedown", (e) => {
+    if (e.target.closest(".search-tab")) e.preventDefault();
+  });
+
+  tabsEl.addEventListener("click", (e) => {
+    const b = e.target.closest(".search-tab");
+    if (!b) return;
+    activeTab = Number(b.dataset.index);
+    for (const el of tabsEl.children) el.classList.toggle("active", el === b);
+    // Switching tabs re-asks the same question of a different service, so the
+    // previous results go now rather than lingering under the new tab while
+    // the request is in flight.
+    items = [];
+    lastQuery = "";
+    schedule(true);
+  });
+
+  // The panel is a sibling of the composer on <body>, not a descendant of
+  // wrap, so it has to be named explicitly here. Checking wrap alone meant a
+  // mousedown on a tab counted as an outside click and closed the dropdown
+  // before the tab's own click handler ever ran.
+  document.addEventListener("mousedown", (e) => {
+    if (panel.classList.contains("hidden")) return;
+    if (wrap.contains(e.target) || panel.contains(e.target)) return;
+    close();
+  });
+}
+
+export function closeSearch() {
+  close();
+}
diff --git a/tests/test_search.py b/tests/test_search.py
new file mode 100644
index 00000000..a3f14bfb
--- /dev/null
+++ b/tests/test_search.py
@@ -0,0 +1,391 @@
+"""Live search for the topbar.
+
+Network is mocked throughout: these cover the parts that are ours, which are
+the extractor allowlists, the URL normalisation, and the duration verdict. What
+YouTube returns for a given phrase is not something a test can pin down.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from unittest.mock import patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api import search as api_search
+from app.pipeline import search as search_mod
+
+
+class _FakeYDL:
+    """Captures the options and the target string, returns canned entries."""
+
+    captured: list[tuple[dict, str]] = []
+    entries: list[dict] = []
+
+    def __init__(self, opts):
+        self._opts = opts
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_exc):
+        return False
+
+    def extract_info(self, target, download=False):
+        _FakeYDL.captured.append((self._opts, target))
+        return {"entries": list(_FakeYDL.entries)}
+
+
+@contextlib.contextmanager
+def _limit(seconds: int):
+    """Both the pipeline and the API imported get_max_duration_sec by value, so
+    each holds its own reference and both have to be patched."""
+    with (
+        patch.object(search_mod, "get_max_duration_sec", return_value=seconds),
+        patch.object(api_search, "get_max_duration_sec", return_value=seconds),
+    ):
+        yield
+
+
+@pytest.fixture(autouse=True)
+def _fake_ydl(monkeypatch):
+    _FakeYDL.captured = []
+    _FakeYDL.entries = []
+    monkeypatch.setattr(search_mod, "YoutubeDL", _FakeYDL)
+    api_search._clear_cache()
+    return _FakeYDL
+
+
+# ── source / kind support ────────────────────────────────────────────
+
+
+def test_soundcloud_has_no_playlist_search():
+    """yt-dlp exposes exactly one SoundCloud search key (scsearch, tracks
+    only), so the UI must not offer a tab that can only ever be empty."""
+    assert search_mod.supported("soundcloud", "track")
+    assert not search_mod.supported("soundcloud", "playlist")
+    assert search_mod.supported("youtube", "track")
+    assert search_mod.supported("youtube", "playlist")
+
+
+def test_unsupported_pair_raises():
+    with pytest.raises(search_mod.UnsupportedSearch):
+        search_mod.search("daft punk", "soundcloud", "playlist")
+
+
+def test_short_query_raises():
+    with pytest.raises(search_mod.UnsupportedSearch):
+        search_mod.search("a", "youtube", "track")
+
+
+def test_unknown_source_raises():
+    with pytest.raises(search_mod.UnsupportedSearch):
+        search_mod.search("daft punk", "spotify", "track")
+
+
+# ── the SSRF boundary ────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    ("source", "kind"),
+    [("youtube", "track"), ("youtube", "playlist"), ("soundcloud", "track")],
+)
+def test_generic_extractor_is_never_allowed(source, kind):
+    """The whole point of #173. A search must not be the way in."""
+    search_mod.search("daft punk", source, kind)
+    opts, _ = _FakeYDL.captured[0]
+    assert "generic" not in opts["allowed_extractors"]
+    assert opts["allowed_extractors"], "a search with no allowlist is unrestricted"
+
+
+def test_track_search_cannot_reach_the_tab_extractor():
+    """Track search has no business expanding a channel or a playlist page."""
+    search_mod.search("daft punk", "youtube", "track")
+    opts, _ = _FakeYDL.captured[0]
+    assert "youtube:tab" not in opts["allowed_extractors"]
+
+
+def test_search_targets():
+    search_mod.search("daft punk", "youtube", "track", limit=5)
+    assert _FakeYDL.captured[0][1] == "ytsearch5:daft punk"
+    _FakeYDL.captured.clear()
+    search_mod.search("daft punk", "soundcloud", "track", limit=3)
+    assert _FakeYDL.captured[0][1] == "scsearch3:daft punk"
+    _FakeYDL.captured.clear()
+    search_mod.search("daft punk", "youtube", "playlist", limit=4)
+    target = _FakeYDL.captured[0][1]
+    assert target.startswith("https://www.youtube.com/results?search_query=daft%20punk")
+    assert "sp=" in target, "without the filter this returns videos, not playlists"
+
+
+def test_query_is_url_encoded_into_the_search_page():
+    search_mod.search("a&b=c d", "youtube", "playlist")
+    target = _FakeYDL.captured[0][1]
+    assert "a%26b%3Dc%20d" in target
+
+
+# ── result normalisation ─────────────────────────────────────────────
+
+
+def test_soundcloud_permalink_is_preferred_over_the_api_url():
+    """SoundCloud search returns `url` as an api.soundcloud.com endpoint, which
+    is not on the allowlisted host set and is rejected on sight. Reading `url`
+    first (as expand_playlist does) silently drops every SoundCloud result."""
+    _FakeYDL.entries = [
+        {
+            "title": "Around the World",
+            "duration": 429.0,
+            "url": "https://api.soundcloud.com/tracks/soundcloud%3Atracks%3A254112221",
+            "webpage_url": "https://soundcloud.com/daftpunkofficial/around-the-world",
+        }
+    ]
+    out = search_mod.search("daft punk", "soundcloud", "track")
+    assert len(out["items"]) == 1
+    assert out["items"][0]["url"] == "https://soundcloud.com/daftpunkofficial/around-the-world"
+
+
+def test_youtube_urls_are_normalised():
+    _FakeYDL.entries = [
+        {"title": "x", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PLabc&t=42"}
+    ]
+    out = search_mod.search("query", "youtube", "track")
+    assert out["items"][0]["url"] == "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+
+def test_unvalidatable_entries_are_dropped_not_shown():
+    """A result we cannot hand to the pipeline must not be offered."""
+    _FakeYDL.entries = [
+        {"title": "evil", "url": "https://evil.example.com/watch?v=aaaaaaaaaaa"},
+        {"title": "ok", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
+        {"title": "nothing", "url": None},
+        "not even a dict",
+    ]
+    out = search_mod.search("query", "youtube", "track")
+    assert [i["title"] for i in out["items"]] == ["ok"]
+
+
+def test_playlist_entries_go_through_the_playlist_validator():
+    _FakeYDL.entries = [
+        {"title": "album", "url": "https://www.youtube.com/playlist?list=PLSdoVPM5Wnnd"},
+        {"title": "radio", "url": "https://www.youtube.com/playlist?list=RDdQw4w9WgXcQ"},
+    ]
+    out = search_mod.search("query", "youtube", "playlist")
+    # Radio playlists are endless and viewer-specific, so validate_playlist_url
+    # rejects them and they must not appear as importable.
+    assert [i["title"] for i in out["items"]] == ["album"]
+
+
+def test_limit_is_honoured_and_clamped():
+    _FakeYDL.entries = [
+        {"title": str(i), "url": f"https://www.youtube.com/watch?v=dQw4w9WgXc{i}"}
+        for i in range(12)
+    ]
+    assert len(search_mod.search("query", "youtube", "track", limit=3)["items"]) == 3
+    assert (
+        len(search_mod.search("query", "youtube", "track", limit=999)["items"])
+        <= search_mod.MAX_LIMIT
+    )
+
+
+def test_smallest_usable_thumbnail_is_chosen():
+    """The dropdown renders these at 64px. Pulling the 720p variant would cost
+    bandwidth and decode time for nothing."""
+    _FakeYDL.entries = [
+        {
+            "title": "x",
+            "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+            "thumbnails": [
+                {"url": "tiny.jpg", "width": 48},
+                {"url": "small.jpg", "width": 168},
+                {"url": "huge.jpg", "width": 1280},
+            ],
+        }
+    ]
+    assert search_mod.search("query", "youtube", "track")["items"][0]["thumbnail"] == "small.jpg"
+
+
+def test_missing_thumbnail_is_none_not_an_error():
+    _FakeYDL.entries = [{"title": "x", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}]
+    assert search_mod.search("query", "youtube", "track")["items"][0]["thumbnail"] is None
+
+
+# ── the duration verdict ─────────────────────────────────────────────
+
+
+def test_over_the_limit_is_flagged():
+    """Over the configured limit the pipeline refuses the job outright, so the
+    UI has to say "cannot import", not "this may be slow"."""
+    _FakeYDL.entries = [
+        {"title": "short", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXc1"},
+        {"title": "long", "duration": 4275, "url": "https://www.youtube.com/watch?v=dQw4w9WgXc2"},
+    ]
+    with patch.object(search_mod, "get_max_duration_sec", return_value=1200):
+        out = search_mod.search("query", "youtube", "track")
+    assert out["max_duration_sec"] == 1200
+    assert [i["too_long"] for i in out["items"]] == [False, True]
+
+
+def test_the_verdict_follows_the_users_configured_limit():
+    """Not a hardcoded 20 minutes: the limit is a setting, 1 to 60 minutes."""
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 2000, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    with patch.object(search_mod, "get_max_duration_sec", return_value=1200):
+        assert search_mod.search("query", "youtube", "track")["items"][0]["too_long"] is True
+    with patch.object(search_mod, "get_max_duration_sec", return_value=3600):
+        assert search_mod.search("query", "youtube", "track")["items"][0]["too_long"] is False
+
+
+def test_unknown_duration_is_not_treated_as_too_long():
+    """Playlists have no duration. They must not all be marked unimportable."""
+    _FakeYDL.entries = [
+        {"title": "album", "url": "https://www.youtube.com/playlist?list=PLSdoVPM5Wnnd"}
+    ]
+    out = search_mod.search("query", "youtube", "playlist")
+    assert out["items"][0]["duration"] is None
+    assert out["items"][0]["too_long"] is False
+
+
+# ── the endpoint ─────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def client():
+    from app.main import app
+
+    with TestClient(app) as c:
+        yield c
+
+
+def test_endpoint_happy_path(client):
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    r = client.post("/api/search", json={"query": "daft punk"})
+    assert r.status_code == 200
+    body = r.json()
+    assert len(body["items"]) == 1
+    assert body["cached"] is False
+
+
+def test_endpoint_rejects_a_short_query(client):
+    assert client.post("/api/search", json={"query": "a"}).status_code == 422
+
+
+def test_endpoint_rejects_an_unsupported_pair(client):
+    r = client.post(
+        "/api/search", json={"query": "daft punk", "source": "soundcloud", "kind": "playlist"}
+    )
+    assert r.status_code == 422
+    assert "no playlist search" in r.json()["detail"]
+
+
+def test_endpoint_rejects_an_unknown_source(client):
+    r = client.post("/api/search", json={"query": "daft punk", "source": "spotify"})
+    assert r.status_code == 422
+
+
+def test_endpoint_rejects_a_silly_limit(client):
+    assert client.post("/api/search", json={"query": "qq", "limit": 500}).status_code == 422
+
+
+def test_endpoint_rejects_invalid_json(client):
+    r = client.post(
+        "/api/search", content=b"{not json", headers={"Content-Type": "application/json"}
+    )
+    assert r.status_code == 422
+
+
+def test_a_repeat_query_is_served_from_cache(client):
+    """Word-boundary triggering means backspacing walks straight back through
+    earlier queries. Those must not each cost a round trip."""
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    assert client.post("/api/search", json={"query": "daft punk"}).json()["cached"] is False
+    calls = len(_FakeYDL.captured)
+    second = client.post("/api/search", json={"query": "daft punk"}).json()
+    assert second["cached"] is True
+    assert len(_FakeYDL.captured) == calls, "a cache hit must not reach yt-dlp"
+    assert second["items"] == [i for i in second["items"]]
+
+
+def test_the_cache_key_ignores_case_but_not_source(client):
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    client.post("/api/search", json={"query": "Daft Punk"})
+    assert client.post("/api/search", json={"query": "daft punk"}).json()["cached"] is True
+    # Same words, different service: must not be served the YouTube results.
+    assert (
+        client.post("/api/search", json={"query": "daft punk", "source": "soundcloud"}).json()[
+            "cached"
+        ]
+        is False
+    )
+
+
+def test_an_expired_entry_is_not_served(client, monkeypatch):
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    client.post("/api/search", json={"query": "daft punk"})
+    monkeypatch.setattr(api_search, "_CACHE_TTL_SEC", -1.0)
+    api_search._clear_cache()
+    assert client.post("/api/search", json={"query": "daft punk"}).json()["cached"] is False
+
+
+def test_the_cache_is_bounded(client):
+    """A long session of typing must not grow the cache without limit."""
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    for i in range(api_search._CACHE_MAX + 20):
+        client.post("/api/search", json={"query": f"query number {i}"})
+    assert len(api_search._cache) <= api_search._CACHE_MAX
+
+
+def test_raising_the_duration_limit_invalidates_the_cache(client):
+    """too_long is computed against a live setting. A cached verdict that
+    outlives a Settings change leaves rows greyed out and unclickable for up to
+    a minute after the user has explicitly allowed them."""
+    _FakeYDL.entries = [
+        {"title": "long", "duration": 2000, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    with _limit(1200):
+        first = client.post("/api/search", json={"query": "daft punk"}).json()
+    assert first["items"][0]["too_long"] is True
+
+    with _limit(3600):
+        second = client.post("/api/search", json={"query": "daft punk"}).json()
+    assert second["cached"] is False, "the old verdict was served from cache"
+    assert second["items"][0]["too_long"] is False
+
+
+def test_the_same_limit_still_caches(client):
+    """The key gained a field; it must not have stopped caching altogether."""
+    _FakeYDL.entries = [
+        {"title": "x", "duration": 200, "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
+    ]
+    with _limit(1200):
+        client.post("/api/search", json={"query": "daft punk"})
+        assert client.post("/api/search", json={"query": "daft punk"}).json()["cached"] is True
+
+
+def test_a_backend_failure_is_a_502_not_a_stack_trace(client):
+    def boom(*_a, **_k):
+        raise RuntimeError("ERROR: [youtube] Sign in to confirm you're not a bot")
+
+    with patch.object(api_search, "search", boom):
+        r = client.post("/api/search", json={"query": "daft punk"})
+    assert r.status_code == 502
+    assert r.json()["detail"] == "Could not reach that service"
+    assert "bot" not in r.text, "the upstream message must not leak to the client"
+
+
+def test_sources_endpoint_reports_what_is_actually_searchable(client):
+    body = client.get("/api/search/sources").json()
+    by_source = {s["source"]: s["kinds"] for s in body["sources"]}
+    assert by_source["youtube"] == ["track", "playlist"]
+    assert by_source["soundcloud"] == ["track"]

From ae1052250aa51cadffd9a88470b6d6112a95308d Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:03:47 +0100
Subject: [PATCH 03/11] Audition a search result before extracting it

Each result carries a Preview button that expands into play, pause and a
seekable time bar, so a wrong take is found in ten seconds rather than after
a separation. It is labelled rather than a bare glyph on purpose: an
unlabelled circle on a search result reads as 'play this result', which is
the one thing it does not do. Auditioning is not selecting.

The stream is proxied rather than handed to the page. The CSP allows
media-src 'self' blob: data:, so a googlevideo.com URL in an audio tag is
blocked, and widening that would let any injected string in the webview pull
media from anywhere. The browser never talks to YouTube: it talks to us, and
we fetch a URL yt-dlp resolved from an already-allowlisted page.

Kept cheap. The smallest audio-only progressive format is chosen, which is
1.2 MB for a four minute track against 11.8 MB for the 360p video. Resolving
is the expensive half at about two seconds, and the result is stable for
hours, so it is cached for twenty minutes. Range is forwarded, so seeking is
a partial request rather than a re-download. One audio element is shared by
the whole panel with preload=none, and its src is dropped on close: a paused
element keeps its connection, which for a proxied stream means holding a
socket open for a preview nobody is listening to.

HLS and video formats are refused rather than served and left to fail in the
player. A manifest rewrite and a segment proxy is a lot of machinery for an
audition button.

The frontend half of this landed with the previous commit, since it shares
static/js/search.js with the search UI.
---
 app/pipeline/preview.py | 159 +++++++++++++++++++++++++++++
 tests/test_preview.py   | 217 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 376 insertions(+)
 create mode 100644 app/pipeline/preview.py
 create mode 100644 tests/test_preview.py

diff --git a/app/pipeline/preview.py b/app/pipeline/preview.py
new file mode 100644
index 00000000..b32af548
--- /dev/null
+++ b/app/pipeline/preview.py
@@ -0,0 +1,159 @@
+"""Resolve a playable audio stream for a search result, so it can be auditioned
+before committing minutes of separation to it.
+
+The stream cannot be handed to the page directly. The CSP allows `media-src
+'self' blob: data:` only, so a googlevideo.com URL in an <audio> tag is blocked,
+and widening that would let any injected string in the webview pull media from
+anywhere. The bytes are proxied instead, which keeps the CSP where it is and
+means the browser never talks to YouTube at all.
+
+Two things make it affordable:
+
+  * Resolving is the expensive half (a real extraction, one to two seconds) and
+    the result is stable for hours, so resolved URLs are cached.
+  * The proxy forwards Range, so the browser pulls only what it plays. Opening
+    a preview costs a few hundred KB, not the whole track.
+
+Only progressive HTTP formats are accepted. HLS would need a manifest rewrite
+and a segment proxy, which is a lot of machinery for an audition button.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+
+from yt_dlp import YoutubeDL
+
+from app.pipeline.download import _ALLOWED_EXTRACTORS, _base_ydl_opts, validate_youtube_url
+
+logger = logging.getLogger("stemdeck.preview")
+
+
+class PreviewUnavailable(RuntimeError):
+    """No progressive audio stream could be resolved for this URL."""
+
+
+# Resolved media URLs are signed and time-limited (YouTube's run about six
+# hours). Twenty minutes is comfortably inside that while still not pinning a
+# stale URL for a whole session.
+_TTL_SEC = 20 * 60
+_MAX_ENTRIES = 64
+
+_lock = threading.Lock()
+_cache: dict[str, tuple[float, dict]] = {}
+
+# Anything not on http(s) needs a player, not a byte proxy.
+_PROGRESSIVE = ("https", "http")
+
+
+def _cache_get(url: str) -> dict | None:
+    with _lock:
+        hit = _cache.get(url)
+        if hit is None:
+            return None
+        expires, payload = hit
+        if expires < time.monotonic():
+            _cache.pop(url, None)
+            return None
+        return payload
+
+
+def _cache_put(url: str, payload: dict) -> None:
+    with _lock:
+        if len(_cache) >= _MAX_ENTRIES:
+            _cache.pop(min(_cache, key=lambda k: _cache[k][0]), None)
+        _cache[url] = (time.monotonic() + _TTL_SEC, payload)
+
+
+def _clear_cache() -> None:
+    with _lock:
+        _cache.clear()
+
+
+def _pick_format(info: dict) -> dict | None:
+    """Smallest progressive audio-only format that will actually play.
+
+    Smallest, not best: this is an audition. The lowest bitrate audio stream is
+    a fraction of the bytes and indistinguishable for deciding whether it is
+    the right song.
+    """
+    candidates = []
+    for f in info.get("formats") or []:
+        if not isinstance(f, dict) or not f.get("url"):
+            continue
+        if f.get("protocol") not in _PROGRESSIVE:
+            continue
+        if f.get("acodec") in (None, "none"):
+            continue
+        # Audio-only. A progressive video format would drag the whole picture
+        # down the wire to play a sound.
+        if f.get("vcodec") not in (None, "none"):
+            continue
+        candidates.append(f)
+    if not candidates:
+        return None
+    candidates.sort(key=lambda f: f.get("abr") or f.get("tbr") or 9999)
+    return candidates[0]
+
+
+def resolve(url: str) -> dict:
+    """Resolve `url` to a proxyable audio stream.
+
+    Returns {"url", "mime", "size", "headers", "title", "duration"}. Blocking:
+    callers must keep this off the event loop.
+    """
+    url = validate_youtube_url(url)
+    cached = _cache_get(url)
+    if cached is not None:
+        return cached
+
+    opts = {
+        **_base_ydl_opts(_ALLOWED_EXTRACTORS),
+        "noplaylist": True,
+        "skip_download": True,
+    }
+    with YoutubeDL(opts) as ydl:
+        info = ydl.extract_info(url, download=False) or {}
+
+    fmt = _pick_format(info)
+    if not fmt:
+        raise PreviewUnavailable("no progressive audio stream")
+
+    payload = {
+        "url": fmt["url"],
+        # yt-dlp knows the container; the browser needs a usable type to decode.
+        "mime": _mime_for(fmt),
+        "size": fmt.get("filesize") or fmt.get("filesize_approx"),
+        # These are not decoration. A googlevideo URL fetched without the
+        # headers yt-dlp negotiated is frequently refused.
+        "headers": {k: v for k, v in (fmt.get("http_headers") or {}).items() if v},
+        "title": info.get("title") or "",
+        "duration": info.get("duration"),
+    }
+    _cache_put(url, payload)
+    return payload
+
+
+_MIME_BY_EXT = {
+    "m4a": "audio/mp4",
+    "mp4": "audio/mp4",
+    "webm": "audio/webm",
+    "opus": "audio/ogg",
+    "ogg": "audio/ogg",
+    "mp3": "audio/mpeg",
+    "wav": "audio/wav",
+}
+
+
+def _mime_for(fmt: dict) -> str:
+    ext = (fmt.get("ext") or "").lower()
+    if ext in _MIME_BY_EXT:
+        return _MIME_BY_EXT[ext]
+    acodec = (fmt.get("acodec") or "").lower()
+    if "opus" in acodec:
+        return "audio/webm"
+    if "mp4a" in acodec or "aac" in acodec:
+        return "audio/mp4"
+    return "audio/mpeg"
diff --git a/tests/test_preview.py b/tests/test_preview.py
new file mode 100644
index 00000000..08cffb6a
--- /dev/null
+++ b/tests/test_preview.py
@@ -0,0 +1,217 @@
+"""Audition a search result before committing minutes of separation to it.
+
+The stream is proxied rather than handed to the page. `media-src 'self' blob:
+data:` in the CSP blocks a googlevideo.com URL in an <audio> tag, and widening
+that would let any injected string in the webview pull media from anywhere. So
+the browser never talks to YouTube: it talks to us, and we fetch a URL that
+yt-dlp resolved from an already-allowlisted page.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.api import search as api_search
+from app.pipeline import preview as preview_mod
+
+URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+AUDIO_LOW = {
+    "url": "https://rr1.googlevideo.com/low",
+    "protocol": "https",
+    "acodec": "opus",
+    "vcodec": "none",
+    "abr": 50,
+    "ext": "webm",
+    "filesize": 1231355,
+    "http_headers": {"User-Agent": "yt-dlp", "Accept": "*/*", "Empty": ""},
+}
+AUDIO_HIGH = {**AUDIO_LOW, "url": "https://rr1.googlevideo.com/high", "abr": 160}
+VIDEO = {
+    "url": "https://rr1.googlevideo.com/video",
+    "protocol": "https",
+    "acodec": "mp4a",
+    "vcodec": "avc1",
+    "abr": 10,
+    "ext": "mp4",
+}
+HLS = {
+    "url": "https://rr1.googlevideo.com/hls.m3u8",
+    "protocol": "m3u8_native",
+    "acodec": "mp4a",
+    "vcodec": "none",
+    "abr": 1,
+    "ext": "mp4",
+}
+
+
+class _FakeYDL:
+    formats: list[dict] = []
+
+    def __init__(self, opts):
+        self.opts = opts
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_exc):
+        return False
+
+    def extract_info(self, url, download=False):
+        return {"title": "A Song", "duration": 213, "formats": list(_FakeYDL.formats)}
+
+
+@pytest.fixture(autouse=True)
+def _fake(monkeypatch):
+    _FakeYDL.formats = [VIDEO, AUDIO_HIGH, AUDIO_LOW, HLS]
+    monkeypatch.setattr(preview_mod, "YoutubeDL", _FakeYDL)
+    preview_mod._clear_cache()
+
+
+def test_the_cheapest_audio_only_stream_wins():
+    """This is an audition, not a bounce. The lowest bitrate audio-only stream
+    is a fraction of the bytes and tells the user what they need to know."""
+    assert preview_mod.resolve(URL)["url"] == AUDIO_LOW["url"]
+
+
+def test_video_formats_are_refused():
+    """A progressive video format would drag the picture down the wire to play
+    a sound."""
+    _FakeYDL.formats = [VIDEO]
+    with pytest.raises(preview_mod.PreviewUnavailable):
+        preview_mod.resolve(URL)
+
+
+def test_hls_is_refused():
+    """m3u8 needs a manifest rewrite and a segment proxy. Out of scope for an
+    audition button, and silently serving a manifest as audio would just fail
+    in the player instead."""
+    _FakeYDL.formats = [HLS]
+    with pytest.raises(preview_mod.PreviewUnavailable):
+        preview_mod.resolve(URL)
+
+
+def test_formats_without_a_url_are_skipped():
+    _FakeYDL.formats = [{**AUDIO_LOW, "url": None}, AUDIO_HIGH]
+    assert preview_mod.resolve(URL)["url"] == AUDIO_HIGH["url"]
+
+
+def test_negotiated_headers_are_carried_and_blanks_dropped():
+    """A googlevideo URL fetched without the headers yt-dlp negotiated is
+    frequently refused."""
+    headers = preview_mod.resolve(URL)["headers"]
+    assert headers["User-Agent"] == "yt-dlp"
+    assert "Empty" not in headers
+
+
+def test_mime_follows_the_container():
+    assert preview_mod.resolve(URL)["mime"] == "audio/webm"
+    preview_mod._clear_cache()
+    _FakeYDL.formats = [{**AUDIO_LOW, "ext": "m4a"}]
+    assert preview_mod.resolve(URL)["mime"] == "audio/mp4"
+
+
+def test_resolution_is_cached():
+    """Resolving is a real extraction, one to two seconds. Pressing play twice
+    must not pay for it twice."""
+    calls = []
+    real = _FakeYDL.extract_info
+
+    def counted(self, url, download=False):
+        calls.append(url)
+        return real(self, url, download)
+
+    with patch.object(_FakeYDL, "extract_info", counted):
+        preview_mod.resolve(URL)
+        preview_mod.resolve(URL)
+    assert len(calls) == 1
+
+
+def test_an_expired_entry_is_refetched(monkeypatch):
+    preview_mod.resolve(URL)
+    monkeypatch.setattr(preview_mod, "_TTL_SEC", -1)
+    preview_mod._clear_cache()
+    _FakeYDL.formats = [AUDIO_HIGH]
+    assert preview_mod.resolve(URL)["url"] == AUDIO_HIGH["url"]
+
+
+def test_the_cache_is_bounded():
+    for i in range(preview_mod._MAX_ENTRIES + 10):
+        preview_mod.resolve(f"https://www.youtube.com/watch?v=dQw4w9WgXc{i:02d}"[:43])
+    assert len(preview_mod._cache) <= preview_mod._MAX_ENTRIES
+
+
+def test_a_url_outside_the_allowlist_never_reaches_yt_dlp():
+    """The proxy is the one place that fetches an arbitrary host, so the URL it
+    is asked about has to clear the #173 boundary first."""
+    from app.pipeline.download import InvalidYouTubeURL
+
+    with pytest.raises(InvalidYouTubeURL):
+        preview_mod.resolve("https://evil.example.com/track.mp3")
+
+
+# ── endpoint ─────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def client():
+    from app.main import app
+
+    with TestClient(app) as c:
+        yield c
+
+
+def test_endpoint_rejects_a_foreign_host(client):
+    r = client.get("/api/search/preview", params={"url": "https://evil.example.com/a.mp3"})
+    assert r.status_code == 422
+
+
+def test_endpoint_404s_when_nothing_is_playable(client):
+    _FakeYDL.formats = [HLS]
+    r = client.get("/api/search/preview", params={"url": URL})
+    assert r.status_code == 404
+    assert "No preview" in r.json()["detail"]
+
+
+def test_endpoint_does_not_leak_upstream_errors(client):
+    def boom(_url):
+        raise RuntimeError("googlevideo said 403 for token abc123")
+
+    with patch.object(api_search, "resolve_preview", boom):
+        r = client.get("/api/search/preview", params={"url": URL})
+    assert r.status_code == 502
+    assert "abc123" not in r.text
+    assert r.json()["detail"] == "Could not load a preview"
+
+
+def test_range_is_forwarded_upstream(client):
+    """Seeking the time bar must cost one short request, not a re-download."""
+    seen = {}
+
+    class FakeUpstream:
+        status = 206
+        headers = {"Content-Range": "bytes 100-199/1000", "Content-Length": "100"}
+
+        def read(self, _n):
+            return b""
+
+        def close(self):
+            pass
+
+    def fake_urlopen(req, timeout=None):
+        seen["range"] = req.get_header("Range")
+        seen["ua"] = req.get_header("User-agent")
+        return FakeUpstream()
+
+    with patch.object(api_search.urllib.request, "urlopen", fake_urlopen):
+        r = client.get(
+            "/api/search/preview", params={"url": URL}, headers={"Range": "bytes=100-199"}
+        )
+    assert r.status_code == 206
+    assert seen["range"] == "bytes=100-199"
+    assert seen["ua"] == "yt-dlp", "yt-dlp's negotiated headers were dropped"
+    assert r.headers["content-range"] == "bytes 100-199/1000"
+    assert r.headers["accept-ranges"] == "bytes"

From 60ba95135a79397ee5acc5e7f8bf760f4293f986 Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:16:08 +0100
Subject: [PATCH 04/11] European Portuguese, and a shorter over-limit badge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

pt-PT is a regional variant rather than a ninth full table. It overrides the
43 strings that genuinely differ from Brazilian Portuguese (ficheiro not
arquivo, Definições not Configurações, Guardar not Salvar, Transferir not
Baixar, and the gerunds European Portuguese renders as 'a' plus infinitive)
and resolves through pt for the other 400.

t() and plural() now walk a fallback chain, variant to base to English,
instead of jumping straight to English on a miss. Duplicating all 439 keys
would have meant writing every future string twice and drifting the first
time one was missed. A key added to pt later is picked up by pt-PT for free.

Locale detection sends an explicit Portugal tag to the variant; pt-BR and a
bare 'pt' still take the Brazilian table, which is the more widely used
variant and so the right default for an unqualified tag.

Separately, the over-limit badge is now 'Over 20 min' rather than 'Over 20
min limit', with the actionable half moved to a tooltip: 'Longer than your 20
minute limit. Change it in Settings.' The row shares 620px with a title, an
uploader, a duration and the Preview pill, and the title is what people
scan.
---
 static/js/i18n.js   | 122 ++++++++++++++++++++++++++++++++++++--------
 static/js/search.js |   4 ++
 2 files changed, 106 insertions(+), 20 deletions(-)

diff --git a/static/js/i18n.js b/static/js/i18n.js
index 8efa8192..ff9df75a 100644
--- a/static/js/i18n.js
+++ b/static/js/i18n.js
@@ -28,12 +28,30 @@ export const LANGUAGES = [
   { code: "zh-Hans", flag: "🇨🇳", name: "简体中文" },
   { code: "de", flag: "🇩🇪", name: "Deutsch" },
   { code: "fr", flag: "🇫🇷", name: "Français" },
-  { code: "pt", flag: "🇧🇷", name: "Português" },
+  { code: "pt", flag: "🇧🇷", name: "Português (Brasil)" },
+  { code: "pt-PT", flag: "🇵🇹", name: "Português (Portugal)" },
   { code: "id", flag: "🇮🇩", name: "Bahasa Indonesia" },
 ];
 const SUPPORTED_CODES = new Set(LANGUAGES.map((l) => l.code));
 const DEFAULT_LANG = "en";
 
+// Regional variants resolve through their base language before English.
+//
+// European and Brazilian Portuguese share the overwhelming majority of 461
+// keys. Duplicating the whole table to change "ficheiro" and a few dozen
+// verb forms would mean every future key had to be written twice and would
+// drift the moment one was missed. A variant carries only what genuinely
+// differs, and falls through for the rest.
+const FALLBACK = { "pt-PT": "pt" };
+
+function _tables() {
+  const chain = [_lang];
+  const base = FALLBACK[_lang];
+  if (base) chain.push(base);
+  chain.push(DEFAULT_LANG);
+  return chain.map((code) => TRANSLATIONS[code]).filter(Boolean);
+}
+
 let _lang = DEFAULT_LANG;
 const _listeners = new Set();
 
@@ -46,8 +64,11 @@ function _detectDefault() {
   // unless it's explicitly a traditional-script region, which we don't ship).
   if (lower.startsWith("zh")) return "zh-Hans";
   if (lower.startsWith("de")) return "de";
-  // Portuguese: pt-BR, pt-PT, or bare "pt" all map to the single pt table
-  // (written in Brazilian Portuguese, the more widely used variant).
+  // Portuguese: an explicit Portugal locale gets the European variant, which
+  // overrides only the words that differ and falls through to pt for the rest.
+  // pt-BR and a bare "pt" both take the Brazilian table, which is the more
+  // widely used variant and so the sensible default for an unqualified tag.
+  if (lower.startsWith("pt-pt") || lower === "pt_pt") return "pt-PT";
   if (lower.startsWith("pt")) return "pt";
   if (lower.startsWith("id")) return "id";
   return "en";
@@ -94,8 +115,10 @@ function _interpolate(str, vars) {
 }
 
 export function t(key, vars) {
-  const table = TRANSLATIONS[_lang] || TRANSLATIONS[DEFAULT_LANG];
-  const str = table[key] ?? TRANSLATIONS[DEFAULT_LANG][key];
+  let str;
+  for (const table of _tables()) {
+    if (table[key] != null) { str = table[key]; break; }
+  }
   if (str == null) {
     console.warn(`[i18n] missing key "${key}"`);
     return key;
@@ -110,7 +133,6 @@ export function t(key, vars) {
 // and the fallback chain below finds it regardless of computed form). Polish
 // needs three (one / few / many) per its numeral rules.
 export function plural(key, count, vars) {
-  const table = TRANSLATIONS[_lang] || TRANSLATIONS[DEFAULT_LANG];
   let form;
   if (_lang === "pl") {
     const n = Math.abs(count);
@@ -127,11 +149,14 @@ export function plural(key, count, vars) {
   // English -- languages with no grammatical plural (Japanese, Chinese) only
   // define ".other", so a singular count must resolve there, not to an
   // English ".one" string mixed into otherwise-translated text.
-  const str =
-    table[fullKey] ??
-    table[`${key}.other`] ??
-    TRANSLATIONS[DEFAULT_LANG][fullKey] ??
-    TRANSLATIONS[DEFAULT_LANG][`${key}.other`];
+  // Walk the same chain as t(), trying each table's exact form before its
+  // "other" bucket, so a variant that does not override a plural falls through
+  // to its base language rather than to English.
+  let str;
+  for (const table of _tables()) {
+    str = table[fullKey] ?? table[`${key}.other`];
+    if (str != null) break;
+  }
   if (str == null) {
     console.warn(`[i18n] missing plural key "${fullKey}"`);
     return key;
@@ -241,7 +266,8 @@ const en = {
   "search.searching": "Searching…",
   "search.noResults": "No results",
   "search.failed": "Search failed. Check your connection.",
-  "search.tooLong": "Over {mins} min limit",
+  "search.tooLong": "Over {mins} min",
+  "search.tooLongHint": "Longer than your {mins} minute limit. Change it in Settings.",
   "search.preview": "Preview",
   "search.play": "Play",
   "search.pause": "Pause",
@@ -764,7 +790,8 @@ const pl = {
   "search.searching": "Szukanie…",
   "search.noResults": "Brak wyników",
   "search.failed": "Wyszukiwanie nie powiodło się. Sprawdź połączenie.",
-  "search.tooLong": "Ponad limit {mins} min",
+  "search.tooLong": "Ponad {mins} min",
+  "search.tooLongHint": "Dłuższy niż Twój limit {mins} minut. Zmień go w Ustawieniach.",
   "search.preview": "Odsłuch",
   "search.play": "Odtwórz",
   "search.pause": "Pauza",
@@ -1277,7 +1304,8 @@ const ja = {
   "search.searching": "検索中…",
   "search.noResults": "結果がありません",
   "search.failed": "検索に失敗しました。接続を確認してください。",
-  "search.tooLong": "{mins} 分の上限超過",
+  "search.tooLong": "{mins} 分超",
+  "search.tooLongHint": "設定した {mins} 分の上限を超えています。設定で変更できます。",
   "search.preview": "試聴",
   "search.play": "再生",
   "search.pause": "一時停止",
@@ -1765,7 +1793,8 @@ const zhHans = {
   "search.searching": "搜索中…",
   "search.noResults": "没有结果",
   "search.failed": "搜索失败，请检查网络连接。",
-  "search.tooLong": "超过 {mins} 分钟上限",
+  "search.tooLong": "超过 {mins} 分钟",
+  "search.tooLongHint": "超过您设置的 {mins} 分钟上限。可在“设置”中修改。",
   "search.preview": "试听",
   "search.play": "播放",
   "search.pause": "暂停",
@@ -2253,7 +2282,8 @@ const de = {
   "search.searching": "Suche läuft…",
   "search.noResults": "Keine Ergebnisse",
   "search.failed": "Suche fehlgeschlagen. Verbindung prüfen.",
-  "search.tooLong": "Über dem Limit von {mins} Min.",
+  "search.tooLong": "Über {mins} Min.",
+  "search.tooLongHint": "Länger als Ihr Limit von {mins} Minuten. Änderbar in den Einstellungen.",
   "search.preview": "Vorhören",
   "search.play": "Abspielen",
   "search.pause": "Pause",
@@ -2752,7 +2782,8 @@ const pt = {
   "search.searching": "Pesquisando…",
   "search.noResults": "Nenhum resultado",
   "search.failed": "A pesquisa falhou. Verifique sua conexão.",
-  "search.tooLong": "Acima do limite de {mins} min",
+  "search.tooLong": "Mais de {mins} min",
+  "search.tooLongHint": "Maior que o seu limite de {mins} minutos. Altere nas Configurações.",
   "search.preview": "Prévia",
   "search.play": "Reproduzir",
   "search.pause": "Pausar",
@@ -3253,7 +3284,8 @@ const id = {
   "search.searching": "Mencari…",
   "search.noResults": "Tidak ada hasil",
   "search.failed": "Pencarian gagal. Periksa koneksi Anda.",
-  "search.tooLong": "Melebihi batas {mins} mnt",
+  "search.tooLong": "Lebih {mins} mnt",
+  "search.tooLongHint": "Lebih panjang dari batas {mins} menit Anda. Ubah di Pengaturan.",
   "search.preview": "Pratinjau",
   "search.play": "Putar",
   "search.pause": "Jeda",
@@ -3741,7 +3773,8 @@ const fr = {
   "search.searching": "Recherche…",
   "search.noResults": "Aucun résultat",
   "search.failed": "La recherche a échoué. Vérifiez votre connexion.",
-  "search.tooLong": "Au-delà de la limite de {mins} min",
+  "search.tooLong": "Plus de {mins} min",
+  "search.tooLongHint": "Plus long que votre limite de {mins} minutes. Modifiable dans les Réglages.",
   "search.preview": "Écouter",
   "search.play": "Lecture",
   "search.pause": "Pause",
@@ -4182,4 +4215,53 @@ const fr = {
   "resetConfirm.failedConnection": "Échec de la réinitialisation — vérifiez votre connexion.",
 };
 
-export const TRANSLATIONS = { en, pl, ja, "zh-Hans": zhHans, de, fr, pt, id };
+// European Portuguese. Overrides only: anything not listed here resolves
+// through pt (see FALLBACK), so the two variants cannot drift and a key
+// added to pt later is picked up here rather than reverting to English.
+const ptPT = {
+  "topbar.urlPlaceholder": "Pesquise, ou cole um link do YouTube ou SoundCloud, ou largue um ficheiro de áudio…",
+  "topbar.removeFile": "Remover ficheiro",
+  "topbar.uploadFile": "Carregar ficheiro de áudio",
+  "library.importedFile": "Ficheiro importado",
+  "track.localFile": "Ficheiro local",
+  "settings.cookies.invalid": "Ficheiro não encontrado ou ilegível.",
+  "upload.unsupportedFormat": "Apenas ficheiros MP3, WAV, FLAC, MP4, M4A, OGG e Opus são compatíveis.",
+  "upload.fileTooLarge": "O ficheiro é demasiado grande ({size}). O máximo é {max}.",
+  "upload.skippedFiles.one": "{count} ficheiro ignorado ({reason}).",
+  "upload.skippedFiles.other": "{count} ficheiros ignorados ({reason}).",
+  "settings.logs.noFilesYet": "Ainda não há ficheiros de log{folderNote}. O registo começa na primeira mensagem após o arranque.",
+  "settings.logs.location.desc": "Onde o StemDeck grava os logs nesta máquina. Só de leitura, abra-os num gestor de ficheiros ou use Exportar logs.",
+  "nav.settings": "Definições",
+  "settings.title": "Definições",
+  "settings.closeAria": "Fechar definições",
+  "settings.readOnlyServer": "Estas definições são só de leitura no modo servidor. Para as alterar, atualize a configuração do servidor (ex.: docker-compose.yml) e reinicie.",
+  "search.tooLongHint": "Maior que o seu limite de {mins} minutos. Altere nas Definições.",
+  "settings.folder.save": "Guardar",
+  "folderEditor.save": "Guardar",
+  "sections.savingAria": "A guardar secções",
+  "aria.download": "Transferir {name}",
+  "release.download": "Transferir",
+  "release.downloading": "A transferir atualização…",
+  "release.pullImage": "Transfira a nova imagem e reinicie o contentor:",
+  "settings.exportLogs.desc": "Transfira todos os ficheiros de log num único zip, o que anexar a um relatório de erro. Veja o separador Logs para saber onde ficam.",
+  "wave.loadingAria": "A carregar forma de onda",
+  "player.stillLoadingWaveform": "Ainda a carregar a forma de onda…",
+  "release.applying": "A aplicar atualização…",
+  "failure.collecting": "A recolher detalhes…",
+  "failure.fetchingLogs": "A obter logs…",
+  "job.processingTrackTitle": "A processar faixa",
+  "settings.stemsLocation.moving": "A mover stems, isto pode demorar numa biblioteca grande.",
+  "settings.cookies.desc": "Opcional. Caminho para um ficheiro cookies.txt, usado apenas quando o YouTube pede ao StemDeck para confirmar que não é um robô. Deixe vazio a menos que as importações estejam a falhar.",
+  "search.preview": "Pré-escuta",
+  "search.previewFailed": "Pré-escuta indisponível",
+  "export.includeClickTitle": "Misturar o clique de referência no ficheiro exportado",
+  "settings.network.allowDesc": "Permite que outros dispositivos (como o seu telemóvel) abram o StemDeck no endereço abaixo.",
+  "settings.network.lockNote": "Só de leitura quando o StemDeck é iniciado em modo servidor, o acesso à rede é então definido pela configuração do seu servidor.",
+  "settings.logs.setupAria": "Log de configuração (só de leitura)",
+  "settings.logs.setup.desc": "A última hora de <code>setup.log</code>, configuração inicial e instalação do runtime de GPU. Apenas app desktop. Só de leitura.",
+  "settings.stemsLocation.movedPersistFailed.one": "{count} item movido, mas o StemDeck não conseguiu guardar isto como o novo local (verifique se a pasta é gravável). Reiniciar agora reverteria para o local antigo. Tente definir novamente.",
+  "settings.stemsLocation.movedPersistFailed.other": "{count} itens movidos, mas o StemDeck não conseguiu guardar isto como o novo local (verifique se a pasta é gravável). Reiniciar agora reverteria para o local antigo. Tente definir novamente.",
+  "failure.hint": "Estes detalhes vão para o relatório. O título da faixa e o link de origem não são incluídos, adicione-os se ajudar. Clicar num botão abaixo copia isto para a área de transferência.",
+};
+
+export const TRANSLATIONS = { en, pl, ja, "zh-Hans": zhHans, de, fr, pt, "pt-PT": ptPT, id };
diff --git a/static/js/search.js b/static/js/search.js
index 6c256d68..a84faf59 100644
--- a/static/js/search.js
+++ b/static/js/search.js
@@ -193,7 +193,11 @@ function render(maxDurationSec) {
       // something that can only fail.
       const warn = document.createElement("span");
       warn.className = "search-warn";
+      // Terse inline, because it shares a 620px row with a title, an uploader,
+      // a duration and the Preview pill. The part the user can act on lives in
+      // the tooltip rather than squeezing the title it sits next to.
       warn.textContent = t("search.tooLong", { mins });
+      warn.title = t("search.tooLongHint", { mins });
       main.appendChild(warn);
     }
 

From 9cdfeeb389251163e38c26786fe9118ad7859fea Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:20:44 +0100
Subject: [PATCH 05/11] Complete the European Portuguese translation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The first pass scanned a hand-written list of nouns and caught 43 strings. A
systematic scan found 41 more, so the variant now carries 84 overrides.

The biggest omission was the progressive aspect. Brazilian Portuguese uses
the gerund, European uses 'a' plus the infinitive, and that is every status
line in the app: Processando, Pesquisando, Exportando, Sincronizando,
Salvando, Iniciando all read as Brazilian to someone in Portugal. Those are
now A processar, A pesquisar, A exportar, A sincronizar, A guardar,
A iniciar.

Also covered:

- Registro to Registo
- aplicativo to aplicação
- conexão to ligação
- somente leitura to só de leitura
- detectar to detetar, where the 1990 orthographic agreement dropped a
  consonant that is silent in Portugal and kept it in Brazil
- em plus article contracting to num/numa
- salvá-la to guardá-la

The four metronome notes are overridden together even though only two were
flagged, because rewording half of a set that reads as one paragraph is worse
than leaving all four alone.

Two matches were left deliberately. 'Log de configuração' stays: the scan
flagged it on 'configuraç', but that pattern exists to catch Configurações
meaning Settings, and configuração meaning configuration is correct in both
variants.
---
 static/js/i18n.js | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/static/js/i18n.js b/static/js/i18n.js
index ff9df75a..c4c90e16 100644
--- a/static/js/i18n.js
+++ b/static/js/i18n.js
@@ -4219,6 +4219,50 @@ const fr = {
 // through pt (see FALLBACK), so the two variants cannot drift and a key
 // added to pt later is picked up here rather than reverting to English.
 const ptPT = {
+  "metro.note.full": "Clique a {bpm} BPM, {conf}% das batidas coincidem com uma batida de bateria, acentuando a cada {accent} batidas. Use /2 ou x2 se o clique parecer metade ou o dobro da velocidade.",
+  "metro.note.noAccent": "Clique a {bpm} BPM, {conf}% das batidas coincidem com uma batida de bateria. Use /2 ou x2 se o clique parecer metade ou o dobro da velocidade.",
+  "metro.note.fallback": "Clique a {bpm} BPM do rastreador alternativo. Use /2 ou x2 se o clique parecer metade ou o dobro da velocidade.",
+  "export.mixing": "A exportar…",
+  "job.cancelling": "A cancelar…",
+  "job.processing": "A processar",
+  "job.working": "A processar…",
+  "library.syncing": "A sincronizar…",
+  "queue.starting": "A iniciar…",
+  "resetConfirm.resetting": "A repor…",
+  "search.searching": "A pesquisar…",
+  "sections.saving": "A guardar",
+  "settings.exportLogs.preparing": "A preparar…",
+  "settings.logs.loading": "A carregar…",
+  "settings.stemsLocation.resetting": "A repor…",
+  "settings.stemsLocation.syncing": "A sincronizar…",
+  "playlist.skippingPrefix": "A ignorar: {list}.",
+  "settings.tab.registry": "Registo",
+  "settings.registry.title": "Registo de tarefas",
+  "settings.registry.aria": "Registo de tarefas (só de leitura)",
+  "settings.registry.desc": "Vista só de leitura de <code>registry.json</code>, a lista persistida de tarefas concluídas no disco.",
+  "settings.language.desc": "Idioma de apresentação desta aplicação.",
+  "settings.logs.application.title": "Log da aplicação",
+  "settings.logs.applicationTab": "Log da aplicação",
+  "settings.logs.applicationAria": "Log da aplicação (só de leitura)",
+  "settings.logs.application.desc": "A última hora de <code>stemdeck.log</code>, atividade de pipeline, API e tarefas. Só de leitura.",
+  "settings.logs.backendAria": "Log do backend (só de leitura)",
+  "settings.logs.backend.desc": "A última hora de <code>backend.log</code>, saída bruta do processo Python incorporado, incluindo qualquer coisa que o tenha bloqueado antes de o log da aplicação conseguir registar. Apenas app desktop. Só de leitura.",
+  "library.syncFailed": "Falha na sincronização, verifique a sua ligação.",
+  "resetConfirm.failedConnection": "Falha ao repor, verifique a sua ligação.",
+  "search.failed": "A pesquisa falhou. Verifique a sua ligação.",
+  "settings.network.noConnection": "Nenhuma ligação de rede local detetada.",
+  "settings.stemsLocation.resetFailed": "Falha ao repor, verifique a sua ligação.",
+  "settings.stemsLocation.syncFailed": "Falha na sincronização, verifique a sua ligação.",
+  "beatgrid.resetTitle": "Descartar todas as edições e restaurar a grelha detetada",
+  "click.auto": "Auto (detetado)",
+  "click.detected": "Tempo detetado",
+  "metro.note.detectedMultiBar": "Clique a {bpm} BPM, {conf}% das batidas coincidem com uma batida de bateria, acentuando {count} regiões métricas detetadas. Use /2 ou x2 se o clique parecer metade ou o dobro da velocidade.",
+  "metro.note.detectedSingleBar": "Clique a {bpm} BPM, {conf}% das batidas coincidem com uma batida de bateria, acentuando {beats}/4 a partir do tempo forte detetado. Use /2 ou x2 se o clique parecer metade ou o dobro da velocidade.",
+  "beatgrid.barLineTitle": "Clique numa batida para a marcar como tempo forte",
+  "beatgrid.deleteTitle": "Clique numa batida para a remover",
+  "playlist.confirmBody.one": "Coloca em fila <strong>{count}</strong> faixa, uma de cada vez, numa pasta com o mesmo nome.{skipped}",
+  "playlist.confirmBody.other": "Coloca em fila <strong>{count}</strong> faixas, uma de cada vez, numa pasta com o mesmo nome.{skipped}",
+  "favorites.empty": "Ainda sem favoritos, clique no ♥ de uma faixa para a guardar",
   "topbar.urlPlaceholder": "Pesquise, ou cole um link do YouTube ou SoundCloud, ou largue um ficheiro de áudio…",
   "topbar.removeFile": "Remover ficheiro",
   "topbar.uploadFile": "Carregar ficheiro de áudio",

From 12c9360ffac744c350a8d59190581484d1f2799b Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:27:28 +0100
Subject: [PATCH 06/11] Max track length: the UI kept its own stale copy of the
 ceiling

Reported as the search badge still saying 'Over 20 min' after setting the
limit to 60. The badge was right. The setting never changed.

Three places disagreed about the ceiling:

  backend  _DURATION_MAX = 3600   60 minutes
  client   Math.min(20, ...)      20 minutes
  label    "(max 20)"             20 minutes

So typing 60 hit the client clamp, posted 1200, and the field snapped back to
20 with nothing said. The backend had allowed 60 all along; only the client
refused to send it.

Fixed by removing the second copy rather than correcting it. /api/settings
now publishes max_duration_min_sec and max_duration_max_sec, the client sends
what was typed and lets the server clamp, and apply() writes back whatever
the server kept. The description text takes {max} from the same source
instead of a hardcoded number, in all eight tables.

That is the actual defect here. A duplicated constant does not announce
itself when it goes stale: nothing failed, no test broke, and the only
symptom was a number quietly refusing to change.
---
 app/core/settings.py          |  3 +++
 app/main.py                   |  7 +++++++
 static/js/catalog.js          | 16 +++++++++++++--
 static/js/i18n.js             | 16 +++++++--------
 tests/test_settings_mirror.py | 37 +++++++++++++++++++++++++++++++++++
 5 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/app/core/settings.py b/app/core/settings.py
index 2ff2cd9f..4e5f4aaf 100644
--- a/app/core/settings.py
+++ b/app/core/settings.py
@@ -42,6 +42,9 @@
 
 # Clamp bounds. Max track length is capped at 60 min (the product ceiling).
 _DURATION_MIN, _DURATION_MAX = 60, 3600  # 1 min .. 60 min
+# Published through /api/settings so the UI reads the ceiling rather than
+# keeping its own copy of it.
+DURATION_MIN_SEC, DURATION_MAX_SEC = _DURATION_MIN, _DURATION_MAX
 _HEIGHT_MIN, _HEIGHT_MAX = 144, 2160
 _PLAYLIST_MIN, _PLAYLIST_MAX = 1, 200
 _PORT_MIN, _PORT_MAX = 1024, 65535
diff --git a/app/main.py b/app/main.py
index ecca117e..78b76115 100644
--- a/app/main.py
+++ b/app/main.py
@@ -40,6 +40,8 @@
 from app.core.registry import reset_all as reset_registry
 from app.core.registry import restore as restore_registry
 from app.core.settings import (
+    DURATION_MAX_SEC,
+    DURATION_MIN_SEC,
     get_allow_network,
     get_cookies_file,
     get_demucs_device,
@@ -319,6 +321,11 @@ def _settings_payload() -> dict[str, object]:
     return {
         "allow_network": get_allow_network(),
         "max_duration_sec": get_max_duration_sec(),
+        # The clamp bounds, so the UI does not need its own copy of them. It
+        # had one, it was stale (20 min against a 60 min ceiling), and the
+        # symptom was a user typing 60 and silently getting 20 back.
+        "max_duration_min_sec": DURATION_MIN_SEC,
+        "max_duration_max_sec": DURATION_MAX_SEC,
         "playlist_max_items": get_playlist_max_items(),
         "video_max_height": get_video_max_height(),
         "export_sample_rate": get_export_sample_rate(),
diff --git a/static/js/catalog.js b/static/js/catalog.js
index 09158379..2d23cb38 100644
--- a/static/js/catalog.js
+++ b/static/js/catalog.js
@@ -3018,6 +3018,7 @@ function wireLanguageSetting(overlay) {
 // and POSTed on change to /api/settings (same runtime store as the toggle).
 async function wireGeneralSettings(overlay) {
   const durInput = overlay.querySelector(".set-max-duration");
+  const durDesc = overlay.querySelector(".set-max-duration-desc");
   const playlistInput = overlay.querySelector(".set-playlist-max");
   const heightSel = overlay.querySelector(".set-video-height");
   const sampleRateSel = overlay.querySelector(".set-export-samplerate");
@@ -3035,6 +3036,13 @@ async function wireGeneralSettings(overlay) {
 
   const apply = (d) => {
     if (durInput && d.max_duration_sec) durInput.value = String(Math.round(d.max_duration_sec / 60));
+    // Same reason: the copy in the description text went stale alongside the
+    // clamp, telling the user "max 20" for a limit that was really 60.
+    if (durDesc && d.max_duration_max_sec) {
+      durDesc.textContent = i18nT("settings.maxDuration.desc", {
+        max: Math.round(d.max_duration_max_sec / 60),
+      });
+    }
     if (playlistInput && d.playlist_max_items) playlistInput.value = String(d.playlist_max_items);
     if (heightSel && d.video_max_height) heightSel.value = String(d.video_max_height);
     if (sampleRateSel && d.export_sample_rate) sampleRateSel.value = String(d.export_sample_rate);
@@ -3097,7 +3105,11 @@ async function wireGeneralSettings(overlay) {
   };
 
   durInput?.addEventListener("change", () => {
-    const mins = Math.max(1, Math.min(20, parseInt(durInput.value, 10) || 20));
+    // No ceiling of its own. This used to clamp to 20 while the backend
+    // allowed 60, so typing 60 silently posted 20 and the field snapped back
+    // with no explanation. The server clamps and returns the value it kept,
+    // and apply() writes that back, so it stays the single authority.
+    const mins = Math.max(1, parseInt(durInput.value, 10) || 20);
     post({ max_duration_sec: mins * 60 });
   });
   playlistInput?.addEventListener("change", () => {
@@ -3485,7 +3497,7 @@ function openLibraryEditor() {
           <div class="settings-row">
             <div class="settings-row-text">
               <div class="settings-row-title" data-i18n="settings.maxDuration.title">Max track length</div>
-              <div class="settings-row-desc" data-i18n="settings.maxDuration.desc">Longest track accepted for processing, in minutes (max 20).</div>
+              <div class="settings-row-desc set-max-duration-desc">Longest track accepted for processing, in minutes (max 60).</div>
             </div>
             <input type="text" class="settings-num-input set-max-duration" inputmode="numeric" maxlength="2" aria-label="Max track length in minutes" data-i18n-aria-label="settings.maxDuration.title" />
           </div>
diff --git a/static/js/i18n.js b/static/js/i18n.js
index c4c90e16..99fae118 100644
--- a/static/js/i18n.js
+++ b/static/js/i18n.js
@@ -456,7 +456,7 @@ const en = {
   "settings.language.desc": "Display language for this app.",
 
   "settings.maxDuration.title": "Max track length",
-  "settings.maxDuration.desc": "Longest track accepted for processing, in minutes (max 20).",
+  "settings.maxDuration.desc": "Longest track accepted for processing, in minutes (max {max}).",
   "settings.playlistLimit.title": "Playlist import limit",
   "settings.playlistLimit.desc": "Most tracks one playlist import will queue (max 200).",
   "settings.cookies.title": "YouTube cookies",
@@ -977,7 +977,7 @@ const pl = {
   "settings.language.desc": "Język wyświetlania tej aplikacji.",
 
   "settings.maxDuration.title": "Maks. długość utworu",
-  "settings.maxDuration.desc": "Najdłuższy utwór akceptowany do przetworzenia, w minutach (maks. 20).",
+  "settings.maxDuration.desc": "Najdłuższy utwór akceptowany do przetworzenia, w minutach (maks. {max}).",
   "settings.playlistLimit.title": "Limit importu playlisty",
   "settings.playlistLimit.desc": "Ile utworów najwyżej zakolejkuje jeden import playlisty (maks. 200).",
   "settings.cookies.title": "Pliki cookie YouTube",
@@ -1490,7 +1490,7 @@ const ja = {
   "settings.language.desc": "このアプリの表示言語。",
 
   "settings.maxDuration.title": "最大トラック長",
-  "settings.maxDuration.desc": "処理を受け付ける最長トラック長(分単位、最大20分)。",
+  "settings.maxDuration.desc": "処理を受け付ける最長トラック長(分単位、最大{max}分)。",
   "settings.playlistLimit.title": "プレイリストインポート上限",
   "settings.playlistLimit.desc": "プレイリストのインポート1回でキューされる最大トラック数(最大200)。",
   "settings.cookies.title": "YouTube の Cookie",
@@ -1979,7 +1979,7 @@ const zhHans = {
   "settings.language.desc": "此应用的显示语言。",
 
   "settings.maxDuration.title": "最长曲目时长",
-  "settings.maxDuration.desc": "可处理的最长曲目时长,单位为分钟(最长20分钟)。",
+  "settings.maxDuration.desc": "可处理的最长曲目时长,单位为分钟(最长{max}分钟)。",
   "settings.playlistLimit.title": "播放列表导入上限",
   "settings.playlistLimit.desc": "单次播放列表导入最多排队的曲目数(最多200首)。",
   "settings.cookies.title": "YouTube Cookie",
@@ -2469,7 +2469,7 @@ const de = {
   "settings.language.desc": "Anzeigesprache für diese App.",
 
   "settings.maxDuration.title": "Maximale Tracklänge",
-  "settings.maxDuration.desc": "Längster zur Verarbeitung akzeptierter Track, in Minuten (max. 20).",
+  "settings.maxDuration.desc": "Längster zur Verarbeitung akzeptierter Track, in Minuten (max. {max}).",
   "settings.playlistLimit.title": "Playlist-Import-Limit",
   "settings.playlistLimit.desc": "Höchste Anzahl Tracks, die ein Playlist-Import einreiht (max. 200).",
   "settings.cookies.title": "YouTube-Cookies",
@@ -2969,7 +2969,7 @@ const pt = {
   "settings.language.desc": "Idioma de exibição deste aplicativo.",
 
   "settings.maxDuration.title": "Duração máxima da faixa",
-  "settings.maxDuration.desc": "Faixa mais longa aceita para processamento, em minutos (máx. 20).",
+  "settings.maxDuration.desc": "Faixa mais longa aceita para processamento, em minutos (máx. {max}).",
   "settings.playlistLimit.title": "Limite de importação de playlist",
   "settings.playlistLimit.desc": "Máximo de faixas que uma importação de playlist enfileira (máx. 200).",
   "settings.cookies.title": "Cookies do YouTube",
@@ -3470,7 +3470,7 @@ const id = {
   "settings.language.desc": "Bahasa tampilan untuk aplikasi ini.",
 
   "settings.maxDuration.title": "Panjang trek maksimum",
-  "settings.maxDuration.desc": "Trek terpanjang yang diterima untuk diproses, dalam menit (maks. 20).",
+  "settings.maxDuration.desc": "Trek terpanjang yang diterima untuk diproses, dalam menit (maks. {max}).",
   "settings.playlistLimit.title": "Batas impor playlist",
   "settings.playlistLimit.desc": "Jumlah trek terbanyak yang akan diantrekan satu kali impor playlist (maks. 200).",
   "settings.cookies.title": "Cookie YouTube",
@@ -3961,7 +3961,7 @@ const fr = {
   "settings.language.desc": "Langue d'affichage de l'application.",
 
   "settings.maxDuration.title": "Durée maximale d'un morceau",
-  "settings.maxDuration.desc": "Durée maximale acceptée pour le traitement, en minutes (max. 20).",
+  "settings.maxDuration.desc": "Durée maximale acceptée pour le traitement, en minutes (max. {max}).",
   "settings.playlistLimit.title": "Limite d'import de playlist",
   "settings.playlistLimit.desc": "Nombre maximal de morceaux mis en file lors d'un import de playlist (max. 200).",
   "settings.cookies.title": "Cookies YouTube",
diff --git a/tests/test_settings_mirror.py b/tests/test_settings_mirror.py
index 55f0b82b..d57e6ccb 100644
--- a/tests/test_settings_mirror.py
+++ b/tests/test_settings_mirror.py
@@ -111,3 +111,40 @@ def test_mirror_holds_the_relocated_stems_folder(tmp_path, monkeypatch):
     _settings.set_jobs_dir(str(chosen))
 
     assert json.loads(mirror.read_text(encoding="utf-8"))["jobs_dir"] == str(chosen)
+
+
+def test_the_duration_ceiling_is_published_not_duplicated():
+    """The UI used to keep its own copy of the max-track-length ceiling. It
+    went stale at 20 minutes against a real ceiling of 60, so typing 60 was
+    silently clamped to 20 and the field snapped back with no explanation.
+
+    The cure was to stop having a second copy, so the bound has to stay in the
+    payload for the client to read.
+    """
+    from fastapi.testclient import TestClient
+
+    from app.core.settings import DURATION_MAX_SEC, DURATION_MIN_SEC
+    from app.main import app
+
+    with TestClient(app) as c:
+        body = c.get("/api/settings").json()
+    assert body["max_duration_max_sec"] == DURATION_MAX_SEC
+    assert body["max_duration_min_sec"] == DURATION_MIN_SEC
+
+
+def test_a_value_at_the_ceiling_is_kept(tmp_path, monkeypatch):
+    """60 minutes is a legal setting. It was reachable through the API all
+    along; only the client refused to send it."""
+    mirror = tmp_path / "settings.json"
+    monkeypatch.setattr(_settings, "_SETTINGS_PATH", mirror)
+    monkeypatch.setattr(_settings, "_state", None)
+    assert _settings.set_max_duration_sec(3600) == 3600
+    assert _settings.get_max_duration_sec() == 3600
+
+
+def test_beyond_the_ceiling_still_clamps(tmp_path, monkeypatch):
+    mirror = tmp_path / "settings.json"
+    monkeypatch.setattr(_settings, "_SETTINGS_PATH", mirror)
+    monkeypatch.setattr(_settings, "_state", None)
+    assert _settings.set_max_duration_sec(99 * 60) == 3600
+    assert _settings.set_max_duration_sec(1) == 60

From f6ad17b2598af037426ee812c023d47abcd45151 Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:49:16 +0100
Subject: [PATCH 07/11] Add a roadmap, 0.1.0 through 0.14.x

There was no written account of where the project has been. Fourteen minor
versions in under four months, and the only record was a tag list and 192 PR
titles, which tells you what changed and never why.

Dates are the first tag in each line, read from the repository rather than
reconstructed. Each release gets what it was actually for, derived from the
PRs merged in its window, not a changelog restatement.

Two threads are worth being able to point at later. The 0.7.0 security pass
(XSS, SSRF, the webview CSP, a pinned FFmpeg checksum) still constrains every
feature added since: search had to fit inside that extractor allowlist and
preview had to be proxied because of that CSP. And 0.8.0's four-phase health
report is the origin of project 2, so the board and the release history now
reference each other instead of being separate stories.

Forward-looking sections point at open issues rather than restating them, so
this does not become a second place to keep the same facts current.
---
 ROADMAP.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 164 insertions(+)
 create mode 100644 ROADMAP.md

diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 00000000..0b12520b
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,164 @@
+# StemDeck roadmap
+
+Where StemDeck has been, and what is next. Dates are the first tag in each
+line, taken from the repository rather than reconstructed.
+
+Live board: [StemDeck Health & Roadmap](https://github.com/orgs/stemdeckapp/projects/2)
+
+---
+
+## Shipped
+
+### 0.1.0 · 2026-05-04 · it exists
+
+First commit and first tag. A URL in, six stems out, a browser to play them in.
+Everything after this is consequence.
+
+### 0.2.0 · 2026-05-07 · it survives being an app
+
+Windows portable in dual CPU and NVIDIA builds, and the first collision with
+what "desktop app" actually costs: WebView2 drag and drop, stem silence in
+WKWebView, certifi certificates missing inside the Demucs subprocess, a setup
+hang after a data reset. The registry began persisting finished jobs across
+restarts, so a library outlived the process that made it.
+
+### 0.3.0 · 2026-05-10 · not only YouTube
+
+Local MP3 and WAV import, so the tool stopped being tied to one source. First
+macOS build.
+
+### 0.4.0 · 2026-05-12 · the runtime problem
+
+Almost entirely portable-Python layout and `PYTHONHOME` on Windows and macOS.
+Unglamorous, and the reason later releases could ship a runtime at all.
+
+### 0.5.0 · 2026-05-18 · the DAW
+
+The redesign that set the shape still in use: library, sections, analysis and
+transport. Export Mix, the footer waveform, tag search. Uploads normalised
+through ffmpeg, after non-standard WAVs were found separating into silence.
+
+### 0.6.0 · 2026-05-23 · exports people can find
+
+Loop-region export, native save dialogs on Windows and macOS, collapsible
+library. Runtime auto-update on version mismatch, and a setup window that
+explains itself when the network is not cooperating.
+
+### 0.7.0 · 2026-05-28 · the long one
+
+A month, forty substantive changes, and three threads at once.
+
+**Audio.** SoundCloud support, pre-computed peaks so waveforms appear instead
+of being computed, the Web Audio decode-and-mix engine, and then several
+rounds of making that engine survive WebView2. FLAC, MP4 and M4A import. MP4
+karaoke export.
+
+**Security.** The security pass that closed XSS (#170) and SSRF (#173), added
+the webview Content-Security-Policy (#171), and pinned the macOS FFmpeg
+download to a verified SHA256 (#172). Those decisions still constrain the
+design today: every feature since has had to work inside that CSP and that
+extractor allowlist.
+
+**Platforms.** Linux portable builds, RTX 50-series CUDA, and the first
+encounter with GitHub's 2 GiB release asset cap, which has shaped packaging
+ever since.
+
+### 0.8.0 · 2026-06-27 · the health report
+
+Six weeks and the largest single body of work in the project. Two halves.
+
+**Reach.** The mobile web UI with a chunked audio engine, network access with
+QR codes, Docker and Unraid via GHCR, playback speed with pitch preservation,
+the click track and beat grid, background import queue and playlist import.
+
+**Health.** A codebase health report turned into
+[project 2](https://github.com/orgs/stemdeckapp/projects/2) and worked in four
+phases:
+
+| Phase | What it was for |
+|---|---|
+| 1 — Evidence | Rotating logs, failed-job quarantine, error classification, per-stage timings, and no more internal exception text in the UI |
+| 2 — Resilience | GPU to CPU fallback, retried metadata probes, the Windows registry persist race, graceful watchdog shutdown, tear-proof SSE serialization |
+| 3 — Performance | Single-pass streamed peaks, a persistent Demucs worker instead of reloading weights per job, SSE dirty flags, cached mixdowns |
+| 4 — Separation SOTA | The RoFormer and lead/backing vocal split investigation |
+
+The persistent worker alone removed 35 to 42 percent of the separate stage on
+an RTX 3080.
+
+### 0.9.0 · 2026-08-12 · the library is yours
+
+Choose where stems are stored. The WAV header parser stopped giving up after
+1 KB, and a track that cannot load now says so instead of failing quietly.
+First browser tests.
+
+### 0.10.0 · 2026-08-16 · count-in, and reporting back
+
+Count-in, a transport footer rebuilt on the studio's column grid, and reporting
+a failure straight from the notification centre.
+
+### 0.11.x · 2026-08-17 · keeping the door open
+
+YouTube import gaps, macOS FFmpeg download reliability, and a yt-dlp relock to
+fix a 403 on download. The first clear sign that YouTube extraction is a moving
+target rather than a solved problem.
+
+### 0.12.x · 2026-08-21 · lead and backing vocals
+
+Phase 4 landing: the lead/backing vocal split. Plus portable Windows data
+directories and the stems relocation fixes that followed.
+
+### 0.13.0 · 2026-08-22 · seven languages
+
+German, Portuguese and Indonesian, taking the UI to seven languages. A system
+FFmpeg is now preferred on desktop when it verifies as compatible.
+
+### 0.14.x · 2026-08-23 · updating in place
+
+The leaner Windows package and the opt-in in-app updater, then the three
+corrections it needed: settings surviving a new install, updates only offered
+once a release is promoted, and a second StemDeck no longer adopting the
+first one's backend. Most recently, YouTube import diagnostics, an opt-in
+cookies file, and 0.75x playback.
+
+---
+
+## In flight
+
+Search, preview, and the fixes found alongside them.
+
+| Issue | |
+|---|---|
+| [#441](https://github.com/stemdeckapp/stemdeck/issues/441) | Search YouTube and SoundCloud from the topbar |
+| [#442](https://github.com/stemdeckapp/stemdeck/issues/442) | Audition a result before extracting it |
+| [#440](https://github.com/stemdeckapp/stemdeck/issues/440) | An undecodable byte kills the whole separation |
+| [#443](https://github.com/stemdeckapp/stemdeck/issues/443) | Max track length clamps to 20 when the ceiling is 60 |
+| [#444](https://github.com/stemdeckapp/stemdeck/issues/444) | Portuguese ships only the Brazilian variant |
+
+## Next
+
+**Keep YouTube import working.** [#432](https://github.com/stemdeckapp/stemdeck/issues/432)
+and [#438](https://github.com/stemdeckapp/stemdeck/issues/438). Extraction
+currently works through a fallback client that yt-dlp has deprecated. The
+solver and a bundled JS runtime are both proven to work and are held on a
+packaging decision, not a technical one. This is not urgent and it is not
+optional.
+
+**Save and restore a workspace.** [#425](https://github.com/stemdeckapp/stemdeck/issues/425).
+Volume, mute and solo persist per song. Loop region, zoom, playhead, speed and
+click settings do not, so a reloaded track does not come back as it was left.
+
+**Pitch and key transposition.** [#245](https://github.com/stemdeckapp/stemdeck/issues/245).
+Requested for vocal practice and karaoke.
+
+**A VST plugin.** [#404](https://github.com/stemdeckapp/stemdeck/issues/404).
+Exploratory.
+
+---
+
+## How releases work
+
+The version comes from the git tag; nothing is hand-edited. Every release ships
+as a pre-release and is promoted by hand once verified, and only a promoted
+release is offered by the in-app updater. Desktop and Docker take deliberately
+different paths for the CPU and GPU split. See
+[`.claude/rules/versioning.md`](.claude/rules/versioning.md).

From 611a821c4a9b1f3f766ea5dffc249e8d3aa901ad Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 14:59:01 +0100
Subject: [PATCH 08/11] Verify the preview stream's scheme before opening it

Bandit B310 on the proxy's urlopen, and it was pointing at something real.

_pick_format reads yt-dlp's `protocol` field, which is metadata about the
format rather than a guarantee about the URL string. Nothing checked the
scheme of the thing actually handed to urlopen, so a file:// or a custom
scheme reaching it would have been read off the host's disk and streamed
straight to the client. The proxy is the one place in the app that opens an
arbitrary host, which is exactly where that matters.

Checked twice on purpose, the same shape as the path-traversal checks in
api/stems.py: refused in resolve() where the URL is chosen, and again at the
call that opens the socket.

The nosec is added only after those checks exist. Suppressing B310 on its own
would have hidden a real hole rather than documented a safe one, and three
tests now assert the refusal so the suppression cannot quietly become untrue.
---
 app/api/search.py       | 15 ++++++++++++++-
 app/pipeline/preview.py | 10 ++++++++++
 tests/test_preview.py   | 42 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/app/api/search.py b/app/api/search.py
index 0ea64890..2c16528f 100644
--- a/app/api/search.py
+++ b/app/api/search.py
@@ -22,6 +22,7 @@
 import logging
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 
 from fastapi import APIRouter, HTTPException, Request
@@ -180,10 +181,22 @@ def _proxy(stream: dict, range_header: str | None):
     Range is forwarded rather than swallowed, so seeking the time bar costs one
     short request instead of pulling the track from the beginning again.
     """
+    # Belt and suspenders, the same shape as the path-traversal checks in
+    # api/stems.py. preview.resolve() already refuses anything that is not
+    # http(s), and this refuses it again at the one call that actually opens a
+    # socket. A file:// or custom scheme here would be read off the host's disk
+    # and streamed to the client.
+    if urllib.parse.urlparse(stream["url"]).scheme not in ("http", "https"):
+        raise ValueError("refusing to proxy a non-http(s) stream")
+
     req = urllib.request.Request(stream["url"], headers=dict(stream["headers"]))
     if range_header:
         req.add_header("Range", range_header)
-    upstream = urllib.request.urlopen(req, timeout=_PREVIEW_TIMEOUT_SEC)
+    # The scheme is verified immediately above and again in preview.resolve(),
+    # and the URL comes from yt-dlp resolving a page that already passed
+    # validate_youtube_url (#173), never from the client. B310 exists to catch
+    # exactly the file:// case those two checks refuse.
+    upstream = urllib.request.urlopen(req, timeout=_PREVIEW_TIMEOUT_SEC)  # nosec B310
 
     def body():
         try:
diff --git a/app/pipeline/preview.py b/app/pipeline/preview.py
index b32af548..ed81efd4 100644
--- a/app/pipeline/preview.py
+++ b/app/pipeline/preview.py
@@ -23,6 +23,7 @@
 import logging
 import threading
 import time
+import urllib.parse
 
 from yt_dlp import YoutubeDL
 
@@ -121,6 +122,15 @@ def resolve(url: str) -> dict:
     if not fmt:
         raise PreviewUnavailable("no progressive audio stream")
 
+    # The proxy opens this URL, so the scheme is checked here rather than
+    # trusted. _pick_format reads yt-dlp's `protocol` field, which is metadata
+    # about the format and not a guarantee about the string: a file:// or a
+    # custom scheme reaching urlopen would be read off the host's disk and
+    # streamed straight to the client. Cheap to assert, and the assertion is
+    # what makes the nosec on the urlopen honest.
+    if urllib.parse.urlparse(fmt["url"]).scheme not in _PROGRESSIVE:
+        raise PreviewUnavailable("resolved stream is not http(s)")
+
     payload = {
         "url": fmt["url"],
         # yt-dlp knows the container; the browser needs a usable type to decode.
diff --git a/tests/test_preview.py b/tests/test_preview.py
index 08cffb6a..94dd822f 100644
--- a/tests/test_preview.py
+++ b/tests/test_preview.py
@@ -215,3 +215,45 @@ def fake_urlopen(req, timeout=None):
     assert seen["ua"] == "yt-dlp", "yt-dlp's negotiated headers were dropped"
     assert r.headers["content-range"] == "bytes 100-199/1000"
     assert r.headers["accept-ranges"] == "bytes"
+
+
+# ── the scheme boundary ──────────────────────────────────────────────
+
+
+def test_a_non_http_url_is_refused_even_when_the_protocol_field_lies():
+    """yt-dlp's `protocol` field is metadata about the format, not a guarantee
+    about the string. The proxy opens this URL, so a file:// slipping through
+    would be read off the host's disk and streamed to the client.
+
+    This is what makes the `# nosec B310` on the urlopen honest rather than a
+    silenced warning.
+    """
+    _FakeYDL.formats = [{**AUDIO_LOW, "url": "file:///etc/passwd", "protocol": "https"}]
+    with pytest.raises(preview_mod.PreviewUnavailable, match="not http"):
+        preview_mod.resolve(URL)
+
+
+@pytest.mark.parametrize("bad", ["file:///etc/passwd", "ftp://host/x", "data:audio/mp3;base64,AA"])
+def test_the_proxy_refuses_a_non_http_scheme_too(client, bad):
+    """Belt and suspenders, the same shape as the path-traversal checks in
+    api/stems.py: refused where it is resolved, and again at the one call that
+    actually opens a socket."""
+    opened = []
+
+    def fake_urlopen(req, timeout=None):
+        opened.append(req)
+        raise AssertionError("urlopen must not be reached")
+
+    stream = {"url": bad, "headers": {}, "mime": "audio/mpeg"}
+    with (
+        patch.object(api_search, "resolve_preview", lambda _u: stream),
+        patch.object(api_search.urllib.request, "urlopen", fake_urlopen),
+    ):
+        r = client.get("/api/search/preview", params={"url": URL})
+    assert r.status_code == 502
+    assert not opened, "a socket was opened for a non-http(s) scheme"
+
+
+def test_a_normal_https_stream_still_passes_the_check():
+    """The guard must not be so tight that it refuses the real thing."""
+    assert preview_mod.resolve(URL)["url"].startswith("https://")

From 544f502b491f662fd9bacd152877f1a62401de10 Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 15:09:16 +0100
Subject: [PATCH 09/11] Roadmap: no links a reader cannot follow

Two dead links in a file whose whole job is orientation.

The repository is public and project 2 is private, so both links to the board
returned 404 for everyone except the people who already knew what was on it.
The board is still where the work is tracked; it is just not something a
public document can point at while it stays private. Making it public is a
visibility decision, not a formatting one, so the links are gone rather than
the board's setting changed.

The versioning link pointed at .claude/rules/versioning.md, which is
gitignored. It resolved locally, which is why it looked fine when written, and
404'd for every reader. Replaced with the content itself: the version comes
from the tag, promotion is manual and is what the updater watches, and desktop
and Docker split CPU/GPU differently on purpose.

Every remaining link now resolves anonymously, which is the only test that
matters for a public file.
---
 ROADMAP.md | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/ROADMAP.md b/ROADMAP.md
index 0b12520b..4503cadb 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -3,7 +3,8 @@
 Where StemDeck has been, and what is next. Dates are the first tag in each
 line, taken from the repository rather than reconstructed.
 
-Live board: [StemDeck Health & Roadmap](https://github.com/orgs/stemdeckapp/projects/2)
+Day to day work is tracked in
+[issues](https://github.com/stemdeckapp/stemdeck/issues).
 
 ---
 
@@ -71,9 +72,7 @@ Six weeks and the largest single body of work in the project. Two halves.
 QR codes, Docker and Unraid via GHCR, playback speed with pitch preservation,
 the click track and beat grid, background import queue and playlist import.
 
-**Health.** A codebase health report turned into
-[project 2](https://github.com/orgs/stemdeckapp/projects/2) and worked in four
-phases:
+**Health.** A codebase health report, worked in four phases:
 
 | Phase | What it was for |
 |---|---|
@@ -157,8 +156,17 @@ Exploratory.
 
 ## How releases work
 
-The version comes from the git tag; nothing is hand-edited. Every release ships
-as a pre-release and is promoted by hand once verified, and only a promoted
-release is offered by the in-app updater. Desktop and Docker take deliberately
-different paths for the CPU and GPU split. See
-[`.claude/rules/versioning.md`](.claude/rules/versioning.md).
+The version comes from the git tag. `pyproject.toml` is `dynamic`, and the
+desktop manifests hold `0.0.0` placeholders the release workflow stamps, so
+there is no version number to hand-edit anywhere.
+
+Every release ships as a pre-release and is promoted by hand once it has been
+verified. That promotion is what the in-app updater watches: it takes the
+newest release that is neither a draft nor a pre-release, so an unpromoted
+build is invisible to it. That is the point, not an oversight.
+
+Desktop and Docker split CPU and GPU differently on purpose. Docker publishes
+one `linux/amd64` image that works on CPU and activates GPU through
+`--runtime=nvidia`. The desktop builds two bundles, and the NVIDIA one installs
+the CUDA torch wheel at first run rather than shipping it, because bundling it
+once put the release past GitHub's 2 GiB asset cap (#318, reverted by #320).

From 12f101d9dfa00d65c26ed40037831a3e28c951db Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 15:32:20 +0100
Subject: [PATCH 10/11] Regression tests for search and preview (#441, #442)

550 lines of new frontend with nothing holding it. The three things these
protect were all found by hand during review and would all come back
silently.

**The request count.** Firing per keystroke instead of per word is not a
visible bug, it is twenty six requests where one would do, and nobody would
notice until a rate limit did.

**The dropdown being visible.** It rendered correctly and was clipped out of
existence by an ancestor's overflow:hidden. My own throwaway check counted
rows in the DOM and passed while the user saw nothing, which is exactly how
that shipped to a screenshot. These assert toBeVisible and check the panel's
box against the composer's.

**Picking not importing.** Extraction is minutes of work, so a click in a
list the user may still be reading must not start one. Asserted by blocking
POST /api/jobs and checking nothing was attempted.

Also covered: a pasted link still bypasses search entirely, the tab switch
that used to close the panel (the panel is a sibling of the composer, so a
mousedown on a tab counted as an outside click), over-limit rows being
unselectable and reading from the setting rather than a hardcoded 20 (#443),
Escape, arrow-key selection with aria-activedescendant, and preview being an
audition rather than a selection.

Both /api/search and /api/search/preview are stubbed. A suite that reaches
YouTube fails on a flagged CI IP for reasons that have nothing to do with the
change under test.

Two of these needed expect.poll rather than a single read. Writing them
against a real browser turned up the same class of race twice: the UI settles
before the network does, so reading a request count the instant a row appears
is testing the wrong moment.
---
 tests/e2e/search.spec.mjs | 296 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 296 insertions(+)
 create mode 100644 tests/e2e/search.spec.mjs

diff --git a/tests/e2e/search.spec.mjs b/tests/e2e/search.spec.mjs
new file mode 100644
index 00000000..7c01c51d
--- /dev/null
+++ b/tests/e2e/search.spec.mjs
@@ -0,0 +1,296 @@
+// Regression tests for topbar search and preview (#441, #442).
+//
+// /api/search and /api/search/preview are stubbed. These cover our behaviour,
+// not YouTube's, and a suite that reaches YouTube fails on a flagged CI IP for
+// reasons that have nothing to do with the change under test.
+//
+// The three things worth protecting here were all found by hand and would all
+// come back silently:
+//
+//   The request count. Firing per keystroke instead of per word is not a
+//   visible bug, it is twenty six requests where one would do.
+//
+//   The dropdown being visible. It rendered correctly and was clipped out of
+//   existence by an ancestor's overflow:hidden. A test that counts rows in the
+//   DOM passes while the user sees nothing, which is exactly what happened.
+//
+//   Picking not importing. Extraction is minutes of work, so a click in a list
+//   the user may still be reading must not start one.
+
+import { expect, test } from "@playwright/test";
+
+import { seedLibrary } from "./helpers.mjs";
+
+const RESULTS = [
+  { title: "Tina Turner - The Best", duration: 250, uploader: "Tina Turner", thumbnail: null, too_long: false, url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
+  { title: "A Very Long Compilation", duration: 4275, uploader: "Someone", thumbnail: null, too_long: true, url: "https://www.youtube.com/watch?v=aQw4w9WgXcA" },
+  { title: "The Best (Live)", duration: 300, uploader: "Tina Turner", thumbnail: null, too_long: false, url: "https://www.youtube.com/watch?v=bQw4w9WgXcB" },
+];
+
+/** Stub search, and record every request so counts can be asserted. */
+async function stubSearch(page, { items = RESULTS, maxDuration = 1200, fail = false } = {}) {
+  const calls = [];
+  await page.route("**/api/search", async (route) => {
+    calls.push(JSON.parse(route.request().postData() || "{}"));
+    if (fail) return route.fulfill({ status: 502, contentType: "application/json", body: '{"detail":"nope"}' });
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({ items, max_duration_sec: maxDuration, cached: false }),
+    });
+  });
+  return calls;
+}
+
+/** A tiny silent wav, so <audio> has something real to load. */
+async function stubPreview(page) {
+  const hits = [];
+  await page.route("**/api/search/preview**", async (route) => {
+    hits.push(route.request().url());
+    const header = Buffer.from(
+      "524946462400000057415645666d7420100000000100010044ac000088580100020010006461746100000000",
+      "hex",
+    );
+    await route.fulfill({ status: 200, contentType: "audio/wav", body: header });
+  });
+  return hits;
+}
+
+async function openApp(page) {
+  await seedLibrary(page);
+  await page.goto("/", { waitUntil: "domcontentloaded" });
+  await page.locator("#url").waitFor({ state: "visible" });
+}
+
+const panel = (page) => page.locator(".search-panel");
+const rows = (page) => page.locator(".search-row");
+
+test.describe("topbar search", () => {
+  test("a typed phrase costs one request, not one per keystroke", async ({ page }) => {
+    const calls = await stubSearch(page);
+    await openApp(page);
+
+    await page.locator("#url").type("simply the best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    // The whole point of word-boundary triggering. Sixteen characters.
+    expect(calls.length).toBeLessThanOrEqual(2);
+    expect(calls.at(-1).query).toBe("simply the best");
+  });
+
+  test("the dropdown is actually visible, not merely rendered", async ({ page }) => {
+    await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+
+    // toBeVisible, not a DOM count: the panel once rendered correctly inside an
+    // ancestor with overflow:hidden and was clipped away entirely.
+    await expect(panel(page)).toBeVisible();
+    await expect(rows(page).first()).toBeVisible();
+
+    const box = await panel(page).boundingBox();
+    const composer = await page.locator(".daw-composer").boundingBox();
+    expect(box.width).toBeGreaterThan(100);
+    expect(Math.abs(box.x - composer.x)).toBeLessThan(2);
+    expect(box.y).toBeGreaterThan(0);
+  });
+
+  test("a pasted link is left to the import flow", async ({ page }) => {
+    const calls = await stubSearch(page);
+    await openApp(page);
+
+    await page.locator("#url").fill("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
+    await page.waitForTimeout(900);
+
+    expect(calls).toHaveLength(0);
+    await expect(panel(page)).toBeHidden();
+  });
+
+  test("a query shorter than the minimum asks nothing", async ({ page }) => {
+    const calls = await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("a", { delay: 25 });
+    await page.waitForTimeout(900);
+    expect(calls).toHaveLength(0);
+  });
+
+  test("switching tab re-asks the same question of a different service", async ({ page }) => {
+    const calls = await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    await page.locator(".search-tab").nth(2).click();
+    // Poll rather than read once: the previous tab's rows stay on screen until
+    // the new request starts, so an immediate read sees the old call.
+    await expect.poll(() => calls.at(-1)?.source, { timeout: 10_000 }).toBe("soundcloud");
+    await expect(rows(page).first()).toBeVisible();
+
+    // The panel is a sibling of the composer, so a mousedown on a tab once
+    // counted as an outside click and closed the dropdown before the tab's own
+    // handler ran.
+    await expect(panel(page)).toBeVisible();
+    await expect(page.locator(".search-tab.active")).toHaveText("SoundCloud songs");
+    // Focus must stay in the box the user is typing into.
+    expect(await page.locator("#url").evaluate((el) => document.activeElement === el)).toBe(true);
+  });
+
+  test("picking a result fills the box and starts nothing", async ({ page }) => {
+    await stubSearch(page);
+    const jobPosts = [];
+    await page.route("**/api/jobs**", async (route) => {
+      if (route.request().method() === "POST") jobPosts.push(route.request().url());
+      await route.fulfill({ status: 503, contentType: "application/json", body: '{"detail":"blocked"}' });
+    });
+    await openApp(page);
+
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+    await page.locator(".search-row:not(.too-long)").first().click();
+
+    await expect(page.locator("#url")).toHaveValue(/youtube\.com\/watch\?v=/);
+    await expect(panel(page)).toBeHidden();
+    // Extraction is minutes of work. It waits for Split stems.
+    expect(jobPosts).toHaveLength(0);
+  });
+
+  test("a result over the limit is refused, and says whose limit", async ({ page }) => {
+    await stubSearch(page, { maxDuration: 1200 });
+    const jobPosts = [];
+    await page.route("**/api/jobs**", async (route) => {
+      if (route.request().method() === "POST") jobPosts.push(1);
+      await route.fulfill({ status: 503, contentType: "application/json", body: "{}" });
+    });
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    const tooLong = page.locator(".search-row.too-long").first();
+    await expect(tooLong).toBeVisible();
+    await expect(tooLong.locator(".search-warn")).toHaveText("Over 20 min");
+    await expect(tooLong.locator(".search-warn")).toHaveAttribute("title", /Settings/);
+
+    await tooLong.click({ force: true });
+    await page.waitForTimeout(400);
+    expect(jobPosts).toHaveLength(0);
+    await expect(page.locator("#url")).not.toHaveValue(/youtube\.com/);
+  });
+
+  test("the limit shown follows the setting, not a hardcoded 20", async ({ page }) => {
+    // #443: three places held the ceiling and the client's copy went stale.
+    await stubSearch(page, { maxDuration: 3600 });
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+    await expect(page.locator(".search-row.too-long .search-warn").first()).toHaveText("Over 60 min");
+  });
+
+  test("a failed search says so and can be retried", async ({ page }) => {
+    await stubSearch(page, { fail: true });
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(page.locator(".search-status")).toBeVisible();
+    await expect(page.locator(".search-status")).toHaveText(/failed/i);
+  });
+
+  test("Escape closes it", async ({ page }) => {
+    await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(panel(page)).toBeVisible();
+    await page.locator("#url").press("Escape");
+    await expect(panel(page)).toBeHidden();
+  });
+
+  test("arrow keys move a selection and name it for assistive tech", async ({ page }) => {
+    await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    await page.locator("#url").press("ArrowDown");
+    await expect(page.locator(".search-row.active")).toHaveCount(1);
+    await expect(page.locator("#url")).toHaveAttribute("aria-activedescendant", /search-row-/);
+  });
+});
+
+test.describe("preview", () => {
+  test("every result offers a labelled preview, not a bare glyph", async ({ page }) => {
+    await stubSearch(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    const btn = page.locator(".search-preview-btn").first();
+    // Visible without hovering: a control you have to discover is one most
+    // people never find.
+    await expect(btn).toBeVisible();
+    await expect(btn).toHaveText("Preview");
+  });
+
+  test("pressing preview opens a player and does not select the track", async ({ page }) => {
+    await stubSearch(page);
+    const hits = await stubPreview(page);
+    const jobPosts = [];
+    await page.route("**/api/jobs**", async (route) => {
+      if (route.request().method() === "POST") jobPosts.push(1);
+      await route.fulfill({ status: 503, contentType: "application/json", body: "{}" });
+    });
+    await openApp(page);
+
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+    await page.locator(".search-row:not(.too-long)").first().locator(".search-preview-btn").click();
+
+    await expect(page.locator(".search-player")).toBeVisible();
+    await expect(page.locator(".search-seek")).toBeVisible();
+    // preload="none" means the fetch starts on play(), not on setting src, so
+    // this has to be waited for rather than read the instant the UI appears.
+    await expect.poll(() => hits.length, { timeout: 10_000 }).toBeGreaterThan(0);
+    // Auditioning is not choosing.
+    expect(jobPosts).toHaveLength(0);
+    await expect(page.locator("#url")).not.toHaveValue(/youtube\.com/);
+  });
+
+  test("only one preview is open at a time", async ({ page }) => {
+    await stubSearch(page);
+    await stubPreview(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    await page.locator(".search-preview-btn").nth(0).click();
+    await expect(page.locator(".search-player")).toHaveCount(1);
+    await page.locator(".search-preview-btn").nth(2).click();
+    await expect(page.locator(".search-player")).toHaveCount(1);
+  });
+
+  test("closing the dropdown stops the audio", async ({ page }) => {
+    await stubSearch(page);
+    await stubPreview(page);
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+    await page.locator(".search-preview-btn").first().click();
+    await expect(page.locator(".search-player")).toBeVisible();
+
+    await page.locator("#url").press("Escape");
+    // Nothing is more jarring than a dropdown that vanishes and keeps playing.
+    await expect(page.locator(".search-player")).toHaveCount(0);
+  });
+
+  test("a playlist result has nothing to audition", async ({ page }) => {
+    await stubSearch(page, {
+      items: [
+        { title: "An Album", duration: null, uploader: "Someone", thumbnail: null, too_long: false, url: "https://www.youtube.com/playlist?list=PLabcdefgh" },
+      ],
+    });
+    await openApp(page);
+    await page.locator("#url").type("best ", { delay: 25 });
+    await expect(rows(page).first()).toBeVisible();
+
+    await page.locator(".search-tab").nth(1).click();
+    await expect(rows(page).first()).toBeVisible();
+    await expect(page.locator(".search-preview-btn")).toHaveCount(0);
+  });
+});

From 3b68d45bd6c57f893950846e255a16be1881ce9f Mon Sep 17 00:00:00 2001
From: Thales <>
Date: Tue, 25 Aug 2026 15:39:33 +0100
Subject: [PATCH 11/11] chore: pin Unraid template to edge

Deliberate change of tracking rather than a version bump. edge is the rolling
image published on every merge to main, so Unraid installs now follow main
instead of the last promoted release.

That means Unraid users see changes before a release is tagged and verified,
which is the trade being made on purpose here. It also decouples the template
from the release cadence: no per-release pin commit, and no window where
Unraid silently lags behind.
---
 templates/stemdeck.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/templates/stemdeck.xml b/templates/stemdeck.xml
index 25637a17..21ca992b 100644
--- a/templates/stemdeck.xml
+++ b/templates/stemdeck.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>StemDeck</Name>
-  <Repository>ghcr.io/stemdeckapp/stemdeck:0.14.2</Repository>
+  <Repository>ghcr.io/stemdeckapp/stemdeck:edge</Repository>
   <Registry>https://github.com/stemdeckapp/stemdeck/pkgs/container/stemdeck</Registry>
   <Network>bridge</Network>
   <Shell>sh</Shell>