Spleeter Web

Spleeter Web is a web application for isolating or removing the vocal, accompaniment, bass, and/or drum components of any song. For example, you can use it to isolate the vocals of a track, or you can use it remove the vocals to get an instrumental version of a song.

It supports a number of different source separation models: Spleeter (4stems-model), Demucs, CrossNet-Open-Unmix, and D3Net.

The app uses Django for the backend API and React for the frontend. Celery is used for the task queue. Docker images are available, including ones with GPU support.

Table of Contents

• Features
• Demo site
• Getting started with Docker
• Getting started without Docker
• Configuration
  • Django settings
  • Environment variables
• Using cloud storage
• Deployment
• Common issues & FAQs
• Credits
• License

Features

• Supports Spleeter, Demucs, CrossNet-Open-Unmix (X-UMX), and D3Net source separation models
  • Each model supports a different set of user-configurable parameters in the UI
• Dynamic Mixes let you export and play back in realtime your own custom mix of the different components
• Import tracks by uploading a file (MP3, FLAC, WAV) or by YouTube link
  • Built-in YouTube search functionality (YouTube Data API key required)
• Persistent audio library with ability to stream and download your source tracks and mixes
• Customize number of background workers working on audio separation and YouTube imports
• Supports third-party storage backends like S3 and Azure Blob Storage
• Clean and responsive UI
• Support for GPU separation
• Fully Dockerized

Demo site

Homepage

Upload modal

Mixer

Getting started with Docker

Requirements

• 4 GB+ of memory (source separation is memory-intensive)
• Docker and Docker Compose

Instructions

1. Clone repo:

   $ git clone https://github.com/JeffreyCA/spleeter-web.git
   $ cd spleeter-web
   

2. (Optional) Set the YouTube Data API key (for YouTube search functionality):

   You can skip this step, but you would not be able to import songs by searching with a query. You would still be able to import songs via YouTube links though.

   Create an .env file at the project root with the following contents:

   YOUTUBE_API_KEY=<YouTube Data API key>
   

3. (Optional) Setup for GPU support: Source separation can be accelerated with a GPU (however only NVIDIA GPUs are supported).

   1. Install NVIDIA drivers for your GPU.

   2. Install the NVIDIA Container Toolkit. If on Windows, refer to this.

   3. Verify Docker works with your GPU by running sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

4. Download and run prebuilt Docker images:

   # CPU separation
   spleeter-web$ docker-compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up
   # GPU separation
   spleeter-web$ docker-compose -f docker-compose.gpu.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up
   

   Alternatively, you can build the Docker images from source:

   # CPU separation
   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
   # GPU separation
   spleeter-web$ docker-compose -f docker-compose.gpu.yml -f docker-compose.build.gpu.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up --build
   

5. Launch Spleeter Web

   Navigate to http://127.0.0.1:80 in your browser. Uploaded tracks and generated mixes will appear in media/uploads and media/separate respectively on your host machine.

Getting started without Docker

If you are on Windows, it's recommended to follow the Docker instructions above. Celery is not well-supported on Windows.

Requirements

• 4 GB+ of memory (source separation is memory-intensive)
• Python 3.6+ (link)
• Node.js 12+ (link)
• Redis (link)
• ffmpeg and ffprobe (link)
  • On macOS, you can install it using Homebrew or MacPorts
  • On Windows, you can follow this guide

Instructions

1. Set environment variables

   Make sure these variables are set in every terminal session prior to running the commands below.

   # Unix/macOS:
   (env) spleeter-web$ export YOUTUBE_API_KEY=<api key>
   # Windows:
   (env) spleeter-web$ set YOUTUBE_API_KEY=<api key>
   

2. Create Python virtual environment

   spleeter-web$ python -m venv env
   # Unix/macOS:
   spleeter-web$ source env/bin/activate
   # Windows:
   spleeter-web$ .\env\Scripts\activate
   

3. Install Python dependencies

   (env) spleeter-web$ pip install -r requirements.txt
   

4. Install Node dependencies

   spleeter-web$ cd frontend
   spleeter-web/frontend$ npm install
   

5. Ensure Redis server is running on localhost:6379 (needed for Celery)

   You can run it on a different host or port, but make sure to update CELERY_BROKER_URL and CELERY_RESULT_BACKEND in settings.py. It must be follow the format: redis://host:port/db.

6. Apply migrations

   (env) spleeter-web$ python manage.py migrate
   

7. Build frontend

   spleeter-web$ npm run build --prefix frontend
   

8. Start backend in separate terminal

   (env) spleeter-web$ python manage.py collectstatic && python manage.py runserver 127.0.0.1:8000
   

