# 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: - `_drums.wav` - `_bass.wav` - `_other.wav` - `_vocals.wav` - `_guitar.wav` - `_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 ` 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 ` 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 -m ./stemsep -m -p ./stemsep --bpm [-t ] ``` 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.