If you have ever wanted a karaoke track, an isolated vocal, or separate drum and bass files, you have probably encountered the awkward side of open-source audio separation: model names are cryptic, command-line options multiply quickly, and the first run may download a large model before producing anything useful.
Split My Music packages that workflow as a self-hosted web application. You upload an audio file, choose a plain-English separation goal, wait for the model to run, and download the resulting tracks from a browser. The project is useful when the audio should stay on a computer, home server, or NAS instead of being uploaded to a third-party service.
This tutorial uses the stable v1.0.0 release and the CPU Docker path documented by the project. It does not claim that every model or GPU setup has been tested.
TL;DR
Clone the release, start the CPU container, open http://localhost:7860, upload a song, select Vocals & Music, and download the generated files. The first model run downloads model weights into a persistent Docker volume. The application has no authentication, so keep it on localhost or behind an authenticated reverse proxy.
Prerequisites
You need:
- Docker Engine with the Compose plugin
- Enough disk space for the image, temporary audio, results, and the first model download
- An audio file that you have the right to process
The release documentation lists Python 3.12 and FFmpeg for a source checkout, but Docker installs the runtime dependencies for you. The repository's CPU Dockerfile installs FFmpeg, PyTorch CPU wheels, and the Python dependencies inside the image.
Start the local CPU service
Use the tagged release so the command remains tied to a reviewed version rather than an evolving default branch:
git clone --branch v1.0.0 --depth 1 https://github.com/paladini/split-my-music.git
cd split-my-music
docker compose up -d --build
The Compose file publishes container port 7860 to the host. It also keeps two kinds of data outside the container: model weights in the model-cache volume and finished jobs in ./data/jobs.
Open http://localhost:7860. The first model run may take longer because the default model is downloaded. The README estimates roughly 50 to 80 MB for the default models, although download size can change with upstream assets.
You can verify the service without uploading a file:
curl http://localhost:7860/health
The application also exposes configuration information through /api/config, which is useful for checking whether the running process detects CPU or NVIDIA GPU support.
Separate vocals and music
The main workflow has three decisions:
- Drop an MP3, WAV, FLAC, M4A, AAC, OGG, or OPUS file into the upload area.
- Choose a goal such as Vocals & Music, Vocals, Drums, Bass & Other, or Full Band (6 Tracks).
- Choose an output format and start the job.
For a first run, keep the default model and choose WAV. WAV is larger than MP3, but it avoids adding lossy compression while you inspect the result. The project also supports FLAC and MP3 at 320 kbps.
The interface reports server-side stages such as upload, audio preparation, model loading, separation, and export. These are stages, not a promise of a precise percentage. Separation time depends on the input, selected model, and available hardware.
When the job completes, use the in-browser players to preview each track. You can download individual tracks or a ZIP archive. Results are stored below the jobs directory and are cleaned up according to the configured retention limits.
Make the deployment reproducible
The default Compose file is intentionally conservative for a CPU host. The relevant settings can be overridden through environment variables:
SPLIT_MAX_UPLOAD_MB=100 \
SPLIT_MAX_DURATION_MINUTES=10 \
SPLIT_RETENTION_HOURS=12 \
docker compose up -d
The defaults are a 200 MB upload limit, 20 minutes per input, one active job, five queued jobs, 500 MB of required free disk space, 24 hours of retention, and a maximum of 20 stored jobs. These limits are read by the application configuration in src/config.py.
Before starting a deployment, validate the rendered Compose configuration:
docker compose config --quiet
This catches malformed environment interpolation and Compose structure errors before containers start. In my release checkout, this check passed, as did Python bytecode compilation for main.py and src/.
NVIDIA GPU mode
The repository includes a GPU override, but it has a narrower support boundary than the CPU path. The documented command is:
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d --build
The host needs a working nvidia-smi command and the NVIDIA Container Toolkit. The override replaces the CPU service, so do not run both variants on the same published port.
The project states that the GPU Docker files were validated with Compose configuration and CI, but not executed by the author on physical NVIDIA hardware for the v1.0.0 release. Apple Silicon, AMD, and Intel GPUs are not accelerated inside these Linux containers according to the README. Treat GPU deployment as an environment-specific task that needs its own validation.
Why the local boundary matters
Split My Music is local by design. Uploaded inputs and generated tracks are processed on the host running the container. The first use of a model can make an outbound request to download weights, but the application does not need a cloud audio API for separation.
The implementation also includes several practical guardrails:
- file names are sanitized before they become storage paths;
- uploads are checked with
ffprobeand bounded by size and duration; - user input is not assembled into shell commands;
- output files are served only when they belong to a completed, validated job;
- queue limits and free-disk checks run before work is accepted;
- interrupted jobs are marked for recovery after a restart;
- temporary input and work directories are removed when a job finishes or fails.
These controls reduce common local-service risks, but they do not turn the application into a multi-user service.
Security boundary and limitations
The most important limitation is simple: Split My Music has no user authentication. Do not expose port 7860 directly to the public internet. For remote access, put it behind a reverse proxy or VPN with HTTPS and authentication, then reduce upload and duration limits for your environment.
Model weights and third-party components have their own licenses. The project's third-party inventory explains that the application code is MIT licensed, while individual model files may carry different terms. Read those terms before redistributing models or generated material.
Finally, source separation is not magic. Vocal bleed, artifacts, slow CPU processing, insufficient memory, and model-specific quality differences are normal possibilities. The README explicitly says that speed and perceptual quality were not benchmarked across models.
FAQ
Does the first run need internet access?
Usually yes, if the selected model is not already cached. After the model is present, audio processing is local, subject to the behavior of the selected dependencies and model.
Can I preserve the original channel layout?
The project preserves mono and stereo inputs and downmixes inputs with more than two channels before inference. Check the resulting files when working with surround material.
Why does the UI show CPU?
The application reports the hardware detected by PyTorch and ONNX Runtime. For NVIDIA acceleration, verify the host driver, toolkit, GPU Compose override, and container configuration instead of assuming that a GPU is available.
How do I remove old results?
Finished jobs are subject to retention and maximum stored-job limits. You can also inspect the host data/jobs directory when stopping the service and backing up or removing local results according to your own retention policy.
Takeaway
Split My Music is a useful local wrapper around model-based audio separation because it makes the ordinary path understandable: Docker, browser upload, a named goal, and downloadable tracks. Its strongest feature is also its boundary. It is a private single-user or trusted-LAN tool, not an authenticated public upload service.
If you try it, what would be more valuable for your workflow: a smaller CPU-oriented model catalog, better batch processing, or a stronger remote-access setup?
AI assistance disclosure: I used AI assistance to organize and edit this tutorial. The commands, version references, project behavior, and security limitations were checked against the v1.0.0 repository and its primary documentation.
Top comments (0)