# Demucs Stem Splitter

## Usage policy

This is a free, single-server community tool running on CPU. Please be a good citizen:
- Submit one job at a time per user/agent
- Wait for your job to complete before submitting another
- Do not submit more than 5 jobs per hour
- Each job takes 10-20 minutes — do not poll more than once per minute for status

Free audio stem separation tool powered by Meta's htdemucs_ft model.
Splits any audio file into four downloadable stems: vocals, drums, bass, other.
No account or authentication required.

## Capabilities

- Input: any audio file (mp3, wav, flac, etc.), up to 200MB
- Output: four WAV files (vocals, drums, bass, other) at 44.1kHz 32-bit float
- Processing time: ~10-20 minutes per song on CPU
- Concurrency: up to 3 simultaneous jobs (queue shown in UI)

## MCP server (recommended for AI agents)

Install locally and add to your Claude config — no code required:

```bash
pip install mcp gradio_client
# or: pip install -r requirements-mcp.txt
```

Then add to `~/.claude/claude_desktop_config.json` (or your MCP host config):

```json
{
  "mcpServers": {
    "demucs": {
      "command": "python",
      "args": ["/path/to/demucs/mcp_server.py"]
    }
  }
}
```

The server exposes one tool: `separate_stems(audio_path)` — pass a local file
path or URL, get back `{"vocals": "...", "drums": "...", "bass": "...", "other": "..."}`.

## Using the API programmatically

This app is built with Gradio. The full interactive API reference is at:
https://demucsr.com/?view=api

### Python example (using the gradio_client library)

```python
from gradio_client import Client, handle_file

client = Client("https://demucsr.com")
result = client.predict(
    audio_path=handle_file("/path/to/song.mp3"),
    api_name="/separate"
)
# result is a list of 4 file paths: [vocals, drums, bass, other]
vocals_path, drums_path, bass_path, other_path = result
```

### HTTP API example

Upload a file and get back stem download URLs:

POST https://demucsr.com/api/predict
Content-Type: application/json

{
  "data": [
    {
      "path": "<upload your file first via POST /upload>",
      "mime_type": "audio/mpeg"
    }
  ]
}

#### Step 1 — upload the audio file

POST https://demucsr.com/upload
Content-Type: multipart/form-data
Body: file=<audio file>

Returns: ["/tmp/gradio/<hash>/audio.mp3"]

#### Step 2 — run stem separation

POST https://demucsr.com/api/predict
Content-Type: application/json

{
  "data": [{"path": "/tmp/gradio/<hash>/audio.mp3", "mime_type": "audio/mpeg"}]
}

Returns:
{
  "data": [
    {"path": "/tmp/.../vocals.wav", "url": "https://demucsr.com/file=/tmp/.../vocals.wav"},
    {"path": "/tmp/.../drums.wav",  "url": "https://demucsr.com/file=/tmp/.../drums.wav"},
    {"path": "/tmp/.../bass.wav",   "url": "https://demucsr.com/file=/tmp/.../bass.wav"},
    {"path": "/tmp/.../other.wav",  "url": "https://demucsr.com/file=/tmp/.../other.wav"}
  ]
}

Download each stem from the returned URLs.