---
license: mit
pipeline_tag: audio-to-audio
library_name: mlx
tags:
  - mlx
  - apple-silicon
  - audio-to-audio
  - music-source-separation
  - demucs
---

# demucs-htdemucs-mlx (HTDemucs v4, MLX)

MLX conversion of [facebookresearch/demucs](https://github.com/facebookresearch/demucs) for inference on Apple silicon via [mlx-audiogen](https://github.com/jasonvassallo/mlx-audiogen).

## Licence

Upstream Demucs is **MIT** — both the code and the released checkpoints, per the
project's [LICENSE](https://github.com/facebookresearch/demucs/blob/main/LICENSE)
and its README. MIT is permissive, including for commercial use, but it is not
obligation-free: the licence requires that

> The above copyright notice and this permission notice shall be included in all
> copies or substantial portions of the Software.

which is why this repository ships the full [`LICENSE`](LICENSE) rather than only
a `license: mit` tag.

mlx-audiogen's own Apache-2.0 licence covers the conversion **code** only. The full licence is in [`LICENSE`](LICENSE); attribution and the statement of modifications are in [`NOTICE`](NOTICE).

## Attribution

HTDemucs v4 was created by Simon Rouard, Francisco Massa and Alexandre Défossez, and published in [Hybrid Transformers for Music Source Separation](https://arxiv.org/abs/2211.08553).

## Modifications

These weights are a modified version of Meta's HTDemucs v4 checkpoint, converted to the MLX array format for inference on Apple silicon. Specifically: the upstream pickled Torch .th checkpoint is read for its tensor state dict only, weight keys are remapped to match this project's module names, convolution weights are transposed where MLX's layout differs from PyTorch's (both the 1-D and 2-D cases), fused QKV projections are split into separate Q, K and V tensors, and the result is re-serialised as safetensors. The model is re-implemented against MLX rather than PyTorch.

No weights are retrained or fine-tuned.

Tensor precision is unchanged: the upstream checkpoint stores float32 and so does this conversion. No weight value is altered by rounding — the Demucs converter performs no dtype cast.

## Usage

```python
from mlx_audiogen.models.demucs.pipeline import DemucsPipeline

# Auto-downloads weights from this repo
pipeline = DemucsPipeline.from_pretrained()

stems = pipeline.separate(audio_np, sample_rate=44100)
# stems = {"drums": np.ndarray, "bass": ..., "other": ..., "vocals": ...}
```

The weights download automatically on first use.

## Provenance

The checkpoint this was converted from is distributed by Meta at https://dl.fbaipublicfiles.com/demucs/hybrid_transformer/955717e8-8726e21a.th, referenced by the upstream project above.