v0.3.0 — browser, htdemucs/htdemucs_6s, docs site

[0.3.0] - 2026-05-21 — Browser support, more models, docs site

This release adds browser inference via onnxruntime-web, two new
model flavors (htdemucs and htdemucs_6s), a published documentation
site, and a session-pooling fix for repeated calls. Highlights:

Added

• New htdemucs flavor — single-file 4-stem ONNX model. ~30%
  faster than the FT bag (1 session instead of 4), slightly lower SDR.
  New HF repo:
  StemSplitio/htdemucs-onnx.
  Use via separate(model="htdemucs").
• New htdemucs_6s flavor — single-file 6-stem ONNX model with
  guitar and piano in addition to the standard 4 stems. The
  only ONNX export of the 6-stem variant on the Hub. New HF repo:
  StemSplitio/htdemucs-6s-onnx.
  Use via separate(model="htdemucs_6s") or
  separate_stem("song.mp3", "guitar").
• demucs_onnx.browser module + CLI commands —
  demucs-onnx browser-config --bundler {vite|webpack|esbuild|next|rollup}
  prints a ready-to-paste onnxruntime-web config snippet for each
  major bundler. demucs-onnx browser-demo PATH [--react]
  scaffolds the in-tree vanilla-HTML or Vite + React + TS demo into a
  directory so users can run python -m http.server and try it
  locally without cloning anything.
• examples/browser/ — zero-build vanilla HTML/JS demo that loads
  the 166 MB fp16weights vocals model from HF and separates a WAV via
  FileReader. Chunked overlap-add ported from the Python infer.py.
• examples/browser-react/ — minimal Vite + React + TS demo with
  the same flow, prettier UI, multi-thread WASM via COOP/COEP.
• prewarm(models=[...]) — pre-download and pre-compile ORT
  sessions so the first separate() call doesn't pay the CoreML
  graph-compile or HF-download tax. New demucs-onnx prewarm CLI too.
• SessionPool + session_pool() — process-wide session cache so
  repeated separate* calls reuse compiled graphs. Especially
  valuable for CoreML EP (the first htdemucs_ft bag call previously
  triggered 4 separate CoreML graph compilations).
• Docs site at
  stemsplit.github.io/demucs-onnx
  built with MkDocs Material + mkdocstrings[python]. Pages:
  Install, CLI, Python API (autogenerated), Browser support, Models,
  Export your own, Comparison, Changelog. Deploys from
  .github/workflows/docs.yml on push to main.
• ALL_KNOWN_STEMS — re-exported as a top-level constant
  (drums, bass, other, vocals, guitar, piano).

Changed

• list_models() shape — each entry now also carries kind
  ("specialist_bag" / "single" / "specialist") and
  sources (comma-joined stem list). CLI list-models output
  updated to a five-column table.
• separate_stem(..., "guitar") and separate_stem(..., "piano")
  auto-route to htdemucs_6s instead of erroring out.
• CLI --stem accepts guitar / piano (auto-routes).
• Quiet huggingface_hub HTTP logs in non-verbose mode and disable
  hf-hub progress bars when --quiet.
• [project.urls] adds Documentation = "https://stemsplit.github.io/demucs-onnx/" and a Changelog URL.

Fixed

• Specialist bag re-compilation on every call — separate() now
  reuses sessions from the process-wide pool, eliminating the
  multi-minute CoreML graph-compile tax on every call after the first
  when using model="htdemucs_ft" in a long-running process.

New model parity (vs PyTorch fp32, random 1×2×343980 input)

Model	max abs diff	tolerance
htdemucs.onnx	6.62 × 10⁻⁴	1 × 10⁻³
htdemucs_fp16weights.onnx	+ 4.6 × 10⁻⁵ (vs fp32 weights)	1 × 10⁻³
htdemucs_6s.onnx	2.42 × 10⁻⁴	1 × 10⁻³
htdemucs_6s_fp16weights.onnx	+ 1.06 × 10⁻⁴ (vs fp32 weights)	1 × 10⁻³