Skip to content

Changelog

The canonical changelog lives in CHANGELOG.md at the repo root. Below is a copy of the most recent versions.

[0.3.1] — 2026-05-21

Documentation-only re-release of v0.3.0 with corrected README and CHANGELOG framing. Runtime is identical to v0.3.0.

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

v0.3.0 adds browser inference via onnxruntime-web, two new model flavors (htdemucs and htdemucs_6s), a published documentation site, and a session-pooling fix that eliminates CoreML graph re-compilation across repeated separate() calls.

Added

  • 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").
  • 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 copy-pasteable onnxruntime-web config snippets, and 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.
  • examples/browser/ and examples/browser-react/ in the GitHub repo with full working demos.
  • 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).
  • Docs site at stemsplit.github.io/demucs-onnx with autogenerated API reference via mkdocstrings[python], the canonical 4-blocker write-up, browser guide, model registry, and honest comparison vs spleeter / cloud APIs.

Changed

  • list_models() includes kind and sources — each entry now reports whether it's a specialist_bag, single, or specialist model and the comma-joined stem list. CLI list-models updated.
  • separate_stem(..., "guitar") and separate_stem(..., "piano") auto-route to htdemucs_6s instead of erroring on unknown stem.
  • CLI --stem accepts guitar and piano (auto-routes).
  • Quiet huggingface_hub HTTP logs in non-verbose mode and disable hf-hub progress bars when --quiet.

Fixed

  • Specialist bag re-compilation on every call — separate() now uses a process-wide SessionPool so repeated calls reuse the loaded InferenceSession, fixing the multi-minute CoreML graph-compile tax on the second-through-Nth call to separate(model="htdemucs_ft").

Polish

  • [project.urls] adds Documentation = "https://stemsplit.github.io/demucs-onnx/".

[0.2.0] — 2026-05-21 — the UX bundle

Backwards-compatible UX overhaul. Four headline features, all opt-in or default-on:

  • providers="auto" (now default) picks CoreML on macOS arm64, CUDA on Linux+NVIDIA, DML on Windows DX12, CPU otherwise.
  • precision="fp16weights" / --small downloads ~1.9× smaller model files with no runtime cost.
  • --mp3 output with --bitrate {32-320}k via the lameenc extra (no ffmpeg required).
  • --mix-stems / --karaoke write a single summed-stem file alongside the individual stems.
  • tqdm progress bar; --quiet / --verbose flags.
  • Auto-resample any sample rate (8 kHz – 192 kHz, mono or multi-channel).

See the full changelog in CHANGELOG.md.

[0.1.0] — 2026-05-21 — initial release

  • Pure numpy + onnxruntime inference path for htdemucs_ft at fp32 parity to the original PyTorch model (max abs diff < 1.71 × 10⁻⁴).
  • export_to_onnx(checkpoint, output) applies the four blocker patches and parity-checks before writing.
  • Five companion model repos under StemSplitio on the Hugging Face Hub.
  • CLI: demucs-onnx separate, demucs-onnx export, demucs-onnx list-models.