demucs-infer

Inference-only distribution of Demucs for PyTorch 2.x

High-quality audio source separation models for extracting vocals, drums, bass, and other instruments from music tracks.

Version compatibility: DemucsSession and DemucsSeparator require v4.3.0 or later. Audio I/O without torchaudio requires v4.4.0 or later. Earlier releases retain their own requirements and behavior.

Why This Exists

The original Demucs repository by Meta AI Research is no longer actively maintained. The models remain state-of-the-art, but the package never received updates for modern PyTorch: it pins torchaudio<2.1, carries training-only dependencies (dora-search, hydra) that most inference users never need, and its packaging predates PEP 621.

demucs-infer re-provides the same models and separation quality as an inference-only, PyPI-installable package:

1. Maintain compatibility — works with PyTorch 2.x (no torchaudio<2.1 restriction) and Python 3.8+.
2. Continue development — addresses issues and compatibility gaps in modern audio and PyTorch stacks.
3. Focus on inference — training code, evaluation scripts, and dataset utilities are removed for a leaner package.
4. Serve the community — lets researchers and developers keep using these models without maintaining a fork themselves.

Before / After

Acknowledgments

demucs-infer is built on the research, architectures, and official models of the original Demucs project. This package maintains the packaging and PyTorch 2.x compatibility layer, and its checkpoint registry also exposes compatible third-party weights from their original public sources.

• Upstream organization: Meta AI Research (FAIR)
• Individual authors: Alexandre Défossez (both papers below, see Citation); Simon Rouard and Francisco Massa (Hybrid Transformer Demucs, co-authors — see arXiv:2211.08553)
• Source repository: github.com/facebookresearch/demucs
• Official pretrained weights host: dl.fbaipublicfiles.com/demucs — Meta's public checkpoint CDN. Compatible third-party sources are credited in Registry-backed compatible models; demucs-infer hosts no mirror.

What this package changed vs. upstream: PyTorch 2.x compatibility, inference-only packaging, and modern dependency management. What stayed identical: every model architecture, every separation algorithm, and every pretrained weight — see Scope below for the full breakdown.

Citation

If you use demucs-infer in your research, please cite the original Demucs papers — this package is a maintenance fork; all credit for the models, algorithms, and research belongs to the original authors.

Hybrid Demucs (2021):

