deezer/spleeter repository overview

About

Spleeter is the Deezer⁠ source separation library with pretrained models written in Python⁠ and uses Tensorflow⁠. It makes it easy to train source separation model (assuming you have a dataset of isolated sources), and provides already trained state of the art model for performing various flavour of separation :

• Vocals (singing voice) / accompaniment separation (2 stems⁠)
• Vocals / drums / bass / other separation (4 stems⁠)
• Vocals / drums / bass / piano / other separation (5 stems⁠)

2 stems and 4 stems models have high performances⁠ on the musdb⁠ dataset. Spleeter is also very fast as it can perform separation of audio files to 4 stems 100x faster than real-time when run on a GPU.

We designed Spleeter so you can use it straight from command line⁠ as well as directly in your own development pipeline as a Python library⁠. It can be installed with Conda⁠, with pip⁠ or be used with Docker⁠.

Usage

We are providing official Docker⁠ images for using Spleeter. You need first to install Docker⁠, for instance the Docker Community Edition⁠.

Run container

Built images entrypoint is Spleeter main command spleeter. Thus you can run the separate command by running this previously built image using docker run³ command with a mounted directory for output writing :

docker run -v $(pwd)/output:/output deezer/spleeter separate -i audio_example.mp3 -o /output

If you want to run the image with GPU device support you can use the dedicated GPU image :

# If you have nvidia-docker:
nvidia-docker run -v $(pwd)/output:/output deezer/spleeter:gpu separate -i audio_example.mp3 -o /output

# Or if your docker client version is high enough to support `Nvidia` runtime :
docker run --runtime=nvidia -v $(pwd)/output:/output deezer/spleeter:gpu separate -i audio_example.mp3 -o /output

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 vocals.wav and accompaniment.wav on your computer in the mounted output folder output/audio_example.

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 \
    deezer/spleeter \
    separate -i /input/audio_1.mp3 /input/audio_2.mp3 -o /output

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 dataset⁴ using museval⁠

# Model training.
nvidia-docker run -v </path/to/musdb>:/musdb deezer/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 deezer/spleeter:gpu evaluate -p spleeter:4stems --mus_dir /musdb -o /eval_output

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).