Demucs Documentation

The quickest way to use Demucs without a permanent installation is using uvx.

Standard usage:

uvx demucs MY_TRACK.mp3

For Intel Macs (non-Apple Silicon): Since PyTorch support for Intel Macs ended after version 2.2, you must use Python 3.12 or lower:

uvx --python 3.12 demucs MY_TRACK.mp3

Permanent installation as a CLI tool:

uv tool install demucs
demucs MY_TRACK.mp3

Using the bleeding edge version from GitHub:

uvx --from git+https://github.com/adefossez/demucs demucs MY_TRACK.mp3

You can export a model before training is complete by running the training command with the --save_model flag. To reduce the model size by half without impacting SDR, add the --half flag to save weights in half precision.

To partially evaluate an exported model, use ./run.py with the --test flag. Note that the model name provided to --test should be relative to the models folder (defaulting to models/), so do not include the directory prefix in the name.

On Apple Silicon Macs, Demucs uses the GPU automatically via Metal (MPS).

If you encounter issues with GPU acceleration, you can force the separation to run on the CPU using the -d cpu flag.

To install the necessary dependencies for training models, use pip with the [train] extra. If you are working from a local clone of the repository, you can use uv.

pip install "demucs[train]"
# OR from a repository clone:
uv sync --extra train

Demucs requires a specific directory structure for training. After extracting the tracks, create train and valid directories. Move all tracks into train, then move the specific validation tracks listed below into the ../valid directory relative to the train folder.

Note: The validation tracks and training tracks are corrupted in different ways for these tasks, so loss curves may behave differently than standard MusDB training.

mkdir train
mv * train
mkdir valid
cd train
mv 5640831d-7853-4d06-8166-988e2844b652  bc964128-da16-4e4c-af95-4d1211e78c70 \
	cc7f7675-d3c8-4a49-a2d7-a8959b694004  f40ffd10-4e8b-41e6-bd8a-971929ca9138 \
	bc1f2967-f834-43bd-aadc-95afc897cfe7  cc3e4991-6cce-40fe-a917-81a4fbb92ea6  \
	ed90a89a-bf22-444d-af3d-d9ac3896ebd2  f4b735de-14b1-4091-a9ba-c8b30c0740a7 ../valid

To submit, clone the Demucs Starter Kit for SDX23.

1. Copy the exported models from your release_models folder into the sdx23/models/ folder of the starter kit.
2. Ensure git-lfs is installed and configured before adding these model files to your fork of sdx23.

To train Demucs on the MusDB-HQ dataset, use the ./run.py script. It is recommended to use 48 channels for optimal performance on MusDB-HQ, as it is faster and uses less memory than the 64-channel version (which may time out during 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]

While Demucs natively decodes common formats like wav, flac, mp3, ogg, and aac, you should install ffmpeg if you need to output to flac or read more exotic audio formats.

brew install ffmpeg

To use Demucs in your Python code, import the demucs.api module, initialize a Separator instance, perform separation, and then save the resulting audio stems.

Note: Always ensure the destination directory exists before calling save_audio to avoid FileNotFoundError.

To install Demucs on Windows, use uv to manage the Python environment. Note that Demucs does not support 32-bit systems.

1. Install uv via terminal (Win + R, type cmd):

   winget install --id=astral-sh.uv -e

2. (Optional) Install ffmpeg to enable FLAC output and support for exotic audio formats:

   winget install ffmpeg

To set up a development environment for training or research, use uv sync with the train extra. This creates a .venv environment compatible with the repository's Makefile targets.

Requirements:

• Python 3.10+
• soundstretch/soundtouch installed on your system:
  • macOS: brew install sound-touch
  • Ubuntu: sudo apt install soundstretch

Setup command:

uv sync --extra train

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

1. Export the model:

   python3 -m tools.export <signature>

   Models are stored in release_models/.

2. Run separation:

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

3. Use a 'Bag of Models': You can combine multiple models by copying demucs/remote/mdx.yaml to ./release_models/my_bag.yaml and editing the weights and model list. Run it via:

   demucs --repo ./release_models -n my_bag <track_file>

python3 -m tools.export 9357e12e