@inproceedings{defossez2021hybrid,
  title={Hybrid Spectrogram and Waveform Source Separation},
  author={D{\'e}fossez, Alexandre},
  booktitle={Proceedings of the ISMIR 2021 Workshop on Music Source Separation},
  year={2021}
}

Hybrid Transformer Demucs (2022):

@article{rouard2022hybrid,
  title={Hybrid Transformers for Music Source Separation},
  author={Rouard, Simon and Massa, Francisco and D{\'e}fossez, Alexandre},
  journal={arXiv preprint arXiv:2211.08553},
  year={2022}
}

Features

• PyTorch 2.x Support: Compatible with modern PyTorch versions (no torchaudio<2.1 restriction)
• Inference-Only: ~50% smaller than original package (removed training code)
• Minimal Dependencies: 8 core packages (vs 15+ in original)
• API Compatible: Drop-in replacement for inference workflows
• Same Quality: Zero changes to separation algorithms
• Schema-v2 Model Registry: Official models plus verified UVR, CDX23, MSST, and DrumSep recipes
• Model Info API: Query model capabilities, separation types, and source translations
• Third-Party Model Support: Stable public names, exact stems, source URLs, and full SHA-256 verification

Scope

In scope — what we built

• PyTorch 2.x compatibility layer (removed version restrictions)
• PyTorch 2.6+ support (compatible with weights_only default changes)
• A minimal logging module replacing the dora-search dependency
• Lazy imports so optional dependencies are truly optional
• Inference-only packaging (7 core packages instead of 15+)
• Model Info API — query model capabilities, separation types, and source translations
• Third-party model support (module aliasing for community-trained models)

In scope — what stays unchanged from upstream

• All separation models: HTDemucs, MDX, and all variants
• Model architectures: zero modifications to the neural networks
• Separation algorithms: identical audio processing
• Model weights: unchanged official checkpoints plus source-pinned compatible checkpoints
• Audio quality: exact on the pinned lossless fixture; MP3 fallback decoding has a measured tolerance (see CLAUDE.md)

Out of scope, forever

• Training code (train.py, solver.py, etc.) — this is an inference-only package by design, not a temporary gap
• Evaluation scripts (evaluate.py)
• Training-only dependencies (hydra, dora-search, omegaconf)
• Dataset utilities (musdb, museval)
• Distributed training tools (submitit)

To retrain or evaluate against the original benchmarks, use the upstream facebookresearch/demucs repository directly.

Install

demucs-infer is available on PyPI and supports both UV (recommended, faster) and pip (traditional).

The DemucsSession and DemucsSeparator examples require v4.3.0 or later. The torchaudio-free audio path requires v4.4.0 or later; until that release is on PyPI, install it from source with pip install "git+https://github.com/openmirlab/demucs-infer.git@main".

With UV:

curl -LsSf https://astral.sh/uv/install.sh | sh   # if you don't have UV yet
uv add demucs-infer

With pip:

python -m venv .venv && source .venv/bin/activate  # recommended
pip install demucs-infer

Requirements

• Python: 3.8+
• PyTorch: 2.0 or later
• OS: Linux, macOS, Windows
• GPU: Optional (CUDA-capable GPU recommended for speed)

Optional Dependencies

With UV:

uv add "demucs-infer[mp3]"         # MP3 output support
uv add "demucs-infer[quantized]"   # Quantized models
uv add "demucs-infer[community]"   # Community model downloads (Google Drive)
uv add "demucs-infer[safetensors]" # Native HTDemucs safetensors checkpoints
uv add "demucs-infer[mp3,quantized,community,safetensors]"  # all of the above

With pip:

pip install demucs-infer[mp3]         # Adds: lameenc>=1.2
pip install demucs-infer[quantized]   # Adds: diffq>=0.2.1
pip install demucs-infer[community]   # Adds: gdown>=5.0.0
pip install demucs-infer[safetensors] # Adds: safetensors>=0.4.2
pip install "demucs-infer[mp3,quantized,community,safetensors]"

Quick Start

Task-level facade

For a small, package-qualified entry point, use DemucsSeparator. It accepts audio paths or tensors and returns the existing Demucs output tuple: the normalized mixture tensor and a mapping of source names to separated tensors. Tensor inputs require their original sample rate; path inputs are decoded and resampled by the existing Separator loader.

import torch

from demucs_infer import DemucsSeparator, separate_file

# One-shot calls create and discard a fresh model helper.
mixture, stems = separate_file("song.wav", model="htdemucs")

# Reuse a loaded model across calls (calls are serialized for safety).
separator = DemucsSeparator(model="htdemucs", device="cpu")
mixture, stems = separator("song.wav")
waveform = torch.zeros(2, 44100)  # or a loaded [channels, time] waveform
mixture, stems = separator(waveform, sample_rate=44100)

Model lifecycle and checkpoint customization

DemucsSession is the package-qualified lifecycle surface. It owns model loading, checkpoint verification, the in-process model, and release while leaving the existing Separator API unchanged:

from demucs_infer import DemucsSession

with DemucsSession(model="htdemucs", device="cpu") as session:
    mixture, stems = session.infer("song.wav")
    print(session.samplerate, session.sources)
    print(session.status, session.cache_info())

load() may be called explicitly; the session-level infer() requires the session to be ready after load() (or context-manager entry). The legacy callable form, session(...), remains lazy for backward compatibility. release() clears the in-memory model but keeps disk checkpoints cached and permits a later reload; close() is terminal and idempotent. Device requests preserve legacy None/auto selection and accept explicit cpu, cuda, or cuda:N, rejecting invalid/unavailable requests before loading. status reports new, loading, ready, failed, released, or closed. A custom checkpoint can be supplied with checkpoint_path, or downloaded with checkpoint_url plus its required full checkpoint_sha256. The package ships its release-pinned metadata in the package-local demucs_infer/config/checkpoints.toml file (URLs, SHA-256 digests, license, provenance, and source revision). Runtime inference reads this local snapshot and does not depend on a remote catalog. Use checkpoint_catalog() or checkpoint_config_path() to inspect it.

Named models download to ~/.cache/demucs-infer/ by default. Pass cache_dir=Path("/your/checkpoint/cache") to DemucsSession or DemucsSeparator to override that location. checkpoint_path remains the single-file override, while explicit legacy get_model(name, repo=Path(...)) repositories remain supported for existing callers.

Native HTDemucs safetensors files use a strict, pickle-free loader from the optional safetensors extra. Load one directly when composing the lower-level API:

from demucs_infer.safetensors import load_safetensors_model

model = load_safetensors_model("5c90dfd2.safetensors")
model.eval()

The same format works with task-level checkpoint overrides. URL overrides still require a full SHA-256 and determine the format from the URL pathname, including URLs with query parameters:

from demucs_infer import DemucsSession

local = DemucsSession(
    checkpoint_path="5c90dfd2.safetensors",
    checkpoint_sha256="<full-sha256>",
    device="cpu",
)
remote = DemucsSession(
    checkpoint_url="https://example.test/5c90dfd2.safetensors?download=1",
    checkpoint_sha256="<full-sha256>",
    device="cpu",
)

The loader accepts only native HTDemucs metadata (klass, args, and kwargs) and a flat tensor state. It rejects unknown classes, nested state structures, malformed metadata (including non-finite numeric values), and state-dict mismatches without falling back to legacy .th deserialization. Existing named models, .th files and bag recipes keep their loading paths. Automatic safetensors discovery, quantized states and conversion are outside this loader's scope.

For a reproducible real-checkpoint comparison, use uv run --extra safetensors python tools/verify_safetensors_parity.py --checkpoint /path/model.th=SHA256 --audio /path/stereo-music.wav --device cuda --report /tmp/parity.json with a trusted legacy checkpoint and its independently verified digest. The verifier compares all session outputs in memory on real music, a silent tail, full silence and seeded synthetic input; temporary serialization is discarded.

The facade is additive: advanced users can continue composing demucs_infer.api.Separator, demucs_infer.pretrained.get_model, and demucs_infer.apply.apply_model directly. Optional backends remain lazy and retain their existing installation requirements.

from demucs_infer.pretrained import get_model
from demucs_infer.apply import apply_model
from demucs_infer.audio import AudioFile, save_audio
import torch

# Load model
model = get_model("htdemucs_ft")
model.eval()

# Load audio with the package's FFmpeg-based reader.
sr = model.samplerate
wav = AudioFile("song.wav").read(streams=0, samplerate=sr, channels=model.audio_channels)
wav = wav.unsqueeze(0)  # Add batch dimension

# Separate audio
with torch.no_grad():
    sources = apply_model(model, wav, device="cuda")

# Save separated stems
# sources shape: [1, 4, channels, time]
# sources order: drums, bass, other, vocals
for i, source_name in enumerate(model.sources):
    source = sources[0, i]  # Remove batch dimension
    save_audio(source, f"output/{source_name}.wav", sr)

Equivalent from the CLI:

demucs-infer "song.wav"                      # basic usage (all 4 stems)
demucs-infer --two-stems=drums "song.wav"    # drums only, faster
demucs-infer -n htdemucs_ft -o output/ "song.wav"   # pick a model + output dir

(Prefix any of these with uv run if you installed with UV into a project environment rather than activating a venv.)

Available Models

Official Demucs Models

4-Source Models (drums, bass, other, vocals)

6-Source Models (drums, bass, other, vocals, guitar, piano)

Registry-backed compatible models

These names use the same package-owned resolver as official models. Stems in the table are the exact programmatic dictionary keys returned by the API. speech is the dialogue stem in the CDX23 recipe. DrumSep's Spanish keys are preserved; their English meanings are bombo = kick, redoblante = snare, and platillos = cymbals.

from demucs_infer.pretrained import get_model

# Registry-backed models download and verify automatically.
model = get_model("cdx23_dnr")

# Explicit local repositories remain available for legacy/custom layouts.
from pathlib import Path
local_model = get_model("my_signature", repo=Path("/path/to/models"))

Use Cases

Music Production — extract vocals for remixing, isolate drums for sampling, remove vocals for karaoke, separate instruments for analysis.

Machine Learning — prepare training data for downstream music ML models, audio preprocessing, dataset augmentation.

Research — music information retrieval (MIR), audio signal processing, music transcription.

Model Info API

Query model capabilities, separation types, and get source name translations programmatically.

from demucs_infer.api import get_model_info, list_supported_separation_types

# Get detailed info about a model
info = get_model_info("htdemucs_ft")
print(info)
# Output:
# HT-Demucs Fine-tuned (htdemucs_ft)
#   Type: Music Separation (4 stems)
#   Architecture: HTDemucs (ensemble of 4)
#   Sources: drums, bass, other, vocals
#   Sample Rate: 44100 Hz
#   Use Case: High quality music separation

# Access individual properties
print(info.sources)          # ['drums', 'bass', 'other', 'vocals']
print(info.separation_type)  # 'music_4stem'
print(info.is_bag)           # True (ensemble model)
print(info.num_models)       # 4

# Get info for third-party model with source translation
from pathlib import Path
info = get_model_info("49469ca8", repo=Path("/path/to/drumsep"))
print(info.sources)          # ['bombo', 'redoblante', 'platillos', 'toms'] (Spanish)
print(info.sources_english)  # ['kick', 'snare', 'cymbals', 'toms'] (English)

List supported separation types:

from demucs_infer.api import list_supported_separation_types

types = list_supported_separation_types()
for key, info in types.items():
    print(f"{key}: {info['name']}")

# Output:
# music_4stem: Music Separation (4 stems)
# music_6stem: Music Separation (6 stems)
# drum_kit: Drum Kit Separation
# cinematic: Cinematic/Film Audio Separation
# speech: Speech Separation
# vocal_instrumental: Vocal/Instrumental Separation

Advanced Usage

Two-Stems Separation (Faster)

# CLI: Extract drums only (faster than 4-source)
demucs-infer --two-stems=drums "song.wav"

# Python API: Extract specific stem
model = get_model("htdemucs_ft")
# Model will automatically optimize for two-stem separation

Batch Processing

import torch
from pathlib import Path
from demucs_infer.pretrained import get_model
from demucs_infer.apply import apply_model
from demucs_infer.audio import AudioFile, save_audio

model = get_model("htdemucs_ft").cuda().eval()

audio_files = list(Path("input/").glob("*.wav"))

for audio_file in audio_files:
    wav = AudioFile(audio_file).read(
        streams=0, samplerate=model.samplerate, channels=model.audio_channels
    )
    sr = model.samplerate
    wav = wav.unsqueeze(0).cuda()

    with torch.no_grad():
        sources = apply_model(model, wav, device="cuda")

    output_dir = Path("output") / audio_file.stem
    output_dir.mkdir(parents=True, exist_ok=True)

    for i, source_name in enumerate(model.sources):
        save_audio(sources[0, i].cpu(), output_dir / f"{source_name}.wav", sr)

    print(f"Processed: {audio_file.name}")

Custom Device Selection

import torch

# Auto-detect best device
device = "cuda" if torch.cuda.is_available() else "cpu"

model = get_model("htdemucs_ft")
model = model.to(device)
model.eval()

# Or specify explicitly
model = model.to("cuda:0")  # GPU 0
model = model.to("cpu")     # CPU

Dependencies

Core Dependencies (8 packages)

torch>=2.0.0
soundfile>=0.12.1
einops
julius>=0.2.3
numpy
pyyaml
tqdm

openunmix was dropped as a dependency: the only thing this package ever used from it (openunmix.filtering.wiener, for optional Wiener-filter post-processing on some model configs) is now vendored directly into demucs_infer/wiener.py (MIT-licensed, with attribution). numpy was added explicitly -- it was always used directly by this package, but had been an unlisted transitive dependency (pulled in by openunmix) until now. soundfile handles WAV/FLAC output and input fallback when FFmpeg is not available. The package does not import or depend on torchaudio.

Audio decoders

demucs-infer reads audio through FFmpeg when available, then tries its declared soundfile dependency. WAV/FLAC fallback decoding matches the recorded v4.3.0 samples exactly. MP3 fallback uses libsndfile's decoder, which can differ slightly from FFmpeg: on the recorded stereo fixture the maximum input difference was 8.94e-7 (about 6.94e-6 relative to input RMS). Real HTDemucs outputs on that fixture stayed within 1e-5 of input RMS for every stem. WAV/FLAC writing preserves the v4.3.0 decoded PCM samples for the verified 16/24/32-bit formats.

If your own application calls torchaudio.load(..., backend="soundfile"), that call is outside demucs-infer. TorchAudio 2.9 and later ignores the backend argument for load/save and requires TorchCodec for those functions. Pass the path to a loaded Demucs session, use DemucsSeparator(path), or decode with soundfile yourself:

from demucs_infer import DemucsSession

with DemucsSession(model="htdemucs", device="cpu") as session:
    mixture, stems = session.infer("song.wav")

import soundfile as sf
audio, sample_rate = sf.read("song.wav", dtype="float32", always_2d=True)
# audio has shape [time, channels]; transpose for tensor APIs.

Troubleshooting

ImportError: No module named 'demucs_infer'

# Make sure you installed demucs-infer, not demucs
pip uninstall demucs
pip install demucs-infer

CUDA Out of Memory

# Use smaller chunks or CPU
model = model.to("cpu")

# Or use two-stems mode (faster)
# demucs-infer --two-stems=drums "audio.wav"

ImportError: TorchCodec is required for ...

This error comes from a direct torchaudio.load or torchaudio.save call in your own code. demucs-infer v4.4.0 and later do not make those calls; use the package path API or soundfile as shown above. If decoding fails inside demucs-infer, install FFmpeg or use a format supported by soundfile.

What This Project Will NEVER Bundle

demucs-infer downloads pretrained model weights at runtime; it does not, and will never, ship them inside the git repository or the published package.

• No weight files in the repo or the PyPI package. .th checkpoints are never committed to git and never included in the sdist/wheel — the package is source code only.
• No re-hosted or mirrored weights. Official models are fetched from Meta's CDN; compatible models are fetched from their registry-recorded original public sources. demucs-infer does not run its own mirror or CDN.
• No silently altered or re-derived weights. What you get from the official checkpoint URLs is bit-for-bit what upstream Demucs produced; this package does not quantize, prune, or fine-tune models and ship the result as a default.
• Compatible models remain separate artifacts. Selecting a registry-backed DrumSep, UVR, CDX23, or MSST model downloads its exact source artifact on first use and verifies the full SHA-256. The bytes are never bundled.

Default cache location (where downloaded weights land on disk):

~/.cache/demucs-infer/

Override it per session with cache_dir:

from pathlib import Path
from demucs_infer import DemucsSession

session = DemucsSession(
    model="uvr_demucs_model_1",
    cache_dir=Path("/srv/demucs-checkpoints"),
)

Manual checkpoint download

For offline or air-gapped use, download each required URL ahead of time and save it under the exact cache filename shown below. Use the default directory above or the directory passed as cache_dir. Multi-component bags require every row listed for that recipe.

The registry verifies every file before loading. A wrong or incomplete file is rejected rather than used. Official Meta and DrumSep artifacts follow the same resolver; inspect demucs_infer/config/checkpoints.toml for their exact filenames, URLs, and hashes. If a live download fails, check the source host, internet connection, and firewall settings.

Development

Development Installation

With UV:

cd /path/to/demucs-infer
uv pip install -e ".[dev]"
# Or add to your project as editable dependency
uv add -e ../path/to/demucs-infer

With pip:

cd /path/to/demucs-infer
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

The package includes a comprehensive test suite using pytest:

# Run all tests
uv run pytest tests/ -v

# Run specific test file
uv run pytest tests/test_import.py -v

# Run with coverage
uv run pytest tests/ --cov=demucs_infer

# Run network tests too (checkpoint URL liveness; deselected by default)
uv run pytest tests/ -v -m "network"

# Run tests needing a real downloaded checkpoint (deselected by default)
uv run pytest tests/ -v -m "realweights"

See CLAUDE.md for the bit-for-bit accuracy gate that any change to demucs_infer/ must pass.

Continuous Integration:

• GitHub Actions runs the complete offline suite on pull requests and on release-gate publishes (.github/workflows/ci.yml, .github/workflows/publish.yml).
• The matrix matches the advertised Python support: 3.8, 3.9, 3.10, 3.11, and 3.12.
• Each matrix job builds a wheel from the sdist, installs that wheel from outside the checkout, imports the public package, and verifies packaged checkpoint/remote resources are present.

Documentation

• Migration Guide (docs/MIGRATION.md, local-only, not on GitHub) - Migrate from original Demucs
• Implementation Notes (docs/dev/IMPLEMENTATION_NOTES.md, local-only, not on GitHub) - Technical details
• CHANGELOG.md - Version history and release notes
• Test Examples - Import verification

License

MIT License (same as original Demucs)

Copyright (c) Meta Platforms, Inc. (Original Demucs) Copyright (c) 2025 (demucs-infer modifications)

See LICENSE for details.

Support

• Migration Help: See docs/MIGRATION.md (local-only, not on GitHub)
• Version History: See CHANGELOG.md
• Bug Reports: GitHub Issues
• Original Demucs: facebookresearch/demucs

Made for the ML community. Based on the excellent work by Alexandre Défossez and Meta AI Research.