Demucs

4.0.1 · active · verified Mon Apr 13

Demucs (Deep Extractor for Music Sources) is a state-of-the-art open-source AI model for music source separation, developed by Meta AI Research. It separates audio into individual stems like vocals, drums, bass, and other instruments in the waveform domain. The current version, 4.0.1, features a Hybrid Transformer architecture. Demucs is actively maintained and regularly updated, offering high-quality separation capabilities for various applications in music production and audio analysis.

Warnings

breaking Demucs v4.0.1 and later require Python 3.8 or higher. Python 3.7 is no longer supported.
Fix: Upgrade your Python environment to 3.8 or later.
breaking Major architectural changes in Demucs v4 introduce breaking changes. Users updating from v3 might need to reinstall the library from scratch due to altered dependencies and internal structures.
Fix: Perform a clean reinstallation (`pip uninstall demucs && pip install demucs`). Review your code for deprecated API calls; prefer `demucs.api.Separator` for programmatic use.
gotcha Users often encounter 'CUDA out of memory' errors when processing long audio files on GPUs, especially with high sample rates or default settings.
Fix: Reduce the segment size by using the `--segment` flag (e.g., `demucs --segment 10 audio.mp3`) or `separator.update_parameter(segment=smaller_value)` with the API. Alternatively, use CPU processing by adding `-d cpu` to the CLI command or setting `device='cpu'` in the API.
gotcha Demucs models (especially V4) are primarily trained on 44.1kHz or 48kHz audio. Using input audio with significantly different sample rates (e.g., 96kHz) may result in suboptimal separation quality.
Fix: Resample your input audio to 44.1kHz or 48kHz before feeding it to Demucs for best results.
gotcha By default, Demucs automatically rescales each output stem to prevent clipping. This can alter the relative volume levels between the separated stems, which might not be desired for certain applications.
Fix: If you prefer hard clipping without altering relative volumes, use the `--clip-mode clamp` flag in the CLI or set `clip_mode='clamp'` when calling `separator.separate_audio_file()`.

Install

pip install demucs Standard Installation
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 && pip install demucs Installation with CUDA (for NVIDIA GPUs, example with CUDA 11.8)

Imports

Separator
```
import demucs.api
separator = demucs.api.Separator()
```
The `demucs.api` module provides a high-level interface for separation, introduced in newer versions.
pretrained, apply_model
```
from demucs import pretrained
from demucs.apply import apply_model
```
Direct `Demucs` class import is not the standard API for users; `pretrained.get_model` and `apply_model` are used for programmatic separation with older API patterns. The `demucs.api.Separator` is now recommended.

Quickstart

This quickstart demonstrates how to use the `demucs.api.Separator` class to load an audio file (using a dummy file here) and separate it into its constituent stems (vocals, drums, bass, other). It then saves each separated stem as a WAV file in a specified output directory. Ensure `soundfile` and `numpy` are installed for the dummy audio generation if you don't use your own file.

import demucs.api
import os

# Create a dummy audio file for demonstration
dummy_audio_path = "test_audio.wav"
# This requires soundfile and numpy. In a real scenario, you would load an actual audio file.
try:
    import numpy as np
    import soundfile as sf
    samplerate = 44100 # Hz
    duration = 5 # seconds
    frequency = 440 # Hz (A4 note)
    t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)
    data = 0.5 * np.sin(2 * np.pi * frequency * t)
    sf.write(dummy_audio_path, data, samplerate)
    print(f"Created dummy audio file: {dummy_audio_path}")

    # Initialize the separator. Uses the default 'htdemucs' model.
    # You can specify other models: 'htdemucs_ft', 'mdx_extra', 'mdx_extra_q'
    separator = demucs.api.Separator()

    print(f"Separating audio file: {dummy_audio_path}")
    # Separate the audio file
    # The 'separated' variable will contain a dictionary where keys are stem names
    # and values are the separated audio tensors (e.g., 'vocals', 'drums', 'bass', 'other')
    origin, separated_stems = separator.separate_audio_file(dummy_audio_path)

    # Save the separated stems
    output_dir = "separated_stems"
    os.makedirs(output_dir, exist_ok=True)

    for stem_name, stem_audio in separated_stems.items():
        output_path = os.path.join(output_dir, f"{os.path.basename(dummy_audio_path).replace('.wav', '')}_{stem_name}.wav")
        demucs.api.save_audio(stem_audio, output_path, samplerate=separator.samplerate)
        print(f"Saved {stem_name} to {output_path}")

finally:
    # Clean up dummy file
    if os.path.exists(dummy_audio_path):
        os.remove(dummy_audio_path)
    # Note: 'separated_stems' directory is left for inspection.
    print(f"Cleaned up dummy audio file: {dummy_audio_path}")

view raw JSON →