Phase 1.e — HTTP range streaming + browser player

[InstaZDLL]

Tracking issue for sub-phase 1.e of RFC-001.

Wire end-to-end audio playback from the server to the web browser: HTTP range requests on flat files, on-demand FFmpeg transcode with LRU cache, Web Audio API player with gapless support.

Scope — waveflow-server

• GET /stream/:track_id?format=auto with Accept + Range header handling.
• Server logic per RFC §6.7:
  1. Resolve track_id → file path.
  2. Probe file format via lofty (cached).
  3. If client Accept includes the file's native format → stream raw with Range.
  4. Else → spawn FFmpeg subprocess, transcode to FLAC (lossless) or Opus 192k (lossy), cache result keyed by (track_id, target_format).
  5. Cache: LRU, configurable cap (default 5 GB), evicted to disk under $CACHE_DIR/transcode/.
• DSD source files: always transcoded to FLAC 24/96 via the waveflow-core DSD→PCM converter.
• Range responses: 206 Partial Content with correct Content-Range + Accept-Ranges: bytes + Content-Length.

Scope — waveflow-web

• Browser player component using Web Audio API.
• Gapless via two <audio> elements (preload next track, swap on ended).
• Play/pause/seek/volume controls.
• Track display: title, artist, album, cover.
• Queue panel (basic).

Out of scope (future sub-phases / Phase 2)

• HLS / DASH (not needed for music file sizes).
• EQ in browser.
• Playlist management UI (basic CRUD only).

Acceptance criteria

• Native FLAC file streams to Firefox + Chromium browsers with seek working.
• MP3 source → MP3 stream when client accepts audio/mpeg.
• FLAC source on a browser without FLAC support → Opus 192k transcode, cached.
• Second request for the same (track_id, format) is served from cache.
• Cache eviction works under fill (default 5 GB cap respected).
• DSF source → FLAC 24/96 transcode plays correctly.
• Gapless playback verified on a continuous-mix album (no audible click between tracks).

Dependencies

• Blocks on: 1.d (auth wired) so streaming endpoint requires a valid JWT.

Estimate

~3 weeks.