Audio Separator

0.44.1 · active · verified Wed Apr 15

Audio Separator is a Python package designed for easy audio stem separation, capable of splitting audio files into various stems (e.g., instrumental, vocals, drums, bass, etc.). It leverages a variety of pre-trained deep learning models, primarily from UVR (Ultimate Vocal Remover) and includes MDX-Net, VR Arch, Demucs, and MDXC models. The library offers both a Command Line Interface (CLI) for batch processing and a Python API for integration into other projects. It supports common audio formats like WAV, MP3, FLAC, and M4A.

Warnings

gotcha For CUDA (NVIDIA GPU) acceleration, default pip installation may not provide optimal Torch/ONNX Runtime versions. You may need to manually uninstall and reinstall `torch` and `onnxruntime` or `onnxruntime-gpu` to ensure CUDA support.
Fix: pip uninstall torch onnxruntime; pip cache purge; pip install --force-reinstall torch torchvision torchaudio; pip install --force-reinstall onnxruntime-gpu (or "optimum[onnxruntime-gpu]" as per earlier docs). Refer to the official GitHub README for the most current recommended GPU installation steps.
gotcha FFmpeg is a mandatory dependency for `audio-separator` to handle audio processing. It must be installed separately and available in your system's PATH.
Fix: Install FFmpeg for your operating system (e.g., via a package manager like `apt` or `brew`, or download from ffmpeg.org) and ensure its binaries are accessible via your system's PATH. You can verify installation by running `audio-separator --env_info`.
gotcha Models used for separation are downloaded on first use and cached locally. This requires an internet connection for the initial run with a new model and can incur a delay.
Fix: Ensure an active internet connection when using a new model for the first time. Subsequent runs with the same model will use the cached version.
gotcha AI-powered stem separation, while advanced, is not perfect. Users may encounter 'bleeding' (components of one stem appearing in another), softening of audio in certain parts, or other artifacts in the separated tracks. The quality can vary significantly depending on the input audio complexity and the chosen model.
Fix: Experiment with different models available through the library. Understand that separated stems are algorithms' best guesses, not perfectly isolated original recordings. Post-processing or manual cleanup may be required for professional applications.

Install

pip install audio-separator Default (CPU)
pip install "audio-separator[cpu]" Explicit CPU
pip install "audio-separator[gpu]" Attempt GPU (see warnings)

Imports

Separator
```
from audio_separator import Separator
```

Quickstart

This quickstart demonstrates how to initialize the `Separator` class with an audio file path, a desired model name, and an output directory, then execute the separation process. The separated stems will be saved in the specified output directory. Models are automatically downloaded on first use. Replace `input_audio.wav` and `output_directory` with your actual paths.

import os
from audio_separator import Separator

# Ensure a dummy audio file exists for demonstration, or provide a real path
# For a runnable example, replace with an actual audio file path
audio_file_path = os.environ.get('AUDIO_FILE_PATH', 'input_audio.wav')
output_directory = os.environ.get('OUTPUT_DIR', 'separated_stems')
model_name = os.environ.get('MODEL_NAME', 'UVR_MDXNET_KARA_2')

# Create dummy input file if it doesn't exist for demonstration purposes
if not os.path.exists(audio_file_path):
    # This part is for demonstration only and won't create a valid audio file
    # In a real scenario, `input_audio.wav` would be a proper audio file.
    print(f"Warning: '{audio_file_path}' not found. Please provide a real audio file.")
    # Example: Create a tiny placeholder file (not actual audio)
    with open(audio_file_path, 'wb') as f:
        f.write(b'RIFF\x00\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00\x44\xAC\x00\x00\x88\x58\x01\x00\x02\x00\x10\x00data\x00\x00\x00\x00')

# Initialize the Separator
separator = Separator(
    audio_file=audio_file_path,
    model_name=model_name,
    output_dir=output_directory,
    output_format='wav' # Specify output format (e.g., 'wav', 'mp3')
)

# Perform the separation
print(f"Separating '{audio_file_path}' using model '{model_name}'...")
primary_stem_path, secondary_stem_path = separator.separate()

print(f"Primary stem saved at: {primary_stem_path}")
print(f"Secondary stem saved at: {secondary_stem_path}")

# Clean up dummy file and directory for demonstration
if os.path.exists(audio_file_path) and audio_file_path == 'input_audio.wav':
    os.remove(audio_file_path)
if os.path.exists(output_directory) and output_directory == 'separated_stems':
    # In a real scenario, you might want to keep the output.
    import shutil
    shutil.rmtree(output_directory)
    print(f"Cleaned up temporary output directory: {output_directory}")

view raw JSON →