Registry / ai-ml / audio-separator

audio-separator

JSON →
library0.44.2pypypiunverified

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.

pip install audio-separator
INSTALL
IMPORT
SIG · AUDIO-SEPARATOR
A
audio-separator
ai-mlpythonv0.44.2
Install
100.0s avg
Import
Disk
5837MB
Pass rate
1/ 10
Env Coverage1 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.44.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ timeout
✓ 100.03s
py 3.11
✕ timeout
✕ build_error
py 3.12
✕ timeout
✕ build_error
py 3.13
✕ timeout
✕ build_error
py 3.9
✕ build_error
✕ timeout
5837MB installed
● package 5837MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Separator
from audio_separator import Separator
from audio_separator import Separator

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}")
audio-separator --version
Debug
Known issues
gotchaFor 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.
affects: All versions
gotchaFFmpeg 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`.
affects: All versions
gotchaModels 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.
affects: All versions
gotchaAI-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.
affects: All versions
Upgrade
Version history
0.44.2latest on PyPI · released May 18, 2026
Audit
Dependencies
pythonrequiredRuntime environment
ffmpegrequiredRequired for audio processing (must be in system PATH)
Agent activity
78 hits · last 30 days
node
72
OpenAI (training)
1
Resources
audio-separator — pip install audio-separator · libregistry