create-stems
Audio stem separation using Demucs' Python API. Default model is htdemucs_6s which splits audio into 6 sources: vocals, drums, bass, other, guitar, piano.
Usage
# 6-source separation (default)
./run.sh separate --mix song.wav --out ./stems
# Extract a specific instrument by name (auto-maps to Demucs source)
./run.sh separate --mix song.wav --out ./stems --instrument vocals
./run.sh separate --mix song.wav --out ./stems --instrument oud
./run.sh separate --mix song.wav --out ./stems --instrument piano
# Raw two-stems mode (if you know the Demucs source name)
./run.sh separate --mix song.wav --out ./stems --two-stems guitar
# 4-source with VRAM control
./run.sh separate --mix song.wav --out ./stems --model htdemucs --segment 12
# Quality mode (GPU recommended)
./run.sh separate --mix song.wav --out ./stems --shifts 2
# MP3 output
./run.sh separate --mix song.wav --out ./stems --mp3
# Low-VRAM mode
./run.sh separate --mix song.wav --out ./stems --segment 8 --no-cuda-mem-caching
Instrument Mapping
Use --instrument with natural names. The skill maps them to the closest Demucs source:
| Instrument | Maps to (6s) | Notes |
|---|---|---|
| vocals, voice, singing | vocals | |
| drums, percussion | drums | |
| bass, upright bass, bass guitar | bass | |
| guitar, oud, lute, banjo, mandolin, sitar, ukulele, bouzouki | guitar | Plucked strings |
| piano, keyboard, keys, organ, synth, accordion, harpsichord | piano | Keyboard family |
| violin, cello, trumpet, sax, flute, strings, brass, woodwind | other | Orchestral/misc |
This means an agent can say --instrument oud and the skill determines the best extraction path (--two-stems guitar on htdemucs_6s).
Models
| Model | Sources | Notes |
|---|---|---|
htdemucs_6s | 6 (vocals/drums/bass/other/guitar/piano) | Default. Best for full separation. |
htdemucs | 4 (vocals/drums/bass/other) | Faster. Guitar+piano in "other". |
htdemucs_ft | 4 (fine-tuned) | Higher quality 4-stem. |
VRAM Tuning
| Flag | Effect |
|---|---|
--segment N | Split size (seconds). Smaller = less VRAM. Try 8-12 for 8GB cards. |
--overlap F | Window overlap (default 0.25). Reduce for speed. |
--shifts N | Random time-shift averaging. Higher = better quality, slower. |
--jobs N | Parallel jobs. Increases RAM proportionally. |
--no-cuda-mem-caching | Sets PYTORCH_NO_CUDA_MEMORY_CACHING=1. Helps with very low VRAM. |
Output Structure
<out_dir>/
htdemucs_6s/
<track_name>/
vocals.wav
drums.wav
bass.wav
other.wav
guitar.wav
piano.wav
manifest.json
Sanity Checks
./sanity.sh # Full environment check
Hardware Requirements
| Component | Minimum | Recommended |
|---|---|---|
| VRAM | 4GB (with --segment 8) | 8GB+ |
| RAM | 8GB | 16GB+ |
| Storage | 5GB (model cache) | 10GB+ |
Integration
Used by:
- create-music - stem separation step in music creation pipeline
- discover-music -
youtube-stemscommand delegates here - learn-artist - vocal/instrument extraction for RVC training