{"id":5179,"library":"demucs","title":"Demucs","description":"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.","status":"active","version":"4.0.1","language":"en","source_language":"en","source_url":"https://github.com/facebookresearch/demucs","tags":["audio","music","separation","AI","deep-learning","waveform","pytorch"],"install":[{"cmd":"pip install demucs","lang":"bash","label":"Standard Installation"},{"cmd":"pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 && pip install demucs","lang":"bash","label":"Installation with CUDA (for NVIDIA GPUs, example with CUDA 11.8)"}],"dependencies":[{"reason":"Core deep learning framework for the model.","package":"torch","optional":false},{"reason":"Audio I/O and transformations, works with PyTorch.","package":"torchaudio","optional":false},{"reason":"Used in priority for audio processing and handling various formats. Not a Python dependency, typically needs to be installed system-wide.","package":"ffmpeg","optional":true},{"reason":"Used for pitch/tempo augmentation during training. Not a Python dependency, typically needs to be installed system-wide (e.g., `brew install sound-touch` on macOS, `apt-get install soundstretch` on Ubuntu).","package":"soundstretch","optional":true}],"imports":[{"note":"The `demucs.api` module provides a high-level interface for separation, introduced in newer versions.","symbol":"Separator","correct":"import demucs.api\nseparator = demucs.api.Separator()"},{"note":"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.","wrong":"from demucs import Demucs","symbol":"pretrained, apply_model","correct":"from demucs import pretrained\nfrom demucs.apply import apply_model"}],"quickstart":{"code":"import demucs.api\nimport os\n\n# Create a dummy audio file for demonstration\ndummy_audio_path = \"test_audio.wav\"\n# This requires soundfile and numpy. In a real scenario, you would load an actual audio file.\ntry:\n    import numpy as np\n    import soundfile as sf\n    samplerate = 44100 # Hz\n    duration = 5 # seconds\n    frequency = 440 # Hz (A4 note)\n    t = np.linspace(0., duration, int(samplerate * duration), endpoint=False)\n    data = 0.5 * np.sin(2 * np.pi * frequency * t)\n    sf.write(dummy_audio_path, data, samplerate)\n    print(f\"Created dummy audio file: {dummy_audio_path}\")\n\n    # Initialize the separator. Uses the default 'htdemucs' model.\n    # You can specify other models: 'htdemucs_ft', 'mdx_extra', 'mdx_extra_q'\n    separator = demucs.api.Separator()\n\n    print(f\"Separating audio file: {dummy_audio_path}\")\n    # Separate the audio file\n    # The 'separated' variable will contain a dictionary where keys are stem names\n    # and values are the separated audio tensors (e.g., 'vocals', 'drums', 'bass', 'other')\n    origin, separated_stems = separator.separate_audio_file(dummy_audio_path)\n\n    # Save the separated stems\n    output_dir = \"separated_stems\"\n    os.makedirs(output_dir, exist_ok=True)\n\n    for stem_name, stem_audio in separated_stems.items():\n        output_path = os.path.join(output_dir, f\"{os.path.basename(dummy_audio_path).replace('.wav', '')}_{stem_name}.wav\")\n        demucs.api.save_audio(stem_audio, output_path, samplerate=separator.samplerate)\n        print(f\"Saved {stem_name} to {output_path}\")\n\nfinally:\n    # Clean up dummy file\n    if os.path.exists(dummy_audio_path):\n        os.remove(dummy_audio_path)\n    # Note: 'separated_stems' directory is left for inspection.\n    print(f\"Cleaned up dummy audio file: {dummy_audio_path}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or later.","message":"Demucs v4.0.1 and later require Python 3.8 or higher. Python 3.7 is no longer supported.","severity":"breaking","affected_versions":">=4.0.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"4.x.x from 3.x.x"},{"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.","message":"Users often encounter 'CUDA out of memory' errors when processing long audio files on GPUs, especially with high sample rates or default settings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Resample your input audio to 44.1kHz or 48kHz before feeding it to Demucs for best results.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly V4"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}