diff --git a/.env.example b/.env.example
index 5e4189a..c65eec5 100644
--- a/.env.example
+++ b/.env.example
@@ -12,3 +12,21 @@ CORS_ORIGINS=http://127.0.0.1,http://localhost
 LOG_LEVEL=INFO
 LOG_JSON=false
 DEBUG=false
+
+# --- hum-subsonic-shim (optional sibling service; docs/SONOS_SPEC.md) ---
+# Required to run the shim: the Subsonic password bonob/Amperfy log in with
+SHIM_SUBSONIC_PASSWORD=
+SHIM_SUBSONIC_USER=hum
+# Token for the shim's calls to Hum; falls back to API_BEARER_TOKEN above.
+# Leave commented unless the shim talks to a different Hum instance.
+#SHIM_HUM_BEARER_TOKEN=
+# Optional
+SHIM_HUM_BASE_URL=http://127.0.0.1:8000
+SHIM_HOST=127.0.0.1
+SHIM_PORT=8001
+SHIM_ALLOW_PLAIN_PASSWORD=false
+SHIM_FFMPEG_PATH=ffmpeg
+SHIM_MP3_BITRATE_KBPS=256
+# Sonos-facing browse surfaces (via bonob)
+SHIM_PINNED_PLAYLISTS=          # comma-separated YouTube playlist IDs for the Playlist shelf
+SHIM_PUBLIC_URL=                # LAN-reachable base for radio streams, e.g. http://192.168.1.10:8001
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1495a0b..149d0e3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,10 +33,10 @@ jobs:
         run: uv sync --extra dev --python ${{ matrix.python }}
 
       - name: Lint (ruff)
-        run: uv run ruff check app/
+        run: uv run ruff check app/ shim/
 
       - name: Type-check (mypy --strict)
-        run: uv run mypy app/ --strict
+        run: uv run mypy app/ shim/ --strict
 
       - name: Test (pytest, unit only)
         # Integration tests hit live YouTube and are deselected by default
diff --git a/.gitignore b/.gitignore
index 081be91..a0573ba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -172,3 +172,6 @@ frontend/node_modules/
 frontend/dist/
 frontend/.svelte-kit/
 frontend/coverage/
+
+# Shim runtime state
+.shim-data/
diff --git a/README.md b/README.md
index 0af6a91..ebb55ad 100644
--- a/README.md
+++ b/README.md
@@ -64,16 +64,20 @@ All `/api/*` endpoints require `Authorization: Bearer <API_BEARER_TOKEN>`.
 
 | Method | Path | Purpose |
 |---|---|---|
-| GET | `/api/search?q=...&limit=20` | Search videos |
+| GET | `/api/search?q=...&limit=20&category=music&live=false` | Search videos (optional music/live filters) |
+| GET | `/api/radio?limit=20` | Currently-live music streams (filtered live search) |
 | GET | `/api/video/{id}` | Video metadata + signed proxy URLs |
 | GET | `/api/channel/{id}` | Channel info |
 | GET | `/api/playlist/{id}` | Playlist with items |
+| GET | `/api/hls/{id}.m3u8?itag&exp&sig` | HLS byterange wrapper over fMP4/AAC audio (Safari seeking) |
+| GET | `/api/live/{id}/manifest.m3u8?exp&sig` | Proxied live-stream HLS playlist (rewritten segment URIs) |
 | GET | `/proxy/audio/{id}?itag&exp&sig` | Audio stream (signed, range-aware) |
 | GET | `/proxy/stream/{id}?itag&exp&sig` | Video stream (signed, range-aware) |
 | GET | `/proxy/thumbnail/{id}?itag=0&exp&sig` | Thumbnail (signed) |
+| GET | `/proxy/live-segment/{id}?u&exp&sig` | Live HLS segment proxy (signed, host-allowlisted) |
 | GET | `/health` | Health check |
 
-Proxy URLs are minted by `/api/video/{id}` — call it first, hand the returned URLs to your player.
+Proxy URLs are minted by `/api/video/{id}` — call it first, hand the returned URLs to your player. For AAC (`audio/mp4`) formats it additionally returns an `hls_url`; for live videos it returns a signed `live_stream_url` manifest. A bearer-protected `/api/debug/live/{id}/upstream` endpoint exposes the raw upstream playlists for live-stream debugging.
 
 ## Testing
 
@@ -118,8 +122,10 @@ app/
 ├── adapters/
 │   ├── youtube.py        Only file that imports pytubefix
 │   └── upstream_http.py  Shared httpx.AsyncClient + YouTube host allowlist
-├── api/                  GET routes: search, video, channel, playlist
-└── proxy/                GET routes: audio, video, thumbnail (range pass-through)
+├── api/                  GET routes: search, radio, video, channel, playlist, hls, live
+├── proxy/                GET routes: audio, video, thumbnail, live-segment (range pass-through)
+├── hls/                  sidx box parsing for the fMP4 byterange HLS wrapper
+└── live/                 HLS master/media playlist parsing + segment-URI rewriting
 ```
 
 ## Why pytubefix?
@@ -132,7 +138,7 @@ If pytubefix breaks (it eventually will), the fix lives in `app/adapters/youtube
 
 - Single uvicorn worker is correct at this scale (single user)
 - No rate limiting beyond the bearer token gate
