demix

audio processing tool: download from YouTube or use local files, separate stems, adjust tempo/pitch, detect and transpose key, and cut segments.

prerequisites

installation

I suggest to create virtualenv for this project to not break existing system-wide installations:

brew install virtualenvwrapper
brew install ffmpeg
brew install yt-dlp
mkdir demix
cd demix
mkvirtualenv -p /Users/pw/.pyenv/versions/3.8.16/bin/python demix
workon demix
pip install demix
demix -v

update

pip install demix --upgrade

development

prepare environment:

brew install virtualenvwrapper
brew install ffmpeg
git clone git@github.com:pwittchen/demix.git
cd demix
mkvirtualenv -p /Users/pw/.pyenv/versions/3.8.16/bin/python demix
workon demix
pip install -r requirements.txt
python demix.py -v

virtualenv

exit virtualenv, when you're done:

deactivate

to activate env again:

workon demix

testing

install pytest:

pip install pytest

run all tests (-v param for verbose):

pytest -v

versioning and deployment

When we create and push a new git tag, e.g. v1.0.4, deploy.yml github action is triggered. It automatically extracts created tag, updates version with bump_version.py script, performs git commit and push. After that, deployment of the new package version to PyPi is executed.

usage

demix -u <youtube-url> [options]
demix -s <search-query> [options]
demix -f <audio-file> [options]

options

modes

examples

# separate a YouTube video into vocals and accompaniment
demix -u 'https://www.youtube.com/watch?v=VIDEO_ID' -m 2stems

# search YouTube by artist and song name
demix -s 'Queen - Bohemian Rhapsody' -m 4stems

# separate a local file with 4 stems
demix -f /path/to/song.mp3 -m 4stems

# cut audio from 1:30 to 3:45
demix -f song.mp3 -ss 1:30 -to 3:45

# start from 0:30 (skip intro)
demix -f song.mp3 -ss 0:30

# keep only the first 2 minutes
demix -f song.mp3 -to 2:00

# combine cutting with tempo and transpose
demix -f song.mp3 -ss 1:00 -to 4:00 -t 0.8 -p -2

# detect musical key of a song
demix -f song.mp3 -k

# detect key before and after transposing
demix -f song.mp3 -k -p -3

# transpose to a specific key (auto-detects current key)
demix -f song.mp3 -K C

# transpose to A minor
demix -f song.mp3 -K Am

# transpose to target key with tempo change
demix -f song.mp3 -K "F# minor" -t 0.9

# slow down without separating stems
demix -f song.mp3 -t 0.8 -m nosplit

# download and cut without separation
demix -u 'https://www.youtube.com/watch?v=VIDEO_ID' -ss 1:00 -to 3:00 -m nosplit

# run silently and only print the final result message
demix -f song.mp3 -m 4stems -q

youtube downloads

When given -u or -s, demix downloads audio with yt-dlp if it's on PATH (brew install yt-dlp), falling back to pytubefix otherwise.

YouTube periodically restricts which player clients may fetch media without a PO token, and a blocked client typically fails with HTTP Error 403: Forbidden partway through the download. To survive that, demix retries the download across several yt-dlp player clients before giving up:

If every strategy fails, demix reports what each attempt returned instead of a single opaque error.

passing extra yt-dlp options

Set DEMIX_YT_DLP_ARGS to append arbitrary arguments to every yt-dlp invocation. This is the usual remedy when downloads are blocked and you're logged into YouTube in a browser:

DEMIX_YT_DLP_ARGS='--cookies-from-browser chrome' demix -u 'https://www.youtube.com/watch?v=VIDEO_ID' -m 2stems

Other useful values: --proxy http://…, --limit-rate 1M, --sleep-requests 2. If downloads still fail, brew upgrade yt-dlp often restores access, since new releases track YouTube's changes closely.

MCP server

The repo also ships an MCP server at mcp/ so LLM clients (Claude Desktop, Claude Code, etc.) can call demix directly. It's a sibling Python package (demix-mcp, Python 3.10+) that shells out to the demix CLI on PATH — keeping it decoupled from demix's own Python 3.8 environment.

Install (in a separate Python 3.10+ env):

pipx install ./mcp

Claude Code

Register the server with the claude mcp CLI (run from your demix workspace so pretrained_models/ and output/ cache there):

claude mcp add-json demix '{"command":"demix-mcp","cwd":"'"$PWD"'"}'

Add --scope user to make it available across all projects, or --scope project to commit it into .mcp.json for your team. Verify with:

claude mcp list

Inside Claude Code, run /mcp to inspect server status and the exposed tools.

Claude Desktop / other clients

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (or your client's equivalent):

{
  "mcpServers": {
    "demix": {
      "command": "demix-mcp",
      "cwd": "/path/to/demix-workspace"
    }
  }
}

Tools exposed: process_audio, detect_key, search_youtube, clean. See mcp/README.md for details.

Claude Code skill

This repo ships a Claude Code skill at .claude/skills/demix/SKILL.md that translates plain-English requests into demix invocations — describe what you want and Claude picks the flags, shows the command, and runs it.

Examples of requests the skill handles:

• "Download https://youtu.be/abc123 and give me the instrumental" → demix -u 'https://youtu.be/abc123' -m 2stems
• "Find 'Radiohead Creep', slow it 15%, keep only the first two minutes" → demix -s 'Radiohead Creep' -t 0.85 -to 2:00
• "~/Music/song.mp3 — transpose to G minor and split into 4 stems" → demix -f '~/Music/song.mp3' -m 4stems -K 'Gm'
• "What key is song.wav in?" → demix -f 'song.wav' -k
• "Make a karaoke video from 'Adele - Hello'" → demix -s 'Adele - Hello' -m 2stems --video

Trigger it by typing /demix in Claude Code, or just describe the task in natural language — the skill loads automatically when the intent matches.