HTDemucs — Music Source Separation

Unofficial HuggingFace packaging of Hybrid Transformer Demucs v4 by Meta AI Research. The model weights and core architecture are unchanged from the official release. This repo adds a from_pretrained interface and native Apple Silicon (MPS) support.

This repo includes two models:

Model	Stems	Notes
htdemucs (default)	vocals, drums, bass, other	Demucs v4 default model
htdemucs_6s	vocals, drums, bass, other, guitar, piano	Guitar and piano separation is experimental — piano quality is limited

Quick start

pip install transformers torch torchaudio soundfile \
            einops omegaconf dora-search openunmix julius lameenc

from transformers import AutoModel

model = AutoModel.from_pretrained("puar-playground/htdemucs", trust_remote_code=True)

# 4-stem: vocals / drums / bass / other  (uses htdemucs)
stems = model.separate("song.wav", stems_mode=4, output_dir="output/")

# 2-stem: vocals / other  (uses htdemucs)
stems = model.separate("song.wav", stems_mode=2, output_dir="output/")

# 6-stem: vocals / drums / bass / other / guitar / piano  (uses htdemucs_6s)
stems = model.separate("song.wav", stems_mode=6, output_dir="output/")

# Access tensors directly (shape: channels × samples, float32)
vocals_tensor = stems["vocals"]

The correct checkpoint is selected automatically based on stems_mode — no manual config needed.

Device selection

# Auto-detect: CUDA → MPS (Apple Silicon) → CPU
model = AutoModel.from_pretrained("puar-playground/htdemucs", trust_remote_code=True)

# Explicit
model = AutoModel.from_pretrained("puar-playground/htdemucs", trust_remote_code=True,
                                  device="mps")   # or "cuda", "cpu", "cuda:1"

Repository layout

htdemucs/
├── modeling_demucs.py   # DemucsConfig + DemucsForSourceSeparation (trust_remote_code)
├── config.json          # auto_map → AutoModel / AutoConfig
├── requirements.txt
├── htdemucs.yaml        # bag-of-models config (4-stem)
├── htdemucs_6s.yaml     # bag-of-models config (6-stem)
├── htdemucs.th          # htdemucs weights (Git LFS)
├── htdemucs_6s.th       # htdemucs_6s weights (Git LFS)
└── demucs_src/          # vendored HTDemucs source (Meta AI, unmodified)

Credits

• Original repository: facebookresearch/demucs
• Paper: Hybrid Transformers for Music Source Separation (Rouard et al., 2022)