1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
# stemsep
`stemsep` is a Linux command-line program that separates a WAV or MP3 file
into six stereo WAV stems using the HTDemucs six-source ONNX model:
- `<music_identifier>_drums.wav`
- `<music_identifier>_bass.wav`
- `<music_identifier>_other.wav`
- `<music_identifier>_vocals.wav`
- `<music_identifier>_guitar.wav`
- `<music_identifier>_piano.wav`
Separation is implemented in `main.c`; stem playback is implemented in
`playback.c` and `playback.h`, and the metronome in `metronome.c` and
`metronome.h`. The bundled ONNX Runtime 1.21 binary is the official Linux
x86-64 CPU release.
## Model setup
The model is not committed because it is 258,159,781 bytes. Download the pinned
model before running the program:
```sh
mkdir -p models
curl -fL -o models/htdemucs_6s.onnx \
https://huggingface.co/StemSplitio/htdemucs-6s-onnx/resolve/52c122c298c21fb0c74e7f04fe6e5d9c1f6dceef/htdemucs_6s.onnx
printf '%s %s\n' \
48f8e84945579f8ab340e083339e9221e03785dbe733a52c388200b6d3ca779a \
models/htdemucs_6s.onnx | sha256sum -c -
```
`STEMSEP_MODEL=/another/model.onnx` can override the model location without
changing the command-line interface. The replacement model must have the same
input/output contract.
## Build and run
```sh
./build.sh
./stemsep -i /path/to/song.wav -m song
./stemsep -i /path/to/song.mp3 -m song
./stemsep -m song -p bdv
./stemsep --bpm 120 -t 4
```
`-m` is required for both separation and playback, and is not used by the
metronome. Options may be passed in either order. A music identifier may contain
letters, digits, `_`, and `-`.
`-i` accepts either format; the file type is detected from its contents, not
its name. `-wav <file>` is still accepted as a deprecated alias for `-i`.
The `-p` value selects any combination of stems using lowercase letters:
- `g`: guitar
- `b`: bass
- `d`: drums
- `p`: piano
- `v`: vocals
- `o`: other
Letter order does not matter, and repeated letters are treated as one. For
example, `bdbd` and `db` both play bass and drums. `mpv` runs in the foreground
and remains attached to the terminal so its normal playback controls work.
`stemsep` assumes `mpv` is installed and available in `PATH`; requested files
are passed directly to mpv, which reports any missing-file errors.
While a stem is playing, these keys adjust speed and pitch independently:
- `>`: increase playback speed by 0.1
- `<`: decrease playback speed by 0.1
- `}`: raise the pitch by one semitone
- `{`: lower the pitch by one semitone
Speed changes keep the pitch and pitch changes keep the speed. The bindings are
written to `$XDG_RUNTIME_DIR/stemsep-mpv-input.conf` (`/tmp` when that variable
is unset) and handed to mpv with `--input-conf`, which replaces the keys mpv
binds to these four characters by default and means the user's own
`input.conf` is not loaded during stem playback. Pitch control uses mpv's
`pitch` property and requires mpv 0.40 or newer.
The same list is printed above the player, and mpv's console output is reduced
to the playback position line (`00:01:23 / 00:04:46 (29%)`). mpv errors are
still shown, and `PIPEWIRE_DEBUG=0` is set for mpv unless it is already set, so
libpipewire's probing messages do not appear.
## Metronome
`--bpm <tempo>` runs `stemsep` as a standalone metronome instead of a separator
or player. It cannot be combined with `-i`, `-m`, or `-p`:
```sh
./stemsep --bpm 120 # 120 BPM, 4 beats per bar
./stemsep --bpm 96 -t 3 # 96 BPM, 3 beats per bar
./stemsep --bpm 140 -t 2 # 140 BPM, 2 beats per bar
```
`-t` (or `--time-signature`) sets how many beats each bar contains; the default
is `4`. Common values are `2` (binary), `3` (ternary), and `4` (quaternary),
and any value from 2 to 16 is accepted. The strong beat of every bar is played
one octave above the weak beats, at a slightly higher level, so the downbeat is
audible at a glance. Tempo accepts a decimal number between 1 and 1000 beats per
minute.
One bar is synthesized at startup as a mono 44.1-kHz float32 WAV file in
`$XDG_RUNTIME_DIR/stemsep-metronome.wav` (`/tmp` when that variable is unset)
and handed to `mpv` with `--loop-file=inf`, so the bar repeats until you press
`q`. Like `-p`, this mode requires `mpv` in `PATH`.
With missing parameters, a wrong flag, or incompatible modes, the program
prints an error followed by:
```text
Usage:
./stemsep -i <audio_file> -m <music_identifier>
./stemsep -m <music_identifier> -p <stem_letters>
./stemsep --bpm <tempo> [-t <beats_per_bar>]
```
For identifier `song`, output is written to `./song_stems/` in the current
directory, regardless of the input file's location. Each output filename is
prefixed with the identifier, such as `song_drums.wav`. Each stem is first
written as a `.part` file and is published only after all six files finish
successfully; normal errors and interruptions remove incomplete files. An
existing output directory is never overwritten. A process crash or power loss
can leave an incomplete directory that must be removed manually.
## Single-file distribution (Linux x86-64)
`./package.sh --portable` produces `dist/stemsep-linux-x86_64`, one executable
containing `stemsep`, the ONNX Runtime shared library, the 258 MB model, and
the license notices. The payload is a zstd-compressed archive appended to a
small statically linked launcher. `mpv` is not part of the bundle: playback
(`-p`) and the metronome (`--bpm`) still require `mpv` in `PATH`.
```sh
./package.sh --portable
./dist/stemsep-linux-x86_64 -i /path/to/song.wav -m song
```
The first run unpacks the payload into a per-user cache; later runs reuse it.
The cache is `$STEMSEP_CACHE` if set, otherwise `$XDG_CACHE_HOME/stemsep`, or
`~/.cache/stemsep`. Extraction takes about a second and uses roughly 270 MB.
Concurrent first runs are serialized with a lock file. Remove the cache with
`rm -rf ~/.cache/stemsep`.
The bundle accepts three informational options before the normal arguments:
- `--stemsep-extract`: print the extraction directory and exit.
- `--stemsep-licenses`: print the bundled license directory and exit.
- `--stemsep-version`: print the bundle build id and exit.
Requirements and notes:
- Linux x86-64 with glibc 2.28 or newer. `--portable` builds `stemsep` in a
`gcc:7` container for that baseline. ONNX Runtime itself requires glibc
2.27, so older glibc systems and musl-based distributions such as Alpine
are not supported.
- No root privileges, FUSE, or runtime installation step are needed.
- `ZSTD_LEVEL` (or `--zstd-level`) controls compression; the default is 19 and
produces a ~140 MB file. Level 0 disables compression and yields a ~280 MB
file.
- `STEMSEP_MODEL` still overrides the bundled model.
- `./package.sh --no-build` packages an existing `./stemsep`, and
`--skip-model-check` permits packaging a model other than the pinned one.
- Packaging needs `gcc` with a static libc and `libzstd.a`, `python3`, `zstd`,
and Docker for `--portable`.
## Input support
WAV input must be an uncompressed RIFF/WAVE file with one or two channels. The
reader supports PCM 8/16/24/32-bit, IEEE float32, and the PCM/float
`WAVE_FORMAT_EXTENSIBLE` variants. Mono is duplicated to stereo. Non-44.1-kHz
input is converted by an adaptive Blackman-windowed sinc resampler.
MP3 input accepts MPEG-1, MPEG-2, and MPEG-2.5 Layer III streams with one or two
channels at 8 kHz to 48 kHz, including VBR files. ID3v2 tags are skipped, ID3v1
and APE tags at the end of the stream are ignored, and LAME encoder delay and
padding are trimmed, so the decoded length matches a gapless player. The exact
number of PCM frames is established by decoding the file once at startup, so an
truncated or damaged stream is rejected before separation begins instead of
failing partway through. That preparation pass typically costs one to three
percent of the total run time.
Outputs are stereo, 44.1-kHz, IEEE float32 WAV files. Standard RIFF limits each
output to less than 4 GiB.
The model runs in 7.8-second chunks with 25% overlap. Its publisher reports
approximately 1.1 GiB of runtime memory on CPU. Separation is model-based and
imperfect; guitar and piano can contain audible bleed from other sources.
## Third-party components
- ONNX Runtime 1.21: MIT license; see `third_party/onnxruntime/LICENSE` and
`third_party/onnxruntime/ThirdPartyNotices.txt`.
- dr_mp3 (pinned commit `bad753d5`): public domain or MIT No Attribution; see
`third_party/dr_mp3/LICENSE`. It is compiled into `stemsep`, so MP3 input adds
no runtime dependency to the portable bundle.
- dr_wav (pinned commit `ebfea72a`): public domain or MIT No Attribution; see
`third_party/dr_wav/LICENSE`. It is compiled into `stemsep`, so WAV input and
stem output add no runtime dependency to the portable bundle.
- `htdemucs_6s.onnx`: distributed separately under the model repository's MIT
license and attribution terms.
|