Demucs Documentation

Machine learning scientists can set up a dedicated environment using Conda. This requires installing dependencies from the provided YAML files and installing the package in editable mode.

Additionally, you must install soundstretch/soundtouch for pitch/tempo augmentation:

• macOS: brew install sound-touch
• Ubuntu: sudo apt-get install soundstretch

conda env update -f environment-cpu.yml  # if you don't have GPUs
conda env update -f environment-cuda.yml # if you have GPUs
conda activate demucs
pip install -e .

You can use Demucs without local installation by running it in a Google Colab notebook. This is useful for quick separations, though transfer speeds for large files may be slow.

https://colab.research.google.com/drive/1dC9nVxk3V_VPjUADsnFu8EiT-xnU1tGH?usp=sharing

For rapid prototyping and testing ideas, you can train a smaller 16kHz model. When training at 16kHz, you must set --repitch=0 to prevent errors.

./run.py --channels=32 --samplerate 16000 --samples 160000 --data_stride 16000 --depth=5 --batch_size 64 --repitch=0 --musdb=PATH_TO_MUSDB --is_wav [EXTRA_FLAGS]

To train Demucs for the Music DemiXing challenge (MDX), use the ./run.py script. It is recommended to use 48 channels for optimal performance on MusDB-HQ to ensure training is faster and fits within memory constraints; 64 channels may cause timeouts in the challenge. You may need to adjust the --batch_size based on your available GPU memory.

./run.py --channels=48 --batch_size 64 --musdb=PATH_TO_MUSDB --is_wav [EXTRA_FLAGS]

If you want to use Demucs to separate tracks, you can install it via pip.

Note for Windows users: Replace python3 with python.exe and always run commands from the Anaconda console.

python3 -m pip install -U demucs

Demucs requires significant GPU VRAM.

• Default usage: ~7GB VRAM recommended.
• Low VRAM (3GB): Use --segment 8 to reduce split size.
• Very Low VRAM (2GB): Set the environment variable PYTORCH_NO_CUDA_MEMORY_CACHING=1 to help, though this slows down separation.
• Fallback: If GPU memory is exhausted, use the -d cpu flag to run on the CPU.

To use NVIDIA GPUs (requires >2GiB VRAM), you must install PyTorch with CUDA support.

If Demucs is already installed, first uninstall the existing torch packages:

python.exe -m pip uninstall torch torchaudio

Then, visit the PyTorch Home Page to install the version compatible with your CUDA version.

Note: Ensure torchaudio is version 2.1 or lower (version 2.2.0 is explicitly unsupported).

Demucs requires a 64-bit system (32-bit is not supported). Follow these steps to install:

1. Install Anaconda with Python 3.8 or more recent.
2. Open the Anaconda Prompt.
3. Install ffmpeg using conda:

   conda install -c conda-forge ffmpeg

4. Install demucs and SoundFile using pip:

   python.exe -m pip install -U demucs SoundFile

For users with Anaconda or those preferring a managed environment, follow these steps:

1. Download and install Anaconda (version 3.8 or more recent).
2. Open the Anaconda Prompt in macOS.
3. Run the following commands to set up and use Demucs:

conda activate
pip3 install -U demucs
# To run Demucs (ensure conda is activated first):
demucs -d cpu PATH_TO_AUDIO_FILE_1

If your Linux distribution has Python 3.8 or newer and you only need to separate tracks (not train the model), you can install Demucs directly via pip.

To run Demucs after installation, use python3 -m demucs. If your user-specific pip bin/ folder is in your PATH, you can use the demucs command directly. Use the -d cpu flag to specify CPU execution.

pip3 install --user -U demucs
# Run using module syntax
python3 -m demucs -d cpu PATH_TO_AUDIO_FILE_1
# Or run directly if in PATH
demucs -d cpu PATH_TO_AUDIO_FILE_1

To use trained models with the demucs separation command, you must first export them:

1. Export the model:

   python3 -m tools.export <signature> [OTHER_SIGS...]

   Models are stored in release_models/.

2. Use the exported model:

   demucs --repo ./release_models -n <signature> <input_file>

python3 -m tools.export 9357e12e
demucs --repo ./release_models -n 9357e12e my_track.mp3