# Spleeter Web: self-hosted source separation with a mixer on top > Spleeter Web is a Django and React application that separates a song into vocal, accompaniment, bass and drums, supports three separation models, and adds a mixer that lets you export your own balance. It is Docker-first, memory-hungry, and MIT licensed. **JeffreyCA/spleeter-web** — Self-hostable web app for isolating the vocal, accompaniment, bass, and drums of any song. Supports Spleeter, Demucs, BS-RoFormer. Started in 2019. - Repository: https://github.com/JeffreyCA/spleeter-web - Website: https://jeffreyca.github.io/spleeter-web/ - Stars: 562 · Forks: 86 - Language: Python - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/jeffreyca-spleeter-web ## A full web application around a separation model Spleeter Web is a web application for isolating or removing the vocal, accompaniment, bass, and/or drum components of any song. The README gives both directions of use: you can use it to isolate the vocals of a track, or you can use it to remove the vocals to get an instrumental version of a song. The architecture is three pieces and they are all named in the README. Django is used for the backend API, React is used for the frontend, and Celery is used for the task queue. Docker images are available, including ones with GPU support. The feature list is what makes it more than a wrapper around a command line tool. Dynamic Mixes let you export and play back your own custom mix of the different components, in realtime. You can import tracks by uploading an audio file or by a YouTube link, with built-in YouTube search functionality that needs a YouTube Data API key. Output can be lossy MP3 or lossless FLAC and WAV. There is a persistent audio library with the ability to stream and download your source tracks and mixes. The number of background workers working on audio separation and YouTube imports is configurable. Third-party storage backends like S3 and Azure Blob Storage are supported, and the UI is described as clean and responsive. The mixer is the feature that separates this from the underlying models, and it is the reason to run your own instance rather than call an API. The project is MIT licensed, started in 2019 according to the repository description, and the release history shows active work: v4.1.0 on 2025-11-29 adding BS-RoFormer support, v4.0.0 on 2025-10-25 retiring D3Net and X-UMX, and v3.21.1 the same day. The last push was on 2026-10-18. ## Three supported models, two retired ones The supported models are Spleeter with the 4stems-model and 5stems-model variants, Demucs v3 and v4, and BS-RoFormer. Three quite different approaches to the same problem, and the choice affects what you get out of the separation. Two models have been retired. CrossNet-Open-Unmix, known as X-UMX, and D3Net are both listed under retired models, and the v4.0.0 release title records the retirement along with dependency updates. The migration path is documented rather than left to guesswork. The README note says that if you want the last version of Spleeter Web supporting D3Net and X-UMX, you should check out the v3 branch. And importantly for existing users, mixes previously created with D3Net and X-UMX remain available for playback and download on all versions of Spleeter Web. That second half is the detail that matters operationally. Retiring a model is easy when you are starting fresh, and hard when people have a library of separated tracks, so the project kept the old artefacts readable rather than making the upgrade a data migration. The stack behind them is pinned hard in the requirements file, and the pins are annotated. TensorFlow is held at 2.15.1 with a comment saying that 2.16 and later are not compatible due to the deprecation of the Estimator APIs, which Spleeter uses. Demucs is pinned at 4.0.1, torch and torchaudio at 2.9.1, Django at 4.2.26, and httpx is overridden at 0.19.0 to override the hard llvmlite dependency that Spleeter brings in. There is also a warning not to upgrade norbert to 0.20.0 or later until a specific Spleeter pull request is fixed. ## Docker first, with the compose overlays you have to combine The Docker path is the recommended one, and the requirements are short. You need 4 GB or more of memory, because source separation is memory-intensive, plus Docker and Docker Compose. The clone step is: ```sh $ git clone https://github.com/JeffreyCA/spleeter-web.git $ cd spleeter-web ``` Then you run a compose command that layers three files. The CPU separation variant is: ```sh spleeter-web$ docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up ``` And the GPU variant swaps the first file: ```sh spleeter-web$ docker compose -f docker-compose.gpu.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up ``` If you would rather build the images yourself, the same command adds a build overlay and the --build flag: ```sh spleeter-web$ docker compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up --build ``` The layering is a bit of work to reason about, and the repository top level explains why there are so many. There is a base compose file, a dev variant, a GPU variant, two build variants, a prod variant, a prod selfhost variant and an https variant with certbot. One platform note matters for planning. On Apple Silicon and other AArch64 systems, the Docker images need to be built from source, since the published images are not built for that architecture. GPU acceleration has its own prerequisites, and only NVIDIA GPUs are supported. You install the NVIDIA drivers, then the NVIDIA Container Toolkit, and verify it with a CUDA image running nvidia-smi. ## The running without Docker path needs six tools The manual path is documented for people who cannot or do not want to use containers, and the README warns about one platform in particular. If you are on Windows, it is recommended to follow the Docker instructions, because Celery is not well-supported on Windows. The requirements list is six items. You need x86-64 architecture, and for AArch64 systems you should use Docker. You need 4 GB or more of memory. You need Python 3.11 or newer, Node.js 16 or newer, Redis, and ffmpeg with ffprobe. There is also a Hugging Face CLI in the list, which the BS-RoFormer models need for downloading weights. The environment variables come first, and the README insists they be set in every terminal session before the commands run: ```sh # Unix/macOS: (env) spleeter-web$ export YOUTUBE_API_KEY= # Windows: (env) spleeter-web$ set YOUTUBE_API_KEY= ``` Then a virtual environment, which is spelled out per platform because the activation path differs: ```sh spleeter-web$ python -m venv env # Unix/macOS: spleeter-web$ source env/bin/activate # Windows: spleeter-web$ .\env\Scripts\activate ``` The YouTube API key is optional in the Docker path too, in the sense that you can still import songs by YouTube link, you just lose the search by query. Once it is running, the application is served on port 80 at the loopback address, and uploaded tracks and generated mixes appear in media/uploads and media/separate respectively on the host machine. ## Celery and Redis, with a fast queue and a slow queue The compose file shows how the task queue is actually arranged, and the design is worth reading because it is the part that makes the app usable with a handful of workers. Redis runs as a separate service, exposed on port 6379 with a named volume for its data, and both the broker and the result backend point at it. The Celery environment sets CELERY_BROKER_URL and CELERY_RESULT_BACKEND to the Redis database, and the Django settings module is set to a docker-specific one. The interesting setting is the pair of concurrency values. CELERY_FAST_QUEUE_CONCURRENCY defaults to 3 and CELERY_SLOW_QUEUE_CONCURRENCY defaults to 1. There is a CPU_SEPARATION flag as well, and the environment block for the api service mirrors the celery one, so the two share the same broker and the same split. So the application runs two kinds of work at different speeds, with more workers on the fast queue and fewer on the slow one. Given that separation is the expensive part and a YouTube import is comparatively quick, a plausible reading is that the split is between the two, though the README does not spell out which queue is which. Either way, the point is that you can scale the worker pools separately, and the two numbers are the knobs. The package.json in the repository confirms the Django side of the arrangement, with scripts that run the Django development server alongside the frontend dev server, a celery worker command, migrations, collectstatic, and a flush command for clearing the database. There is also a clean script that empties the media directories. ## Recovering the database is an explicit workflow The table of contents includes a section on recovering from a lost database, and the presence of that section is a sign of how the application stores its state. The compose file shows a SQLite volume mounted into the api service, and the settings have a docker-specific module. So the persistent state of the installation is a SQLite file in a named volume, and the media lives in separate volumes for the frontend assets, the static files and the uploads. That is a simple deployment shape and it has a simple consequence. There is no external database to operate, and no shared database between replicas, so a backup is a file copy. The alternative to losing it is the recovery workflow, and the project treats that as a documented procedure rather than an emergency. The scripts in the package.json support the operational tasks this implies. There is a migrate script that runs makemigrations followed by migrate, a flush command using the no-input flag, and the clean command that empties the separated output and the uploads directory. The CHANGELOG.md and the AGENTS.md in the root are the other two files you would expect in a project that takes its own release process seriously. The cloud storage support is the escape hatch for anyone who outgrows a local SQLite file. The requirements include boto3 and azure-storage-blob, and the compose environment block lists a set of AWS and Azure variables, including bucket name, custom domain, region and signature version on the S3 side, and account key, account name, container and custom domain on the Azure side. django-storages is the library that makes Django use them. ## Conclusion Adopt Spleeter Web if you want to run source separation on your own hardware, you have at least 4 GB of memory, and you want to remix the stems yourself rather than accept a preset balance. Do not adopt it if you need a hosted service or a stable public API, since it is a self-hosted application with a SQLite-backed library and a Celery queue you have to operate. Before you deploy, decide which model to use, because the retired X-UMX and D3Net models are only available on the v3 branch, and check the compose file you pick, since the CPU and GPU variants are separate overlays that have to be combined with the prod and selfhost ones. ## FAQ ### How do I run Spleeter Web with Docker? Clone the repository, then run a compose command that layers the base file with the prod and prod selfhost overlays: `docker compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up` for CPU separation, or swap in docker-compose.gpu.yml for GPU. You need 4 GB or more of memory, and on Apple Silicon the images must be built from source. ### Which separation models does Spleeter Web support? Spleeter with the 4stems-model and 5stems-model variants, Demucs v3 and v4, and BS-RoFormer. The X-UMX and D3Net models have been retired, and the last version supporting them is on the v3 branch, though mixes created with them remain playable and downloadable on all versions. ### What does the Dynamic Mixes feature in Spleeter Web do? It lets you export and play back your own custom mix of the separated components in realtime, rather than accepting a fixed balance. The output can be lossy MP3 or lossless FLAC and WAV, and the application keeps a persistent library of source tracks and mixes you can stream or download. ### What does Spleeter Web need before I run it without Docker? Python 3.11 or newer, Node.js 16 or newer, Redis, ffmpeg and ffprobe, the Hugging Face CLI, 4 GB or more of memory, and x86-64 architecture. The README recommends Docker on Windows, because Celery is not well-supported there. ## Sources - [JeffreyCA/spleeter-web on GitHub](https://github.com/JeffreyCA/spleeter-web) - [License: MIT](https://github.com/JeffreyCA/spleeter-web/blob/master/LICENSE) - [Project website](https://jeffreyca.github.io/spleeter-web/) - [README](https://github.com/JeffreyCA/spleeter-web/blob/master/README.md) - [Releases](https://github.com/JeffreyCA/spleeter-web/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jeffreyca-spleeter-web