ferraus separate

Split a mix into stems (vocals, drums, bass, other, ...)

Synopsis

ferraus separate <input> [options] [-o <output>]

Separates a song into stems with open models run through ONNX Runtime. Tiers trade speed for quality: fast (Demucs v4), balanced (Demucs v4 fine-tuned bag), quality (Mel-Band RoFormer vocals + fine-tuned Demucs), max (ensemble with test-time augmentation); the default, auto, picks the best tier whose models are verified. Models run one at a time over the song window by window, and long inputs spill to temporary files so the run stays within --max-memory. Models download on first use only with -y or models.auto_download = true; otherwise the command fails with exit code 5 and the exact ferraus models pull command. With --sum-to-mix on (default) the residual goes to other, so the written stems add back to the input within one LSB. Each stem's JSON result carries a quality estimate (ensemble agreement, or mask confidence for a single model). --vocal-split splits the vocal stem into lead and backing with a built-in method (no model): it tracks the lead's pitch, keeps the energy on its harmonics (and, for stereo input, mainly the centred part of it), sends other voices' harmonics to the backing, and makes backing = vocals - lead; it is best effort, reported as method melody_mask, and --cascade-models vocal-split=<model> runs a separation model instead.

Examples

Four stems with the default tier (auto: the best verified tier, quality today): song.vocals.wav, song.drums.wav, ...

ferraus separate song.wav

Quick vocals + instrumental

ferraus separate song.wav --tier fast --stems 2

Best possible vocal stem

ferraus separate song.wav --only vocals --tier max

Vocal stem plus song.lead.wav and song.backing.wav (built-in pitch-guided split, best effort)

ferraus separate song.wav --only vocals --vocal-split

Custom ensemble

ferraus separate song.wav --ensemble separate/htdemucs,separate/htdemucs-6s --weights 0.6,0.4

Options

Flag	Type	Default	Meaning
`--stems`	2 \| 4 \| 6	`4`	2 = vocals + instrumental, 4 = vocals/drums/bass/other, 6 = adds guitar and piano
`--tier`	auto \| fast \| balanced \| quality \| max	`auto`	Model tier from the registry; auto picks the best tier whose models are verified and downloadable in this registry and not held back (see the registry's auto_skip; balanced in this release, quality after its license review) and reports the choice
`--only`	list	—	Write only these stems, e.g. vocals,drums
`--instrumental`	flag	—	Write one file with the vocals removed
`--model`	text	—	Pin a registry model (name[@version]) or an ONNX file instead of a tier
`--ensemble`	list	—	Custom ensemble of models, e.g. a,b,c
`--weights`	list	—	Ensemble weights, e.g. 0.5,0.3,0.2 (default equal)
`--ensemble-mode`	avg \| max \| min	`avg`	avg = balanced, max = fuller (more bleed), min = cleaner (less bleed)
`--vocal-split`	flag	—	Second stage on the vocals: lead and backing (built in: a mask that follows the lead's pitch; best effort)
`--vocal-split-tracker`	pyin \| crepe \| swiftf0	`pyin`	Pitch tracker of the built-in vocal split: pyin (built in) or a model tracker (needs 'ferraus models pull pitch/<name>' or -y)
`--drum-split`	flag	—	Second stage on the drums: kick, snare, toms, hh, cymbals
`--extended`	list	—	Best-effort extraction from other: guitar,piano,keys,strings,brass
`--overlap`	percent	`25%`	Window overlap, crossfaded with a raised-cosine window
`--shifts`	integer	`1`	Test-time augmentation passes with random sub-second offsets (max tier uses 2) Range: 1..10.
`--segment`	text	`auto`	Window length: auto (the model's trained length), a duration such as 10s, or whole
`--sum-to-mix`	on\|off	`on`	Assign the residual to other so stems add back to the input exactly
`--accept-license`	flag	—	Accept a research-only or unclear model license (with --model or --cascade-models)
`--cascade-models`	list	—	Override cascade models: vocal-split=<model>, drum-split=<model>, extended=<model>

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Code	Meaning
0	Success
1	Processing failed
2	Usage or parameter error
3	Input missing or unreadable
4	Unsupported format or codec
5	Model not cached and downloads disabled
6	Model download or verification failed
8	Cancelled
10	Network error
70	Internal error (bug)

Common mistakes

Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
Percentages accept 80% or the fraction 0.8; a bare 80 means 80x, not 80%.

For models

MCP tool: ferraus_separate
Schema: ferraus schema separate
Pipeline: { op: separate, args: { ... } } (flag names with _ instead of -)
fx stage: no

{"command": "separate", "defaults": {"stems": "4", "tier": "auto", "ensemble_mode": "avg", "vocal_split_tracker": "pyin", "overlap": "25%", "shifts": "1", "segment": "auto", "sum_to_mix": "on"}}