# audio-separator: CLI and Python Audio Stem Separation > audio-separator exposes Ultimate Vocal Remover models through a CLI and Python API. It suits developers who need vocals, instruments, and other audio stems in scripted or application-based workflows. **nomadkaraoke/python-audio-separator** — Easy to use stem (e.g. instrumental/vocals) separation from CLI or as a python package, using a variety of amazing pre-trained models (primarily from UVR) - Repository: https://github.com/nomadkaraoke/python-audio-separator - Stars: 1,437 · Forks: 208 - Language: Python - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/nomadkaraoke-python-audio-separator ## Why nomadkaraoke Built Audio Separator audio-separator addresses a concrete media-processing task: splitting mixed audio into component stems. Its most obvious result is a vocals file paired with an instrumental file for karaoke production. According to the README, available models can also isolate drums, bass, piano, and guitar, or perform tasks such as denoising and removing echo or reverb. The target users include people processing tracks from a terminal, developers writing batch jobs, and Python programmers embedding separation in another application. The project is not presented as a general audio editor or a framework for training separation models. It packages pre-trained models behind a Python interface, a command-line interface, and Docker images. That boundary matters for production use. The caller selects a model and supplies audio, but output depends on the model, source recording, and inference backend. Labels such as `Vocals` and `Instrumental` should not be interpreted as universal components with exact waveform-level guarantees. Production workflows need a fixed model and backend if repeatability matters. ## Model Formats and Audio Inputs Supported The README lists support for common audio formats, including WAV, MP3, FLAC, and M4A. Inference can use pre-trained models in PTH or ONNX format. This gives callers a choice of model representation instead of limiting the package to a single execution path. Audio Separator exposes models from Ultimate Vocal Remover, with the README crediting models trained by Anjok07. The Python project serves as an execution and integration layer for those assets. It provides model discovery and filtering, model selection, processing, output handling, and stem renaming through its CLI and API. Several execution paths exist. PyTorch models can use MPS on supported Apple Silicon hardware, while ONNX models can use the CoreML execution provider. CUDA uses the GPU ONNX runtime, CPU installations use the regular ONNX runtime, and the experimental Windows DirectML option uses `onnxruntime-directml` and `torch_directml`. Repository files include CPU, CUDA 11, CUDA 12, cloud, and RunPod Docker definitions. This variety is useful, but it creates a compatibility surface. Host architecture, operating system, Torch version, ONNX runtime package, and execution provider can all affect installation. A model working on a CUDA workstation may require different setup on macOS or Windows. Docker reduces host installation work, but the selected image must still match the machine and required acceleration. ## Docker Setup and the First CLI Run The shortest documented first use runs the published CPU Docker image and mounts the current directory at `/workdir`. If `input.wav` is already in that directory, use: ```bash docker run -it -v `pwd`:/workdir beveradb/audio-separator input.wav ``` The mount makes the input and output directory accessible inside the container. The README does not specify exact default output filenames for this invocation, so they should be checked in the mounted directory rather than assumed. For an NVIDIA GPU, the documented GPU image and device flag are: ```bash docker run -it --gpus all -v `pwd`:/workdir beveradb/audio-separator:gpu input.wav ``` If the GPU is not detected, the README points to checking whether the Docker runtime passes the GPU through correctly. That check separates container configuration problems from model or audio processing failures. Environment inspection is available through: ```bash audio-separator --env_info ``` For CUDA, the documented acceptance message includes `ONNXruntime has CUDAExecutionProvider available, enabling acceleration`. On Apple Silicon, the check should report MPS in Torch, an ARM processor, and the CoreML ONNX execution provider. Verifying this output before a long batch run gives operators a concrete deployment check instead of relying on inference failures. ## Pip and Conda Installation by Hardware Users who do not need Docker can install the GPU extra with Pip: ```bash pip install "audio-separator[gpu]" ``` The README documents CUDA 11.8 and 12.2 as supported versions. It also gives this Conda installation: ```bash conda install pytorch=*=*cuda* onnxruntime=*=*cuda* audio-separator -c pytorch -c conda-forge ``` For M1 or newer Apple Silicon hardware running macOS Sonoma or newer, the README gives: ```bash pip install "audio-separator[cpu]" ``` Although this is the `cpu` package extra, the documented Apple configuration still benefits from hardware acceleration. PyTorch models use MPS, and ONNX models can use CoreML. Apple Silicon requires PyTorch 2.13 or newer and earlier than PyTorch 3. Other platforms specify PyTorch 2.3 or newer. Windows DirectML support is marked experimental. The `pyproject.toml` defines its dependencies as `onnxruntime-directml>=1.17` and `torch_directml`, but the README excerpt does not provide a complete DirectML tutorial. It is therefore a less certain starting point than the documented Docker, CUDA, and Apple paths. FFmpeg is also identified as a dependency. The package metadata includes audio and inference libraries such as `librosa`, `numpy`, `pydub`, `scipy`, `soundfile`, `onnx-weekly`, and Torch. Installation is consequently a backend setup exercise rather than a matter of placing one executable on `PATH`. ## CLI Control and Python Embedding The CLI is intended for direct use, scripts, and batch processing. The README includes commands for listing models, filtering results, limiting results, requesting JSON output, inspecting all CLI options, processing with multiple models, handling output and errors, and renaming stems. Model discovery therefore forms part of the same interface used for separation. For Python projects, audio-separator can be installed as a dependency and invoked through its `Separator` class. The README documents batch processing, multiple-model processing, output and error handling, and stem renaming. This is a broader API surface than a one-function wrapper, which matters when an application needs predictable file naming or centralized exception handling. The README does not include a complete Python example or the full constructor signature in the available section, so inventing imports or parameters would risk producing invalid integration code. Developers should read the current `Separator` documentation and verify model identifiers, output arguments, callbacks, and error behavior against the installed package version. Remote API usage is also documented. However, the README section listed in the table of contents does not establish an endpoint, authentication scheme, request schema, service limit, or data-retention policy. A hosted deployment cannot be evaluated from the Python package alone. Operators need separate documentation before sending client audio to a remote service. ## Where Audio Separator Is the Wrong Tool audio-separator is the wrong choice when an application needs a mathematical guarantee that every sample belongs unambiguously to one source. Source separation is model inference, not a documented contract for exact waveform reconstruction. The README names useful stem categories, but it does not promise zero bleed, perfect isolation, exact sample preservation, or identical output across models and backends. Model delivery is another limitation. The README describes model discovery and filtering, but it does not guarantee complete offline operation or describe every failure mode when a hosted model asset is unavailable. Batch processing must account for model availability and local storage instead of assuming that installing the package contains every model needed for inference. Hardware paths are not interchangeable in practice. CPU execution is supported, but the README does not promise any particular throughput for a model, track length, or machine. CUDA has explicit supported versions, Apple acceleration has hardware and operating-system requirements, and DirectML is experimental. For frame-accurate editing or deterministic mixing, a digital audio workstation is more appropriate. Audio Separator belongs earlier in a media pipeline, where creating separate stems is itself the goal. ## Upgrade Work and MIT License Boundaries The repository is not archived, and its last push was on 2026-10-01. Releases v0.47.0, v0.46.0, and v0.45.0 were published in August 2026. The README does not publish a support lifetime or a compatibility guarantee for future operating-system and hardware releases. Upgrade requirements are explicit in `pyproject.toml`. Python 3.10 or newer is required, except Python 3.14.1 is excluded. Python 3.13 adds the `audioop-lts` dependency. Apple ARM systems require `torch>=2.13,<3`, while other platforms permit `torch>=2.3,<3`. Other runtime constraints include `numpy>=2`, `scipy>=1.13.0,<2.0.0`, `librosa>=0.10`, and `onnx-weekly`. This dependency matrix creates maintenance work. A host or Python upgrade can require rebuilding an environment or container even if application code is unchanged. Reproducible deployments should retain the package version, selected model, installation route, and accelerator image as one configuration. The repository includes Poetry metadata, tests, Dockerfiles, and a lock file, but the README does not document a model migration or rollback procedure. The Python package is identified as MIT licensed. Its license governs the wrapper code under its terms. Separately downloaded model files may carry their own notices or conditions, so project users should inspect the terms attached to each model asset rather than assuming every downloaded file is covered by the package license. ## Conclusion Adopt audio-separator when a command-line script or Python application can download and run a supported pre-trained model, then verify the audio format, selected model, output location, and available accelerator before building automation around it. Do not choose it when offline model delivery, rollback documentation, or exact sample-level source allocation is mandatory. For the first deployment, confirm that the intended model is available and that `audio-separator --env_info` reports the expected backend. ## FAQ ### What is audio-separator used for? It separates audio into stems such as vocals and instruments. The README also lists drums, bass, piano, guitar, denoising, and echo or reverb removal among supported model tasks. ### How do I install audio-separator with NVIDIA CUDA? The README gives `pip install "audio-separator[gpu]"` for CUDA and documents CUDA 11.8 and 12.2. It also provides a Conda command and Docker GPU images. ### Does audio-separator support CPU-only and Apple Silicon systems? Yes. The CPU extra is used for CPU installation, while Apple Silicon PyTorch models use MPS and ONNX models can use CoreML. Apple Silicon requires PyTorch 2.13 or newer and earlier than PyTorch 3. ## Sources - [Issues](https://github.com/nomadkaraoke/python-audio-separator/issues) - [License: MIT](https://github.com/nomadkaraoke/python-audio-separator/blob/main/LICENSE) - [nomadkaraoke/python-audio-separator on GitHub](https://github.com/nomadkaraoke/python-audio-separator) - [README](https://github.com/nomadkaraoke/python-audio-separator/blob/main/README.md) - [Releases](https://github.com/nomadkaraoke/python-audio-separator/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nomadkaraoke-python-audio-separator