higginsrob/htdemucs repository overview

⁠Docker + HTDemucs Web Application

A modern web application for audio source separation using Demucs⁠. Split music tracks into separate stems (bass, drums, vocals, and other instruments) through an intuitive web interface with real-time progress tracking.

⁠Based On

This project is based on xserrat/docker-facebook-demucs⁠, which provides an excellent Dockerized implementation of Demucs. This repository extends that foundation with a full-featured web application, real-time processing updates, YouTube integration, and an interactive audio player.

⁠Features

• 🎵 Web-Based Interface - Upload audio files or paste YouTube URLs directly in your browser
• 📊 Real-Time Progress - Watch separation progress with live updates via Socket.IO
• 🎚️ Interactive Audio Player - Play and mix separated stems with individual volume controls
• 📋 Job Queue Management - Process multiple tracks and view job history
• 🎬 YouTube Integration - Download and process audio from YouTube videos automatically
• 🎯 Multiple Models - Choose from htdemucs, htdemucs_ft, htdemucs_6s, and more
• 🔄 Persistent Storage - All processed tracks saved and accessible via the UI
• 🎨 Modern UI - Clean, responsive interface with dark theme support

⁠Screenshots

⁠Security

This application is intended for local or trusted LAN use only.

• The HTTP API has no authentication. Anyone who can reach the server can upload jobs, process YouTube URLs, list/delete jobs, and stream results.
• Do not expose port 8080 to the public internet without putting authentication, rate limiting, and network isolation in front of it.
• YouTube downloads run via yt-dlp inside the server container (no Docker socket / privileged mode required).

⁠Quick Start

⁠Prerequisites

• Docker installed and running
• Make utility (standard on macOS/Linux)
• 4GB+ RAM recommended
• Optional: NVIDIA GPU with CUDA support for faster processing

Check your system:

make check

⁠Option 1: Using Pre-Built Images from Docker Hub

The fastest way to get started is using our pre-built images from Docker Hub:

# Run the server (it will automatically pull the image)
docker run -d --rm \
  --name htdemucs \
  -p 8080:8080 \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/models:/data/models \
  higginsrob/htdemucs:latest

With GPU support:

docker run -d --rm \
  --name htdemucs \
  --gpus all \
  -p 8080:8080 \
  -v $(pwd)/output:/app/output \
  -v $(pwd)/models:/data/models \
  higginsrob/htdemucs:latest

Then open http://localhost:8080⁠ in your browser!

⁠Option 2: Running the Development Server

1. Clone this repository

   git clone [email protected]:higginsrob/htdemucs.git demucs
   cd demucs
   

   Copy

2. Start the server

   make dev
   

   Copy

   This will:

   • Build the Docker image (first time only)
   • Start the web server on http://localhost:8080⁠
   • Mount the static files for live editing
   • Stream logs to your terminal

3. Open in your browser

   http://localhost:8080
   

   Copy

⁠Background Mode (local / trusted network)

For running in the background on a trusted machine (not internet-facing without extra hardening — see Security⁠):

# Build and start server in background
make server-run

# View logs
make server-logs

# Stop server
make server-stop

⁠With GPU Support

If you have an NVIDIA GPU with CUDA:

make server-run-gpu

⁠How It Works

⁠Architecture

┌─────────────────┐
│   Web Browser   │
│  (Static HTML)  │
└────────┬────────┘
         │ HTTP/WebSocket
         ↓
┌─────────────────┐
│  Flask Server   │
│  + Socket.IO    │
└────────┬────────┘
         │
         ↓
┌─────────────────┐     ┌──────────────┐
│  Job Manager    │────→│ Demucs Core  │
│  (Queue System) │     │  (Processor) │
└─────────────────┘     └──────────────┘
         │
         ↓
┌─────────────────┐
│  File Storage   │
│   /app/output   │
└─────────────────┘

⁠Processing Flow

1. Upload - User uploads audio file or provides YouTube URL
2. Queue - Job added to processing queue with unique ID
3. Download (if YouTube) - Audio downloaded via yt-dlp
4. Process - Demucs separates audio into stems
5. Progress - Real-time updates sent via Socket.IO
6. Complete - Stems saved and available for playback/download
7. Persist - All output saved to mounted volume

⁠API Endpoints

