How facebookresearch/demucs works
Demucs is a music-source-separation toolkit: a user supplies a song, the separation command loads a pretrained model, runs chunked inference, and writes separated stems. Its model family includes waveform, spectrogram/hybrid, and Hybrid Transformer architectures. The repository also supports model training and evaluation, pretrained-checkpoint handling, and audio-dataset workflows. The README documents karaoke-style stem selection and arbitrary WAV inputs. Source excerpts are partial, so uncertain internal call wiring is omitted; documented capabilities are retained where the tree supports a subsystem.
Main entry points: separate.py Separation command · apply.py Inference runner · solver.py Optimization loop · audio.py Audio utilities
Components 22
Separation workflow
- Command entry
demucs/__main__.py - Separation command
demucs/separate.py - Python API
demucs/api.py - Inference runner
demucs/apply.py
Separation models
- Hybrid Transformer
demucs/htdemucs.py - Hybrid Demucs
demucs/hdemucs.py - Waveform Demucs
demucs/demucs.py - Waveform variant
demucs/wdemucs.py - Attention layers
demucs/transformer.py
Training and evaluation
- Training orchestration
demucs/train.py - Optimization loop
demucs/solver.py - Training augmentation
demucs/augment.py - Model evaluation
demucs/evaluate.py - Pitch processing
demucs/repitch.py
Audio and checkpoints
- Model lookup
demucs/pretrained.py - Audio utilities
demucs/audio.py - WAV datasets
demucs/wav.py - Model repository
demucs/repo.py - Model states
demucs/states.py
Other components
- Audio user
- Input audio
- Separated stems
Connections 25
- Audio user → Command entry: invokes
- Command entry → Separation command: dispatches
- Input audio → Separation command: provides audio
- Separation command → Audio utilities: loads audio
- Separation command → Model lookup: loads model
- Model lookup → Model repository: retrieves weights
- Model repository → Model states: reads checkpoint
- Separation command → Inference runner: runs inference
- Inference runner → Hybrid Transformer: calls model
- Inference runner → Hybrid Demucs: calls model
- Inference runner → Waveform Demucs: calls model
- Inference runner → Waveform variant: calls model
- Hybrid Transformer → Attention layers: uses attention
- Separation command → Audio utilities: writes stems
- Audio utilities → Separated stems: writes files
- Audio user → Python API: uses API
- Python API → Model lookup: loads model
- Training orchestration → Optimization loop: runs optimization
- Training orchestration → WAV datasets: uses datasets
- Optimization loop → Training augmentation: augments batches
- Optimization loop → Model evaluation: evaluates models
- Optimization loop → Hybrid Transformer: trains model
- WAV datasets → Audio utilities: loads audio
- Training augmentation → Pitch processing: may repitch
- Training orchestration → Model states: saves model