Spleeter Source Separation Library

Spleeter is a source separation library written in Python using TensorFlow. It provides pretrained models for various separation tasks:

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

It can be used via the command line, as a Python library, or via Docker.

Spleeter is a fast music source separation tool based on TensorFlow that allows users to split audio files into different stems using pre-trained models.

Supported separation modes:

• 2 stems: Vocals and Accompaniment.
• 4 stems: Vocals, Drums, Bass, and Other.
• 5 stems: Vocals, Drums, Bass, Piano, and Other.

Beyond inference, Spleeter allows users to train new source separation models or fine-tune existing pre-trained ones using TensorFlow, provided a dataset of isolated sources is available.

Spleeter uses a U-net architecture, which is an encoder/decoder Convolutional Neural Network (CNN) with skip connections.

Key technical details:

• Architecture: 12-layer U-nets (6 layers for the encoder and 6 for the decoder).
• Mechanism: The U-net estimates a soft mask for each source (stem).
• Training Loss: $L_1$-norm between masked input mix spectrograms and source-target spectrograms.
• Separation Methods: Separation is performed from estimated source spectrograms using either soft masking or multi-channel Wiener filtering.
• Runtime: Implemented in TensorFlow, supporting both CPU and GPU execution.

Spleeter is designed for high-speed processing of large datasets. On a single GPU (e.g., GeForce RTX 2080), it can separate a 4-stem mix approximately 100 times faster than real-time.

Example benchmark: Processing the entire musdb18 test dataset (~3.5 hours of audio) into 4 stems in less than 2 minutes using a single GPU and a dual Intel Xeon Gold CPU (where the CPU handles mix loading and stem export).

Spleeter can be consumed in several ways depending on your environment:

• Python Package: Available as a standalone package via pip.
• Conda: Provided via a conda recipe.
• Docker: Available as self-contained Docker images for easy deployment across various platforms.

Spleeter is managed using Poetry. To set up a development environment and run the test suite, follow these steps:

1. Clone the repository.
2. Install Poetry.
3. Install dependencies using poetry install.
4. Run tests using poetry run pytest.

# Clone spleeter repository
git clone https://github.com/Deezer/spleeter && cd spleeter

# Install poetry
pip install poetry

# Install spleeter dependencies
poetry install

# Run unit test suite
poetry run pytest tests/

To quickly test Spleeter, you can install the necessary dependencies, install the package via pip, download an example file, and run a separation task.

Note: Spleeter requires ffmpeg and libsndfile to be installed on your system. While Conda can be used to install these, it is no longer the recommended method for installing Spleeter itself.

Warning for Apple M1 users: There are known TensorFlow compatibility issues with Apple M1 chips. Check the official issue tracker for workarounds.

# install dependencies using conda
conda install -c conda-forge ffmpeg libsndfile

# install spleeter with pip
pip install spleeter

# download an example audio file
wget https://github.com/deezer/spleeter/raw/master/audio_example.mp3

# separate the example audio into two components
spleeter separate -p spleeter:2stems -o output audio_example.mp3

You can perform audio separation from the command line using the spleeter separate command.

To separate an audio file into its constituent parts (e.g., vocals and accompaniment), use the following syntax:

spleeter separate -o <output_directory> <input_audio_file>

By default, this will create a directory within the specified output path named after the input file, containing the separated .wav files.

!spleeter separate -o output/ audio_example.mp3

Spleeter can be invoked as a Python module. The CLI provides three primary commands: train for training models, evaluate for testing models on the MUSDB dataset, and separate for performing audio source separation.

Usage Pattern:

python -m spleeter {train,evaluate,separate} [options]

python -m spleeter separate ...

To use Spleeter in a Jupyter/Colab environment, you must first install ffmpeg (a system dependency for audio processing) and then install the spleeter package via pip.

!apt install ffmpeg
!pip install spleeter

When using separate_to_file, you can control how the output files are named and organized using the filename_format parameter. This is a Python-style format string that supports the following placeholders:

• {instrument}: The name of the separated source (e.g., 'vocals', 'drums').
• {filename}: The base filename of the input audio.
• {foldername}: The name of the directory containing the input audio.
• {codec}: The output codec used (e.g., 'wav', 'mp3').

Default format: "{filename}/{instrument}.{codec}"