• POST /api/upload - Upload audio file for processing
• POST /api/upload_youtube - Submit YouTube URL for processing
• GET /api/jobs - List all jobs
• GET /api/jobs/<job_id> - Get job status
• GET /api/jobs/<job_id>/stems - List available stems
• GET /api/jobs/<job_id>/stems/<stem> - Stream audio stem
• DELETE /api/jobs/<job_id> - Cancel/delete job

⁠Socket.IO Events

• progress - Processing progress updates (0-100%)
• completed - Job completed successfully
• failed - Job failed with error message

⁠Development

⁠Project Structure

.
├── demucs/                  # Demucs Docker base image
│   ├── Dockerfile          # Base Demucs image
│   ├── models/             # Downloaded model cache (persisted)
│   └── output/             # Processed stems (persisted)
├── server/                  # Web application
│   ├── Dockerfile          # Web server image (extends demucs)
│   ├── app/
│   │   ├── server.py       # Flask application
│   │   ├── services/       # Business logic
│   │   │   ├── demucs_processor.py
│   │   │   ├── job_manager.py
│   │   │   └── youtube_service.py
│   │   └── utils/          # Validation, helpers
│   ├── static/             # Frontend assets
│   │   ├── index.html      # Main UI
│   │   ├── css/style.css   # Styling
│   │   └── js/             # Client-side JavaScript
│   │       └── app.js      # Main application
│   └── requirements.txt    # Python dependencies
├── scripts/                 # Helper scripts
├── Makefile                # Build and run commands
└── README.md               # This file

⁠Development Workflow

1. Edit static files (HTML/CSS/JS)

   # Files are live-mounted, just refresh browser
   # Edit: server/static/**/*
   

   Copy

2. Edit Python code

   # Rebuild and restart
   make dev
   

   Copy

3. Test changes

   # Upload a test file via the web UI
   # Watch logs in the terminal
   

   Copy

4. View logs

   make server-logs
   

   Copy

⁠Available Commands

make help            # Show all available commands
make check           # Check system prerequisites
make build           # Build base Demucs image
make server-build    # Build web server image
make server-run      # Run in background (production)
make dev             # Run in foreground (development)
make server-stop     # Stop server
make server-logs     # View logs
make clean-outputs   # Clean processed files
make clean-all       # Clean everything

⁠Features in Detail

⁠Audio Models

⁠YouTube Integration

1. Paste any YouTube URL into the web interface
2. Audio is automatically downloaded (audio-only, no video)
3. Processing begins immediately
4. Metadata (title, artist) extracted and saved

⁠Docker Hub Images

Pre-built multi-architecture Docker images (linux/amd64, linux/arm64) are published to Docker Hub via GitHub Actions:

• higginsrob/htdemucs:latest⁠ - Latest server with web interface
• higginsrob/htdemucs:server⁠ - Server image alias
• higginsrob/demucs-base:latest⁠ - Multi-arch Demucs base image
• higginsrob/htdemucs:v*⁠ - Versioned releases

Images are automatically built on:

• Every push to the main branch
• Git tags (for versioned releases)
• Manual workflow triggers

See .github/workflows/README.md⁠ for complete CI/CD documentation.

⁠Documentation

• instructions/DEVELOPMENT.md⁠ - Development guide
• server/TESTING.md⁠ - Testing guide
• instructions/TROUBLESHOOTING.md⁠ - Troubleshooting
• .github/workflows/README.md⁠ - GitHub Actions CI/CD

⁠Troubleshooting

⁠Server won't start

# Check Docker is running
docker info

# Check port 8080 is available
lsof -i :8080

# View detailed logs
make server-logs

⁠Processing is slow

• Use make server-run-gpu if you have an NVIDIA GPU
• Choose htdemucs instead of htdemucs_ft for faster processing
• Shorter audio files process faster

⁠Models re-downloading

Make sure the models volume is properly mounted:

docker inspect demucs | grep models

⁠Out of disk space

# Clean old outputs
make clean-outputs

⁠Contributing

Contributions welcome! Please see instructions/DEVELOPMENT.md⁠ for guidelines.

⁠Credits

• Meta's Demucs⁠ - The core audio separation engine
• xserrat/docker-facebook-demucs⁠ - Dockerized Demucs foundation that this project builds upon

⁠License

This repository is released under the MIT license as found in the LICENSE⁠ file.