2. Getting started
- Using Docker image
Once installed, Spleeter can be used directly from any CLI through
spleeter command. It provides three action with following
||Separate audio files using pretrained model|
||Train a source separation model. You need a dataset of separated tracks to use it|
||Pretrained model evaluation over musDB test set|
To get help on the different options available with the
separate command, type:
spleeter separate -h
If you are using the GPU version and want to specify the device card number, you'll need to set the
Using 2stems model
You can straightforwardly separate audio files with the default 2 stems (vocals / accompaniment) pretrained model like following1 :
spleeter separate -i audio_example.mp3 -o audio_output
1 be sure to be in the
spleeterfolder if you are using cloned repository or replace
audio_example.mp3by a valid path to an audio file).
-i option is for providing a list of audio filenames. The
for providing the output path where to write the separated wav files.
The command may take quite some time to execute at first run, since it
will download the pre-trained model. If everything goes well, you should
then get a folder
audio_output/audio_example that contains two files:
Using 4stems model
You can also use a pretrained 4 stems (vocals / bass / drums / other ) model :
spleeter separate -i audio_example.mp3 -o audio_output -p spleeter:4stems
-p option is for providing the model settings. It could be either a Spleeter
embedded setting identifier2 or a path to a JSON file configuration such
as this one.
This time, it will generate four files:
2 at this time, following embedded configuration are available :
Using 5stems model
Finally a pretrained 5 stems (vocals / bass / drums / piano / other) model is also available out of the box :
spleeter separate -i audio_example.mp3 -o audio_output -p spleeter:5stems
Which would generate five files:
separate command builds the model each time it is called and downloads it
the first time. This process may be long compared to the separation process by
itself if you process a single audio file (especially a short one). If you have
several files to separate, it is then recommended to perform all separation with
a single call to
spleeter separate \ -i <path/to/audio1.mp3> <path/to/audio2.wav> <path/to/audio3.ogg> \ -o audio_output
For training your own model, you need:
- A dataset of separated files such as musDB.
- Dataset must be described in CSV files : one for training and one for validation) which are used for generating training data.
- A JSON configuration file such as this one that gathers all parameters needed for training and paths to CSV file.
Once your train configuration is setup, you can run model training as following :
spleeter train -p configs/musdb_config.json -d </path/to/musdb>
For evaluating a model, you need the musDB dataset. You can for instance evaluate the provided 4 stems pre-trained model this way:
spleeter evaluate -p spleeter:4stems --mus_dir </path/to/musdb> -o eval_output
For using multi-channel Wiener filtering for performing the separation, you need to add the
--mwf option (to get the results reported in the paper):
spleeter evaluate -p spleeter:4stems --mus_dir </path/to/musdb> -o eval_output --mwf
Using Docker image
You can build image using
docker build command from cloned
git clone https://github.com/deezer/spleeter cd spleeter # Build CPU image. docker build -f docker/cpu.Dockerfile -t spleeter:cpu . # Build GPU image. docker build -f docker/gpu.Dockerfile -t spleeter:gpu .
Built images entrypoint is Spleeter main command
Thus you can run the
separate command by running this previously built image
docker run3 command with a mounted directory for output writing :
# Run with CPU : docker run -v $(pwd)/output:/output spleeter:cpu separate -i audio_example.mp3 -o /output # Or with GPU if available : nvidia-docker run -v $(pwd)/output:/output spleeter:gpu separate -i audio_example.mp3 -o /output
3 For running command over GPU, you should use nvidia-docker command instead of
dockercommand. This alternative command allows container to access Nvidia driver and the GPU devices from host.
This will separate the audio file provided as input (here
audio_example.mp3 which is embedded
in the built image) and put the separated files
accompaniment.wav on your
computer in the mounted output folder
For using your own audio file you will need to create container volume when running the image, we also suggest you to create a volume for storing downloaded model. This will avoid Spleeter to download model files each time you run the image.
To do so let's first create some environment variable :
export AUDIO_IN='/path/to/directory/with/audio/file' export AUDIO_OUT='/path/to/write/separated/source/into' export MODEL_DIRECTORY='/path/to/model/storage'
Then we can run the
separate command through container :
docker run \ -v $AUDIO_IN:/input \ -v $AUDIO_OUT:/output \ -v $MODEL_DIRECTORY:/model \ -e MODEL_PATH=/model \ spleeter:cpu \ separate -i /input/audio_1.mp3 /input/audio_2.mp3 -o /output
⚠️ As for non docker usage we recommend you to perform separation of multiple file with a single call on Spleeter image.
You can use the
train command (that you should mainly use with a GPU as it
is very computationally expensive), as well as the
evaluate command, that
performs evaluation on the musDB
test dataset4 using museval
# Model training. nvidia-docker run -v </path/to/musdb>:/musdb spleeter:gpu train -p configs/musdb_config.json -d /musdb # Model evaluation. nvidia-docker run -v $(pwd)/eval_output:/eval_output -v </path/to/musdb>:/musdb spleeter:gpu evaluate -p spleeter:4stems --mus_dir /musdb -o /eval_output
4 You need to request access and download it from here
The separation process should be quite fast on a GPU (should be less than 90s on the musdb test set) but the execution of museval takes much more time (a few hours).