mixforge
Make test mixes where you know the right answer.
You give mixforge separate stems (vocals, drums, bass, other). It mixes them at known levels, can add a known amount of bleed (for example "a little drums leaking into the vocal"), and keeps the exact originals plus a recipe.json. You can then test whether a separation tool, or a bleed detector, gives the right answer, because you know what went in.
Status: alpha (0.1.0). Tested on synthetic audio with known answers, mutation checks, and verified on real music stems from MUSDB18-HQ (see Real-data check below).
Install
pip install --pre mixforge
(--pre is needed while it is an alpha release.)
Quick start
Folder layout, one folder per song (this is the MUSDB18-HQ layout; a mixture.wav next to the stems is ignored):
stems/
Song A/ vocals.wav drums.wav bass.wav other.wav
Song B/ ...
mixforge make stems --out mixes --count 3 --seconds 10 \
--gain-range -6 6 \
--bleed "drums>vocals:-26@4000" --bleed "bass>other:-30" \
--seed 1
mixforge verify mixes
Each mix gets its own folder:
mixes/0000_Song_A_000/
mixture.wav the mix
stems/*.wav the answer key: the clean stems exactly as they sit in the mix
leaky/*.wav the same stems with the bleed added (only if you asked for bleed)
recipe.json everything that was done, so the result can be repeated and checked
mixes/index.csv one line per mix
What the options mean
| Option | Meaning |
|---|---|
--gain-range LO HI |
random level change per stem, in dB, drawn from the seed |
--gain STEM=DB |
fixed level for one stem |
--bleed SRC>DST:DB[@HZ] |
leak SRC into DST. DB is the leak level relative to SRC as it sits in the mix: -20 = a tenth of the amplitude, -6 = about half. @HZ low-passes the leak (real bleed is often duller) |
--seconds S |
cut the same random window of S seconds out of every stem |
--count N |
N different mixes per song |
--seed N |
same seed, same files (byte for byte) |
--subtype |
FLOAT (default, never clips), PCM_16 or PCM_24 |
--max-songs N |
only the first N songs, for a quick trial |
--html FILE |
write an interactive HTML listening audit report with multi-track players |
Rules mixforge follows:
- The mixture is the exact sum of the stems in
stems/. If the sum would clip, everything is turned down together so the sum still holds.recipe.jsonrecords the change. - Stems that do not match are matched up and noted. Different sample rates are resampled to the most common one, mono stems are copied to stereo, and different lengths are trimmed to the shortest. Each fix is written into
recipe.jsonundernotes. - Your files are never modified, and existing output is never overwritten.
mixforge verifyre-checks any output folder: mixture = sum of stems, and each leaky file really equals the clean stem plus the bleed the recipe describes. It exits 0 if all is well, 1 if something fails, 2 for usage errors.
Python
import mixforge
from mixforge import Bleed, make_mix
r = make_mix(stems, sr, gain_range=(-6, 6), seed=1,
bleed=[Bleed("drums", "vocals", -26.0, lowpass_hz=4000)])
r.mixture, r.stems, r.leaky, r.recipe
Real-data check
Dataset: MUSDB18-HQ (train split, 20 songs, 40 mixes, 10 s windows)
Date: November 5, 2026
Recipe: gain range -6..+6 dB, bleed drums>vocals:-26@4000, bass>other:-30, vocals>other:-20, 2 mixes per song.
Pipeline, FLOAT
- Mixes verified: 40 of 40 (0 failures)
- Largest $|\text{mixture} - \sum \text{stems}|$: 6.52e-08
- Bleed without low-pass: 0.0000 dB gap between asked and measured level
- Bleed with low-pass: measured level minus asked level between -1.21 dB and 0.0 dB
- Headroom scaling: 15 mixes scaled automatically to prevent clipping
- Time: 8.5 s
Pipeline, PCM_16
- Mixes verified: 40 of 40 (0 failures)
- Largest $|\text{mixture} - \sum \text{stems}|$: 9.16e-05
- Bleed without low-pass: 0.0000 dB gap between asked and measured level
- Bleed with low-pass: measured level minus asked level between -1.21 dB and 0.0 dB
- Headroom scaling: 15 mixes scaled automatically to prevent clipping
- Time: 9.9 s
Information check vs dataset's own mixture.wav (30 s window, no gain changes)
- Songs compared: 20
- Residual (lower is closer): best -73.3 dB, median -69.3 dB, worst -62.8 dB (all well below the -60 dB auditory perception threshold)
Limits (please read)
- This is test material, not music. The mixes are gain-scaled sums of stems. They are not mastered and do not claim to sound like finished records.
- The bleed is simple. It is a quieter, optionally duller copy of one stem added to another. Real microphone bleed also has delay, room sound and frequency changes that this does not copy. A detector that works here may still struggle on real recordings.
- Stems must already be time-aligned (as in MUSDB18-HQ). mixforge does not align them.
- No cross-song remixing yet (vocals from one song over drums from another).
- Stems are read with
soundfile(WAV, FLAC, OGG, AIFF, and MP3 where your libsndfile supports it). Not supported:.stem.mp4files (use MUSDB18-HQ's WAV version).
Related work
- MUSDB18 and
musevalprovide real stems and standard separation scores. mixforge does not replace them. It makes controlled, repeatable test mixes you can use next to them. - Mixing tools such as Scaper and audiomentations exist for other uses (sound-event data, augmentation). mixforge's focus is a recorded answer key and controlled bleed for separation testing.
Development
pip install -e ".[dev]"
python -m pytest -q
License
MIT. Copyright (c) 2026 Boobalan Arjunan.
Metadata
Release files for mixforge-audio 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mixforge_audio-0.1.0.tar.gz | 27.5 kB | Without provenance | Details for mixforge_audio-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mixforge_audio-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mixforge_audio-0.1.0-py3-none-any.whl |
Total release size: 47.8 kB
Release files / mixforge_audio-0.1.0.tar.gz
| Download URL | mixforge_audio-0.1.0.tar.gz |
|---|---|
| Size | 27.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4a49b05b0afce6532340ced4f1b84b426baa37a4541f41b07d45b265fc48769
|
|
BLAKE2b-256 checksum How to use checksums |
9e85ce088774bf1f1cfe71fba6b0a3b6c3f531febbce9f1ce3eddcc5ce564d7a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
Release files / mixforge_audio-0.1.0-py3-none-any.whl
| Download URL | mixforge_audio-0.1.0-py3-none-any.whl |
|---|---|
| Size | 20.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc8124384942341e13bb12f08f4d4da8b3685c34e3dfdeb30590f51f13df468e
|
|
BLAKE2b-256 checksum How to use checksums |
8a0d05a199480138310ee99096698dd3b0b70d0aa4f53d5d9d86fe46a167d0cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
Security for mixforge-audio 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.