-- In-memory stream URL cache only (5-min TTL); restart loses it
+- In-memory stream URL cache only (capped at 1h, bounded by YouTube's own `expire=`); restart loses it
 - Not for public deployment without further hardening
 - pytubefix is reverse-engineered; YouTube can break it without notice
 
diff --git a/app/config.py b/app/config.py
index 9e050c5..fc6b70d 100644
--- a/app/config.py
+++ b/app/config.py
@@ -2,15 +2,20 @@
 from __future__ import annotations
 
 from functools import lru_cache
+from pathlib import Path
 
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+# Anchor .env to the repo root (this file is <root>/app/config.py), not the
+# current working directory — launching from a subdir must not lose settings.
+_ENV_FILE = str(Path(__file__).resolve().parents[1] / ".env")
+
 
 class Settings(BaseSettings):
     """Single source of truth for runtime configuration."""
 
-    model_config = SettingsConfigDict(env_file=".env", case_sensitive=False, extra="ignore")
+    model_config = SettingsConfigDict(env_file=_ENV_FILE, case_sensitive=False, extra="ignore")
 
     # App
     app_name: str = "Hum"
diff --git a/app/main.py b/app/main.py
index cf8f1ab..b886e20 100644
--- a/app/main.py
+++ b/app/main.py
@@ -119,6 +119,15 @@ async def health() -> dict[str, str]:
 
 
 def main() -> None:
+    import sys
+
+    # The `hum` script takes no subcommands; `hum shim` is a common slip — the
+    # shim has its own entry point. Fail loudly instead of silently starting Hum.
+    if len(sys.argv) > 1:
+        raise SystemExit(
+            f"hum: unknown argument {sys.argv[1]!r} — did you mean 'hum-shim'?"
+        )
+
     import uvicorn
 
     settings = get_settings()
diff --git a/docs/SONOS_SPEC.md b/docs/SONOS_SPEC.md
new file mode 100644
index 0000000..5d78aec
--- /dev/null
+++ b/docs/SONOS_SPEC.md
@@ -0,0 +1,460 @@
+# Hum → Sonos Integration Spec
+
+**Status:** audited against the Hum codebase at `c68470e` (Hum 0.1.0). This
+revision corrects the original draft where the repo had moved past the README
+it was written from, and resolves the open decisions the code already answers.
+
+**Goal:** Make Hum (self-hosted YouTube audio streamer) appear as a first-class
+music source *inside the Sonos app* — browsable, searchable, queueable —
+without writing a Sonos SMAPI server from scratch.
+
+**Strategy:** Implement a **Subsonic-compatible API adapter** in front of Hum,
+then point **bonob** (an existing, mature SMAPI⇄Subsonic bridge) at it. bonob
+handles all Sonos-facing complexity; we only build the Hum→Subsonic translation.
+
+```
+Sonos app  ─SMAPI(SOAP)─►  bonob  ─Subsonic API─►  hum-subsonic-shim  ─►  Hum backend  ─►  YouTube
+   │                         │                          │                     │
+ controller            (unmodified,                (new component         (existing FastAPI,
+ (phone, out          mature project)              we build)              pytubefix, signed URLs)
+  of audio path)
+                                          Sonos speaker pulls audio directly ◄─── shim /stream
+```
+
+The phone is only a controller. The **Sonos speaker fetches audio directly**
+from the shim's `/stream` endpoint — true handoff, phone can sleep/leave.
+
+-----
+
+## 1. Architecture decision record
+
+### Why the shim-over-bonob path (Option A) instead of a native SMAPI server (Option B)
+
+|Factor                                    |Shim + bonob (chosen)                       |From-scratch SMAPI                     |
+|------------------------------------------|--------------------------------------------|---------------------------------------|
+|Sonos SOAP / auth / S2 cloud handling     |Handled by bonob                            |We build & maintain it                 |
+|Browse/search/art/now-playing in Sonos app|Inherited from bonob                        |We build it                            |
+|API surface to implement                  |Subsonic subset (well-documented, REST/JSON)|SMAPI (SOAP, fiddlier)                 |
+|Local test client before Sonos            |**Amperfy** (already in use)                |None — must test against Sonos directly|
+|Reuse of existing stack                   |Aligns with existing Gonic/Subsonic setup   |Parallel new stack                     |
+|Long-term maintenance                     |Track bonob releases                        |Solo-maintain SMAPI quirks             |
+
+The deciding factor: an existing Gonic+Amperfy setup means a Subsonic shim can
+be validated end-to-end with a trusted client (Amperfy) **before Sonos ever
+sees it**. That feedback loop is worth more than the control gained by going
+native.
+
+### Accepted constraints
+
+- Sonos network is already internet-connected; the S2 "expose to internet"
+  requirement is therefore an accepted cost, not a blocker. (See §6.)
+- Hum is pytubefix-based and inherently ToS-fragile. This integration does not
+  change that; it inherits it.
+
+### Audit deltas from the original draft
+
+1. **Hum exposes AAC, not just Opus.** `AudioFormat.codec` is `"aac" | "opus"`;
+   the adapter maps `mp4a → aac` and signs an `hls_url` for `audio/mp4`
+   formats. The transcode strategy is therefore **remux-first** (§4), which
+   downgrades the draft's biggest technical risk.
+2. **Hum has live-stream and radio surfaces** (`/api/radio`, `/api/live/...`,
+   `/proxy/live-segment/...`). Live content is **out of scope** for the shim:
+   it doesn't fit the Subsonic track model and can't be transcoded the same
+   way. `search3` must filter live hits out (§3.4).
+3. **Hum has zero persistence.** No play history, no favourites, in-memory
+   caches only. "Recently played" and `star`/`unstar` are shim-side features
+   or omitted (§3.2–3.3, §9).
+4. **Internal upstream URL cache is 1 h** (capped by YouTube's own `expire=`),
+   not the 5 min the old README claimed. Signed *proxy* URL TTL remains 6 h.
+   Latency budgeting in §4/§5 reflects this.
+5. **`/api/video/{id}` is the expensive call** (full pytubefix extraction,
+   seconds when cold; single-flighted and cached inside Hum). The shim must
+   cache its responses (§5) so `getCoverArt` and repeat `stream` calls don't
+   re-trigger extraction.
+
+-----
+
+## 2. Component inventory
+
+|Component            |Status      |Role                                                      |
+|---------------------|------------|----------------------------------------------------------|
+|Hum backend          |Exists      |YouTube search + signed, range-aware proxy URLs; AAC+Opus formats; live/radio (unused here)|
+|Gonic                |Exists      |Current Subsonic server feeding Amperfy (untouched)       |
+|Amperfy              |Exists      |Subsonic client — used here as the shim's **test harness**|
+|**hum-subsonic-shim**|**To build**|Translates Subsonic API → Hum API; remuxes/transcodes audio|
+|bonob                |To deploy   |SMAPI⇄Subsonic bridge; registers Hum as a Sonos source    |
+|Sonos                |Exists      |Endpoint; speakers pull audio directly from the shim      |
+
+Key point: the shim is a **separate** Subsonic endpoint from Gonic. Do not graft
+YouTube content into the Gonic library. bonob supports multiple registrations;
+Hum becomes its own Sonos source alongside the existing music.
+
+**Shim location & stack (resolved):** Python/FastAPI, living in the Hum repo as
+a sibling service. The shim reuses Hum's idioms — ports-and-adapters layout,
+`StreamingResponse` lifecycle handling modelled on `app/proxy/_common.py`
+(`body_iterator`'s guaranteed-close pattern is exactly what the ffmpeg pipe
+needs), pydantic-settings config, same deploy story.
+
+-----
+
+## 3. The shim: Subsonic API surface to implement
+
+bonob calls a subset of the Subsonic API. Implement only what it touches. All
+Subsonic endpoints live under `/rest/` and accept `u`, `p`/`t`+`s`, `v`, `c`,
+`f=json` query params. Respond in JSON (`subsonic-response` envelope).
+
+### 3.1 Must-have (minimum playable)
+
+|Subsonic endpoint|Maps to Hum                             |Notes                                                            |
+|-----------------|----------------------------------------|-----------------------------------------------------------------|
+|`ping`           |—                                       |Health/auth check. Return OK envelope.                           |
+|`getLicense`     |—                                       |Return `valid=true`.                                             |
+|`stream?id=`     |Hum `/api/video/{id}` → signed proxy URL|**Remux/transcode to a Sonos-safe format** (see §4).             |
+|`getCoverArt?id=`|see §3.5                                |Shim fetches and re-serves bytes; never redirects the client.    |
+|`search3?query=` |Hum `/api/search`                       |Map YouTube results → Subsonic `song`/`album`/`artist` shapes. **Filter live hits** (§3.4).|
+
+### 3.2 Browsing (makes it feel native in the Sonos app)
+
+|Subsonic endpoint                 |Maps to / strategy                                                   |
+|----------------------------------|---------------------------------------------------------------------|
+|`getMusicFolders`                 |Return one synthetic folder, e.g. "Hum".                             |
+|`getIndexes` / `getArtists`       |Synthetic top-level: "Search", "Playlists". ("Recently Played" only if built shim-side — Hum has no history.)|
+|`getPlaylists` / `getPlaylist?id=`|Hum `/api/playlist/{id}` → Subsonic playlist.                        |
+|`getAlbumList2?type=`             |Hum has no history; return empty for `recent`/`frequent` unless the shim records its own.|
+|`getArtist` / `getAlbum`          |Synthesize from playlist/channel (`/api/channel/{id}`) where it makes sense.|
+
+### 3.3 Optional / nice-to-have
+
+|Subsonic endpoint|Purpose                                                           |
+|-----------------|------------------------------------------------------------------|
+|`scrobble`       |bonob reports now-playing/scrobble; accept and no-op or log. Doubles as the data source if the shim grows its own "recently played".|
+|`star` / `unstar`|Favourites from the Sonos app — requires shim-side storage (Hum stores nothing).|
+|`getGenres`      |Skip unless you want genre browsing.                              |
+
+### 3.4 The modelling problem (the real design work)
+
+Subsonic assumes a **library** (artists → albums → tracks). Hum is **search +
+stream**. You are mapping a search engine onto a library shape. Decide the
+synthetic hierarchy up front:
+
+- **Search** as the primary entry (Sonos search box → `search3` → Hum search).
+  Pass `category=music` to Hum's search for better signal where appropriate.
+- **Playlists** map cleanly (Hum already has `/api/playlist/{id}`).
+- A single video → model as a single-track "album" so it slots into Subsonic's
+  album/track expectations.
+- **Live hits must be excluded.** `SearchHit.is_live` is unreliable from
+  pytubefix (often `None` for live streams); use the inverse of the heuristic
+  already proven in `app/api/radio.py:_looks_live` — zero/missing duration
+  means live, so drop the hit. Concretely:
+  ```python
+  results = [h for h in raw if not _looks_live(h)]
+  ```
+  (`radio.py` keeps hits where `_looks_live` is True; `search3` drops them.)
+  A "Radio" browse entry for live streams is a possible later phase, not Phase 1/2.
+
+Stable ID scheme is critical: Subsonic IDs must round-trip to YouTube IDs.
+Prefixing: `vid:<ytid>`, `pl:<ytplaylistid>`, `art:<channelid>` so the shim can
+route any incoming `id` back to the right Hum call. Note Hum validates video
+IDs as exactly 11 chars of `[A-Za-z0-9_-]`; playlist IDs 2–64 chars; channel
+IDs 5–64 chars — the shim should reject malformed IDs before calling Hum.
+
+### 3.5 Cover art strategy
+
+Two sources, both server-side (the Sonos client never sees a YouTube URL):
+
+- **Search hits / playlist items** carry raw `i.ytimg.com` thumbnail URLs in
+  Hum's responses. The shim may fetch these directly and re-serve the bytes —
+  cheap, no extraction triggered.
+- **Video details** (`/api/video/{id}`) return a **signed**
+  `/proxy/thumbnail/{id}` URL. Use this when the shim already has a cached
+  details response; do **not** call `/api/video/{id}` solely for cover art —
+  that triggers a full pytubefix extraction.
+
+Resize/normalize to the `size=` Subsonic param as needed; cache aggressively.
+
+-----
+
+## 4. Audio delivery: remux first, transcode as fallback
+
+**The original draft assumed Opus/WebM only and made mp3 re-encode the plan of
+record. The codebase says otherwise:** Hum surfaces YouTube's AAC (`audio/mp4`,
+itag-140 class) formats with `codec="aac"`, alongside Opus. Sonos plays AAC
+natively. So:
+
+### Mode 1 (default): AAC remux — `ffmpeg -c copy`
+
+```
+Sonos GET /rest/stream?id=vid:<ytid>
+  → shim calls Hum /api/video/<ytid>  (cached; picks audio format with codec=="aac")
+  → shim spawns:  ffmpeg -i <signed_proxy_url> -c:a copy -f mp4 -movflags frag_keyframe+empty_moov -   (pipe)
+  → shim streams stdout to Sonos with Content-Type: audio/mp4
+```
+
+Near-zero CPU, no quality loss, first byte limited only by Hum URL resolution.
+Fragmented MP4 (fMP4) is preferred over ADTS: it preserves the timing atom so
+Sonos can display track length and seek, and is the same container Hum's own
+HLS path produces (`app/api/hls.py`). ADTS is a secondary experiment — try it
+if fMP4 causes buffering issues, but expect no seek bar. Mode 2 is the last
+resort.
+
+**Mode 1 container preference order:**
+1. `-f mp4 -movflags frag_keyframe+empty_moov` → `Content-Type: audio/mp4` (start here)
+2. `-f adts` → `Content-Type: audio/aac` (try if fMP4 causes issues)
+3. Mode 2 (mp3 re-encode) if both AAC containers are rejected
+
+### Mode 2 (fallback): mp3 re-encode
+
+```
+  → shim spawns:  ffmpeg -i <signed_proxy_url> -f mp3 -b:a 256k -   (pipe)
+  → Content-Type: audio/mpeg
+```
+
+Used when no AAC format exists for a video (rare) or if Sonos rejects the
+remuxed AAC in Amperfy/Sonos testing. mp3 CBR 256k, no exotic sample rates.
+
+### Requirements / gotchas (both modes)
+
+- **Range requests:** Sonos issues HTTP range requests for seeking. Live ffmpeg
+  pipes are not seekable. Options:
+  - (a) Ignore ranges, stream straight through (works for play-through; seeking
+    may be degraded). Simplest. Start here.
+  - (b) Pre-transcode to a temp file, then serve with proper range support.
+    Adds latency + disk, gains seeking. Optimize to this later.
+  - (c) *Possible Mode-1-only shortcut, verify before relying on it:* since
+    remux is byte-cheap, a ranged request can be served by restarting the remux
+    and discarding output up to the offset — still (a)-class simplicity with
+    approximate seek support.
+- **Container/timing:** fMP4/ADTS/mp3 over a chunked pipe generally works; some
+  renderers want `Content-Length`. If Sonos balks, fall back to temp-file mode (b).
+- **Process lifecycle:** kill ffmpeg when Sonos disconnects (skip/stop) or you
+  leak processes. Wire to the request lifecycle — follow the
+  `app/proxy/_common.py` `body_iterator` pattern: a generator whose `finally`
+  reaps the process, wrapped in `StreamingResponse`.
+- **Latency:** first-byte latency = Hum `/api/video` call (seconds when the
+  extraction is cold; Hum single-flights and caches upstream URLs for up to
+  1 h) + ffmpeg spin-up (negligible in copy mode). The shim's own details
+  cache (§5) keeps the warm path fast; consider prefetching the *next* queue
+  item's details on `stream` calls.
+
+Test this in isolation before involving Sonos: curl the shim's `/stream` into
+a file, inspect with `ffprobe`, play locally — then Amperfy — then Sonos.
+
+-----
+
+## 5. URL signing, TTLs, and the shim's cache
+
+Three clocks to keep straight:
+
+|Layer                                |TTL          |Where               |
+|-------------------------------------|-------------|--------------------|
+|Hum signed proxy URLs (`exp`/`sig`)  |6 h default (`STREAM_URL_TTL_SECONDS`)|minted by `/api/video/{id}`, per-itag|
+|Hum internal upstream-URL cache      |≤ 1 h, also capped by YouTube's `expire=`|inside `app/adapters/youtube.py`; transparent to the shim|
+|Shim details cache (to build)        |`min(1800, exp − now − 60)` s|shim-side|
+
+- Hum mints signed proxy URLs per-itag with `exp`/`sig` query params. The
+  **shim** consumes those internally and re-exposes its own `/stream` to Sonos
+  — Sonos never sees a Hum signed URL or a raw YouTube CDN URL. (Preserves Hum
+  invariant #3.)
+- The shim's own `/stream` URL is what bonob/Sonos hold; it embeds only the
+  `vid:` ID, so it never expires. The shim mints/refreshes Hum URLs per stream
+  request — the 6 h TTL is never the limiting factor, including for gapless/
+  queued playback.
+- **Cache `/api/video/{id}` responses in the shim** (metadata + signed URLs +
+  signed thumbnail URL). This is what keeps `getCoverArt`, repeated `stream`
+  calls, and queue prefetch from hammering pytubefix extraction. Evict each
+  entry using `ttl = min(1800, exp − now − 60)` — the 60 s safety margin
+  prevents serving an already-expired signed URL to ffmpeg mid-stream.
+- The shim holds Hum's `API_BEARER_TOKEN` server-side; it is never exposed to
+  bonob/Sonos.
+
+-----
+
+## 6. S1 vs S2 deployment (network exposure)
+
+bonob behaves differently by Sonos generation:
+
+- **S1:** works fully **local** — bonob only needs to be reachable by Sonos
+  devices on the LAN (`BNB_URL` = LAN IP). No internet exposure.
+- **S2 (since May 2024):** bonob **must be reachable from the internet** because
+  Sonos's cloud calls into it. `BNB_URL` must be a public DNS name (HTTPS).
+
+Since the Sonos network is already internet-connected, the S2 path is acceptable
+here. Hardening checklist for S2:
+
+- Expose **only bonob** publicly (HTTPS/443). Keep the shim and Hum on the LAN,
+  reachable by bonob but **not** from the internet. (Hum already defaults to
+  binding `127.0.0.1`; the shim must be reachable by the Sonos *speakers* on
+  the LAN for `/stream`, but not by the internet.)
+- Restrict the firewall to Sonos's published IP ranges where possible.
+- Terminate TLS at a reverse proxy (Caddy/nginx/Cloudflare Tunnel — bonob docs
+  confirm cloudflared works).
+- Long random `BNB_SECRET`.
+- Note the trust boundary: bonob is the only internet-facing surface; the
+  YouTube-extracting shim + Hum stay private.
+
+If any Sonos units can run S1, you could keep everything LAN-only — worth
+checking per device, but not required given current setup.
+
+-----
+
+## 7. Development trajectory (build order = feedback order)
+
+Each phase is independently testable. Do not start a phase until the previous
+one is green.
+
+> **Build status (code phases done; hardware phases pending).** Phases 0, 1, 2,
+> and the code-able parts of Phase 5 are implemented, unit-tested (ruff + mypy
+> --strict + pytest green), and on PR #2. What remains is human/hardware: the
+> Amperfy listening/browse test (Phase 1/2 exit), then bonob + Sonos (Phases
+> 3–4). An opt-in live harness (`pytest -m integration`) produces the audio
+> evidence for the Amperfy step.
+
+### Phase 0 — Scaffolding ✅ done
+
+- Stand up the shim as a sibling FastAPI service in the Hum repo (stack
+  decision resolved, §2), with `/rest/ping` returning a valid
+  `subsonic-response` JSON envelope.
+- **Exit test:** `curl` ping returns the correct envelope. ✅
+
+### Phase 1 — Auth + search + stream (minimum playable) ✅ code done
+
+- Implement `ping`, `getLicense`, `search3`, `stream`, `getCoverArt`.
+- Implement Subsonic token auth (`t`+`s` salted-MD5; plaintext `p` fallback
+  for dev) — bonob sends token auth by default (§9).
+- Implement the ID scheme (`vid:`/`pl:`/`art:`) with Hum's ID validation rules.
+- Implement live-hit filtering in `search3` (§3.4).
+- Implement the shim details cache (§5).
+- Implement `stream` as **AAC remux (Mode 1)** with mp3 re-encode (Mode 2)
+  fallback, range-ignoring first.
+- **Exit test:** point **Amperfy** at the shim. Search a track, play it, hear
+  audio. Verify both an AAC-remuxed and a forced-mp3 stream play. This
+  validates the hardest parts with a trusted client. **Do not proceed to Sonos
+  until Amperfy plays cleanly.** ⏳ awaiting human test.
+
+### Phase 2 — Browsing ✅ code done
+
+- Implement `getMusicFolders`, `getArtists`/`getIndexes`, `getPlaylists`,
+  `getPlaylist`, `getAlbumList2` (empty `recent`/`frequent`). ✅
+- Build the synthetic hierarchy (Search / Playlists). ✅ Playlist hits surface
+  as drill-in albums (`getAlbum`/`getPlaylist` on `pl:` ids); artist/album
+  catalog is intentionally empty (discovery via search).
+- **Exit test:** Amperfy shows browsable structure; playlists load and play.
+  ⏳ awaiting human test.
+
+**Sonos/bonob note (verified against bonob source).** bonob is a browse bridge,
+not a library-syncing client: it fetches from the shim on demand and Sonos keeps
+no persistent catalog, so `search3` results are **not** accumulated into a
+library (the DB-pollution seen in Amperfy does not occur on Sonos). bonob's
+top-level containers map to `getArtists`/`getAlbumList2`/`getGenres` (empty
+here — no catalog), `getStarred2` (Favourites ✅), `getPlaylists`, **Internet
+Radio** (`getInternetRadioStations`), and Search. The populated, non-polluting
+Sonos surfaces are therefore:
+- **Playlists** ✅ — `getPlaylists` returns `SHIM_PINNED_PLAYLISTS` + starred
+  `pl:` playlists (Hum can't enumerate; curated only).
+- **Internet Radio** ✅ (listing) — `getInternetRadioStations` maps Hum
+  `/api/radio` live streams to stations; `streamUrl` → the shim's
+  unauthenticated `/radio/{id}` mp3 pipe (needs `SHIM_PUBLIC_URL`).
+  ⚠️ **live-stream → Sonos-radio playback is unverified** (hardware gate).
+- **Favourites** ✅ — `getStarred2`.
+
+### Phase 3 — bonob (LAN, S1-style first if possible)
+
+- Run bonob (Docker, pinned tag) pointed at the shim via `BNB_SUBSONIC_URL`.
+- If any S1-capable device: register locally, validate end to end on LAN.
+- **Exit test:** Hum appears as a source in the Sonos app; search + play works.
+
+### Phase 4 — S2 / internet exposure (if required)
+
+- Put bonob behind HTTPS reverse proxy with public DNS.
+- Lock down firewall; keep shim + Hum private.
+- Re-register service for S2; confirm Sonos cloud reaches bonob.
+- **Exit test:** play from Sonos app on S2 hardware.
+
+### Phase 5 — Polish (code-able parts ✅ done)
+
+- ✅ scrobble (accepts/no-ops; Hum has no history to write).
+- ✅ favourites — `star`/`unstar`/`getStarred2` over a shim-side JSON store
+  (`SHIM_DATA_DIR`), titles rendered from a recently-emitted cache (no
+  extraction).
+- ✅ cover-art sizing — `size` selects an `i.ytimg` variant (no decode/dep).
+- ✅ richer error envelopes — Hum 4xx (unplayable/region/live) → Subsonic 70,
+  5xx/transport (Hum down) → 0, instead of bare 500s.
+- ✅ ffmpeg lifecycle hardening — stderr logged on real failure; disconnect vs
+  failure distinguished via GeneratorExit/cancel, not returncode.
+- ✅ transcode mode (b) seeking — `SHIM_SEEKABLE_REMUX` materializes the remux
+  to a cached `+faststart` file served with Range. **Off by default** (adds
+  first-byte latency); flip on and validate during the Sonos phase.
+- **Queue-ahead prefetch — investigated, not built.** The per-track Subsonic
+  `stream` contract never exposes the next queue item to the shim, so there's
+  nothing to prefetch from; speculative warming would trigger expensive
+  extractions. The details cache (§5) remains the latency mitigation.
+- Possible later phase: "Radio" browse entry backed by `/api/radio` if live
+  HLS → Sonos-safe stream proves workable.
+
+-----
+
+## 8. Risk register
+
+|Risk                                             |Likelihood|Impact|Mitigation                                                              |
+|-------------------------------------------------|----------|------|------------------------------------------------------------------------|
+|Remuxed AAC rejected by Sonos                    |Low-Med   |Med   |Validate with Amperfy first; ADTS variant second; mp3 256k re-encode fallback|
+|Range requests break seeking                     |High      |Med   |Ship range-ignoring first; temp-file mode later                         |
+|ffmpeg process leaks                             |Med       |Med   |Tie process lifecycle to request (`body_iterator` pattern); reap on disconnect|
+|Cold-extraction first-byte latency (seconds)     |Med       |Med   |Shim details cache; queue-ahead prefetch; Hum single-flights extraction |
+|pytubefix breaks (YouTube change)                |Med       |High  |Inherited from Hum; fix isolated to `app/adapters/youtube.py`           |
+|Live hits leak into search results, fail playback|Med       |Med   |`_looks_live`-style filter in `search3`                                 |
+|Subsonic↔library model mismatch confuses Sonos UI|Med       |Low   |Keep hierarchy minimal; lead with Search                                |
+|S2 internet exposure surface                     |Accepted  |Med   |Only bonob public; firewall to Sonos IPs; TLS; private shim/Hum         |
+|bonob version drift                              |Low       |Low   |Pin bonob image to a fixed `vX.Y.Z` tag                                 |
+
+-----
+
+## 9. Decisions
+
+Resolved by the codebase audit:
+
+1. ~~Shim language~~ → **Python/FastAPI** (matches Hum; reuses its streaming
+   and config idioms).
+2. ~~Shim location~~ → **sibling service in the Hum repo**.
+3. ~~Transcode format~~ → **AAC remux first, mp3 256k re-encode fallback** (§4).
+4. ~~History/Recently-played~~ → **Hum has none.** Omit at Phase 1/2; optional
+   shim-side feature later (fed by `scrobble`).
+5. ~~Auth model~~ → **shim implements Subsonic token auth.** bonob sends
+   **salted-MD5 token auth** by default — `t` (MD5 hex of `password + s`) +
+   `s` (random salt). The shim must implement the token-auth hash check
+   (`MD5(password + salt)`). Plain `p` (password in clear/hex) is acceptable
+   as a fallback for Amperfy dev mode only. Treating auth as fully optional
+   means bonob's credential handshake will silently fail.
+
+6. ~~Hierarchy scope~~ → **Search + Playlists.** search3 returns video songs +
+   playlist albums; `getAlbum`/`getPlaylist` expand a playlist's items. The
+   artist/album catalog (`getArtists`/`getAlbumList2`) is intentionally empty —
+   a search-centric source has no static library.
+
+-----
+
+## 10. Reference endpoints (Hum, verified against code)
+
+In scope for the shim:
+
+|Hum endpoint                          |Use in shim                          |
+|--------------------------------------|-------------------------------------|
+|`GET /api/search?q=&limit=&category=` |`search3` (filter live hits)         |
+|`GET /api/video/{id}`                 |signed audio/thumbnail URLs + metadata for `stream`/`getCoverArt`; **expensive — cache**|
+|`GET /api/playlist/{id}`              |`getPlaylist`                        |
+|`GET /api/channel/{id}`               |`getArtist` (optional)               |
+|`GET /proxy/audio/{id}?itag&exp&sig`  |ffmpeg input for `stream` (range-aware)|
+|`GET /proxy/thumbnail/{id}?itag=0&exp&sig`|`getCoverArt` (when details cached) |
+|`GET /health`                         |shim → Hum liveness                  |
+
+Exists in Hum but **out of scope** for the shim (live/radio/HLS surfaces):
+
+|Hum endpoint                              |Why excluded                          |
+|------------------------------------------|--------------------------------------|
+|`GET /api/radio`                          |Live streams don't fit the Subsonic track model; possible Phase 5+|
+|`GET /api/hls/{id}.m3u8`                  |Safari-specific byterange wrapper; Subsonic wants progressive streams|
+|`GET /api/live/{id}/manifest.m3u8`        |Live HLS; out of scope                |
+|`GET /proxy/live-segment/{id}`            |Live HLS; out of scope                |
+
+All Hum `/api/*` calls require `Authorization: Bearer <token>`; the shim holds
+that token server-side and never exposes it to bonob/Sonos.
diff --git a/docs/SONOS_VALIDATION.md b/docs/SONOS_VALIDATION.md
new file mode 100644
index 0000000..3483403
--- /dev/null
+++ b/docs/SONOS_VALIDATION.md
@@ -0,0 +1,198 @@
+# Sonos shim — validation runbook (pick-up guide)
+
+Everything code-able is done and on **PR #2** (branch `smapi`). What remains is
+**human/hardware validation** — things a test suite can't do: listening by ear,
+running bonob, and playing through a real Sonos speaker. Work top to bottom;
+each step says what to expect and what to capture if it fails.
+
+Status legend: ✅ done in code · 🎧 needs you (ear) · 📦 needs bonob · 🔊 needs Sonos hardware
+
+---
+
+## 0. Where things stand
+
+- **Implemented + unit-tested (245 tests, green):** Subsonic `ping`, `getLicense`,
+  `search3`, `stream` (AAC remux → mp3 fallback), `getCoverArt`, browsing
+  (`getMusicFolders`/`getArtists`/`getIndexes`/`getAlbumList2`/`getPlaylists`/
+  `getPlaylist`/`getAlbum`), favourites (`star`/`unstar`/`getStarred2`),
+  `scrobble`, **Internet Radio** (`getInternetRadioStations` + `/radio/{id}`),
+  XML+JSON responses, token + legacy auth.
+- **Already validated this session:** Phase 0 ping; live integration suite
+  (search3 + stream→ffprobe); Amperfy **login works** after the XML fix; search
+  returns results; one track streamed end-to-end.
+- **Not yet validated (this runbook):** Amperfy clean playback by ear; bonob;
+  Sonos browse + playback; Internet Radio playback (the big unknown); seekable
+  remux; S2 internet exposure.
+
+---
+
+## 1. One-time `.env` settings
+
+Edit the repo-root `.env` (the shim and Hum share it):
+
+```bash
+# Required
+SHIM_SUBSONIC_PASSWORD=<your password>        # what bonob/Amperfy log in with (>=8 chars)
+
+# For Amperfy "legacy login" and curl poking (plain password). Turn OFF before any
+# internet exposure (S2) — legacy sends the password in clear.
+SHIM_ALLOW_PLAIN_PASSWORD=true
+
+# For Internet Radio: the LAN address Sonos speakers can reach the shim at.
+# Find your IP:  ipconfig getifaddr en0
+SHIM_PUBLIC_URL=http://<imac-LAN-ip>:8001
+
+# Optional: curated playlists for the Sonos Playlist shelf (comma-separated YT playlist IDs)
+SHIM_PINNED_PLAYLISTS=
+
+# Optional: gives Sonos a seek bar (adds first-byte latency). Validate separately.
+SHIM_SEEKABLE_REMUX=false
+```
+
+`SHIM_HUM_BEARER_TOKEN` is **not** needed on the same box — it falls back to `API_BEARER_TOKEN`.
+
+---
+
+## 2. Start the stack (and the stale-process gotcha)
+
+Always pull and **restart both** so the running processes have current code — a
+stale shim caused several false failures this session.
+
+```bash
+cd /Volumes/Data/Workspace/dev/audio-tools/hum
+git pull
+uv sync --extra dev                 # refresh entry points after pulling
+
+# stop any old shim still holding :8001
+kill $(lsof -ti :8001) 2>/dev/null
+
+hum &                               # Hum on :8000  (MUST be up — the shim proxies it)
+hum-shim &                          # shim on :8001
+```
+
+Gotchas:
+- If you see `address already in use` after "Application startup complete", a
+  stale shim is on :8001 — `kill $(lsof -ti :8001)` and retry. (uvicorn logs the
+  bind error *after* the startup line; misleading but harmless.)
+- `hum shim` (space) is wrong and now errors — the shim is `hum-shim` (hyphen).
+- Run from the repo root. Hum down → the shim returns clean "Hum unreachable"
+  errors, but nothing will play.
+
+---
+
+## 3. Smoke test with curl (30 seconds, no client needed)
+
+```bash
+P=<your password>
+# XML by default (what Amperfy/bonob get) — should be <subsonic-response status="ok">
+curl -s "http://127.0.0.1:8001/rest/ping.view?u=hum&p=$P"
+# JSON when asked
+curl -s "http://127.0.0.1:8001/rest/ping.view?u=hum&p=$P&f=json"
+# Root probe (Amperfy Auto-Detect needs this non-404)
+curl -s "http://127.0.0.1:8001/"
+# Search (slow: 6–60s, real pytubefix)
+curl -s "http://127.0.0.1:8001/rest/search3?u=hum&p=$P&f=json&query=lofi"
+# Radio shelf (needs Hum live search working)
+curl -s "http://127.0.0.1:8001/rest/getInternetRadioStations?u=hum&p=$P&f=json"
+```
+
+Expect `status="ok"` envelopes; search returns `song` entries. If any return
+`status="failed"`, the `error.message` says why (it surfaces Hum's error).
+
+---
+
+## 4. Integration suite (automated end-to-end, with the stack up)
+
+```bash
+pytest -m integration tests/shim/integration
+```
+
+Hits the running shim → Hum → YouTube, and ffprobes a stream as audio. Skips
+cleanly if the shim or Hum is down. Green here = the server side is sound.
+
+---
+
+## 5. 🎧 Amperfy (Phase 1/2 exit) — confirms playback by ear
+
+Amperfy is the trusted test client *before* Sonos. Note: Amperfy caches search
+results into a local library (it's a syncing client) — that's an Amperfy trait,
+**not** how Sonos behaves, so ignore the library "pollution" here.
+
+1. Add server: URL `http://<imac-LAN-ip>:8001` (or `localhost` if same machine),
+   user `hum`, your password.
+2. **API mode: pick `Subsonic` or `Subsonic (legacy login)`** — not Ampache
+   (wrong protocol), Auto-Detect now works too.
+3. Search a track → it appears under **Songs**. Play it.
+
+**Pass:** audio plays cleanly, no stutter/dropout. Try both an AAC track (most)
+and confirm it sounds right. **This is the gate to proceed to Sonos.**
+
+Capture if it fails: the shim's log lines for that play (the `/rest/stream` call)
+and whether audio started at all.
+
+---
+
+## 6. 📦🔊 bonob + Sonos (Phase 3) — the real target
+
+bonob bridges Sonos (SMAPI/SOAP) to the shim (Subsonic). Unlike Amperfy, Sonos
+keeps **no persistent library** — it browses live, so search doesn't accumulate.
+
+1. Run bonob (Docker, **pin a version tag**), pointed at the shim:
+   ```
+   BNB_SUBSONIC_URL=http://<imac-LAN-ip>:8001
+   BNB_SECRET=<long random>
+   BNB_URL=http://<imac-LAN-ip>:4534      # bonob's own LAN URL (S1/local)
+   ```
+2. Register bonob as a music service in the Sonos app (it prints setup steps).
+3. In the Sonos app, open the Hum service and check each shelf:
+
+| Shelf | Expect | Backed by |
+|---|---|---|
+| **Search** | finds + plays tracks | `search3` → `stream` |
+| **Playlists** | your `SHIM_PINNED_PLAYLISTS` + starred playlists | `getPlaylists` |
+| **Favourites** | tracks/playlists you starred | `getStarred2` |
+| **Internet Radio** | live stations from Hum `/api/radio` | `getInternetRadioStations` |
+| Artists/Albums/Genres | **empty** (no catalog — expected) | — |
+
+**Pass:** Hum appears as a Sonos source; Search finds and **plays** a track on a
+speaker. Capture if it fails: bonob's container logs + which shelf is empty/erroring.
+
+---
+
+## 7. 🔊 Internet Radio playback — the known unknown
+
+Listing the stations is done; whether Sonos *plays* one is **unverified**. It
+chains live YouTube → Hum HLS → ffmpeg mp3 → Sonos, and the last hop couldn't be
+tested without hardware.
+
+- Requires `SHIM_PUBLIC_URL` set to a LAN IP (not `127.0.0.1`) so the speaker can
+  fetch `/radio/{id}` directly.
+- Test: open **Internet Radio** in Sonos, pick a station, hit play.
+- If it **doesn't** play: capture the shim log for the `/radio/<id>` request and
+  run this to see if the pipe itself produces audio:
+  ```bash
+  curl -s "http://<imac-LAN-ip>:8001/radio/<a_live_video_id>" --max-time 10 -o /tmp/r.mp3
+  ffprobe /tmp/r.mp3       # should show an mp3 audio stream
+  ```
+  That isolates "shim can't produce the stream" from "Sonos won't accept it."
+
+---
+
+## 8. Optional / later
+
+- **Seekable remux (seek bar):** set `SHIM_SEEKABLE_REMUX=true`, restart, re-test
+  a track in Sonos/Amperfy. Trades first-byte latency for a seek bar. Falls back
+  to the streaming pipe if it fails.
+- **S2 / internet exposure (Phase 4):** only if Sonos units are S2. Put **bonob
+  only** behind HTTPS with a public DNS name; keep shim + Hum LAN-only. Set
+  `SHIM_ALLOW_PLAIN_PASSWORD=false` and use token auth. (Spec §6.)
+
+---
+
+## 9. If you hand it back to Claude
+
+For any failure, paste: (a) which step, (b) the shim log lines for the failing
+request, (c) for bonob issues, the bonob container logs. The shim maps Hum errors
+into the response `message`, so a `status="failed"` envelope usually names the
+cause. Known perf note: search is slow (pytubefix, ~6–60s) and Amperfy fires one
+search per keystroke — that's Hum-side latency, not a shim bug.
diff --git a/pyproject.toml b/pyproject.toml
index d77b26a..c894f53 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -41,9 +41,10 @@ dev = [
 
 [project.scripts]
 hum = "app.main:main"
+hum-shim = "shim.main:main"
 
 [tool.setuptools.packages.find]
-include = ["app*"]
+include = ["app*", "shim*"]
 
 [tool.ruff]
 line-length = 100
diff --git a/shim/__init__.py b/shim/__init__.py
new file mode 100644
index 0000000..4bb353e
--- /dev/null
+++ b/shim/__init__.py
@@ -0,0 +1,6 @@
+"""hum-subsonic-shim — a Subsonic-compatible adapter in front of Hum.
+
+Sibling service to the Hum backend (spec: docs/SONOS_SPEC.md). bonob points
+at this shim via BNB_SUBSONIC_URL; the shim translates the Subsonic subset
+bonob calls into Hum API calls and remuxes/transcodes audio for Sonos.
+"""
diff --git a/shim/auth.py b/shim/auth.py
new file mode 100644
index 0000000..80d258a
--- /dev/null
+++ b/shim/auth.py
@@ -0,0 +1,70 @@
+"""Subsonic credential check: salted-MD5 token auth (spec §9.5).
+
+bonob sends `t` (MD5 hex of password + salt) and `s` (random salt) by
+default. Plaintext `p` — optionally hex-encoded as `enc:<hex>` — is accepted
+only when SHIM_ALLOW_PLAIN_PASSWORD is on (Amperfy dev mode).
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from fastapi import Request
+
+from shim.config import ShimSettings, get_settings
+from shim.subsonic import (
+    MISSING_PARAMETER,
+    WRONG_CREDENTIALS,
+    SubsonicError,
+    set_response_format,
+)
+
+_WRONG = "wrong username or password"
+
+
+def _md5_hex(text: str) -> str:
+    # MD5 is mandated by the Subsonic token-auth scheme, not a security choice.
+    return hashlib.md5(text.encode(), usedforsecurity=False).hexdigest()
+
+
+def check_credentials(
+    settings: ShimSettings,
+    u: str | None,
+    p: str | None,
+    t: str | None,
+    s: str | None,
+) -> None:
+    if not u:
+        raise SubsonicError(MISSING_PARAMETER, "missing required parameter: u")
+    if not hmac.compare_digest(u.encode(), settings.subsonic_user.encode()):
+        raise SubsonicError(WRONG_CREDENTIALS, _WRONG)
+
+    if t is not None and s is not None:
+        expected = _md5_hex(settings.subsonic_password + s)
+        if not hmac.compare_digest(t.lower().encode(), expected.encode()):
+            raise SubsonicError(WRONG_CREDENTIALS, _WRONG)
+        return
+
+    if p is not None and settings.allow_plain_password:
+        password = p
+        if p.startswith("enc:"):
+            try:
+                password = bytes.fromhex(p[4:]).decode()
+            except (ValueError, UnicodeDecodeError) as e:
+                raise SubsonicError(WRONG_CREDENTIALS, _WRONG) from e
+        if not hmac.compare_digest(password.encode(), settings.subsonic_password.encode()):
+            raise SubsonicError(WRONG_CREDENTIALS, _WRONG)
+        return
+
+    raise SubsonicError(
+        MISSING_PARAMETER, "token auth required: pass t=md5(password+salt) and s=salt"
+    )
+
+
+async def require_subsonic_auth(request: Request) -> None:
+    """FastAPI dependency: every /rest endpoint authenticates, ping included.
+    Also records the requested response format (runs before the handler, so
+    ok_response picks JSON vs XML correctly)."""
+    q = request.query_params
+    set_response_format(q.get("f"))
+    check_credentials(get_settings(), q.get("u"), q.get("p"), q.get("t"), q.get("s"))
diff --git a/shim/config.py b/shim/config.py
new file mode 100644
index 0000000..8f62573
--- /dev/null
+++ b/shim/config.py
@@ -0,0 +1,105 @@
+"""Shim settings loaded from environment variables (SHIM_* prefix)."""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import AliasChoices, Field, ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+# Anchor paths to the repo root (this file is <root>/shim/config.py), not the
+# current working directory — launching from a subdir must not lose settings.
+_REPO_ROOT = Path(__file__).resolve().parents[1]
+_ENV_FILE = str(_REPO_ROOT / ".env")
+# Default location for shim-side runtime state (favourites). Gitignored.
+DATA_DIR_DEFAULT = _REPO_ROOT / ".shim-data"
+
+
+class ShimSettings(BaseSettings):
+    """Single source of truth for shim runtime configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="SHIM_",
+        env_file=_ENV_FILE,
+        case_sensitive=False,
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    # Upstream Hum — the bearer token lives here server-side and is never
+    # exposed to bonob/Sonos (spec §5). Falls back to Hum's own
+    # API_BEARER_TOKEN since the services share an .env in this repo.
+    hum_base_url: str = "http://127.0.0.1:8000"
+    hum_bearer_token: str = Field(
+        ...,
+        min_length=16,
+        validation_alias=AliasChoices("shim_hum_bearer_token", "api_bearer_token"),
+    )
+
+    # Subsonic credentials bonob/Amperfy authenticate with. bonob sends
+    # salted-MD5 token auth by default (spec §9.5); plaintext `p` is a
+    # dev-only fallback for Amperfy testing — keep it off in production.
+    subsonic_user: str = "hum"
+    subsonic_password: str = Field(..., min_length=8)
+    allow_plain_password: bool = False
+
+    # Server
+    host: str = "127.0.0.1"
+    port: int = 8001
+    debug: bool = False
+    # Base URL Sonos speakers use to fetch radio streams directly (must be
+    # LAN-reachable, e.g. http://192.168.1.10:8001). Empty → http://host:port,
+    # which only works if host isn't 127.0.0.1.
+    public_url: str = ""
+
+    # Audio delivery (spec §4)
+    ffmpeg_path: str = "ffmpeg"
+    mp3_bitrate_kbps: int = 256
+
+    # Shim-side state (favourites). Empty → DATA_DIR_DEFAULT (<repo>/.shim-data).
+    data_dir: str = ""
+
+    # Curated playlists for the Sonos "Playlist" shelf — comma-separated YouTube
+    # playlist IDs. Combined with starred (pl:) playlists; Hum can't enumerate.
+    pinned_playlists: str = ""
+
+    # Seekable remux (spec §4 mode (b)): materialize the remuxed fMP4 to a
+    # cached temp file and serve it with Range support (gives Sonos a seek bar)
+    # at the cost of first-byte latency. Off by default — the streaming pipe
+    # (mode (a)) stays the default; flip on and validate during the Sonos phase.
+    seekable_remux: bool = False
+    temp_dir: str = ""  # empty → DATA_DIR_DEFAULT/cache
+    temp_cache_mb: int = 512
+
+    # Details cache (spec §5): ttl = min(max_ttl, exp - now - safety)
+    details_cache_max_ttl_seconds: float = 1800.0
+    details_cache_safety_seconds: float = 60.0
+
+    # Upstream HTTP
+    upstream_connect_timeout: float = 10.0
+    upstream_read_timeout: float = 30.0
+
+    log_level: str = "INFO"
+
+    def pinned_playlist_ids(self) -> list[str]:
+        return [p.strip() for p in self.pinned_playlists.split(",") if p.strip()]
+
+    def public_base_url(self) -> str:
+        return (self.public_url or f"http://{self.host}:{self.port}").rstrip("/")
+
+
+@lru_cache
+def get_settings() -> ShimSettings:
+    try:
+        return ShimSettings()  # type: ignore[call-arg]
+    except ValidationError as e:
+        missing = sorted(
+            str(err["loc"][0]).upper() for err in e.errors() if err["type"] == "missing"
+        )
+        if missing:
+            names = ", ".join(n if n.startswith("SHIM_") else f"SHIM_{n}" for n in missing)
+            # A concise exit beats a pydantic traceback that echoes .env values.
+            raise SystemExit(
+                f"hum-subsonic-shim: missing required settings: {names} (see .env.example)"
+            ) from e
+        raise
diff --git a/shim/hum_client.py b/shim/hum_client.py
new file mode 100644
index 0000000..7a252cc
--- /dev/null
+++ b/shim/hum_client.py
@@ -0,0 +1,254 @@
+"""HTTP adapter to the Hum backend — the only place the bearer token lives.
+
+Also owns the details cache (spec §5): /api/video/{id} is the expensive call
+(cold pytubefix extraction takes seconds), so responses are cached with
+ttl = min(max_ttl, exp − now − safety) derived from the signed URLs' `exp`,
+and cover art is sourced without ever triggering an extraction (spec §3.5).
+"""
+from __future__ import annotations
+
+import contextlib
+import time
+from urllib.parse import parse_qs, urljoin, urlparse, urlunparse
+
+import httpx
+
+from shim.config import get_settings
+from shim.models import HumPlaylistInfo, HumSearchHit, HumVideoDetails
+from shim.subsonic import GENERIC, NOT_FOUND, SubsonicError
+
+# YouTube thumbnail hosts and the always-present size variants. We cap at
+# hqdefault (480x360): sddefault/maxresdefault 404 for many uploads, and a 404
+# here would surface as "no cover art". default/mqdefault/hqdefault always exist.
+_YTIMG_HOSTS = {"i.ytimg.com", "img.youtube.com", "i9.ytimg.com"}
+_YTIMG_EXTS = (".jpg", ".jpeg", ".webp")
+
+
+def _exp_param(url: str) -> float | None:
+    values = parse_qs(urlparse(url).query).get("exp")
+    if not values:
+        return None
+    try:
+        return float(values[0])
+    except ValueError:
+        return None
+
+
+def _ytimg_variant(url: str, size: int | None) -> str:
+    """Rewrite a YouTube thumbnail URL to the variant nearest `size` (spec §3.5
+    cover-art sizing without decoding/resizing). Non-ytimg URLs pass through."""
+    if size is None:
+        return url
+    parsed = urlparse(url)
+    if parsed.hostname not in _YTIMG_HOSTS:
+        return url
+    base, sep, name = parsed.path.rpartition("/")
+    if not sep or "." not in name or not name.lower().endswith(_YTIMG_EXTS):
+        return url
+    ext = name[name.rfind(".") :]
+    variant = "default" if size <= 120 else "mqdefault" if size <= 320 else "hqdefault"
+    return urlunparse(parsed._replace(path=f"{base}/{variant}{ext}"))
+
+
+def _raise_for_hum_error(r: httpx.Response) -> None:
+    if r.status_code == 200:
+        return
+    code = ""
+    message = ""
+    with contextlib.suppress(ValueError, KeyError, TypeError):
+        body = r.json()
+        code = str(body.get("error", ""))
+        message = str(body.get("message", ""))
+    detail = message or f"HTTP {r.status_code}"
+    if code:
+        detail = f"{detail} ({code})"
+    # Client-side conditions (not found / unplayable / region-locked / live)
+    # → Subsonic 70; transient/upstream → generic 0.
+    if r.status_code in (403, 404, 410, 415, 422, 451):
+        raise SubsonicError(NOT_FOUND, detail)
+    raise SubsonicError(GENERIC, f"Hum upstream error {r.status_code}: {detail}")
+
+
+class HumClient:
+    def __init__(
+        self,
+        base_url: str,
+        bearer_token: str,
+        *,
+        connect_timeout: float,
+        read_timeout: float,
+        cache_max_ttl: float,
+        cache_safety: float,
+    ) -> None:
+        timeout = httpx.Timeout(connect_timeout, read=read_timeout)
+        self._base_url = base_url.rstrip("/")
+        self._hum = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {bearer_token}"},
+            timeout=timeout,
+        )
+        # External fetches (raw i.ytimg thumbnails) must not carry the Hum token.
+        self._ext = httpx.AsyncClient(timeout=timeout)
+        self._cache_max_ttl = cache_max_ttl
+        self._cache_safety = cache_safety
+        self._details: dict[str, tuple[HumVideoDetails, float]] = {}
+        # Keyed by full Subsonic id ("vid:<id>" / "pl:<id>") so cover art for
+        # both videos and playlists is served without triggering extraction.
+        self._art_urls: dict[str, str] = {}
+
+    async def close(self) -> None:
+        await self._hum.aclose()
+        await self._ext.aclose()
+
+    def absolute(self, signed_path: str) -> str:
+        """Resolve a Hum-relative signed URL against the Hum base."""
+        return urljoin(self._base_url + "/", signed_path.lstrip("/"))
+
+    async def _get(
+        self, client: httpx.AsyncClient, url: str, *, params: dict[str, str | int] | None = None
+    ) -> httpx.Response:
+        """GET that turns a transport failure (Hum down/unreachable) into a
+        Subsonic error envelope instead of letting httpx.RequestError escape as
+        a 500 — caught by the integration harness with Hum stopped."""
+        try:
+            return await client.get(url, params=params)
+        except httpx.RequestError as e:
+            raise SubsonicError(GENERIC, f"Hum unreachable: {e.__class__.__name__}") from e
+
+    # ----- search -------------------------------------------------------
+
+    async def search(self, q: str, limit: int) -> list[HumSearchHit]:
+        r = await self._get(self._hum, "/api/search", params={"q": q, "limit": limit})
+        _raise_for_hum_error(r)
+        hits = [HumSearchHit.model_validate(item) for item in r.json()["items"]]
+        # Remember raw thumbnail URLs so getCoverArt never needs an extraction.
+        for hit in hits:
+            if not hit.thumbnail_url:
+                continue
+            if hit.kind == "video":
+                self._art_urls[f"vid:{hit.id}"] = hit.thumbnail_url
+            elif hit.kind == "playlist":
+                self._art_urls[f"pl:{hit.id}"] = hit.thumbnail_url
+        return hits
+
+    # ----- radio (live music streams) -------------------------------------
+
+    async def radio(self, limit: int) -> list[HumSearchHit]:
+        r = await self._get(self._hum, "/api/radio", params={"limit": limit})
+        _raise_for_hum_error(r)
+        return [HumSearchHit.model_validate(item) for item in r.json()["items"]]
+
+    async def live_manifest_url(self, video_id: str) -> str:
+        """Absolute, signed HLS manifest URL for a live video — ffmpeg input
+        for the radio stream. Raises NOT_FOUND if the video isn't live."""
+        r = await self._get(self._hum, f"/api/video/{video_id}")
+        _raise_for_hum_error(r)
+        details = HumVideoDetails.model_validate(r.json())
+        if not details.is_live or not details.live_stream_url:
+            raise SubsonicError(NOT_FOUND, f"{video_id} is not a live stream")
+        return self.absolute(details.live_stream_url)
+
+    # ----- playlist -------------------------------------------------------
+
+    async def playlist(self, playlist_id: str) -> HumPlaylistInfo:
+        r = await self._get(self._hum, f"/api/playlist/{playlist_id}")
+        _raise_for_hum_error(r)
+        info = HumPlaylistInfo.model_validate(r.json())
+        # Remember item thumbnails so per-track getCoverArt stays extraction-free.
+        for item in info.items:
+            if item.thumbnail_url:
+                self._art_urls.setdefault(f"vid:{item.video_id}", item.thumbnail_url)
+        return info
+
+    # ----- video details (cached) ----------------------------------------
+
+    async def video_details(self, video_id: str) -> HumVideoDetails:
+        now = time.time()
+        cached = self._details.get(video_id)
+        if cached and cached[1] > now:
+            return cached[0]
+        r = await self._get(self._hum, f"/api/video/{video_id}")
+        _raise_for_hum_error(r)
+        details = HumVideoDetails.model_validate(r.json())
+        ttl = self._cache_ttl(details, now=now)
+        if ttl > 0:
+            self._details[video_id] = (details, now + ttl)
+        return details
+
+    def _cache_ttl(self, details: HumVideoDetails, *, now: float) -> float:
+        """Eviction rule from spec §5: min(max_ttl, exp − now − safety)."""
+        exps = [e for f in details.audio_formats if (e := _exp_param(f.url)) is not None]
+        if not exps:
+            return 0.0
+        return min(self._cache_max_ttl, min(exps) - now - self._cache_safety)
+
+    # ----- cover art ------------------------------------------------------
+
+    async def fetch_art(
+        self, kind: str, value: str, size: int | None = None
+    ) -> tuple[bytes, str]:
+        """Fetch cover art bytes server-side (spec §3.5) — never an extraction.
+
+        Video: cached signed Hum thumbnail → remembered search-hit thumbnail →
+        the predictable i.ytimg URL. Playlist: remembered playlist thumbnail →
+        the playlist's first item thumbnail (cheap /api/playlist call). `size`
+        selects a ytimg variant where applicable; signed Hum thumbnails are
+        served as-is (resizing them would mean decoding).
+        """
+        if kind == "video":
+            url, client = self._video_art_source(value)
+        elif kind == "playlist":
+            url, client = await self._playlist_art_source(value)
+        else:
+            raise SubsonicError(NOT_FOUND, f"no cover art for {kind} ids")
+        r = await self._get(client, _ytimg_variant(url, size))
+        if r.status_code != 200:
+            raise SubsonicError(NOT_FOUND, f"cover art unavailable for {kind}:{value}")
+        return r.content, r.headers.get("content-type", "image/jpeg")
+
+    def _video_art_source(self, video_id: str) -> tuple[str, httpx.AsyncClient]:
+        now = time.time()
+        cached = self._details.get(video_id)
+        if cached and cached[1] > now and cached[0].thumbnail_url:
+            return self.absolute(cached[0].thumbnail_url), self._hum
+        remembered = self._art_urls.get(f"vid:{video_id}")
+        if remembered:
+            return remembered, self._ext
+        return f"https://i.ytimg.com/vi/{video_id}/hqdefault.jpg", self._ext
+
+    async def _playlist_art_source(self, playlist_id: str) -> tuple[str, httpx.AsyncClient]:
+        remembered = self._art_urls.get(f"pl:{playlist_id}")
+        if remembered:
+            return remembered, self._ext
+        info = await self.playlist(playlist_id)
+        for item in info.items:
+            if item.thumbnail_url:
+                return item.thumbnail_url, self._ext
+        raise SubsonicError(NOT_FOUND, f"no cover art for playlist {playlist_id}")
+
+
+# ----- module-level singleton (mirrors app/adapters/upstream_http.py) -------
+
+_client: HumClient | None = None
+
+
+def get_client() -> HumClient:
+    global _client
+    if _client is None:
+        s = get_settings()
+        _client = HumClient(
+            s.hum_base_url,
+            s.hum_bearer_token,
+            connect_timeout=s.upstream_connect_timeout,
+            read_timeout=s.upstream_read_timeout,
+            cache_max_ttl=s.details_cache_max_ttl_seconds,
+            cache_safety=s.details_cache_safety_seconds,
+        )
+    return _client
+
+
+async def close_client() -> None:
+    global _client
+    if _client is not None:
+        await _client.close()
+        _client = None
diff --git a/shim/ids.py b/shim/ids.py
new file mode 100644
index 0000000..d264188
--- /dev/null
+++ b/shim/ids.py
@@ -0,0 +1,55 @@
+"""Stable Subsonic↔YouTube ID scheme: vid:<video>, pl:<playlist>, art:<channel>.
+
+Every ID handed to a Subsonic client must round-trip back to the right Hum
+call (spec §3.4). Patterns mirror Hum's own validators (app/models.py,
+app/api/playlist.py, app/api/channel.py) so malformed IDs are rejected here
+instead of surfacing as Hum 422s.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal
+
+from shim.subsonic import NOT_FOUND, SubsonicError
+
+Kind = Literal["video", "playlist", "artist"]
+
+_PATTERNS: dict[str, tuple[Kind, re.Pattern[str]]] = {
+    "vid": ("video", re.compile(r"^[A-Za-z0-9_-]{11}$")),
+    "pl": ("playlist", re.compile(r"^[A-Za-z0-9_-]{2,64}$")),
+    "art": ("artist", re.compile(r"^[A-Za-z0-9_-]{5,64}$")),
+}
+
+_PREFIXES: dict[Kind, str] = {"video": "vid", "playlist": "pl", "artist": "art"}
+
+
+@dataclass(frozen=True)
+class SubsonicId:
+    kind: Kind
+    value: str
+
+    def __str__(self) -> str:
+        return f"{_PREFIXES[self.kind]}:{self.value}"
+
+
+def video_id(ytid: str) -> str:
+    return f"vid:{ytid}"
+
+
+def playlist_id(yt_playlist_id: str) -> str:
+    return f"pl:{yt_playlist_id}"
+
+
+def artist_id(channel_id: str) -> str:
+    return f"art:{channel_id}"
+
+
+def parse_id(raw: str) -> SubsonicId:
+    prefix, sep, value = raw.partition(":")
+    if not sep or prefix not in _PATTERNS:
+        raise SubsonicError(NOT_FOUND, f"unrecognized id: {raw!r}")
+    kind, pattern = _PATTERNS[prefix]
+    if not pattern.match(value):
+        raise SubsonicError(NOT_FOUND, f"malformed {kind} id: {raw!r}")
+    return SubsonicId(kind=kind, value=value)
diff --git a/shim/main.py b/shim/main.py
new file mode 100644
index 0000000..8083818
--- /dev/null
+++ b/shim/main.py
@@ -0,0 +1,88 @@
+"""hum-subsonic-shim FastAPI entry point (spec: docs/SONOS_SPEC.md)."""
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, Request, Response
+from fastapi.exceptions import RequestValidationError
+
+from shim import hum_client
+from shim.config import get_settings
+from shim.radio import router as radio_router
+from shim.rest import router
+from shim.subsonic import MISSING_PARAMETER, SubsonicError, error_response
+
+
+def _request_format(request: Request) -> str:
+    # Read the format off the request directly: an exception may fire before
+    # the auth dependency set the ContextVar (e.g. param-validation errors).
+    return "json" if request.query_params.get("f") == "json" else "xml"
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    settings = get_settings()
+    logging.basicConfig(level=getattr(logging, settings.log_level.upper(), logging.INFO))
+    logging.getLogger("shim").info("starting up")
+    yield
+    await hum_client.close_client()
+    logging.getLogger("shim").info("shut down")
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    app = FastAPI(
+        title="hum-subsonic-shim",
+        docs_url="/docs" if settings.debug else None,
+        redoc_url=None,
+        lifespan=lifespan,
+    )
+
+    @app.exception_handler(SubsonicError)
+    async def _handle_subsonic(request: Request, exc: SubsonicError) -> Response:
+        return error_response(exc.code, exc.message, fmt=_request_format(request))
+
+    @app.exception_handler(RequestValidationError)
+    async def _handle_validation(request: Request, exc: RequestValidationError) -> Response:
+        # Subsonic clients expect protocol error 10, not an HTTP 422.
+        return error_response(
+            MISSING_PARAMETER, "missing or invalid request parameter",
+            fmt=_request_format(request),
+        )
+
+    app.include_router(router)
+    app.include_router(radio_router)
+
+    @app.get("/")
+    async def root() -> dict[str, str]:
+        # Subsonic clients (e.g. Amperfy's Auto-Detect) probe the base URL to
+        # confirm a server is there before hitting /rest/. A 404 here aborts
+        # that probe, so answer with a small liveness payload.
+        return {"service": "hum-subsonic-shim", "api": "/rest"}
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "healthy"}
+
+    return app
+
+
+app = create_app()
+
+
+def main() -> None:
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "shim.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/shim/mediacache.py b/shim/mediacache.py
new file mode 100644
index 0000000..996593f
--- /dev/null
+++ b/shim/mediacache.py
@@ -0,0 +1,106 @@
+"""On-disk cache of materialized media files for seekable (range) serving.
+
+Used by the remux path so Sonos gets Content-Length + Range — a seek bar
+(spec §4 mode (b)). Bounded by total size; least-recently-modified files are
+evicted first. Off by default (SHIM_SEEKABLE_REMUX); the streaming pipe
+(mode (a)) stays the latency-optimized default.
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import re
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from shim.config import DATA_DIR_DEFAULT, get_settings
+
+_SAFE = re.compile(r"[^A-Za-z0-9_.-]")
+
+# Producer writes the materialized bytes to the given (temporary) path and
+# returns True on success; False (or a missing file) means "could not produce".
+Producer = Callable[[Path], Awaitable[bool]]
+
+
+class MediaCache:
+    def __init__(self, directory: Path, max_bytes: int) -> None:
+        self._dir = directory
+        self._max_bytes = max_bytes
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    def path_for(self, key: str, suffix: str = ".m4a") -> Path:
+        return self._dir / (_SAFE.sub("_", key) + suffix)
+
+    def has(self, key: str, suffix: str = ".m4a") -> bool:
+        return self.path_for(key, suffix).exists()
+
+    async def get_or_produce(
+        self, key: str, producer: Producer, suffix: str = ".m4a"
+    ) -> Path | None:
+        """Return the cached file for `key`, producing it if absent. Returns
+        None if production fails (caller falls back to streaming). Single-
+        flighted per key so concurrent requests don't transcode twice."""
+        path = self.path_for(key, suffix)
+        if path.exists():
+            _touch(path)
+            return path
+        lock = self._locks.setdefault(key, asyncio.Lock())
+        async with lock:
+            if path.exists():  # produced while we waited on the lock
+                _touch(path)
+                return path
+            self._dir.mkdir(parents=True, exist_ok=True)
+            part = path.parent / (path.name + ".part")
+            try:
+                ok = await producer(part)
+            except BaseException:
+                _unlink(part)
+                raise
+            if not ok or not part.exists():
+                _unlink(part)
+                return None
+            os.replace(part, path)  # atomic publish
+            self._evict()
+            return path
+
+    def _evict(self) -> None:
+        files = [p for p in self._dir.iterdir() if p.is_file() and p.suffix != ".part"]
+        files.sort(key=lambda p: p.stat().st_mtime)
+        total = sum(p.stat().st_size for p in files)
+        for p in files:
+            if total <= self._max_bytes:
+                break
+            size = p.stat().st_size
+            _unlink(p)
+            total -= size
+
+
+def _touch(path: Path) -> None:
+    with contextlib.suppress(OSError):
+        os.utime(path, None)
+
+
+def _unlink(path: Path) -> None:
+    with contextlib.suppress(FileNotFoundError):
+        path.unlink()
+
+
+# ----- singleton (mirrors hum_client.get_client / store.get_store) ----------
+
+_cache: MediaCache | None = None
+
+
+def get_cache() -> MediaCache:
+    global _cache
+    if _cache is None:
+        s = get_settings()
+        directory = Path(s.temp_dir) if s.temp_dir else DATA_DIR_DEFAULT / "cache"
+        _cache = MediaCache(directory, s.temp_cache_mb * 1024 * 1024)
+    return _cache
+
+
+def reset_cache() -> None:
+    """Test seam: drop the singleton."""
+    global _cache
+    _cache = None
diff --git a/shim/models.py b/shim/models.py
new file mode 100644
index 0000000..cdbe8a3
--- /dev/null
+++ b/shim/models.py
@@ -0,0 +1,63 @@
+"""Pydantic mirrors of the subset of Hum responses the shim consumes."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class HumSearchHit(BaseModel):
+    kind: str
+    id: str
+    title: str
+    author: str | None = None
+    thumbnail_url: str = ""
+    duration_seconds: int | None = None
+    video_count: int | None = None  # playlist hits only
+    is_live: bool | None = None
+
+
+class HumPlaylistItem(BaseModel):
+    video_id: str
+    title: str
+    author: str | None = None
+    duration_seconds: int | None = None
+    thumbnail_url: str = ""
+
+
+class HumPlaylistInfo(BaseModel):
+    playlist_id: str
+    title: str
+    author: str | None = None
+    video_count: int = 0
+    items: list[HumPlaylistItem] = Field(default_factory=list)
+
+
+class HumAudioFormat(BaseModel):
+    itag: int
+    mime_type: str
+    bitrate: int
+    codec: str
+    url: str  # Hum-relative signed proxy URL
+
+
+class HumVideoDetails(BaseModel):
+    video_id: str
+    title: str
+    author: str
+    duration_seconds: int
+    thumbnail_url: str = ""
+    audio_formats: list[HumAudioFormat] = Field(default_factory=list)
+    is_live: bool = False
+    live_stream_url: str | None = None  # signed HLS manifest path (live only)
+
+
+def looks_live(hit: HumSearchHit) -> bool:
+    """Duration heuristic from app/api/radio.py:_looks_live. Polarity note
+    from spec §3.4: search3 *drops* hits where this returns True —
+    `[h for h in hits if not looks_live(h)]` — whereas /api/radio keeps them.
+    """
+    if hit.is_live is True:
+        return True
+    if hit.is_live is False:
+        return False
+    # is_live is None — ambiguous; zero/missing duration means live.
+    return not hit.duration_seconds
diff --git a/shim/radio.py b/shim/radio.py
new file mode 100644
index 0000000..01eba0b
--- /dev/null
+++ b/shim/radio.py
@@ -0,0 +1,32 @@
+"""Unauthenticated /radio/{id} continuous-stream endpoint for Sonos radio.
+
+Sonos fetches an internet-radio station's streamUrl directly, without Subsonic
+credentials, so this router sits outside /rest and carries no auth dependency
+(LAN-only exposure assumed; see SHIM_PUBLIC_URL). It resolves the live HLS
+manifest via Hum and transcodes it to a continuous mp3 stream with ffmpeg.
+
+NOTE: live-stream → Sonos-radio playback is unverified (spec §4/§7 hardware
+gate). The station list and this pipe are in place; whether Sonos accepts the
+output must be confirmed on real hardware.
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Path
+from fastapi.responses import StreamingResponse
+
+from shim import hum_client, transcode
+from shim.config import get_settings
+
+router = APIRouter(tags=["radio"])
+
+
+@router.get("/radio/{video_id}")
+async def radio_stream(
+    video_id: str = Path(..., min_length=11, max_length=11, pattern=r"^[A-Za-z0-9_-]{11}$"),
+) -> StreamingResponse:
+    manifest_url = await hum_client.get_client().live_manifest_url(video_id)
+    settings = get_settings()
+    args = transcode.live_radio_args(
+        manifest_url, ffmpeg_path=settings.ffmpeg_path, bitrate_kbps=settings.mp3_bitrate_kbps
+    )
+    return StreamingResponse(transcode.stream_ffmpeg(args), media_type="audio/mpeg")
diff --git a/shim/rest.py b/shim/rest.py
new file mode 100644
index 0000000..bc7531b
--- /dev/null
+++ b/shim/rest.py
@@ -0,0 +1,385 @@
+"""The /rest Subsonic surface — Phase 1 endpoints (spec §3.1, §7).
+
+Every endpoint answers both /name and /name.view (Subsonic clients vary).
+All endpoints authenticate, ping included; errors surface as failed
+envelopes via the SubsonicError handler in shim.main.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Depends, Query, Response
+from fastapi.responses import FileResponse, StreamingResponse
+
+from shim import hum_client, ids, mediacache, store, transcode
+from shim.auth import require_subsonic_auth
+from shim.config import get_settings
+from shim.models import HumPlaylistItem, HumSearchHit, looks_live
+from shim.store import StarredItem
+from shim.subsonic import NOT_FOUND, SubsonicError, ok_response
+
+router = APIRouter(prefix="/rest", dependencies=[Depends(require_subsonic_auth)])
+
+
+def _remember(entry: dict[str, Any], kind: str) -> dict[str, Any]:
+    """Record an emitted song/album so a later star can render its name
+    without re-fetching from Hum. Returns the entry for inline use."""
+    name = entry.get("title") or entry.get("name") or entry["id"]
+    store.remember(entry["id"], kind, str(name), str(entry.get("artist", "Unknown")))
+    return entry
+
+
+def _song_from_hit(hit: HumSearchHit) -> dict[str, Any]:
+    sid = ids.video_id(hit.id)
+    # Single video → single-track "album" (spec §3.4) so it slots into
+    # Subsonic's album/track expectations.
+    return {
+        "id": sid,
+        "isDir": False,
+        "type": "music",
+        "title": hit.title,
+        "album": hit.title,
+        "artist": hit.author or "Unknown",
+        "coverArt": sid,
+        "duration": hit.duration_seconds or 0,
+        "contentType": "audio/mp4",
+        "suffix": "m4a",
+    }
+
+
+def _song_from_playlist_item(item: HumPlaylistItem) -> dict[str, Any]:
+    sid = ids.video_id(item.video_id)
+    return {
+        "id": sid,
+        "isDir": False,
+        "type": "music",
+        "title": item.title,
+        "artist": item.author or "Unknown",
+        "coverArt": sid,
+        "duration": item.duration_seconds or 0,
+        "contentType": "audio/mp4",
+        "suffix": "m4a",
+    }
+
+
+def _album_from_hit(hit: HumSearchHit) -> dict[str, Any]:
+    # A YouTube playlist → a Subsonic album the user can drill into via
+    # getAlbum/getPlaylist (spec §3.4: playlists map cleanly).
+    sid = ids.playlist_id(hit.id)
+    return {
+        "id": sid,
+        "name": hit.title,
+        "title": hit.title,
+        "artist": hit.author or "Unknown",
+        "coverArt": sid,
+        "songCount": hit.video_count or 0,
+    }
+
+
+@router.get("/ping")
+@router.get("/ping.view")
+async def ping() -> Response:
+    return ok_response()
+
+
+@router.get("/getLicense")
+@router.get("/getLicense.view")
+async def get_license() -> Response:
+    return ok_response({"license": {"valid": True}})
+
+
+@router.get("/search3")
+@router.get("/search3.view")
+async def search3(
+    query: str = Query(..., min_length=1, max_length=200),
+    song_count: int = Query(20, alias="songCount", ge=1, le=50),
+) -> Response:
+    hits = await hum_client.get_client().search(query, limit=song_count)
+    songs = [
+        _remember(_song_from_hit(h), "song")
+        for h in hits
+        # Spec §3.4 polarity: radio.py keeps live hits, search3 drops them.
+        if h.kind == "video" and not looks_live(h)
+    ][:song_count]
+    # Playlist hits become drill-in albums; channels (artists) are out of scope
+    # for the Search + Playlists hierarchy.
+    albums = [
+        _remember(_album_from_hit(h), "album") for h in hits if h.kind == "playlist"
+    ][:song_count]
+    return ok_response({"searchResult3": {"artist": [], "album": albums, "song": songs}})
+
+
+# ----- browsing (spec §3.2; Search + Playlists hierarchy) -------------------
+
+
+@router.get("/getMusicFolders")
+@router.get("/getMusicFolders.view")
+async def get_music_folders() -> Response:
+    return ok_response({"musicFolders": {"musicFolder": [{"id": 0, "name": "Hum"}]}})
+
+
+@router.get("/getArtists")
+@router.get("/getArtists.view")
+async def get_artists() -> Response:
+    # A search-centric source has no static artist catalog; discovery is the
+    # search box plus playlist drill-in. A valid empty index, not a stub.
+    return ok_response({"artists": {"ignoredArticles": "", "index": []}})
+
+
+@router.get("/getIndexes")
+@router.get("/getIndexes.view")
+async def get_indexes() -> Response:
+    return ok_response(
+        {"indexes": {"ignoredArticles": "", "lastModified": 0, "index": []}}
+    )
+
+
+@router.get("/getAlbumList2")
+@router.get("/getAlbumList2.view")
+async def get_album_list2(
+    list_type: str = Query("newest", alias="type"),
+    size: int = Query(10, ge=1, le=500),
+    offset: int = Query(0, ge=0),
+) -> Response:
+    # Hum has no catalog or play history (spec §3.2/§9.4), so recent/frequent/
+    # newest/random are all empty; discovery happens through search.
+    return ok_response({"albumList2": {"album": []}})
+
+
+def _pinned_playlist_ids() -> list[str]:
+    """Playlist ids for the Sonos shelf: SHIM_PINNED_PLAYLISTS config first,
+    then starred playlists (pl: ids), de-duplicated, order preserved."""
+    ids_list = list(get_settings().pinned_playlist_ids())
+    seen = set(ids_list)
+    for it in store.get_store().starred():
+        if it.kind == "album" and it.id.startswith("pl:"):
+            value = it.id[len("pl:") :]
+            if value not in seen:
+                seen.add(value)
+                ids_list.append(value)
+    return ids_list
+
+
+async def _playlist_summary(yt_playlist_id: str) -> dict[str, Any]:
+    info = await hum_client.get_client().playlist(yt_playlist_id)
+    return {
+        "id": ids.playlist_id(yt_playlist_id),
+        "name": info.title,
+        "owner": info.author or "Unknown",
+        "songCount": info.video_count,
+    }
+
+
+@router.get("/getPlaylists")
+@router.get("/getPlaylists.view")
+async def get_playlists() -> Response:
+    # Hum can't enumerate playlists, so the shelf is the curated/starred set
+    # (spec §3.2). Resolve summaries concurrently; drop any that fail (e.g. a
+    # deleted playlist) rather than failing the whole shelf.
+    pins = _pinned_playlist_ids()
+    results = await asyncio.gather(
+        *(_playlist_summary(pid) for pid in pins), return_exceptions=True
+    )
+    playlists = [r for r in results if isinstance(r, dict)]
+    return ok_response({"playlists": {"playlist": playlists}})
+
+
+@router.get("/getPlaylist")
+@router.get("/getPlaylist.view")
+async def get_playlist(item_id: str = Query(..., alias="id")) -> Response:
+    sid = ids.parse_id(item_id)
+    if sid.kind != "playlist":
+        raise SubsonicError(NOT_FOUND, "getPlaylist expects a pl: id")
+    info = await hum_client.get_client().playlist(sid.value)
+    entries = [_remember(_song_from_playlist_item(i), "song") for i in info.items]
+    return ok_response(
+        {
+            "playlist": {
+                "id": ids.playlist_id(sid.value),
+                "name": info.title,
+                "owner": info.author or "Unknown",
+                "songCount": info.video_count,
+                "entry": entries,
+            }
+        }
+    )
+
+
+@router.get("/getAlbum")
+@router.get("/getAlbum.view")
+async def get_album(item_id: str = Query(..., alias="id")) -> Response:
+    sid = ids.parse_id(item_id)
+    if sid.kind != "playlist":
+        raise SubsonicError(NOT_FOUND, "getAlbum expects a pl: id")
+    info = await hum_client.get_client().playlist(sid.value)
+    songs = [_remember(_song_from_playlist_item(i), "song") for i in info.items]
+    pid = ids.playlist_id(sid.value)
+    return ok_response(
+        {
+            "album": {
+                "id": pid,
+                "name": info.title,
+                "artist": info.author or "Unknown",
+                "coverArt": pid,
+                "songCount": info.video_count,
+                "song": songs,
+            }
+        }
+    )
+
+
+# ----- internet radio (spec §3.2 radio; backed by Hum /api/radio) -----------
+
+_RADIO_LIMIT = 20
+
+
+@router.get("/getInternetRadioStations")
+@router.get("/getInternetRadioStations.view")
+async def get_internet_radio_stations() -> Response:
+    # bonob surfaces these as a non-library "Internet Radio" shelf in Sonos.
+    # Each live music stream becomes a station whose streamUrl points back at
+    # the shim's (unauthenticated) /radio/{id} continuous-stream endpoint.
+    hits = await hum_client.get_client().radio(limit=_RADIO_LIMIT)
+    base = get_settings().public_base_url()
+    stations = [
+        {
+            "id": f"rad:{h.id}",
+            "name": h.title,
+            "streamUrl": f"{base}/radio/{h.id}",
+            "homePageUrl": f"https://www.youtube.com/watch?v={h.id}",
+        }
+        for h in hits
+    ]
+    return ok_response(
+        {"internetRadioStations": {"internetRadioStation": stations}}
+    )
+
+
+@router.get("/getCoverArt")
+@router.get("/getCoverArt.view")
+async def get_cover_art(
+    item_id: str = Query(..., alias="id"),
+    size: int | None = Query(None, ge=1),
+) -> Response:
+    sid = ids.parse_id(item_id)
+    content, media_type = await hum_client.get_client().fetch_art(sid.kind, sid.value, size)
+    return Response(content=content, media_type=media_type)
+
+
+# ----- favourites + scrobble (spec §3.3 — shim-side; Hum stores nothing) ----
+
+
+def _starred2_lists() -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    songs: list[dict[str, Any]] = []
+    albums: list[dict[str, Any]] = []
+    for it in store.get_store().starred():
+        if it.kind == "song":
+            songs.append(
+                {
+                    "id": it.id,
+                    "title": it.title,
+                    "artist": it.artist,
+                    "isDir": False,
+                    "type": "music",
+                    "coverArt": it.id,
+                    "contentType": "audio/mp4",
+                    "suffix": "m4a",
+                }
+            )
+        else:
+            albums.append(
+                {
+                    "id": it.id,
+                    "name": it.title,
+                    "title": it.title,
+                    "artist": it.artist,
+                    "coverArt": it.id,
+                }
+            )
+    return songs, albums
+
+
+@router.get("/star")
+@router.get("/star.view")
+async def star(item_id: str = Query(..., alias="id")) -> Response:
+    sid = ids.parse_id(item_id)
+    kind = "song" if sid.kind == "video" else "album"
+    seen = store.recall(item_id)
+    title, artist = (seen[1], seen[2]) if seen else (item_id, "Unknown")
+    store.get_store().star(StarredItem(id=item_id, kind=kind, title=title, artist=artist))
+    return ok_response()
+
+
+@router.get("/unstar")
+@router.get("/unstar.view")
+async def unstar(item_id: str = Query(..., alias="id")) -> Response:
+    ids.parse_id(item_id)  # validate shape; unknown ids are a harmless no-op
+    store.get_store().unstar(item_id)
+    return ok_response()
+
+
+@router.get("/getStarred2")
+@router.get("/getStarred2.view")
+async def get_starred2() -> Response:
+    songs, albums = _starred2_lists()
+    return ok_response({"starred2": {"artist": [], "album": albums, "song": songs}})
+
+
+@router.get("/getStarred")
+@router.get("/getStarred.view")
+async def get_starred() -> Response:
+    songs, albums = _starred2_lists()
+    return ok_response({"starred": {"artist": [], "album": albums, "song": songs}})
+
+
+@router.get("/scrobble")
+@router.get("/scrobble.view")
+async def scrobble(
+    item_id: str = Query(..., alias="id"),
+    submission: bool = Query(True),
+) -> Response:
+    # Hum has no play history to write to (spec §9.4); accept gracefully so
+    # bonob's now-playing/scrobble reports don't error.
+    return ok_response()
+
+
+@router.get("/stream")
+@router.get("/stream.view")
+async def stream(item_id: str = Query(..., alias="id")) -> Response:
+    sid = ids.parse_id(item_id)
+    if sid.kind != "video":
+        raise SubsonicError(NOT_FOUND, "only vid: ids are streamable")
+    client = hum_client.get_client()
+    details = await client.video_details(sid.value)
+    fmt, mode = transcode.pick_audio_format(details.audio_formats)
+    settings = get_settings()
+    input_url = client.absolute(fmt.url)
+
+    # Seekable mode (b): materialize the remux to a cached file and let
+    # Starlette serve it with Content-Length + Range (a Sonos seek bar). Falls
+    # back to the streaming pipe if materialization fails.
+    if mode == "remux" and settings.seekable_remux:
+
+        async def _produce(dest: Path) -> bool:
+            return await transcode.materialize(
+                transcode.remux_file_args(
+                    input_url, dest, ffmpeg_path=settings.ffmpeg_path
+                )
+            )
+
+        path = await mediacache.get_cache().get_or_produce(sid.value, _produce)
+        if path is not None:
+            return FileResponse(path, media_type="audio/mp4")
+
+    # Range-ignoring mode (a) from spec §4: stream straight through.
+    args = transcode.ffmpeg_args(
+        input_url,
+        mode,
+        ffmpeg_path=settings.ffmpeg_path,
+        mp3_bitrate_kbps=settings.mp3_bitrate_kbps,
+    )
+    return StreamingResponse(
+        transcode.stream_ffmpeg(args), media_type=transcode.media_type_for(mode)
+    )
diff --git a/shim/store.py b/shim/store.py
new file mode 100644
index 0000000..2c04774
--- /dev/null
+++ b/shim/store.py
@@ -0,0 +1,115 @@
+"""Shim-side persistence for favourites (spec §3.3/§9.4 — Hum stores nothing).
+
+A small JSON file with atomic writes, mirrored by an in-process dict. Single
+user, single worker, so the event loop serializes writes; no extra locking.
+
+`star` only receives an id from Subsonic clients, so display metadata (title,
+artist) is recalled from a bounded cache of items the shim has recently emitted
+(`remember`/`recall`). This lets getStarred2 render names without re-fetching
+from Hum (which would trigger pytubefix extraction).
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import tempfile
+from collections import OrderedDict
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from shim.config import DATA_DIR_DEFAULT, get_settings
+
+
+@dataclass(frozen=True)
+class StarredItem:
+    id: str
+    kind: str  # "song" | "album"
+    title: str
+    artist: str
+
+
+class FavouritesStore:
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        self._items: dict[str, StarredItem] = {}
+        self._load()
+
+    def _load(self) -> None:
+        try:
+            raw = json.loads(self._path.read_text())
+        except (FileNotFoundError, ValueError):
+            return
+        for d in raw.get("items", []):
+            with contextlib.suppress(KeyError, TypeError):
+                item = StarredItem(
+                    id=str(d["id"]),
+                    kind=str(d["kind"]),
+                    title=str(d.get("title", "")),
+                    artist=str(d.get("artist", "")),
+                )
+                self._items[item.id] = item
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"items": [asdict(i) for i in self._items.values()]}
+        fd, tmp = tempfile.mkstemp(dir=self._path.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                json.dump(payload, f)
+            os.replace(tmp, self._path)  # atomic on POSIX
+        except BaseException:
+            with contextlib.suppress(FileNotFoundError):
+                os.unlink(tmp)
+            raise
+
+    def star(self, item: StarredItem) -> None:
+        self._items[item.id] = item
+        self._save()
+
+    def unstar(self, item_id: str) -> None:
+        if self._items.pop(item_id, None) is not None:
+            self._save()
+
+    def is_starred(self, item_id: str) -> bool:
+        return item_id in self._items
+
+    def starred(self) -> list[StarredItem]:
+        return list(self._items.values())
+
+
+# ----- recently-emitted metadata cache (for star without re-fetch) ----------
+
+_SEEN_MAX = 512
+_seen: OrderedDict[str, tuple[str, str, str]] = OrderedDict()
+
+
+def remember(item_id: str, kind: str, title: str, artist: str) -> None:
+    _seen[item_id] = (kind, title, artist)
+    _seen.move_to_end(item_id)
+    while len(_seen) > _SEEN_MAX:
+        _seen.popitem(last=False)
+
+
+def recall(item_id: str) -> tuple[str, str, str] | None:
+    return _seen.get(item_id)
+
+
+# ----- singleton (mirrors hum_client.get_client) ----------------------------
+
+_store: FavouritesStore | None = None
+
+
+def get_store() -> FavouritesStore:
+    global _store
+    if _store is None:
+        data_dir = Path(get_settings().data_dir) if get_settings().data_dir else DATA_DIR_DEFAULT
+        _store = FavouritesStore(data_dir / "favourites.json")
+    return _store
+
+
+def reset_store() -> None:
+    """Test seam: drop the singleton and the seen-cache."""
+    global _store
+    _store = None
+    _seen.clear()
diff --git a/shim/subsonic.py b/shim/subsonic.py
new file mode 100644
index 0000000..e36d324
--- /dev/null
+++ b/shim/subsonic.py
@@ -0,0 +1,122 @@
+"""Subsonic response envelopes (JSON + XML) and protocol error codes.
+
+All Subsonic responses — including errors — travel inside an HTTP 200 with a
+`subsonic-response` envelope; clients read `status` + `error.code`, not the
+HTTP status line.
+
+Format negotiation: the Subsonic `f` query param selects JSON (`f=json`) or
+XML (anything else, including absent — XML is the protocol default, which is
+what Amperfy and other older clients expect). The per-request format is stashed
+in a ContextVar by the auth dependency so endpoints can keep returning
+`ok_response(payload)` without threading the format through every signature.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from contextvars import ContextVar
+from typing import Any
+
+from fastapi import Response
+from fastapi.responses import JSONResponse
+
+SUBSONIC_API_VERSION = "1.16.1"
+SUBSONIC_XMLNS = "http://subsonic.org/restapi"
+SHIM_NAME = "hum-subsonic-shim"
+
+# Subsonic protocol error codes (the subset the shim uses).
+GENERIC = 0
+MISSING_PARAMETER = 10
+WRONG_CREDENTIALS = 40
+NOT_FOUND = 70
+
+_response_fmt: ContextVar[str] = ContextVar("subsonic_response_fmt", default="xml")
+
+
+def set_response_format(f: str | None) -> None:
+    """Record the request's desired format. Absent/unknown → XML (the Subsonic
+    default — clients like Amperfy omit `f` and expect XML)."""
+    _response_fmt.set("json" if f == "json" else "xml")
+
+
+def current_response_format() -> str:
+    return _response_fmt.get()
+
+
+class SubsonicError(Exception):
+    """Raised by handlers/dependencies; rendered as a failed envelope."""
+
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def envelope(payload: dict[str, Any] | None = None, *, status: str = "ok") -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "status": status,
+        "version": SUBSONIC_API_VERSION,
+        "type": SHIM_NAME,
+    }
+    if payload:
+        body.update(payload)
+    return {"subsonic-response": body}
+
+
+# ----- XML rendering --------------------------------------------------------
+
+
+def _xml_scalar(value: object) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _build(parent: ET.Element, key: str, value: object) -> None:
+    """Subsonic XML shape: scalars become attributes on their parent element,
+    nested dicts become child elements, and lists become repeated child
+    elements named for the key (e.g. song/album/musicFolder)."""
+    if isinstance(value, dict):
+        el = ET.SubElement(parent, key)
+        for k, v in value.items():
+            if isinstance(v, (dict, list)):
+                _build(el, k, v)
+            elif v is not None:
+                el.set(k, _xml_scalar(v))
+    elif isinstance(value, list):
+        for item in value:
+            _build(parent, key, item)
+    elif value is not None:
+        parent.set(key, _xml_scalar(value))
+
+
+def to_xml(payload: dict[str, Any] | None, *, status: str) -> str:
+    root = ET.Element(
+        "subsonic-response",
+        {
+            "xmlns": SUBSONIC_XMLNS,
+            "status": status,
+            "version": SUBSONIC_API_VERSION,
+            "type": SHIM_NAME,
+        },
+    )
+    for key, value in (payload or {}).items():
+        _build(root, key, value)
+    return '<?xml version="1.0" encoding="UTF-8"?>\n' + ET.tostring(root, encoding="unicode")
+
+
+# ----- response builders ----------------------------------------------------
+
+
+def _render(payload: dict[str, Any] | None, *, status: str, fmt: str | None) -> Response:
+    fmt = fmt or current_response_format()
+    if fmt == "json":
+        return JSONResponse(envelope(payload, status=status))
+    return Response(to_xml(payload, status=status), media_type="text/xml; charset=utf-8")
+
+
+def ok_response(payload: dict[str, Any] | None = None, *, fmt: str | None = None) -> Response:
+    return _render(payload, status="ok", fmt=fmt)
+
+
+def error_response(code: int, message: str, *, fmt: str | None = None) -> Response:
+    return _render({"error": {"code": code, "message": message}}, status="failed", fmt=fmt)
diff --git a/shim/transcode.py b/shim/transcode.py
new file mode 100644
index 0000000..08c1a92
--- /dev/null
+++ b/shim/transcode.py
@@ -0,0 +1,133 @@
+"""ffmpeg pipe for /rest/stream (spec §4).
+
+Mode 1 (default): AAC remux to fragmented MP4 — container fix only, near-zero
+CPU, timing metadata preserved. Mode 2 (fallback): mp3 re-encode when a video
+has no AAC format. Range requests are ignored for now (mode (a) in §4).
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Literal
+
+from shim.models import HumAudioFormat
+from shim.subsonic import NOT_FOUND, SubsonicError
+
+_CHUNK_BYTES = 64 * 1024
+# How much stderr tail to keep for diagnostics on a non-zero exit.
+_STDERR_TAIL_BYTES = 2048
+
+_log = logging.getLogger("shim.transcode")
+
+StreamMode = Literal["remux", "mp3"]
+
+
+def pick_audio_format(formats: list[HumAudioFormat]) -> tuple[HumAudioFormat, StreamMode]:
+    """Prefer the highest-bitrate AAC (remuxable); otherwise the
+    highest-bitrate format of any codec, re-encoded to mp3."""
+    if not formats:
+        raise SubsonicError(NOT_FOUND, "no audio formats available")
+    aac = [f for f in formats if f.codec == "aac"]
+    if aac:
+        return max(aac, key=lambda f: f.bitrate), "remux"
+    return max(formats, key=lambda f: f.bitrate), "mp3"
+
+
+def media_type_for(mode: StreamMode) -> str:
+    return "audio/mp4" if mode == "remux" else "audio/mpeg"
+
+
+def ffmpeg_args(
+    input_url: str, mode: StreamMode, *, ffmpeg_path: str, mp3_bitrate_kbps: int
+) -> list[str]:
+    base = [ffmpeg_path, "-hide_banner", "-loglevel", "error", "-i", input_url, "-vn"]
+    if mode == "remux":
+        return [*base, "-c:a", "copy", "-f", "mp4", "-movflags", "frag_keyframe+empty_moov", "-"]
+    return [*base, "-c:a", "libmp3lame", "-b:a", f"{mp3_bitrate_kbps}k", "-f", "mp3", "-"]
+
+
+def remux_file_args(input_url: str, dest: Path, *, ffmpeg_path: str) -> list[str]:
+    """Remux AAC to a complete .m4a file with the moov atom up front
+    (+faststart) so it serves cleanly under Range requests — distinct from the
+    fragmented, headerless container used for the streaming pipe."""
+    return [
+        ffmpeg_path, "-hide_banner", "-loglevel", "error",
+        "-i", input_url, "-vn", "-c:a", "copy", "-movflags", "+faststart",
+        str(dest),
+    ]
+
+
+def live_radio_args(manifest_url: str, *, ffmpeg_path: str, bitrate_kbps: int) -> list[str]:
+    """Read a live HLS manifest and emit a continuous mp3 stream for Sonos
+    internet radio (mp3 is the safe, universally-supported radio codec)."""
+    return [
+        ffmpeg_path, "-hide_banner", "-loglevel", "error",
+        "-i", manifest_url, "-vn",
+        "-c:a", "libmp3lame", "-b:a", f"{bitrate_kbps}k", "-f", "mp3", "-",
+    ]
+
+
+async def materialize(args: list[str]) -> bool:
+    """Run ffmpeg to completion writing to a file (args end in the dest path).
+    Returns True on a clean exit; logs a stderr tail and returns False otherwise
+    so the caller can fall back to the streaming pipe."""
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.DEVNULL,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    _, stderr = await proc.communicate()
+    if proc.returncode != 0:
+        tail = (stderr or b"")[-_STDERR_TAIL_BYTES:].decode("utf-8", "replace").strip()
+        _log.warning("ffmpeg materialize exited %s: %s", proc.returncode, tail or "<no stderr>")
+        return False
+    return True
+
+
+async def stream_ffmpeg(args: list[str]) -> AsyncIterator[bytes]:
+    """Yield ffmpeg stdout chunks, reaping the process on completion or client
+    disconnect (the body_iterator pattern from app/proxy/_common.py applied to
+    a subprocess — spec §4 process-lifecycle requirement).
+
+    stderr is captured (ffmpeg runs at -loglevel error, so it's low-volume) and
+    logged when ffmpeg exits non-zero for a reason other than our own kill, so a
+    failed transcode leaves a diagnostic instead of a silently truncated stream.
+    """
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    assert proc.stdout is not None  # guaranteed by stdout=PIPE
+    disconnected = False
+    try:
+        while chunk := await proc.stdout.read(_CHUNK_BYTES):
+            yield chunk
+    except (BrokenPipeError, ConnectionResetError):
+        disconnected = True
+    except (GeneratorExit, asyncio.CancelledError):
+        # Client went away (Starlette closes/cancels the body iterator).
+        disconnected = True
+        raise
+    finally:
+        # Reap. returncode is often still None here even when ffmpeg has already
+        # exited (e.g. on failure), so we can't infer disconnect from it — kill
+        # is harmless on an already-dead process, and wait() yields the real code.
+        if proc.returncode is None:
+            with contextlib.suppress(ProcessLookupError):
+                proc.kill()
+        stderr = b""
+        if proc.stderr is not None:
+            with contextlib.suppress(Exception):
+                stderr = await proc.stderr.read()
+        await proc.wait()
+        # A non-zero exit we didn't cause by disconnecting = a real transcode
+        # failure; leave a diagnostic instead of a silently truncated stream.
+        if not disconnected and proc.returncode not in (0, None):
+            tail = stderr[-_STDERR_TAIL_BYTES:].decode("utf-8", "replace").strip()
+            _log.warning("ffmpeg exited %s: %s", proc.returncode, tail or "<no stderr>")
diff --git a/tests/shim/conftest.py b/tests/shim/conftest.py
new file mode 100644
index 0000000..7250dca
--- /dev/null
+++ b/tests/shim/conftest.py
@@ -0,0 +1,58 @@
+"""Shared fixtures for the shim test suite."""
+from __future__ import annotations
+
+import hashlib
+import os
+from collections.abc import Iterator
+
+import pytest
+from fastapi.testclient import TestClient
+
+_TEST_USER = "tester"
+_TEST_PASSWORD = "correct-horse-battery"
+
+# Pre-populate env vars required by ShimSettings before any test imports
+# shim modules (same pattern as the root conftest for app/).
+os.environ.setdefault("SHIM_HUM_BEARER_TOKEN", "test-hum-bearer-token")
+os.environ.setdefault("SHIM_SUBSONIC_USER", _TEST_USER)
+os.environ.setdefault("SHIM_SUBSONIC_PASSWORD", _TEST_PASSWORD)
+
+
+@pytest.fixture
+def shim_user() -> str:
+    return _TEST_USER
+
+
+@pytest.fixture
+def shim_password() -> str:
+    return _TEST_PASSWORD
+
+
+@pytest.fixture
+def subsonic_auth() -> dict[str, str]:
+    """Valid token-auth query params for the test credentials."""
+    salt = "abc123"
+    token = hashlib.md5(
+        (_TEST_PASSWORD + salt).encode(), usedforsecurity=False
+    ).hexdigest()
+    return {"u": _TEST_USER, "t": token, "s": salt, "v": "1.16.1", "c": "tests", "f": "json"}
+
+
+@pytest.fixture
+def shim_client() -> TestClient:
+    from shim.main import app
+
+    return TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def isolate_favourites(monkeypatch: pytest.MonkeyPatch, tmp_path: object) -> Iterator[None]:
+    """Point the favourites store at a per-test temp dir and clear the
+    seen-cache + singleton, so star/unstar state never leaks across tests
+    or touches the repo's real .shim-data."""
+    from shim import store
+
+    store.reset_store()
+    monkeypatch.setattr(store, "DATA_DIR_DEFAULT", tmp_path)
+    yield
+    store.reset_store()
diff --git a/tests/shim/integration/conftest.py b/tests/shim/integration/conftest.py
new file mode 100644
index 0000000..7e12d66
--- /dev/null
+++ b/tests/shim/integration/conftest.py
@@ -0,0 +1,70 @@
+"""Fixtures for opt-in integration tests against a LIVE shim + Hum.
+
+These do not use the in-process TestClient: they hit a running shim over HTTP
+(start `hum` and `hum-shim` first), so they exercise the real Hum bearer token,
+ffmpeg, and YouTube. Run explicitly:
+
+    hum &              # :8000
+    hum-shim &         # :8001  (needs SHIM_SUBSONIC_PASSWORD in .env)
+    pytest -m integration tests/shim/integration
+
+Everything skips cleanly if the shim isn't reachable or ffprobe is missing, so
+the suite never fails just because the services aren't up.
+"""
+from __future__ import annotations
+
+import hashlib
+import shutil
+
+import httpx
+import pytest
+from dotenv import dotenv_values
+
+from shim.config import _REPO_ROOT
+
+pytestmark = pytest.mark.integration
+
+_ENV = dotenv_values(_REPO_ROOT / ".env")
+
+
+def _shim_base() -> str:
+    host = _ENV.get("SHIM_HOST") or "127.0.0.1"
+    port = _ENV.get("SHIM_PORT") or "8001"
+    return f"http://{host}:{port}"
+
+
+def _health_or_skip(base: str, what: str) -> None:
+    try:
+        httpx.get(f"{base}/health", timeout=2.0).raise_for_status()
+    except (httpx.HTTPError, OSError) as e:
+        pytest.skip(f"{what} not reachable at {base}: {e}")
+
+
+@pytest.fixture(scope="session")
+def shim_base() -> str:
+    base = _shim_base()
+    _health_or_skip(base, "shim")
+    # The live tests exercise the whole chain, so Hum must be up too — without
+    # this, a stopped Hum surfaces as a confusing error instead of a skip.
+    hum_base = _ENV.get("SHIM_HUM_BASE_URL") or "http://127.0.0.1:8000"
+    _health_or_skip(hum_base, "Hum")
+    return base
+
+
+@pytest.fixture(scope="session")
+def shim_auth() -> dict[str, str]:
+    user = _ENV.get("SHIM_SUBSONIC_USER") or "hum"
+    password = _ENV.get("SHIM_SUBSONIC_PASSWORD")
+    if not password:
+        pytest.skip("SHIM_SUBSONIC_PASSWORD not set in .env")
+    salt = "integ-salt"
+    token = hashlib.md5((password + salt).encode(), usedforsecurity=False).hexdigest()
+    return {"u": user, "t": token, "s": salt, "v": "1.16.1", "c": "integ", "f": "json"}
+
+
+@pytest.fixture(scope="session")
+def ffprobe() -> str:
+    path = shutil.which("ffprobe")
+    if not path:
+        pytest.skip("ffprobe not installed")
+    return path
diff --git a/tests/shim/integration/test_integration_live.py b/tests/shim/integration/test_integration_live.py
new file mode 100644
index 0000000..f97519c
--- /dev/null
+++ b/tests/shim/integration/test_integration_live.py
@@ -0,0 +1,63 @@
+"""Live end-to-end checks: search returns songs, and a stream decodes as audio.
+
+Opt-in (`-m integration`); skips unless a running shim is reachable. Produces
+the same evidence a human would check before the Amperfy test.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+import httpx
+import pytest
+
+pytestmark = pytest.mark.integration
+
+_MAX_STREAM_BYTES = 512 * 1024  # enough for ffprobe to identify the codec
+
+
+def _first_song_id(base: str, auth: dict[str, str], query: str) -> str:
+    r = httpx.get(f"{base}/rest/search3", params={**auth, "query": query}, timeout=30.0)
+    r.raise_for_status()
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok", body
+    songs = body.get("searchResult3", {}).get("song", [])
+    if not songs:
+        pytest.skip(f"no songs returned for {query!r}")
+    return str(songs[0]["id"])
+
+
+def test_search3_returns_songs(shim_base: str, shim_auth: dict[str, str]) -> None:
+    sid = _first_song_id(shim_base, shim_auth, "lofi hip hop")
+    assert sid.startswith("vid:")
+
+
+def test_stream_decodes_as_audio(
+    shim_base: str, shim_auth: dict[str, str], ffprobe: str
+) -> None:
+    sid = _first_song_id(shim_base, shim_auth, "lofi hip hop")
+
+    collected = bytearray()
+    with httpx.stream(
+        "GET", f"{shim_base}/rest/stream", params={**shim_auth, "id": sid}, timeout=60.0
+    ) as r:
+        r.raise_for_status()
+        assert r.headers["content-type"] in ("audio/mp4", "audio/mpeg")
+        for chunk in r.iter_bytes():
+            collected.extend(chunk)
+            if len(collected) >= _MAX_STREAM_BYTES:
+                break
+    assert collected, "stream produced no bytes"
+
+    with tempfile.NamedTemporaryFile(suffix=".bin") as f:
+        Path(f.name).write_bytes(bytes(collected))
+        out = subprocess.run(
+            [ffprobe, "-v", "error", "-show_entries", "stream=codec_type",
+             "-of", "json", f.name],
+            capture_output=True, text=True, timeout=30,
+        )
+    streams = json.loads(out.stdout or "{}").get("streams", [])
+    codec_types = {s.get("codec_type") for s in streams}
+    assert "audio" in codec_types, f"ffprobe found no audio stream: {out.stdout} {out.stderr}"
diff --git a/tests/shim/test_browse.py b/tests/shim/test_browse.py
new file mode 100644
index 0000000..bdd4450
--- /dev/null
+++ b/tests/shim/test_browse.py
@@ -0,0 +1,199 @@
+"""Phase 2 browsing tests: synthetic hierarchy + playlist drill-in (Search + Playlists)."""
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim.models import HumPlaylistInfo, HumPlaylistItem, HumSearchHit
+
+_PLID = "PLabcdef123"
+
+
+class FakeHumClient:
+    def __init__(
+        self,
+        hits: list[HumSearchHit] | None = None,
+        playlist: HumPlaylistInfo | None = None,
+    ) -> None:
+        self._hits = hits or []
+        self._playlist = playlist
+
+    async def search(self, q: str, limit: int) -> list[HumSearchHit]:
+        return self._hits[:limit]
+
+    async def playlist(self, playlist_id: str) -> HumPlaylistInfo:
+        assert self._playlist is not None
+        return self._playlist
+
+    async def fetch_art(
+        self, kind: str, value: str, size: int | None = None
+    ) -> tuple[bytes, str]:
+        return b"art-bytes", "image/jpeg"
+
+
+def _install(monkeypatch: pytest.MonkeyPatch, fake: FakeHumClient) -> None:
+    from shim import hum_client
+
+    monkeypatch.setattr(hum_client, "get_client", lambda: fake)
+
+
+def _resp(client: TestClient, auth: dict[str, str], path: str, **params: str) -> dict:
+    r = client.get(path, params={**auth, **params})
+    assert r.status_code == 200
+    return r.json()["subsonic-response"]
+
+
+def test_get_music_folders(shim_client: TestClient, subsonic_auth: dict[str, str]) -> None:
+    body = _resp(shim_client, subsonic_auth, "/rest/getMusicFolders")
+    folders = body["musicFolders"]["musicFolder"]
+    assert folders == [{"id": 0, "name": "Hum"}]
+
+
+def test_get_artists_and_indexes_empty(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    assert _resp(shim_client, subsonic_auth, "/rest/getArtists")["artists"]["index"] == []
+    assert _resp(shim_client, subsonic_auth, "/rest/getIndexes")["indexes"]["index"] == []
+
+
+def test_get_album_list2_empty(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    body = _resp(shim_client, subsonic_auth, "/rest/getAlbumList2", type="newest")
+    assert body["albumList2"]["album"] == []
+
+
+def test_get_playlists_empty_without_pins(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install(monkeypatch, FakeHumClient())
+    body = _resp(shim_client, subsonic_auth, "/rest/getPlaylists")
+    assert body["playlists"]["playlist"] == []
+
+
+def test_get_playlists_lists_config_pins(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from shim.config import get_settings
+
+    _install(monkeypatch, FakeHumClient(playlist=_playlist()))
+    monkeypatch.setattr(get_settings(), "pinned_playlists", _PLID)
+    body = _resp(shim_client, subsonic_auth, "/rest/getPlaylists")
+    playlists = body["playlists"]["playlist"]
+    assert [p["id"] for p in playlists] == [f"pl:{_PLID}"]
+    assert playlists[0]["name"] == "Chill Mix"
+    assert playlists[0]["songCount"] == 2
+
+
+def test_get_playlists_includes_starred(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from shim import store
+
+    _install(monkeypatch, FakeHumClient(playlist=_playlist()))
+    store.get_store().star(
+        store.StarredItem(id=f"pl:{_PLID}", kind="album", title="Chill Mix", artist="Curator")
+    )
+    body = _resp(shim_client, subsonic_auth, "/rest/getPlaylists")
+    assert [p["id"] for p in body["playlists"]["playlist"]] == [f"pl:{_PLID}"]
+
+
+def test_get_playlists_drops_failed_lookups(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from shim.config import get_settings
+
+    class _Failing(FakeHumClient):
+        async def playlist(self, playlist_id: str) -> HumPlaylistInfo:
+            raise RuntimeError("deleted playlist")
+
+    _install(monkeypatch, _Failing())
+    monkeypatch.setattr(get_settings(), "pinned_playlists", _PLID)
+    body = _resp(shim_client, subsonic_auth, "/rest/getPlaylists")
+    # A failing pin is skipped, not fatal.
+    assert body["playlists"]["playlist"] == []
+
+
+def test_search3_surfaces_playlist_as_album(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    hits = [
+        HumSearchHit(
+            kind="playlist",
+            id=_PLID,
+            title="Chill Mix",
+            author="Curator",
+            thumbnail_url="https://i.ytimg.com/x.jpg",
+            video_count=42,
+        ),
+    ]
+    _install(monkeypatch, FakeHumClient(hits=hits))
+    body = _resp(shim_client, subsonic_auth, "/rest/search3", query="chill")
+    albums = body["searchResult3"]["album"]
+    assert len(albums) == 1
+    assert albums[0]["id"] == f"pl:{_PLID}"
+    assert albums[0]["name"] == "Chill Mix"
+    assert albums[0]["songCount"] == 42
+    assert body["searchResult3"]["song"] == []
+
+
+def _playlist() -> HumPlaylistInfo:
+    return HumPlaylistInfo(
+        playlist_id=_PLID,
+        title="Chill Mix",
+        author="Curator",
+        video_count=2,
+        items=[
+            HumPlaylistItem(video_id="dQw4w9WgXcQ", title="Track 1", duration_seconds=200),
+            HumPlaylistItem(video_id="abcdefghijk", title="Track 2", duration_seconds=180),
+        ],
+    )
+
+
+def test_get_playlist_expands_to_entries(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install(monkeypatch, FakeHumClient(playlist=_playlist()))
+    body = _resp(shim_client, subsonic_auth, "/rest/getPlaylist", id=f"pl:{_PLID}")
+    pl = body["playlist"]
+    assert pl["id"] == f"pl:{_PLID}"
+    assert pl["songCount"] == 2
+    assert [e["id"] for e in pl["entry"]] == ["vid:dQw4w9WgXcQ", "vid:abcdefghijk"]
+    assert pl["entry"][0]["title"] == "Track 1"
+
+
+def test_get_album_expands_to_songs(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install(monkeypatch, FakeHumClient(playlist=_playlist()))
+    body = _resp(shim_client, subsonic_auth, "/rest/getAlbum", id=f"pl:{_PLID}")
+    album = body["album"]
+    assert album["id"] == f"pl:{_PLID}"
+    assert album["coverArt"] == f"pl:{_PLID}"
+    assert len(album["song"]) == 2
+    assert album["song"][0]["id"] == "vid:dQw4w9WgXcQ"
+
+
+def test_get_playlist_rejects_video_id(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get(
+        "/rest/getPlaylist", params={**subsonic_auth, "id": "vid:dQw4w9WgXcQ"}
+    )
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 70
+
+
+def test_get_cover_art_for_playlist(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _install(monkeypatch, FakeHumClient())
+    r = shim_client.get("/rest/getCoverArt", params={**subsonic_auth, "id": f"pl:{_PLID}"})
+    assert r.status_code == 200
+    assert r.content == b"art-bytes"
+
+
+def test_browse_requires_auth(shim_client: TestClient) -> None:
+    r = shim_client.get("/rest/getMusicFolders", params={"f": "json"})
+    assert r.json()["subsonic-response"]["status"] == "failed"
diff --git a/tests/shim/test_favourites.py b/tests/shim/test_favourites.py
new file mode 100644
index 0000000..8ddb20f
--- /dev/null
+++ b/tests/shim/test_favourites.py
@@ -0,0 +1,81 @@
+"""Endpoint tests for star/unstar/getStarred2 and scrobble."""
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim import store
+
+_YTID = "dQw4w9WgXcQ"
+_PLID = "PLabcdef123"
+
+
+def _ok(client: TestClient, auth: dict[str, str], path: str, **params: str) -> dict:
+    r = client.get(path, params={**auth, **params})
+    assert r.status_code == 200
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok"
+    return body
+
+
+def test_star_then_getstarred2_uses_seen_metadata(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    # Simulate the song having been emitted by a prior search3/getAlbum.
+    store.remember(f"vid:{_YTID}", "song", "Never Gonna", "Rick Astley")
+    _ok(shim_client, subsonic_auth, "/rest/star", id=f"vid:{_YTID}")
+
+    body = _ok(shim_client, subsonic_auth, "/rest/getStarred2")
+    songs = body["starred2"]["song"]
+    assert len(songs) == 1
+    assert songs[0]["id"] == f"vid:{_YTID}"
+    assert songs[0]["title"] == "Never Gonna"
+    assert songs[0]["artist"] == "Rick Astley"
+
+
+def test_star_album_appears_in_albums(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    store.remember(f"pl:{_PLID}", "album", "Chill Mix", "Curator")
+    _ok(shim_client, subsonic_auth, "/rest/star", id=f"pl:{_PLID}")
+    body = _ok(shim_client, subsonic_auth, "/rest/getStarred2")
+    albums = body["starred2"]["album"]
+    assert [a["id"] for a in albums] == [f"pl:{_PLID}"]
+    assert albums[0]["name"] == "Chill Mix"
+
+
+def test_star_without_seen_falls_back_to_id_title(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    _ok(shim_client, subsonic_auth, "/rest/star", id=f"vid:{_YTID}")
+    body = _ok(shim_client, subsonic_auth, "/rest/getStarred2")
+    assert body["starred2"]["song"][0]["title"] == f"vid:{_YTID}"
+
+
+def test_unstar_removes(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    _ok(shim_client, subsonic_auth, "/rest/star", id=f"vid:{_YTID}")
+    _ok(shim_client, subsonic_auth, "/rest/unstar", id=f"vid:{_YTID}")
+    body = _ok(shim_client, subsonic_auth, "/rest/getStarred2")
+    assert body["starred2"]["song"] == []
+
+
+def test_star_rejects_malformed_id(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/star", params={**subsonic_auth, "id": "vid:bad"})
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 70
+
+
+def test_scrobble_is_accepted(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    _ok(shim_client, subsonic_auth, "/rest/scrobble", id=f"vid:{_YTID}", submission="true")
+
+
+def test_favourites_require_auth(shim_client: TestClient) -> None:
+    r = shim_client.get("/rest/getStarred2", params={"f": "json"})
+    assert r.json()["subsonic-response"]["status"] == "failed"
diff --git a/tests/shim/test_hum_client.py b/tests/shim/test_hum_client.py
new file mode 100644
index 0000000..57aef42
--- /dev/null
+++ b/tests/shim/test_hum_client.py
@@ -0,0 +1,160 @@
+"""Unit tests for HumClient's playlist fetch and extraction-free cover-art sourcing."""
+from __future__ import annotations
+
+import httpx
+import pytest
+
+from shim.hum_client import HumClient, _raise_for_hum_error, _ytimg_variant
+from shim.subsonic import GENERIC, NOT_FOUND, SubsonicError
+
+
+def _client(handler: "httpx.MockTransport") -> HumClient:
+    c = HumClient(
+        "http://hum.local",
+        "x" * 16,
+        connect_timeout=1.0,
+        read_timeout=1.0,
+        cache_max_ttl=1800.0,
+        cache_safety=60.0,
+    )
+    # Swap both internal AsyncClients for ones backed by the mock transport.
+    c._hum = httpx.AsyncClient(  # type: ignore[attr-defined]
+        base_url="http://hum.local",
+        headers={"Authorization": "Bearer " + "x" * 16},
+        transport=handler,
+    )
+    c._ext = httpx.AsyncClient(transport=handler)  # type: ignore[attr-defined]
+    return c
+
+
+@pytest.mark.asyncio
+async def test_playlist_parsed_and_thumbnails_remembered() -> None:
+    def handle(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/playlist/PLabc"
+        assert request.headers["authorization"] == "Bearer " + "x" * 16
+        return httpx.Response(
+            200,
+            json={
+                "playlist_id": "PLabc",
+                "title": "Mix",
+                "author": "Curator",
+                "video_count": 1,
+                "items": [
+                    {
+                        "video_id": "dQw4w9WgXcQ",
+                        "title": "T1",
+                        "thumbnail_url": "https://i.ytimg.com/t1.jpg",
+                    }
+                ],
+            },
+        )
+
+    c = _client(httpx.MockTransport(handle))
+    try:
+        info = await c.playlist("PLabc")
+        assert info.title == "Mix"
+        assert info.items[0].video_id == "dQw4w9WgXcQ"
+        # Item thumbnail remembered for extraction-free getCoverArt.
+        url, _ = c._video_art_source("dQw4w9WgXcQ")  # type: ignore[attr-defined]
+        assert url == "https://i.ytimg.com/t1.jpg"
+    finally:
+        await c.close()
+
+
+@pytest.mark.asyncio
+async def test_video_art_falls_back_to_ytimg() -> None:
+    c = _client(httpx.MockTransport(lambda r: httpx.Response(404)))
+    try:
+        url, _ = c._video_art_source("dQw4w9WgXcQ")  # type: ignore[attr-defined]
+        assert url == "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
+    finally:
+        await c.close()
+
+
+@pytest.mark.asyncio
+async def test_playlist_art_uses_first_item_thumbnail() -> None:
+    def handle(request: httpx.Request) -> httpx.Response:
+        if request.url.path == "/api/playlist/PLxyz":
+            return httpx.Response(
+                200,
+                json={
+                    "playlist_id": "PLxyz",
+                    "title": "Mix",
+                    "video_count": 1,
+                    "items": [
+                        {"video_id": "abcdefghijk", "title": "T", "thumbnail_url": "https://i/y.jpg"}
+                    ],
+                },
+            )
+        # The art fetch itself.
+        return httpx.Response(200, content=b"img", headers={"content-type": "image/jpeg"})
+
+    c = _client(httpx.MockTransport(handle))
+    try:
+        content, media_type = await c.fetch_art("playlist", "PLxyz")
+        assert content == b"img"
+        assert media_type == "image/jpeg"
+    finally:
+        await c.close()
+
+
+# ----- ytimg variant sizing (spec §3.5) -------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("size", "expected"),
+    [
+        (None, "https://i.ytimg.com/vi/abc/hqdefault.jpg"),
+        (90, "https://i.ytimg.com/vi/abc/default.jpg"),
+        (300, "https://i.ytimg.com/vi/abc/mqdefault.jpg"),
+        (1000, "https://i.ytimg.com/vi/abc/hqdefault.jpg"),  # capped at hqdefault
+    ],
+)
+def test_ytimg_variant_rewrites_by_size(size: int | None, expected: str) -> None:
+    assert _ytimg_variant("https://i.ytimg.com/vi/abc/hqdefault.jpg", size) == expected
+
+
+def test_ytimg_variant_passes_through_non_ytimg() -> None:
+    signed = "http://hum.local/proxy/thumbnail/abc?itag=0&exp=1&sig=x"
+    assert _ytimg_variant(signed, 300) == signed
+
+
+# ----- error envelope mapping (spec §5 / error envelopes) -------------------
+
+
+def test_unplayable_maps_to_not_found() -> None:
+    r = httpx.Response(422, json={"error": "LIVE_NOT_SUPPORTED", "message": "live"})
+    with pytest.raises(SubsonicError) as exc:
+        _raise_for_hum_error(r)
+    assert exc.value.code == NOT_FOUND
+    assert "LIVE_NOT_SUPPORTED" in exc.value.message
+    assert "live" in exc.value.message
+
+
+def test_upstream_5xx_maps_to_generic() -> None:
+    r = httpx.Response(502, json={"error": "UPSTREAM_ERROR", "message": "boom"})
+    with pytest.raises(SubsonicError) as exc:
+        _raise_for_hum_error(r)
+    assert exc.value.code == GENERIC
+    assert "502" in exc.value.message
+
+
+def test_200_does_not_raise() -> None:
+    _raise_for_hum_error(httpx.Response(200, json={"ok": True}))
+
+
+@pytest.mark.asyncio
+async def test_transport_error_becomes_subsonic_error() -> None:
+    # Hum down/unreachable must surface as a Subsonic error (failed envelope),
+    # not an unhandled httpx.RequestError → HTTP 500.
+    def boom(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("connection refused", request=request)
+
+    c = _client(httpx.MockTransport(boom))
+    try:
+        with pytest.raises(SubsonicError) as exc:
+            await c.search("anything", limit=5)
+        assert exc.value.code == GENERIC
+        assert "unreachable" in exc.value.message.lower()
+    finally:
+        await c.close()
diff --git a/tests/shim/test_ids.py b/tests/shim/test_ids.py
new file mode 100644
index 0000000..9d2faf7
--- /dev/null
+++ b/tests/shim/test_ids.py
@@ -0,0 +1,45 @@
+"""Unit tests for the vid:/pl:/art: ID scheme."""
+from __future__ import annotations
+
+import pytest
+
+from shim.ids import SubsonicId, parse_id, video_id
+from shim.subsonic import NOT_FOUND, SubsonicError
+
+_YTID = "dQw4w9WgXcQ"
+
+
+def test_video_round_trip() -> None:
+    sid = parse_id(video_id(_YTID))
+    assert sid == SubsonicId(kind="video", value=_YTID)
+    assert str(sid) == f"vid:{_YTID}"
+
+
+def test_playlist_parse() -> None:
+    sid = parse_id("pl:PLabc123")
+    assert sid.kind == "playlist"
+    assert sid.value == "PLabc123"
+
+
+def test_artist_parse() -> None:
+    sid = parse_id("art:UCabcdef")
+    assert sid.kind == "artist"
+    assert sid.value == "UCabcdef"
+
+
+@pytest.mark.parametrize(
+    "raw",
+    [
+        "vid:short",  # not 11 chars
+        "vid:" + "x" * 12,  # too long
+        "vid:bad!chars$$",  # invalid chars
+        "art:abc",  # below channel minimum length
+        "unknown:xyz",  # unknown prefix
+        "noprefix",  # no separator
+        "",  # empty
+    ],
+)
+def test_malformed_ids_rejected(raw: str) -> None:
+    with pytest.raises(SubsonicError) as exc:
+        parse_id(raw)
+    assert exc.value.code == NOT_FOUND
diff --git a/tests/shim/test_mediacache.py b/tests/shim/test_mediacache.py
new file mode 100644
index 0000000..cbb93ef
--- /dev/null
+++ b/tests/shim/test_mediacache.py
@@ -0,0 +1,75 @@
+"""Unit tests for the on-disk media cache (seekable remux backing store)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from shim.mediacache import MediaCache
+
+
+def _writer(data: bytes, calls: list[int]) -> object:
+    async def produce(dest: Path) -> bool:
+        calls.append(1)
+        dest.write_bytes(data)
+        return True
+
+    return produce
+
+
+async def test_produces_then_caches(tmp_path: Path) -> None:
+    cache = MediaCache(tmp_path, max_bytes=10 * 1024 * 1024)
+    calls: list[int] = []
+    p1 = await cache.get_or_produce("vid:abc", _writer(b"DATA", calls))
+    assert p1 is not None and p1.read_bytes() == b"DATA"
+    # Second call is served from cache — producer not invoked again.
+    p2 = await cache.get_or_produce("vid:abc", _writer(b"DATA", calls))
+    assert p2 == p1
+    assert calls == [1]
+
+
+async def test_producer_failure_returns_none(tmp_path: Path) -> None:
+    cache = MediaCache(tmp_path, max_bytes=1024)
+
+    async def fail(dest: Path) -> bool:
+        return False
+
+    assert await cache.get_or_produce("vid:x", fail) is None
+    # No partial left behind.
+    assert list(tmp_path.iterdir()) == []
+
+
+async def test_producer_not_writing_returns_none(tmp_path: Path) -> None:
+    cache = MediaCache(tmp_path, max_bytes=1024)
+
+    async def claims_ok_but_writes_nothing(dest: Path) -> bool:
+        return True  # returns success without creating dest
+
+    assert await cache.get_or_produce("vid:x", claims_ok_but_writes_nothing) is None
+
+
+async def test_eviction_drops_oldest_over_cap(tmp_path: Path) -> None:
+    cache = MediaCache(tmp_path, max_bytes=100)
+    calls: list[int] = []
+    # Three 40-byte entries = 120 bytes > 100 cap → oldest evicted.
+    a = await cache.get_or_produce("a", _writer(b"x" * 40, calls))
+    assert a is not None
+    os.utime(a, (1, 1))  # make 'a' the oldest by mtime
+    b = await cache.get_or_produce("b", _writer(b"x" * 40, calls))
+    assert b is not None
+    os.utime(b, (2, 2))
+    await cache.get_or_produce("c", _writer(b"x" * 40, calls))
+    assert not cache.has("a")  # evicted
+    assert cache.has("c")
+
+
+def test_path_for_sanitizes_key(tmp_path: Path) -> None:
+    cache = MediaCache(tmp_path, max_bytes=1024)
+    p = cache.path_for("vid:dQw4/../w9", ".m4a")
+    # The real safety property: separators are stripped, so the result is a
+    # single component directly under the cache dir (no traversal). Dots are
+    # kept, but "a.._b" is a plain filename, not a parent ref.
+    assert p.parent == tmp_path
+    assert os.sep not in p.name
+    assert os.altsep is None or os.altsep not in p.name
diff --git a/tests/shim/test_radio.py b/tests/shim/test_radio.py
new file mode 100644
index 0000000..5daf292
--- /dev/null
+++ b/tests/shim/test_radio.py
@@ -0,0 +1,87 @@
+"""Internet radio: getInternetRadioStations listing + the /radio/{id} stream."""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim.models import HumSearchHit
+from shim.transcode import live_radio_args
+
+_LIVE = "dQw4w9WgXcQ"
+
+
+class _FakeClient:
+    def __init__(self, hits: list[HumSearchHit]) -> None:
+        self._hits = hits
+
+    async def radio(self, limit: int) -> list[HumSearchHit]:
+        return self._hits
+
+    async def live_manifest_url(self, video_id: str) -> str:
+        return f"http://hum.local/api/live/{video_id}/manifest.m3u8?exp=1&sig=ab"
+
+
+def test_get_internet_radio_stations_maps_hits(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from shim import hum_client
+    from shim.config import get_settings
+
+    hits = [HumSearchHit(kind="video", id=_LIVE, title="Lofi Radio", is_live=True)]
+    monkeypatch.setattr(hum_client, "get_client", lambda: _FakeClient(hits))
+    monkeypatch.setattr(get_settings(), "public_url", "http://192.168.1.10:8001")
+
+    r = shim_client.get("/rest/getInternetRadioStations", params=subsonic_auth)
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok"
+    stations = body["internetRadioStations"]["internetRadioStation"]
+    assert len(stations) == 1
+    assert stations[0]["id"] == f"rad:{_LIVE}"
+    assert stations[0]["name"] == "Lofi Radio"
+    assert stations[0]["streamUrl"] == f"http://192.168.1.10:8001/radio/{_LIVE}"
+
+
+def test_radio_stations_require_auth(shim_client: TestClient) -> None:
+    r = shim_client.get("/rest/getInternetRadioStations", params={"f": "json"})
+    assert r.json()["subsonic-response"]["status"] == "failed"
+
+
+def test_radio_stream_is_unauthenticated_and_pipes_audio(
+    shim_client: TestClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from shim import hum_client, transcode
+
+    monkeypatch.setattr(hum_client, "get_client", lambda: _FakeClient([]))
+
+    captured: dict[str, list[str]] = {}
+
+    async def fake_stream(args: list[str]) -> AsyncIterator[bytes]:
+        captured["args"] = args
+        yield b"MP3DATA"
+
+    monkeypatch.setattr(transcode, "stream_ffmpeg", fake_stream)
+
+    # No Subsonic credentials — Sonos fetches the stream URL directly.
+    r = shim_client.get(f"/radio/{_LIVE}")
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "audio/mpeg"
+    assert r.content == b"MP3DATA"
+    # ffmpeg reads the resolved live manifest and emits mp3.
+    assert "manifest.m3u8" in captured["args"][captured["args"].index("-i") + 1]
+    assert "libmp3lame" in captured["args"]
+
+
+def test_radio_stream_rejects_bad_id(shim_client: TestClient) -> None:
+    # Path pattern rejects a malformed id; the global validation handler turns
+    # it into a failed envelope. Either way, no audio stream is produced.
+    r = shim_client.get("/radio/not-an-id")
+    assert r.headers.get("content-type") != "audio/mpeg"
+
+
+def test_live_radio_args_shape() -> None:
+    args = live_radio_args("http://x/m.m3u8", ffmpeg_path="ffmpeg", bitrate_kbps=256)
+    assert args[args.index("-i") + 1] == "http://x/m.m3u8"
+    assert "libmp3lame" in args and "256k" in args
+    assert args[-1] == "-"
diff --git a/tests/shim/test_rest_endpoints.py b/tests/shim/test_rest_endpoints.py
new file mode 100644
index 0000000..deb0393
--- /dev/null
+++ b/tests/shim/test_rest_endpoints.py
@@ -0,0 +1,173 @@
+"""Endpoint tests for search3, getCoverArt, and stream with a fake Hum client."""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim.models import HumAudioFormat, HumSearchHit, HumVideoDetails
+
+_YTID = "dQw4w9WgXcQ"
+
+
+class FakeHumClient:
+    def __init__(self, hits: list[HumSearchHit], details: HumVideoDetails | None = None) -> None:
+        self._hits = hits
+        self._details = details
+
+    async def search(self, q: str, limit: int) -> list[HumSearchHit]:
+        return self._hits[:limit]
+
+    async def video_details(self, video_id: str) -> HumVideoDetails:
+        assert self._details is not None
+        return self._details
+
+    async def fetch_art(
+        self, kind: str, value: str, size: int | None = None
+    ) -> tuple[bytes, str]:
+        return b"jpeg-bytes", "image/jpeg"
+
+    def absolute(self, signed_path: str) -> str:
+        return f"http://hum.local{signed_path}"
+
+
+def _vod(ytid: str, title: str, duration: int) -> HumSearchHit:
+    return HumSearchHit(
+        kind="video",
+        id=ytid,
+        title=title,
+        author="Some Channel",
+        thumbnail_url="https://i.ytimg.com/vi/x/hq.jpg",
+        duration_seconds=duration,
+        is_live=None,
+    )
+
+
+class _Installer:
+    """Install a FakeHumClient as the module singleton for one test."""
+
+    def __init__(self, monkeypatch: pytest.MonkeyPatch, fake: FakeHumClient) -> None:
+        from shim import hum_client
+
+        monkeypatch.setattr(hum_client, "get_client", lambda: fake)
+
+
+def test_search3_maps_and_filters(
+    shim_client: TestClient,
+    subsonic_auth: dict[str, str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    hits = [
+        _vod(_YTID, "A Song", 215),
+        HumSearchHit(kind="video", id="live4567890", title="Live!", is_live=True),
+        HumSearchHit(kind="video", id="nodur456789", title="Ambiguous"),  # no duration → live
+        HumSearchHit(kind="channel", id="UCabcdef", title="A Channel"),
+    ]
+    _Installer(monkeypatch, FakeHumClient(hits))
+
+    r = shim_client.get("/rest/search3", params={**subsonic_auth, "query": "a song"})
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok"
+    songs = body["searchResult3"]["song"]
+    assert len(songs) == 1
+    song = songs[0]
+    assert song["id"] == f"vid:{_YTID}"
+    assert song["title"] == "A Song"
+    assert song["album"] == "A Song"  # single-track album model
+    assert song["artist"] == "Some Channel"
+    assert song["coverArt"] == f"vid:{_YTID}"
+    assert song["duration"] == 215
+    assert body["searchResult3"]["artist"] == []
+    assert body["searchResult3"]["album"] == []
+
+
+def test_search3_requires_query(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/search3", params=subsonic_auth)
+    assert r.status_code == 200  # protocol error, not HTTP error
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 10
+
+
+def test_cover_art_returns_bytes(
+    shim_client: TestClient,
+    subsonic_auth: dict[str, str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _Installer(monkeypatch, FakeHumClient([]))
+    r = shim_client.get(
+        "/rest/getCoverArt", params={**subsonic_auth, "id": f"vid:{_YTID}"}
+    )
+    assert r.status_code == 200
+    assert r.content == b"jpeg-bytes"
+    assert r.headers["content-type"] == "image/jpeg"
+
+
+def test_cover_art_rejects_malformed_id(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/getCoverArt", params={**subsonic_auth, "id": "vid:nope"})
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 70
+
+
+def test_stream_remuxes_aac(
+    shim_client: TestClient,
+    subsonic_auth: dict[str, str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    details = HumVideoDetails(
+        video_id=_YTID,
+        title="A Song",
+        author="Some Channel",
+        duration_seconds=215,
+        audio_formats=[
+            HumAudioFormat(
+                itag=140,
+                mime_type="audio/mp4",
+                bitrate=130000,
+                codec="aac",
+                url=f"/proxy/audio/{_YTID}?itag=140&exp=99999999999&sig=ab",
+            ),
+            HumAudioFormat(
+                itag=251,
+                mime_type="audio/webm",
+                bitrate=160000,
+                codec="opus",
+                url=f"/proxy/audio/{_YTID}?itag=251&exp=99999999999&sig=cd",
+            ),
+        ],
+    )
+    _Installer(monkeypatch, FakeHumClient([], details))
+
+    captured: dict[str, list[str]] = {}
+
+    async def fake_stream(args: list[str]) -> AsyncIterator[bytes]:
+        captured["args"] = args
+        yield b"fmp4-bytes"
+
+    from shim import transcode
+
+    monkeypatch.setattr(transcode, "stream_ffmpeg", fake_stream)
+
+    r = shim_client.get("/rest/stream", params={**subsonic_auth, "id": f"vid:{_YTID}"})
+    assert r.status_code == 200
+    assert r.headers["content-type"] == "audio/mp4"
+    assert r.content == b"fmp4-bytes"
+    # AAC preferred over the higher-bitrate Opus; remux args, not re-encode.
+    assert "itag=140" in captured["args"][captured["args"].index("-i") + 1]
+    assert "copy" in captured["args"]
+    assert "libmp3lame" not in captured["args"]
+
+
+def test_stream_rejects_playlist_id(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/stream", params={**subsonic_auth, "id": "pl:PLabc123"})
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 70
diff --git a/tests/shim/test_rest_envelope.py b/tests/shim/test_rest_envelope.py
new file mode 100644
index 0000000..013e9e2
--- /dev/null
+++ b/tests/shim/test_rest_envelope.py
@@ -0,0 +1,59 @@
+"""Phase 0/1 exit tests: envelope correctness for ping/getLicense and auth.
+
+Subsonic errors travel inside HTTP 200 envelopes — these tests pin that down.
+"""
+from __future__ import annotations
+
+from fastapi.testclient import TestClient
+
+
+def test_ping_ok_envelope(shim_client: TestClient, subsonic_auth: dict[str, str]) -> None:
+    r = shim_client.get("/rest/ping", params=subsonic_auth)
+    assert r.status_code == 200
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok"
+    assert body["version"] == "1.16.1"
+    assert body["type"] == "hum-subsonic-shim"
+
+
+def test_ping_view_suffix(shim_client: TestClient, subsonic_auth: dict[str, str]) -> None:
+    r = shim_client.get("/rest/ping.view", params=subsonic_auth)
+    assert r.status_code == 200
+    assert r.json()["subsonic-response"]["status"] == "ok"
+
+
+def test_ping_wrong_token_fails_in_envelope(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/ping", params={**subsonic_auth, "t": "0" * 32})
+    assert r.status_code == 200  # protocol errors are not HTTP errors
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 40
+
+
+def test_ping_missing_user(shim_client: TestClient) -> None:
+    r = shim_client.get("/rest/ping", params={"f": "json"})
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "failed"
+    assert body["error"]["code"] == 10
+
+
+def test_get_license(shim_client: TestClient, subsonic_auth: dict[str, str]) -> None:
+    r = shim_client.get("/rest/getLicense", params=subsonic_auth)
+    body = r.json()["subsonic-response"]
+    assert body["status"] == "ok"
+    assert body["license"]["valid"] is True
+
+
+def test_health_is_unauthenticated(shim_client: TestClient) -> None:
+    r = shim_client.get("/health")
+    assert r.status_code == 200
+    assert r.json() == {"status": "healthy"}
+
+
+def test_root_is_not_404(shim_client: TestClient) -> None:
+    # Amperfy's Auto-Detect probes GET / before /rest/; a 404 aborts it.
+    r = shim_client.get("/")
+    assert r.status_code == 200
+    assert r.json()["api"] == "/rest"
diff --git a/tests/shim/test_shim_config.py b/tests/shim/test_shim_config.py
new file mode 100644
index 0000000..5d9b88c
--- /dev/null
+++ b/tests/shim/test_shim_config.py
@@ -0,0 +1,59 @@
+"""Tests for ShimSettings loading: env_file anchoring, token fallback, friendly failure."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from shim.config import ShimSettings, get_settings
+
+_PASSWORD = "correct-horse-battery"
+
+
+@pytest.fixture(autouse=True)
+def isolate_dotenv(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """Point the settings at a non-existent .env so these tests never read a
+    developer's real repo-root .env. env vars (monkeypatch.setenv) still apply."""
+    monkeypatch.setitem(
+        ShimSettings.model_config, "env_file", str(tmp_path / "nonexistent.env")
+    )
+
+
+def test_env_file_is_absolute_and_cwd_independent() -> None:
+    # The footgun: a relative ".env" resolves against cwd, so launching from a
+    # subdir loses settings. The configured path must be absolute.
+    configured = ShimSettings.model_config["env_file"]
+    assert configured is not None
+    assert Path(str(configured)).is_absolute()
+
+
+def test_bearer_token_falls_back_to_hum_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("SHIM_HUM_BEARER_TOKEN", raising=False)
+    monkeypatch.setenv("API_BEARER_TOKEN", "shared-hum-token-123")
+    s = ShimSettings(subsonic_password=_PASSWORD)
+    assert s.hum_bearer_token == "shared-hum-token-123"
+
+
+def test_explicit_shim_token_wins_over_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SHIM_HUM_BEARER_TOKEN", "shim-specific-token-1")
+    monkeypatch.setenv("API_BEARER_TOKEN", "shared-hum-token-123")
+    s = ShimSettings(subsonic_password=_PASSWORD)
+    assert s.hum_bearer_token == "shim-specific-token-1"
+
+
+def test_missing_required_settings_exit_cleanly(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("SHIM_SUBSONIC_PASSWORD", raising=False)
+    monkeypatch.delenv("SHIM_HUM_BEARER_TOKEN", raising=False)
+    monkeypatch.delenv("API_BEARER_TOKEN", raising=False)
+    get_settings.cache_clear()
+    try:
+        with pytest.raises(SystemExit) as exc:
+            get_settings()
+        message = str(exc.value)
+        assert "SHIM_SUBSONIC_PASSWORD" in message
+        assert "SHIM_HUM_BEARER_TOKEN" in message
+        assert ".env.example" in message
+        # No secret values echoed, unlike the raw pydantic ValidationError.
+        assert "input_value" not in message
+    finally:
+        get_settings.cache_clear()
diff --git a/tests/shim/test_store.py b/tests/shim/test_store.py
new file mode 100644
index 0000000..f487c67
--- /dev/null
+++ b/tests/shim/test_store.py
@@ -0,0 +1,56 @@
+"""Unit tests for the favourites store and the recently-seen metadata cache."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from shim import store
+from shim.store import FavouritesStore, StarredItem
+
+
+def test_star_unstar_roundtrip(tmp_path: Path) -> None:
+    s = FavouritesStore(tmp_path / "fav.json")
+    item = StarredItem(id="vid:abc", kind="song", title="T", artist="A")
+    s.star(item)
+    assert s.is_starred("vid:abc")
+    assert s.starred() == [item]
+    s.unstar("vid:abc")
+    assert not s.is_starred("vid:abc")
+    assert s.starred() == []
+
+
+def test_persists_across_instances(tmp_path: Path) -> None:
+    path = tmp_path / "fav.json"
+    FavouritesStore(path).star(StarredItem(id="pl:x", kind="album", title="Mix", artist="C"))
+    reloaded = FavouritesStore(path)
+    assert reloaded.is_starred("pl:x")
+    assert reloaded.starred()[0].title == "Mix"
+
+
+def test_creates_missing_parent_dir(tmp_path: Path) -> None:
+    nested = tmp_path / "deep" / "dir" / "fav.json"
+    FavouritesStore(nested).star(StarredItem(id="vid:y", kind="song", title="t", artist="a"))
+    assert nested.exists()
+
+
+def test_corrupt_file_is_ignored(tmp_path: Path) -> None:
+    path = tmp_path / "fav.json"
+    path.write_text("{not json")
+    s = FavouritesStore(path)  # must not raise
+    assert s.starred() == []
+
+
+def test_seen_cache_remember_recall() -> None:
+    store.reset_store()
+    store.remember("vid:abc", "song", "Title", "Artist")
+    assert store.recall("vid:abc") == ("song", "Title", "Artist")
+    assert store.recall("vid:missing") is None
+
+
+def test_seen_cache_is_bounded() -> None:
+    store.reset_store()
+    for i in range(store._SEEN_MAX + 50):
+        store.remember(f"vid:{i:011d}", "song", "t", "a")
+    assert len(store._seen) == store._SEEN_MAX
+    # Oldest evicted, newest retained.
+    assert store.recall("vid:00000000000") is None
+    assert store.recall(f"vid:{store._SEEN_MAX + 49:011d}") is not None
diff --git a/tests/shim/test_stream_seekable.py b/tests/shim/test_stream_seekable.py
new file mode 100644
index 0000000..83e7b95
--- /dev/null
+++ b/tests/shim/test_stream_seekable.py
@@ -0,0 +1,100 @@
+"""Seekable remux (spec §4 mode b): stream served from a cached file with Range."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim import hum_client, mediacache, transcode
+from shim.config import get_settings
+from shim.mediacache import MediaCache
+from shim.models import HumAudioFormat, HumVideoDetails
+
+_YTID = "dQw4w9WgXcQ"
+_BODY = b"FMP4-MATERIALIZED-BYTES"
+
+
+class _FakeClient:
+    def __init__(self, details: HumVideoDetails) -> None:
+        self._details = details
+
+    async def video_details(self, video_id: str) -> HumVideoDetails:
+        return self._details
+
+    def absolute(self, signed_path: str) -> str:
+        return f"http://hum.local{signed_path}"
+
+
+@pytest.fixture
+def seekable_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    details = HumVideoDetails(
+        video_id=_YTID,
+        title="A Song",
+        author="Chan",
+        duration_seconds=200,
+        audio_formats=[
+            HumAudioFormat(
+                itag=140, mime_type="audio/mp4", bitrate=130000, codec="aac",
+                url=f"/proxy/audio/{_YTID}?itag=140&exp=99999999999&sig=ab",
+            )
+        ],
+    )
+    monkeypatch.setattr(hum_client, "get_client", lambda: _FakeClient(details))
+    monkeypatch.setattr(get_settings(), "seekable_remux", True)
+    # Real MediaCache in a temp dir; fake the ffmpeg materialize to write bytes.
+    cache = MediaCache(tmp_path, max_bytes=10 * 1024 * 1024)
+    monkeypatch.setattr(mediacache, "get_cache", lambda: cache)
+
+    async def fake_materialize(args: list[str]) -> bool:
+        dest = Path(args[-1])  # remux_file_args ends with the dest path
+        dest.write_bytes(_BODY)
+        return True
+
+    monkeypatch.setattr(transcode, "materialize", fake_materialize)
+
+
+def test_seekable_stream_serves_full_body(
+    shim_client: TestClient, subsonic_auth: dict[str, str], seekable_env: None
+) -> None:
+    r = shim_client.get("/rest/stream", params={**subsonic_auth, "id": f"vid:{_YTID}"})
+    assert r.status_code == 200
+    assert r.content == _BODY
+    assert r.headers["content-type"] == "audio/mp4"
+    # FileResponse advertises range support — that's what gives Sonos a seek bar.
+    assert r.headers.get("accept-ranges") == "bytes"
+    assert r.headers["content-length"] == str(len(_BODY))
+
+
+def test_seekable_stream_honors_range(
+    shim_client: TestClient, subsonic_auth: dict[str, str], seekable_env: None
+) -> None:
+    r = shim_client.get(
+        "/rest/stream",
+        params={**subsonic_auth, "id": f"vid:{_YTID}"},
+        headers={"Range": "bytes=0-3"},
+    )
+    assert r.status_code == 206
+    assert r.content == _BODY[:4]
+    assert r.headers["content-range"] == f"bytes 0-3/{len(_BODY)}"
+
+
+def test_materialize_failure_falls_back_to_pipe(
+    shim_client: TestClient,
+    subsonic_auth: dict[str, str],
+    seekable_env: None,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # If materialization fails, stream must still work via the pipe (mode a).
+    async def fail_materialize(args: list[str]) -> bool:
+        return False
+
+    monkeypatch.setattr(transcode, "materialize", fail_materialize)
+
+    async def fake_pipe(args: list[str]):
+        yield b"PIPED"
+
+    monkeypatch.setattr(transcode, "stream_ffmpeg", fake_pipe)
+    r = shim_client.get("/rest/stream", params={**subsonic_auth, "id": f"vid:{_YTID}"})
+    assert r.status_code == 200
+    assert r.content == b"PIPED"
diff --git a/tests/shim/test_subsonic_auth.py b/tests/shim/test_subsonic_auth.py
new file mode 100644
index 0000000..1e2f0e8
--- /dev/null
+++ b/tests/shim/test_subsonic_auth.py
@@ -0,0 +1,78 @@
+"""Unit tests for the Subsonic credential check (token auth + dev fallback)."""
+from __future__ import annotations
+
+import hashlib
+
+import pytest
+
+from shim.auth import check_credentials
+from shim.config import ShimSettings
+from shim.subsonic import MISSING_PARAMETER, WRONG_CREDENTIALS, SubsonicError
+
+_PASSWORD = "correct-horse-battery"
+
+
+def make_settings(**overrides: object) -> ShimSettings:
+    kwargs: dict[str, object] = {
+        "hum_bearer_token": "x" * 16,
+        "subsonic_user": "tester",
+        "subsonic_password": _PASSWORD,
+    }
+    kwargs.update(overrides)
+    # _env_file=None: ignore the repo .env so these unit tests are hermetic
+    # (e.g. a dev's SHIM_ALLOW_PLAIN_PASSWORD=true must not leak into them).
+    return ShimSettings(_env_file=None, **kwargs)  # type: ignore[arg-type]
+
+
+def token_for(salt: str) -> str:
+    return hashlib.md5((_PASSWORD + salt).encode(), usedforsecurity=False).hexdigest()
+
+
+def test_valid_token_auth_passes() -> None:
+    check_credentials(make_settings(), "tester", None, token_for("s4lt"), "s4lt")
+
+
+def test_uppercase_token_accepted() -> None:
+    check_credentials(make_settings(), "tester", None, token_for("s4lt").upper(), "s4lt")
+
+
+def test_wrong_token_rejected() -> None:
+    with pytest.raises(SubsonicError) as exc:
+        check_credentials(make_settings(), "tester", None, "0" * 32, "s4lt")
+    assert exc.value.code == WRONG_CREDENTIALS
+
+
+def test_wrong_user_rejected() -> None:
+    with pytest.raises(SubsonicError) as exc:
+        check_credentials(make_settings(), "intruder", None, token_for("s4lt"), "s4lt")
+    assert exc.value.code == WRONG_CREDENTIALS
+
+
+def test_missing_user_is_missing_parameter() -> None:
+    with pytest.raises(SubsonicError) as exc:
+        check_credentials(make_settings(), None, None, token_for("s4lt"), "s4lt")
+    assert exc.value.code == MISSING_PARAMETER
+
+
+def test_plain_password_rejected_by_default() -> None:
+    with pytest.raises(SubsonicError) as exc:
+        check_credentials(make_settings(), "tester", _PASSWORD, None, None)
+    assert exc.value.code == MISSING_PARAMETER  # told to use token auth
+
+
+def test_plain_password_accepted_in_dev_mode() -> None:
+    settings = make_settings(allow_plain_password=True)
+    check_credentials(settings, "tester", _PASSWORD, None, None)
+
+
+def test_enc_hex_password_accepted_in_dev_mode() -> None:
+    settings = make_settings(allow_plain_password=True)
+    enc = "enc:" + _PASSWORD.encode().hex()
+    check_credentials(settings, "tester", enc, None, None)
+
+
+def test_wrong_plain_password_rejected_in_dev_mode() -> None:
+    settings = make_settings(allow_plain_password=True)
+    with pytest.raises(SubsonicError) as exc:
+        check_credentials(settings, "tester", "not-the-password", None, None)
+    assert exc.value.code == WRONG_CREDENTIALS
diff --git a/tests/shim/test_transcode.py b/tests/shim/test_transcode.py
new file mode 100644
index 0000000..5c51966
--- /dev/null
+++ b/tests/shim/test_transcode.py
@@ -0,0 +1,140 @@
+"""Unit tests for format selection, ffmpeg args, and pipe lifecycle."""
+from __future__ import annotations
+
+import asyncio
+import logging
+
+import pytest
+
+from shim import transcode
+from shim.models import HumAudioFormat
+from shim.subsonic import SubsonicError
+from shim.transcode import ffmpeg_args, media_type_for, pick_audio_format, stream_ffmpeg
+
+
+def _fmt(codec: str, bitrate: int, itag: int = 1) -> HumAudioFormat:
+    return HumAudioFormat(
+        itag=itag, mime_type=f"audio/{codec}", bitrate=bitrate, codec=codec, url="/x"
+    )
+
+
+def test_prefers_aac_even_at_lower_bitrate() -> None:
+    fmt, mode = pick_audio_format([_fmt("opus", 160000), _fmt("aac", 128000)])
+    assert fmt.codec == "aac"
+    assert mode == "remux"
+
+
+def test_picks_highest_bitrate_aac() -> None:
+    fmt, _ = pick_audio_format([_fmt("aac", 48000, itag=139), _fmt("aac", 128000, itag=140)])
+    assert fmt.itag == 140
+
+
+def test_falls_back_to_mp3_without_aac() -> None:
+    fmt, mode = pick_audio_format([_fmt("opus", 70000), _fmt("opus", 160000)])
+    assert fmt.bitrate == 160000
+    assert mode == "mp3"
+
+
+def test_no_formats_raises() -> None:
+    with pytest.raises(SubsonicError):
+        pick_audio_format([])
+
+
+def test_remux_args_are_copy_to_fmp4() -> None:
+    args = ffmpeg_args("http://x/a", "remux", ffmpeg_path="ffmpeg", mp3_bitrate_kbps=256)
+    assert args[0] == "ffmpeg"
+    assert ["-c:a", "copy"] == args[args.index("-c:a") : args.index("-c:a") + 2]
+    assert ["-f", "mp4"] == args[args.index("-f") : args.index("-f") + 2]
+    assert "frag_keyframe+empty_moov" in args
+    assert args[-1] == "-"
+
+
+def test_mp3_args_re_encode() -> None:
+    args = ffmpeg_args("http://x/a", "mp3", ffmpeg_path="ffmpeg", mp3_bitrate_kbps=256)
+    assert "libmp3lame" in args
+    assert "256k" in args
+    assert args[-1] == "-"
+
+
+def test_media_types() -> None:
+    assert media_type_for("remux") == "audio/mp4"
+    assert media_type_for("mp3") == "audio/mpeg"
+
+
+# ----- ffmpeg pipe lifecycle (spec §4 hardening) ----------------------------
+
+
+class _FakeReader:
+    def __init__(self, chunks: list[bytes]) -> None:
+        self._chunks = list(chunks)
+
+    async def read(self, n: int = -1) -> bytes:
+        if n == -1:  # stderr drain: return everything at once
+            data = b"".join(self._chunks)
+            self._chunks = []
+            return data
+        return self._chunks.pop(0) if self._chunks else b""
+
+
+class _FakeProc:
+    def __init__(
+        self,
+        stdout: list[bytes],
+        returncode: int,
+        stderr: bytes = b"",
+        running: bool = False,
+    ) -> None:
+        self.stdout = _FakeReader(stdout)
+        self.stderr = _FakeReader([stderr] if stderr else [])
+        self._final = returncode
+        self._running = running  # still executing when reaped (disconnect case)
+        self.returncode: int | None = None
+        self.killed = False
+
+    def kill(self) -> None:
+        self.killed = True
+
+    async def wait(self) -> int:
+        # Killing a still-running process yields -9 (SIGKILL); killing an
+        # already-exited one is a no-op and wait() returns its real code.
+        self.returncode = -9 if (self._running and self.killed) else self._final
+        return self.returncode
+
+
+def _patch_proc(monkeypatch: pytest.MonkeyPatch, proc: _FakeProc) -> None:
+    async def fake_exec(*args: object, **kwargs: object) -> _FakeProc:
+        return proc
+
+    monkeypatch.setattr(asyncio, "create_subprocess_exec", fake_exec)
+
+
+async def test_stream_yields_all_chunks(monkeypatch: pytest.MonkeyPatch) -> None:
+    _patch_proc(monkeypatch, _FakeProc([b"frag1", b"frag2"], returncode=0))
+    out = b"".join([chunk async for chunk in stream_ffmpeg(["ffmpeg"])])
+    assert out == b"frag1frag2"
+
+
+async def test_nonzero_exit_logs_stderr(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    _patch_proc(monkeypatch, _FakeProc([], returncode=1, stderr=b"boom: bad input"))
+    with caplog.at_level(logging.WARNING, logger="shim.transcode"):
+        out = b"".join([chunk async for chunk in stream_ffmpeg(["ffmpeg"])])
+    assert out == b""
+    messages = [r.getMessage() for r in caplog.records]
+    assert any("boom: bad input" in m and "1" in m for m in messages)
+
+
+async def test_client_disconnect_kills_without_warning(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    proc = _FakeProc([b"a", b"b", b"c"], returncode=1, running=True)
+    _patch_proc(monkeypatch, proc)
+    agen = stream_ffmpeg(["ffmpeg"])
+    first = await agen.__anext__()
+    assert first == b"a"
+    with caplog.at_level(logging.WARNING, logger="shim.transcode"):
+        await agen.aclose()  # client went away
+    assert proc.killed is True
+    # Killed-by-us is not a transcode failure, so no warning is emitted.
+    assert not [r for r in caplog.records if r.levelno >= logging.WARNING]
diff --git a/tests/shim/test_xml.py b/tests/shim/test_xml.py
new file mode 100644
index 0000000..9eb7099
--- /dev/null
+++ b/tests/shim/test_xml.py
@@ -0,0 +1,78 @@
+"""XML response format (Subsonic default; Amperfy omits f=json and expects XML)."""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+import pytest
+from fastapi.testclient import TestClient
+
+from shim.models import HumSearchHit
+from shim.subsonic import SUBSONIC_XMLNS
+
+_NS = {"s": SUBSONIC_XMLNS}
+
+
+def _auth_no_format(subsonic_auth: dict[str, str]) -> dict[str, str]:
+    # Drop f=json so the request takes the XML default, like Amperfy.
+    return {k: v for k, v in subsonic_auth.items() if k != "f"}
+
+
+def test_ping_defaults_to_xml(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/ping.view", params=_auth_no_format(subsonic_auth))
+    assert r.status_code == 200
+    assert r.headers["content-type"].startswith("text/xml")
+    root = ET.fromstring(r.text)
+    assert root.tag == f"{{{SUBSONIC_XMLNS}}}subsonic-response"
+    assert root.attrib["status"] == "ok"
+    assert root.attrib["version"] == "1.16.1"
+
+
+def test_explicit_json_still_works(
+    shim_client: TestClient, subsonic_auth: dict[str, str]
+) -> None:
+    r = shim_client.get("/rest/ping.view", params={**subsonic_auth, "f": "json"})
+    assert r.headers["content-type"].startswith("application/json")
+    assert r.json()["subsonic-response"]["status"] == "ok"
+
+
+def test_search3_xml_has_song_elements(
+    shim_client: TestClient, subsonic_auth: dict[str, str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    hits = [
+        HumSearchHit(
+            kind="video", id="dQw4w9WgXcQ", title="A Song", author="Chan",
+            thumbnail_url="https://i/x.jpg", duration_seconds=215,
+        )
+    ]
+
+    class _Fake:
+        async def search(self, q: str, limit: int) -> list[HumSearchHit]:
+            return hits
+
+    from shim import hum_client
+
+    monkeypatch.setattr(hum_client, "get_client", lambda: _Fake())
+    r = shim_client.get(
+        "/rest/search3", params={**_auth_no_format(subsonic_auth), "query": "x"}
+    )
+    root = ET.fromstring(r.text)
+    songs = root.findall(".//s:searchResult3/s:song", _NS)
+    assert len(songs) == 1
+    assert songs[0].attrib["id"] == "vid:dQw4w9WgXcQ"
+    assert songs[0].attrib["title"] == "A Song"
+    assert songs[0].attrib["duration"] == "215"
+    # Booleans render as true/false, not Python's True/False.
+    assert songs[0].attrib["isDir"] == "false"
+
+
+def test_error_renders_as_xml(shim_client: TestClient) -> None:
+    # No credentials, XML default → a failed envelope with <error> as XML.
+    r = shim_client.get("/rest/ping.view")
+    assert r.headers["content-type"].startswith("text/xml")
+    root = ET.fromstring(r.text)
+    assert root.attrib["status"] == "failed"
+    err = root.find("s:error", _NS)
+    assert err is not None
+    assert err.attrib["code"] == "10"
diff --git a/tests/unit/test_cli.py b/tests/unit/test_cli.py
new file mode 100644
index 0000000..41a0b89
--- /dev/null
+++ b/tests/unit/test_cli.py
@@ -0,0 +1,18 @@
+"""The `hum` console script takes no subcommands; `hum shim` is a common slip
+(the shim's entry point is `hum-shim`). Guard with a helpful message."""
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+
+def test_hum_main_rejects_stray_args(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(sys, "argv", ["hum", "shim"])
+    from app.main import main
+
+    with pytest.raises(SystemExit) as exc:
+        main()
+    # Exits before touching settings/uvicorn, and points at the real command.
+    assert "hum-shim" in str(exc.value)
+    assert "shim" in str(exc.value)