| --- |
| language: en |
| license: mit |
| library_name: demucs |
| pipeline_tag: audio-to-audio |
| tags: |
| - stem-separation |
| - source-separation |
| - vocal-isolation |
| - vocal-remover |
| - music |
| - demucs |
| - htdemucs |
| - karaoke |
| - audio-to-audio |
| datasets: |
| - StemSplitio/stem-separation-benchmark-2026 |
| inference: false |
| --- |
| |
| # HT-Demucs FT — Production-ready PyTorch model card |
|
|
| The **highest-vocal-SDR open-source stem separator on MUSDB18-HQ** (9.19 dB |
| median), packaged for Hugging Face Inference Endpoints with a ready-to-deploy |
| `handler.py`. Use it for vocal removal, karaoke generation, acapella |
| extraction, and any task that needs clean 4-stem separation of music |
| (`vocals`, `drums`, `bass`, `other`). |
|
|
| This is the `htdemucs_ft` 4-bag ensemble by [Défossez et al. (Meta AI)][demucs-repo], |
| repackaged with attribution. Original training and weights are unchanged; |
| we add the deployment handler, the model card, and the benchmark context. |
|
|
| > Need it as a REST API today, without standing up GPUs? Use the |
| > [**StemSplit API**](https://stemsplit.io/developers) — same model, hosted |
| > for you, with credits and a dashboard. |
|
|
| --- |
|
|
| ## Quality (independently benchmarked) |
|
|
| Median SDR per stem on the standard MUSDB18-HQ test split (50 songs), BSS |
| Eval v4 via `museval`. Higher is better. Source: |
| [StemSplitio/stem-separation-benchmark-2026](https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026) |
| v1.1. |
|
|
| | Model | vocals | drums | bass | other | |
| |---|---:|---:|---:|---:| |
| | `htdemucs_ft` *(this card)* | **9.19** | 10.11 | 10.38 | 6.34 | |
| | `mdx_extra_q` | 9.04 | **11.49** | **11.42** | **7.67** | |
| | `htdemucs_6s` | 8.66 | 9.54 | 9.11 | 5.74 | |
| | `htdemucs` | 8.53 | 10.01 | 9.78 | 6.42 | |
| | `mdx_net_inst_hq3` *(vocals-only)* | 5.81 | — | — | — | |
|
|
| **Pick this model when vocals are the priority** — it beats every other |
| open-source separator on MUSDB18-HQ vocals. For drums/bass-focused work, |
| consider `mdx_extra_q` instead. |
|
|
| --- |
|
|
| ## Quick start (Python) |
|
|
| ```python |
| import base64, io, soundfile as sf |
| from huggingface_hub import InferenceClient |
| |
| with open("your-song.mp3", "rb") as f: |
| audio_b64 = base64.b64encode(f.read()).decode() |
| |
| client = InferenceClient(model="StemSplitio/htdemucs-ft-pytorch") |
| result = client.post(json={"inputs": audio_b64}) |
| |
| for stem in ("vocals", "drums", "bass", "other"): |
| wav, sr = sf.read(io.BytesIO(base64.b64decode(result[stem]))) |
| sf.write(f"out_{stem}.wav", wav, sr) |
| ``` |
|
|
| Or run locally without Hugging Face at all: |
|
|
| ```python |
| import torch, soundfile as sf |
| from demucs.apply import apply_model |
| from demucs.audio import convert_audio |
| from demucs.pretrained import get_model |
| |
| model = get_model("htdemucs_ft").eval() |
| wav, sr = sf.read("your-song.mp3", dtype="float32", always_2d=True) |
| wav = torch.from_numpy(wav.T).contiguous() |
| wav = convert_audio(wav, sr, model.samplerate, model.audio_channels).unsqueeze(0) |
| |
| with torch.no_grad(): |
| stems = apply_model(model, wav, device="mps" if torch.backends.mps.is_available() else "cpu")[0] |
| |
| for i, name in enumerate(model.sources): # ["drums", "bass", "other", "vocals"] |
| sf.write(f"out_{name}.wav", stems[i].T.numpy(), model.samplerate) |
| ``` |
|
|
| --- |
|
|
| ## Deploy on Hugging Face Inference Endpoints |
|
|
| Click **Deploy → Inference Endpoints** above, pick a GPU instance, and HF |
| will spin up a container running [`handler.py`](handler.py). Recommended |
| hardware tiers based on M4 Pro reference latency: |
|
|
| | Hardware | RTF | Latency for 3-min song | |
| |---|---:|---:| |
| | NVIDIA L4 | ~0.04 | ~7 s | |
| | NVIDIA T4 small | ~0.10 | ~18 s | |
| | CPU x4 (basic) | ~0.7 | ~125 s | |
|
|
| Then call the endpoint: |
|
|
| ```bash |
| curl -X POST https://<your-endpoint>.endpoints.huggingface.cloud \ |
| -H "Authorization: Bearer $HF_TOKEN" \ |
| -H "Content-Type: application/json" \ |
| -d "{\"inputs\": \"$(base64 < your-song.mp3)\"}" |
| ``` |
|
|
| Response is a JSON object with `vocals`, `drums`, `bass`, `other` |
| base64-encoded WAVs at 44.1 kHz. |
|
|
| --- |
|
|
| ## Skip the infrastructure — use the StemSplit API |
|
|
| If you'd rather not run your own endpoint, the |
| [**StemSplit API**](https://stemsplit.io/developers) wraps this same model |
| (and the rest of the [benchmarked lineup](https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026)) |
| behind a hosted REST API with credits, a dashboard, and webhooks. |
|
|
| ```bash |
| curl -X POST https://stemsplit.io/api/v1/jobs \ |
| -H "Authorization: Bearer $STEMSPLIT_API_KEY" \ |
| -F "audio=@your-song.mp3" \ |
| -F "model=htdemucs_ft" |
| ``` |
|
|
| - 📘 [Developer docs](https://stemsplit.io/developers/docs) |
| - 🔌 [API reference](https://stemsplit.io/developers/reference) |
| - 📚 [Guides & recipes](https://stemsplit.io/developers/guides) |
|
|
| Or try it in your browser, no code: |
|
|
| - 🎤 [**Vocal Remover** (free online tool)](https://stemsplit.io/vocal-remover) |
| — upload a song, get an instrumental + isolated vocals |
| - 🎶 [Karaoke Maker](https://stemsplit.io/karaoke-maker) — |
| same model, optimised for karaoke output |
| - 🎙️ [Acapella Maker](https://stemsplit.io/acapella-maker) — extract clean |
| vocal acapellas for remixes and sampling |
| - 📺 [YouTube Stem Splitter](https://stemsplit.io/youtube-stem-splitter) — |
| paste a YouTube URL, get the stems |
|
|
| --- |
|
|
| ## Performance |
|
|
| Measured on an Apple M4 Pro (24 GB unified memory) with PyTorch 2.4 MPS, for |
| the full 4-bag ensemble on 50 MUSDB18-HQ tracks (median track length ~4 min, |
| RTF 0.26 ± 0.02). Cloud GPU numbers are extrapolated from public Demucs |
| benchmarks. |
|
|
| | Hardware | Per 3-min song | Peak RAM | Notes | |
| |---|---:|---:|---| |
| | Apple M4 Pro (MPS) | ~47 s | 3.1 GB | Measured in [our benchmark](https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026) (RTF 0.26) | |
| | NVIDIA L4 (CUDA) | ~7 s | 4 GB | Extrapolated | |
| | NVIDIA T4 small (CUDA) | ~18 s | 4 GB | Extrapolated | |
| | CPU (8-core) | ~125 s | 3 GB | Slow, but works for batch jobs | |
|
|
| --- |
|
|
| ## How `htdemucs_ft` differs from the other Demucs models |
| |
| | Variant | Bag size | Best at | When to choose | |
| |---|---:|---|---| |
| | `htdemucs_ft` *(this)* | 4 | **Vocals** | Karaoke, vocal isolation, acapella extraction | |
| | `htdemucs` | 1 | Balanced | Lower latency / smaller deploy | |
| | `htdemucs_6s` | 1 | 6-stem (adds piano, guitar) | When you need piano/guitar separately | |
| | `mdx_extra_q` | 4 | **Drums, bass** | Music production where rhythm section is the priority | |
|
|
| See the full |
| [stem-separation benchmark dataset](https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026) |
| for SDR / ISR / SIR / SAR across all stems. |
|
|
| --- |
|
|
| ## Single-stem specialist variants (faster, smaller) |
|
|
| If you only need **one** stem in production, ship a specialist sub-model |
| instead of the full 4-bag ensemble. Same per-stem quality, ~160 MB instead |
| of ~640 MB, ~2.6× faster on M4 Pro MPS: |
|
|
| | Repo | Stem | Use cases | |
| |---|---|---| |
| | [`htdemucs-ft-drums-pytorch`](https://huggingface.co/StemSplitio/htdemucs-ft-drums-pytorch) | drums | Drum extraction, beat transcription, sample-pack creation | |
| | [`htdemucs-ft-bass-pytorch`](https://huggingface.co/StemSplitio/htdemucs-ft-bass-pytorch) | bass | Bassline transcription, mix rebalancing, sub-bass mastering | |
| | [`htdemucs-ft-other-pytorch`](https://huggingface.co/StemSplitio/htdemucs-ft-other-pytorch) | other / instrumental | Karaoke instrumentals (pair with this vocals model), sample-flipping | |
|
|
| This repo (the full bag) remains the best choice when you need vocals plus |
| any other stem in a single request — it amortises the inference cost across |
| all 4 stems. |
|
|
| --- |
|
|
| ## Files in this repo |
|
|
| - [`handler.py`](handler.py) — `EndpointHandler` class HF Inference Endpoints |
| calls on each request. Accepts base64 audio in, returns base64 stems out. |
| - [`requirements.txt`](requirements.txt) — Python deps (torch, demucs, soundfile). |
| - `README.md` — this card. |
|
|
| Model weights are downloaded into the container's torch hub cache on first |
| run (no `.pt` / `.th` files are stored in this repo to keep it small). |
|
|
| --- |
|
|
| ## License & attribution |
|
|
| This repo is **MIT-licensed**, matching the original HT-Demucs. |
|
|
| **Please cite the original authors** if you use this model in research: |
|
|
| ```bibtex |
| @inproceedings{rouard2023hybrid, |
| title = {Hybrid Transformers for Music Source Separation}, |
| author = {Rouard, Simon and Massa, Francisco and D{\'e}fossez, Alexandre}, |
| booktitle = {ICASSP}, |
| year = {2023} |
| } |
| ``` |
|
|
| And if you use the benchmark or this packaging: |
|
|
| ```bibtex |
| @misc{stemsplit_benchmark_2026, |
| title = {StemSplit Stem-Separation Benchmark 2026}, |
| author = {StemSplit}, |
| year = {2026}, |
| url = {https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026} |
| } |
| ``` |
|
|
| - Original model: [`facebookresearch/demucs`][demucs-repo] |
| - Packaging by [StemSplit](https://stemsplit.io) |
| - Benchmark dataset: [StemSplitio/stem-separation-benchmark-2026](https://huggingface.co/datasets/StemSplitio/stem-separation-benchmark-2026) |
|
|
| [demucs-repo]: https://github.com/facebookresearch/demucs |
|
|
