{"id":6313,"library":"audio-separator","title":"Audio Separator","description":"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.","status":"active","version":"0.44.1","language":"en","source_language":"en","source_url":"https://github.com/karaokenerds/python-audio-separator","tags":["audio","stem-separation","music","machine-learning","AI","signal-processing"],"install":[{"cmd":"pip install audio-separator","lang":"bash","label":"Default (CPU)"},{"cmd":"pip install \"audio-separator[cpu]\"","lang":"bash","label":"Explicit CPU"},{"cmd":"pip install \"audio-separator[gpu]\"","lang":"bash","label":"Attempt GPU (see warnings)"}],"dependencies":[{"reason":"Runtime environment","package":"python","version":">=3.10"},{"reason":"Required for audio processing (must be in system PATH)","package":"ffmpeg","optional":false}],"imports":[{"symbol":"Separator","correct":"from audio_separator import Separator"}],"quickstart":{"code":"import os\nfrom audio_separator import Separator\n\n# Ensure a dummy audio file exists for demonstration, or provide a real path\n# For a runnable example, replace with an actual audio file path\naudio_file_path = os.environ.get('AUDIO_FILE_PATH', 'input_audio.wav')\noutput_directory = os.environ.get('OUTPUT_DIR', 'separated_stems')\nmodel_name = os.environ.get('MODEL_NAME', 'UVR_MDXNET_KARA_2')\n\n# Create dummy input file if it doesn't exist for demonstration purposes\nif not os.path.exists(audio_file_path):\n    # This part is for demonstration only and won't create a valid audio file\n    # In a real scenario, `input_audio.wav` would be a proper audio file.\n    print(f\"Warning: '{audio_file_path}' not found. Please provide a real audio file.\")\n    # Example: Create a tiny placeholder file (not actual audio)\n    with open(audio_file_path, 'wb') as f:\n        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')\n\n# Initialize the Separator\nseparator = Separator(\n    audio_file=audio_file_path,\n    model_name=model_name,\n    output_dir=output_directory,\n    output_format='wav' # Specify output format (e.g., 'wav', 'mp3')\n)\n\n# Perform the separation\nprint(f\"Separating '{audio_file_path}' using model '{model_name}'...\")\nprimary_stem_path, secondary_stem_path = separator.separate()\n\nprint(f\"Primary stem saved at: {primary_stem_path}\")\nprint(f\"Secondary stem saved at: {secondary_stem_path}\")\n\n# Clean up dummy file and directory for demonstration\nif os.path.exists(audio_file_path) and audio_file_path == 'input_audio.wav':\n    os.remove(audio_file_path)\nif os.path.exists(output_directory) and output_directory == 'separated_stems':\n    # In a real scenario, you might want to keep the output.\n    import shutil\n    shutil.rmtree(output_directory)\n    print(f\"Cleaned up temporary output directory: {output_directory}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"FFmpeg is a mandatory dependency for `audio-separator` to handle audio processing. It must be installed separately and available in your system's PATH.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}