9. Start Celery workers in separate terminal

   Unix/macOS:

   # Start fast worker
   (env) spleeter-web$ celery -A api worker -l INFO -Q fast_queue -c 3
   
   # Start slow worker
   (env) spleeter-web$ celery -A api worker -l INFO -Q slow_queue -c 1
   

   This launches two Celery workers: one processes fast tasks like YouTube imports and the other processes slow tasks like source separation. The one working on fast tasks can work on 3 tasks concurrently, while the one working on slow tasks only handles a single task at a time (since it's memory-intensive). Feel free to adjust these values to your fitting.

   Windows:

   You'll first need to install gevent. Note however that you will not be able to abort in-progress tasks if using Celery on Windows.

   (env) spleeter-web$ pip install gevent
   

   # Start fast worker
   (env) spleeter-web$ celery -A api worker -l INFO -Q fast_queue -c 3 --pool=gevent
   
   # Start slow worker
   (env) spleeter-web$ celery -A api worker -l INFO -Q slow_queue -c 1 --pool=gevent
   

10. Launch Spleeter Web

    Navigate to http://127.0.0.1:8000 in your browser. Uploaded and mixed tracks will appear in media/uploads and media/separate respectively.

Configuration

Django settings

Environment variables

Here is a list of all the environment variables you can use to further customize Spleeter Web:

Using cloud storage (Azure Storage, AWS S3, etc.)

By default, Spleeter Web uses the local filesystem to store uploaded files and mixes. It uses django-storages, so you can also configure it to use other storage backends like Azure Storage or AWS S3.

You can set the environment variable DEFAULT_FILE_STORAGE (.env if using Docker) to either FILE (for local storage), AWS (S3 storage), or AZURE (Azure Storage).

Then, depending on which backend you're using, set these additional variables:

AWS S3:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_STORAGE_BUCKET_NAME

Azure Storage:

• AZURE_ACCOUNT_KEY
• AZURE_ACCOUNT_NAME
• AZURE_CONTAINER

CORS

To play back a dynamic mix, you may need to configure your storage service's CORS settings to allow the Access-Control-Allow-Origin header.

If you have ENABLE_CROSS_ORIGIN_HEADERS set, then you'll need to additionally set the Cross-Origin-Resource-Policy response headers of audio files to cross-origin. See this for more details.

Deployment

Spleeter Web can be deployed on a VPS or a cloud server such as Azure VMs, AWS EC2, DigitalOcean, etc. Deploying to cloud container services like ECS is not yet supported out of the box.

1. Clone this git repo

   $ git clone https://github.com/JeffreyCA/spleeter-web.git
   $ cd spleeter-web
   

2. (Optional) If self-hosting, update docker-compose.prod.selfhost.yml and replace ./media with the path where media files should be stored on the server.

3. In spleeter-web, create an .env file with the production environment variables

   Example .env file:

   APP_HOST=<domain name or public IP of server>
   DEFAULT_FILE_STORAGE=<FILE or AWS or AZURE>       # Optional (default = FILE)
   CELERY_FAST_QUEUE_CONCURRENCY=<concurrency count> # Optional (default = 3)
   CELERY_SLOW_QUEUE_CONCURRENCY=<concurrency count> # Optional (default = 1)
   YOUTUBE_API_KEY=<youtube api key>                 # Optional
   

   See Environment Variables for all the available variables. You can also set these directly in the docker-compose.*.yml files.

4. Build and start production containers

   For GPU separation, replace docker-compose.yml and docker-compose.build.yml below for docker-compose.gpu.yml and docker-compose.build.gpu.yml respectively.

   If you are self-hosting media files:

   # Use prebuilt images
   spleeter-web$ sudo docker-compose -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up -d
   # Or build from source
   spleeter-web$ sudo docker-compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.prod.yml -f docker-compose.prod.selfhost.yml up --build -d
   

   Otherwise if using a storage provider:

   # Use prebuilt images
   spleeter-web$ sudo docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
   # Or build from source
   spleeter-web$ sudo docker-compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.prod.yml up --build -d
   

5. Access Spleeter Web at whatever you set APP_HOST to. Note that it will be running on port 80, not 8000.

HTTPS support

Enabling HTTPS allows you to export Dynamic Mixes from your browser. To enable HTTPS, set APP_HOST to your domain name and CERTBOT_EMAIL to your email in .env and include -f docker-compose.https.yml in your docker-compose up command.

Common issues & FAQs

Credits

Special thanks to:

• tone.js
• youtube-dl
• react-dropzone-uploader
• react-music-player
• docker-nginx-certbot

And to all the researchers and devs behind the supported source separation models:

• Spleeter
• Demucs
• CrossNet-Open-Unmix
• D3Net

Turntable icon made from Icon Fonts is licensed by CC BY 3.0.

License

MIT