Add Sonos integration spec and document Hum API surface

[betmoar]

Summary

This PR adds comprehensive documentation for integrating Hum with Sonos via a Subsonic-compatible adapter (the "hum-subsonic-shim"), along with an updated API reference documenting Hum's full endpoint surface including live-stream and HLS support.

Changes

• New file: docs/SONOS_SPEC.md — A complete 405-line integration specification covering:

  • Architecture decision record (why a Subsonic shim + bonob bridge vs. native SMAPI)
  • Component inventory and deployment topology
  • Subsonic API surface to implement (must-have, browsing, optional endpoints)
  • Audio delivery strategy: AAC remux (Mode 1) with mp3 re-encode fallback (Mode 2)
  • URL signing, TTL management, and shim-side caching strategy
  • S1 vs S2 deployment considerations and hardening checklist
  • Seven-phase development trajectory with exit tests for each
  • Risk register and open decisions
  • Reference endpoints (in-scope and out-of-scope)

• Updated: README.md — Enhanced API documentation:

  • Added optional category=music and live=false filters to /api/search
  • Documented new endpoints: /api/radio, /api/hls/{id}.m3u8, /api/live/{id}/manifest.m3u8, /proxy/live-segment/{id}
  • Clarified that /api/video/{id} returns signed hls_url for AAC formats and live_stream_url for live videos
  • Added note about bearer-protected /api/debug/live/{id}/upstream for live-stream debugging
  • Updated proxy URL explanation to reflect AAC and live-stream handling

Notable Details

• The spec is audited against Hum codebase at c68470e (Hum 0.1.0), resolving discrepancies in the original draft
• Key audit findings: Hum exposes AAC (not just Opus), has live/radio surfaces (out of scope for Phase 1), and has zero persistence
• The remux-first strategy (AAC via ffmpeg -c copy) significantly reduces technical risk vs. the original mp3 re-encode plan
• Detailed latency budgeting accounts for Hum's 1-hour internal cache and 6-hour signed URL TTL
• Development trajectory is structured for incremental validation: Amperfy testing before Sonos involvement

[betmoar]

@copilot review spec

[Copilot]

@copilot review spec

Here's a cross-reference review of the spec against the codebase (c68470e). Overall it's accurate and well-structured. Four items worth addressing before Phase 1:

---

🔴 §9 (open decision #6) — Subsonic auth is underdetermined

The decision says "decide whether the shim validates or accepts" the credentials bonob sends. bonob's default is salted-MD5 token auth — it posts t (MD5 hash of password + s) + s (random salt), not plaintext p. The shim must implement the Subsonic token-auth hash check (MD5(password + salt)), not just "accept credentials." Treating this as optional will result in bonob's auth calls silently succeeding or failing depending on the shim's fallback behaviour. Recommend upgrading decision #6 to: "implement Subsonic token-auth (MD5 hash); plain p auth as fallback for Amperfy dev mode only."

---

🟡 §4 — Mode 1 container ordering should be inverted

ADTS (-f adts) is listed as the default, with fragmented MP4 (-f mp4 -movflags frag_keyframe+empty_moov) as a "second option before Mode 2." In practice ADTS is the riskier choice: it has no duration atom, no bitrate header, and Sonos speakers typically display no track-length or seek bar for ADTS streams. Fragmented MP4 (fMP4) preserves timing metadata and is what Hum's own HLS path produces (see app/api/hls.py — it wraps fMP4 byteranges). Recommend reversing the order: fMP4 first, ADTS as secondary experiment, mp3 as fallback.

---

🟡 §3.4 — _looks_live polarity not stated

The spec says "combine it with the duration heuristic already proven in app/api/radio.py:_looks_live" but radio.py uses _looks_live to keep hits (items = [h for h in raw if _looks_live(h)]). For search3, the shim must use the inverse — [h for h in results if not _looks_live(h)]. Worth making that explicit in the spec (or showing the actual filter expression) to prevent an off-by-one logic error.

---

🟡 §5 — Cache eviction formula is ambiguous

"Recommend ~30 min, always < remaining exp" doesn't define the eviction rule when exp is close. The correct logic is cache_ttl = min(1800, exp - now - safety_buffer) (e.g. 60 s safety margin). Without this, a cached entry whose signed URL expires in 5 minutes will still be served to ffmpeg, producing a 410 from Hum mid-stream. Recommend stating the eviction formula explicitly.

---

✅ Everything else checks out

• Video/playlist/channel ID constraints match the validators in models.py, playlist.py, channel.py.
• Proxy endpoints (/proxy/audio/) use HMAC signature auth, not ****** the ffmpeg -i <signed_proxy_url> invocation works without extra headers. The ****** is only needed for /api/* calls, which the shim makes server-side.
• The 1 h upstream URL cache and 6 h signed-URL TTL match app/adapters/youtube.py (_CACHE_MAX_TTL = 3600.0) and app/config.py (stream_url_ttl_seconds: int = 21600).
• _looks_live heuristic, body_iterator process-lifecycle pattern, and cover-art two-source strategy are all accurately described.