# facebookresearch/demucs architecture

> Architecture diagram of the GitHub repository facebookresearch/demucs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebookresearch/demucs
- Repository: https://github.com/facebookresearch/demucs

## Overview

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: [`demucs/separate.py`](https://github.com/facebookresearch/demucs/blob/main/demucs/separate.py) (Separation command), [`demucs/apply.py`](https://github.com/facebookresearch/demucs/blob/main/demucs/apply.py) (Inference runner), [`demucs/solver.py`](https://github.com/facebookresearch/demucs/blob/main/demucs/solver.py) (Optimization loop), [`demucs/audio.py`](https://github.com/facebookresearch/demucs/blob/main/demucs/audio.py) (Audio utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_separation["Separation workflow"]
  node_cli["Command entry<br/>[__main__.py]"]
  node_separate["Separation command<br/>[separate.py]"]
  node_api["Python API<br/>[api.py]"]
  node_apply["Inference runner<br/>[apply.py]"]
end

subgraph group_models["Separation models"]
  node_htdemucs["Hybrid Transformer<br/>[htdemucs.py]"]
  node_hdemucs["Hybrid Demucs<br/>[hdemucs.py]"]
  node_demucs_model["Waveform Demucs<br/>[demucs.py]"]
  node_wdemucs["Waveform variant<br/>[wdemucs.py]"]
  node_transformer["Attention layers<br/>[transformer.py]"]
end

subgraph group_training["Training and evaluation"]
  node_train["Training orchestration<br/>[train.py]"]
  node_solver["Optimization loop<br/>[solver.py]"]
  node_augment["Training augmentation<br/>[augment.py]"]
  node_evaluate["Model evaluation<br/>[evaluate.py]"]
  node_repitch["Pitch processing<br/>[repitch.py]"]
end

subgraph group_audio["Audio and checkpoints"]
  node_model_lookup["Model lookup<br/>[pretrained.py]"]
  node_audio["Audio utilities<br/>[audio.py]"]
  node_wav["WAV datasets<br/>[wav.py]"]
  node_repo["Model repository<br/>[repo.py]"]
  node_states["Model states<br/>[states.py]"]
end

node_user(("Audio user"))
node_source_files["Input audio"]
node_stem_files["Separated stems"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_separate
node_source_files -->|"provides audio"| node_separate
node_separate -->|"loads audio"| node_audio
node_separate -->|"loads model"| node_model_lookup
node_model_lookup -->|"retrieves weights"| node_repo
node_repo -->|"reads checkpoint"| node_states
node_separate -->|"runs inference"| node_apply
node_apply -->|"calls model"| node_htdemucs
node_apply -->|"calls model"| node_hdemucs
node_apply -->|"calls model"| node_demucs_model
node_apply -->|"calls model"| node_wdemucs
node_htdemucs -->|"uses attention"| node_transformer
node_separate -->|"writes stems"| node_audio
node_audio -->|"writes files"| node_stem_files
node_user -.->|"uses API"| node_api
node_api -.->|"loads model"| node_model_lookup
node_train -->|"runs optimization"| node_solver
node_train -->|"uses datasets"| node_wav
node_solver -->|"augments batches"| node_augment
node_solver -->|"evaluates models"| node_evaluate
node_solver -->|"trains model"| node_htdemucs
node_wav -->|"loads audio"| node_audio
node_augment -.->|"may repitch"| node_repitch
node_train -->|"saves model"| node_states

click node_cli "https://github.com/facebookresearch/demucs/blob/main/demucs/__main__.py"
click node_separate "https://github.com/facebookresearch/demucs/blob/main/demucs/separate.py"
click node_api "https://github.com/facebookresearch/demucs/blob/main/demucs/api.py"
click node_apply "https://github.com/facebookresearch/demucs/blob/main/demucs/apply.py"
click node_model_lookup "https://github.com/facebookresearch/demucs/blob/main/demucs/pretrained.py"
click node_htdemucs "https://github.com/facebookresearch/demucs/blob/main/demucs/htdemucs.py"
click node_hdemucs "https://github.com/facebookresearch/demucs/blob/main/demucs/hdemucs.py"
click node_demucs_model "https://github.com/facebookresearch/demucs/blob/main/demucs/demucs.py"
click node_wdemucs "https://github.com/facebookresearch/demucs/blob/main/demucs/wdemucs.py"
click node_transformer "https://github.com/facebookresearch/demucs/blob/main/demucs/transformer.py"
click node_audio "https://github.com/facebookresearch/demucs/blob/main/demucs/audio.py"
click node_wav "https://github.com/facebookresearch/demucs/blob/main/demucs/wav.py"
click node_repo "https://github.com/facebookresearch/demucs/blob/main/demucs/repo.py"
click node_states "https://github.com/facebookresearch/demucs/blob/main/demucs/states.py"
click node_train "https://github.com/facebookresearch/demucs/blob/main/demucs/train.py"
click node_solver "https://github.com/facebookresearch/demucs/blob/main/demucs/solver.py"
click node_augment "https://github.com/facebookresearch/demucs/blob/main/demucs/augment.py"
click node_evaluate "https://github.com/facebookresearch/demucs/blob/main/demucs/evaluate.py"
click node_repitch "https://github.com/facebookresearch/demucs/blob/main/demucs/repitch.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_separate,node_api,node_apply,node_user toneBlue
class node_htdemucs,node_hdemucs,node_demucs_model,node_wdemucs,node_transformer toneAmber
class node_train,node_solver,node_augment,node_evaluate,node_repitch toneMint
class node_model_lookup,node_audio,node_wav,node_repo,node_states toneRose
class node_source_files,node_stem_files toneIndigo
```

## Components

### Separation workflow

- [Command entry](https://github.com/facebookresearch/demucs/blob/main/demucs/__main__.py): `demucs/__main__.py`
- [Separation command](https://github.com/facebookresearch/demucs/blob/main/demucs/separate.py): `demucs/separate.py`
- [Python API](https://github.com/facebookresearch/demucs/blob/main/demucs/api.py): `demucs/api.py`
- [Inference runner](https://github.com/facebookresearch/demucs/blob/main/demucs/apply.py): `demucs/apply.py`

### Separation models

- [Hybrid Transformer](https://github.com/facebookresearch/demucs/blob/main/demucs/htdemucs.py): `demucs/htdemucs.py`
- [Hybrid Demucs](https://github.com/facebookresearch/demucs/blob/main/demucs/hdemucs.py): `demucs/hdemucs.py`
- [Waveform Demucs](https://github.com/facebookresearch/demucs/blob/main/demucs/demucs.py): `demucs/demucs.py`
- [Waveform variant](https://github.com/facebookresearch/demucs/blob/main/demucs/wdemucs.py): `demucs/wdemucs.py`
- [Attention layers](https://github.com/facebookresearch/demucs/blob/main/demucs/transformer.py): `demucs/transformer.py`

### Training and evaluation

- [Training orchestration](https://github.com/facebookresearch/demucs/blob/main/demucs/train.py): `demucs/train.py`
- [Optimization loop](https://github.com/facebookresearch/demucs/blob/main/demucs/solver.py): `demucs/solver.py`
- [Training augmentation](https://github.com/facebookresearch/demucs/blob/main/demucs/augment.py): `demucs/augment.py`
- [Model evaluation](https://github.com/facebookresearch/demucs/blob/main/demucs/evaluate.py): `demucs/evaluate.py`
- [Pitch processing](https://github.com/facebookresearch/demucs/blob/main/demucs/repitch.py): `demucs/repitch.py`

### Audio and checkpoints

- [Model lookup](https://github.com/facebookresearch/demucs/blob/main/demucs/pretrained.py): `demucs/pretrained.py`
- [Audio utilities](https://github.com/facebookresearch/demucs/blob/main/demucs/audio.py): `demucs/audio.py`
- [WAV datasets](https://github.com/facebookresearch/demucs/blob/main/demucs/wav.py): `demucs/wav.py`
- [Model repository](https://github.com/facebookresearch/demucs/blob/main/demucs/repo.py): `demucs/repo.py`
- [Model states](https://github.com/facebookresearch/demucs/blob/main/demucs/states.py): `demucs/states.py`

### Other components

- **Audio user**
- **Input audio**
- **Separated stems**

## Connections

- 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
