| --- |
| license: mit |
| pipeline_tag: audio-to-audio |
| tags: |
| - audio-source-separation |
| - music-source-separation |
| - htdemucs |
| - demucs |
| - gguf |
| - stems.cpp |
| --- |
| |
| # HTDemucs GGUF |
|
|
| Meta's Hybrid Transformer Demucs (v4) converted to GGUF for |
| [stems.cpp](https://github.com/betweentwomidnights/stems.cpp), a C++/ggml stem separator that runs |
| on CPU, CUDA, Vulkan and Metal with no Python. The three published HTDemucs models are here: |
|
|
| | model | stems | files | |
| |---|---|---| |
| | `htdemucs` | drums, bass, other, vocals | `htdemucs-42M-v1.0-{F32,F16}.gguf` | |
| | `htdemucs_6s` | drums, bass, other, vocals, guitar, piano | `htdemucs_6s-27M-v1.0-{F32,F16}.gguf` | |
| | `htdemucs_ft` | drums, bass, other, vocals (a bag of four fine-tuned models, one per stem) | `htdemucs_ft-4x42M-v1.0-{F32,F16}.gguf` | |
|
|
| | file | size | |
| |---|---:| |
| | `htdemucs-42M-v1.0-F32.gguf` | 160 MiB | |
| | `htdemucs-42M-v1.0-F16.gguf` | 100 MiB | |
| | `htdemucs_6s-27M-v1.0-F32.gguf` | 104 MiB | |
| | `htdemucs_6s-27M-v1.0-F16.gguf` | 70 MiB | |
| | `htdemucs_ft-4x42M-v1.0-F32.gguf` | 640 MiB | |
| | `htdemucs_ft-4x42M-v1.0-F16.gguf` | 400 MiB | |
|
|
| ## Download and run |
|
|
| ```sh |
| git clone --recursive https://github.com/betweentwomidnights/stems.cpp && cd stems.cpp |
| ./build.sh vulkan # or cpu | cuda | metal (Windows: build.cmd) |
| ./models.sh htdemucs_6s # F32; --encoding f16 for the smaller files |
| build-vulkan/bin/stems-split -m models/htdemucs_6s-27M-v1.0-F32.gguf -i song.wav -o stems/ |
| ``` |
|
|
| `stems-server` finds these files by model name (`"model": "htdemucs_6s"`); see the stems.cpp README. |
|
|
| ## Parity with PyTorch |
|
|
| Each figure is the SNR of the C++ output against `demucs 4.0.1` in float32, full separation of a |
| 20 s clip (demucs' `test.mp3`), for the worst stem of each model. Every stem of every model passes |
| stems.cpp's parity check (cosine 0.9999 or better). Measured 2026-10-02/03 on stems.cpp with ggml |
| `f30f0cdc`. CPU, CUDA and Vulkan: Core Ultra 9 275HX / RTX 5070 Laptop. Metal: Apple M4, against |
| torch refs dumped on the M4. |
|
|
| | model | encoding | CPU | CUDA | Vulkan | Metal | |
| |---|---|---:|---:|---:|---:| |
| | htdemucs | F32 | 78.4 | 73.5 | 78.3 | 70.7 | |
| | htdemucs | F16 | 56.9 | 73.5 | 56.4 | | |
| | htdemucs_6s | F32 | 75.3 | 68.5 | 75.2 | 74.3 | |
| | htdemucs_6s | F16 | 53.9 | 68.5 | 55.5 | | |
| | htdemucs_ft | F32 | 70.7 | 69.5 | 70.6 | 67.1 | |
| | htdemucs_ft | F16 | 63.5 | 69.5 | 64.4 | | |
|
|
| **F32 is the reference.** F16 stores only the cross-transformer's matmul weights in half |
| precision, with the convolutions kept F32. It costs about 20 dB on CPU and Vulkan and nothing |
| measurable on CUDA (whose F32 matmuls already run as TF32), and stays more than 50 dB below every |
| stem. It is about 40% smaller, not faster. The per-stem tables are in stems.cpp's `docs/PARITY.md`. |
|
|
| ## Sources and license |
|
|
| - Upstream: [facebookresearch/demucs](https://github.com/facebookresearch/demucs), `demucs 4.0.1`. |
| Checkpoints: htdemucs `955717e8-8726e21a.th`; htdemucs_6s `5c90dfd2-34c22ccb.th`; htdemucs_ft |
| `f7e0c4bc-ba3fe64a.th`, `d12395a8-e57c48e6.th`, `92cfc3b6-ef3bcb9c.th`, `04573f0d-f3cf25b2.th`. |
| - Converted with stems.cpp's `tools/convert_htdemucs.py`. Tensors are renamed, packed attention |
| projections are split into q/k/v, constants are folded into metadata, and the F16 files halve |
| the transformer's matmul weights. The architecture and weights are otherwise unchanged; every |
| GGUF records its upstream checkpoint in `general.source.file`. |
| - Code and weights are MIT-licensed by Meta Platforms, Inc. and affiliates; see `LICENSE` and |
| `NOTICE`. `SHA256SUMS` lists every GGUF. |
|
|
| If you use HTDemucs, cite *Hybrid Transformers for Music Source Separation* (Rouard, Massa, |
| Défossez, ICASSP 2023). |
|
|
