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, Tasnet, and CrossNet-Open-Unmix.

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, Tasnet, and CrossNet-Open-Unmix (X-UMX) source separation models
  • Each model supports a different set of user-configurable parameters in the UI
• Dynamic Mixes lets you control the outputs of each component while playing back the track in real-time
• 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.

   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:

   # For regular CPU separation
   spleeter-web$ docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
   # For GPU separation
   spleeter-web$ docker-compose -f docker-compose.gpu.yml -f docker-compose.dev.yml up
   

   Alternatively, you can build the Docker images from source:

   # For regular CPU separation
   spleeter-web$ docker-compose -f docker-compose.yml -f docker-compose.build.yml -f docker-compose.dev.yml up --build
   # For GPU separation
   spleeter-web$ docker-compose -f docker-compose.gpu.yml -f docker-compose.build.gpu.yml -f docker-compose.dev.yml up --build
   

5. Launch Spleeter Web

   Navigate to http://127.0.0.1:8000 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 using Homebrew or MacPorts
  • On Windows, you can follow this guide

Instructions

1. Set environment variables

   Make sure these variables are set when running all subsequent commands.

   # Unix/macOS:
   (env) spleeter-web$ export DJANGO_DEVELOPMENT=true
   (env) spleeter-web$ export YOUTUBE_API_KEY=<api key>
   # Windows:
   (env) spleeter-web$ set DJANGO_DEVELOPMENT=true
   (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. Start frontend

   spleeter-web$ npm run dev --prefix frontend
   

8. Start backend in separate terminal

   (env) spleeter-web$ python manage.py runserver 0.0.0.0: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 resource-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

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.

To do this, edit django_react/settings_docker.py (if using Docker) or django_react/settings.py and set DEFAULT_FILE_STORAGE to another backend like api.storage.S3Boto3Storage or api.storage.AzureStorage.

Then, set the following environment variables (.env if using Docker), depending on which backend you're using:

S3:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_STORAGE_BUCKET_NAME

Azure:

• 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.

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. If you want your server to self-host the media files instead of using a cloud storage provider, then first edit django_react/settings_docker.py and uncomment this line:

   DEFAULT_FILE_STORAGE = 'api.storage.FileSystemStorage'
   

   Next, update docker-compose.prod.selfhost.yml and replace /path/to/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

   .env file:

   APP_HOST=<domain name or public IP of server>
   AWS_ACCESS_KEY_ID=<access key id>                 # Optional
   AWS_SECRET_ACCESS_KEY=<secret key>                # Optional
   AWS_STORAGE_BUCKET_NAME=<bucket name>             # Optional
   AWS_S3_CUSTOM_DOMAIN=<custom domain>              # Optional
   AZURE_ACCOUNT_KEY=<account key>                   # Optional
   AZURE_ACCOUNT_NAME=<account name>                 # Optional
   AZURE_CONTAINER=<container name>                  # Optional
   AZURE_CUSTOM_DOMAIN=<custom domain>               # Optional
   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
   

   These values are referenced in django_react/settings_docker.py and docker-compose.yml, so you can also edit those files directly to set your production settings.

4. Build and start production containers

   To enable GPU separation, substitute docker-compose.yml and docker-compose.build.yml for docker-compose.gpu.yml and docker-compose.build.gpu.yml below 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.

Common issues & FAQs

Credits

Special thanks to:

• Spleeter
• Demucs/Tasnet
• CrossNet-Open-Unmix
• tone.js
• youtube-dl
• react-dropzone-uploader
• react-music-player

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

License

MIT