Open-source music source separation.
Uncompose separates recorded music into vocals, drums, bass, and instruments — locally, openly, and without a subscription. It is a local-first tool for musicians who want to isolate or reduce parts of a recording for practice, transcription, remixing, or study, while keeping control over their audio, models, and workflow.
v0.2.0 is on PyPI. Development happens in the
open on the issue tracker, with
decisions recorded in docs/adr/ and each release described in
docs/releases/.
Uncompose ships on PyPI with uv as the recommended installer — uv is also what Uncompose itself uses at runtime, so have it installed either way:
uvx uncompose separate song.mp3 # run without installing
uv tool install uncompose # or install the `uncompose` command
pip install uncompose # pip works too; uv is still needed at runtimeThe package is small; the heavy part comes on first use. Uncompose then builds its
engine environment (PyTorch and the separation stack, several GB, CUDA build by
default) into ~/.local/share/uncompose/ — announced with progress, one time per
version. On a machine without an NVIDIA GPU, make that first run route torch to the
CPU build:
UV_TORCH_BACKEND=cpu uncompose separate song.mp3Later runs reuse the environment; the variable is only needed while it is first built. Model weights (≈900 MB for the default preset) download automatically on first use, hash-verified, with each model's license status shown.
uncompose separate song.mp3That produces song.stems/ next to the input:
song.stems/
├── vocals.wav drums.wav bass.wav guitar.wav keys.wav other.wav
├── engine.log
└── job.json
Every run prints a header first — input, preset, models with their license status,
device, output folder — so you know what is about to happen before the slow part
starts. Repeated runs on the same input never overwrite: you get song.stems-2/,
song.stems-3/, and so on. job.json records everything needed to understand or
rerun the job (input hash, models, device, timings); it is written last, so its
presence means the folder is complete.
Then:
uncompose play vocals # audition a stem of the last job (mpv or ffplay)
uncompose open # open the last job's folder
uncompose models list # cached models, license status, hardware needs
uncompose models fetch 6-stem # pre-download weights before a session6-stem(default): vocals, drums, bass, guitar, keys, other. A Mel-Band RoFormer vocal pass followed by htdemucs_6s for the rest.2-stem(--preset 2-stem): vocals and instrumental. GPU-required.
The keys.wav caveat: the v0.1 model behind it is piano-trained. Acoustic piano
lands in keys.wav; synths and organs usually land in other.wav. The stem keeps
the name keys so nothing changes when a broader keys model arrives.
Device is auto-detected: CUDA when an NVIDIA GPU is present, CPU otherwise
(--device cpu|cuda overrides). On the machine of record a song takes 1 to 5
minutes on GPU; CPU produces identical stems but takes tens of minutes — correct,
just slow.
uncompose composes with two sibling tools — uncompose-project (the manifest
that records where every file came from and how it was judged) and
uncompose-compare (side-by-side stem auditioning) — through one --project
flag. uncompose separate --project . separates and registers the job;
uncompose compare --project . compares stems by manifest reference and records
the verdict back into the project.
The end-to-end walkthrough performs the whole slice from
three installed wheels — install, project init, separate --project, show,
compare --project, verify — with nothing checked out. The
demo/ directory rebuilds that finished project from synthetic
fixtures in seconds, no GPU or model downloads required.
Any executable named uncompose-<command> on PATH becomes a subcommand
(uncompose compare runs uncompose-compare). See
docs/extensions.md for the extension-author guide and a
minimal example extension.
Uncompose is Linux-only for v0.1: NVIDIA CUDA is the primary target with CPU as the
slow-but-correct fallback, and the machine of record is Ubuntu Studio 26.04 with an
RTX 4060 Ti. macOS and Windows are untested; reports welcome. It needs ffmpeg on
your PATH to read and write audio. Install it with your system package manager, for example sudo apt install ffmpeg
on Debian/Ubuntu. If ffmpeg is missing, Uncompose stops before a run with a one-line
install message rather than a cryptic error.
Uncompose processes audio you provide, entirely on your own machine — nothing is uploaded anywhere. You are responsible for making sure you have the rights to the audio you separate, and the rights to what you do with the resulting stems follow from the rights you hold in the input. Separating a recording does not grant you any rights to it.
The separation models Uncompose can download carry their own licenses, some of which restrict commercial use; Uncompose surfaces each model's license status but it is up to you to comply with it.
MIT © Dominic Hanzely