mixforge-audio 0.1.0__tar.gz

mixforge_audio-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Boobalan Arjunan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+This project depends on third-party libraries (numpy, scipy, soundfile,
+librosa, pyloudnorm, scikit-learn, tqdm, langdetect, matplotlib, and
+optionally openai-whisper, torch/torchaudio). Each carries its own license
+(mostly BSD/MIT/Apache-2.0) -- check requirements.txt and each package's own
+license before redistributing, especially if your GTV program has its own
+licensing rules.

mixforge_audio-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE README.md
+recursive-include tests *.py

mixforge_audio-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mixforge-audio
+Version: 0.1.0
+Summary: Build test mixes with a known answer key: mix separate stems at known levels, add a known amount of bleed, and keep the exact originals plus a recipe. For testing music source separation.
+Author-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+Maintainer-email: Boobalan Arjunan <boobalan_arjunan@composermind.com>
+License: MIT
+Project-URL: Homepage, https://github.com/BoobalanArjunan/Mix-Forge
+Project-URL: Issues, https://github.com/BoobalanArjunan/Mix-Forge/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Mix-Forge
+Keywords: audio,music,source-separation,stems,ground-truth,synthetic-data,bleed,evaluation,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: soundfile
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# 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](#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.json` records 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.json` under `notes`.
+- **Your files are never modified**, and existing output is never overwritten.
+- **`mixforge verify`** re-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
+
+```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.mp4` files (use MUSDB18-HQ's WAV version).
+
+## Related work
+
+- [MUSDB18](https://sigsep.github.io/datasets/musdb.html) and `museval` provide 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.

mixforge_audio-0.1.0/README.md

@@ -0,0 +1,126 @@
+# 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](#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.json` records 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.json` under `notes`.
+- **Your files are never modified**, and existing output is never overwritten.
+- **`mixforge verify`** re-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
+
+```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.mp4` files (use MUSDB18-HQ's WAV version).
+
+## Related work
+
+- [MUSDB18](https://sigsep.github.io/datasets/musdb.html) and `museval` provide 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.

mixforge_audio-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mixforge-audio"
+version = "0.1.0"
+description = "Build test mixes with a known answer key: mix separate stems at known levels, add a known amount of bleed, and keep the exact originals plus a recipe. For testing music source separation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Boobalan Arjunan", email = "boobalan_arjunan@composermind.com" },
+]
+maintainers = [
+  { name = "Boobalan Arjunan", email = "boobalan_arjunan@composermind.com" },
+]
+keywords = ["audio", "music", "source-separation", "stems", "ground-truth", "synthetic-data", "bleed", "evaluation", "machine-learning"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio :: Analysis",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["numpy", "scipy", "soundfile"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/BoobalanArjunan/Mix-Forge"
+Issues = "https://github.com/BoobalanArjunan/Mix-Forge/issues"
+Source = "https://github.com/BoobalanArjunan/Mix-Forge"
+
+[project.scripts]
+mixforge = "mixforge.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mixforge_audio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mixforge_audio-0.1.0/src/mixforge/__init__.py

@@ -0,0 +1,5 @@
+"""mixforge: build test mixes with a known answer key (for testing music source separation)."""
+from ._version import __version__  # noqa: F401
+from .core import Bleed, MixforgeError, MixResult, leak_signal, make_mix, parse_bleed  # noqa: F401
+from .data import DatasetResult, make_dataset, write_mix  # noqa: F401
+from .verify import VerifyResult, verify_folder  # noqa: F401

mixforge_audio-0.1.0/src/mixforge/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

mixforge_audio-0.1.0/src/mixforge/cli.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ._version import __version__
+from .core import MixforgeError, parse_bleed
+from .data import DEFAULT_EXCLUDE, SUBTYPES, make_dataset
+from .report import to_html
+from .verify import verify_folder
+
+
+def _gains(items):
+    out = {}
+    for it in items or []:
+        name, sep, val = it.partition("=")
+        try:
+            if not sep or not name:
+                raise ValueError
+            out[name] = float(val)
+        except ValueError:
+            raise MixforgeError(f"bad --gain {it!r}: use STEM=DB, e.g. vocals=-3") from None
+    return out
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="mixforge", description="Build test mixes with a known answer key.")
+    ap.add_argument("--version", action="version", version=f"mixforge {__version__}")
+    sub = ap.add_subparsers(dest="cmd")
+
+    m = sub.add_parser("make", help="mix stems into test songs, with an answer key and a recipe")
+    m.add_argument("source", help="a folder of stem files (one song) or a folder of song folders")
+    m.add_argument("--out", required=True, help="new folder to write the mixes into")
+    m.add_argument("--count", type=int, default=1, help="mixes per song (default 1)")
+    m.add_argument("--seconds", type=float, help="cut a random window of this length (same window for every stem)")
+    m.add_argument("--gain-range", type=float, nargs=2, metavar=("LO", "HI"), default=(0.0, 0.0),
+                   help="random level change per stem in dB, e.g. -6 6 (default: none)")
+    m.add_argument("--gain", action="append", metavar="STEM=DB", help="fixed level for one stem; can repeat")
+    m.add_argument("--bleed", action="append", metavar="SRC>DST:DB[@HZ]",
+                   help="leak SRC into DST at DB (negative = quieter), optional low-pass; can repeat")
+    m.add_argument("--max-songs", type=int, help="only use the first N songs (alphabetical), for a quick trial")
+    m.add_argument("--seed", type=int, default=0, help="same seed gives the same mixes (default 0)")
+    m.add_argument("--subtype", choices=SUBTYPES, default="FLOAT", help="audio format (default FLOAT, no clipping)")
+    m.add_argument("--sr", type=int, help="sample rate to use (default: the most common one among the stems)")
+    m.add_argument("--exclude", action="append", default=None,
+                   help=f"file name to ignore (default: {', '.join(DEFAULT_EXCLUDE)}); can repeat")
+    m.add_argument("--peak", type=float, default=0.98, help="loudest allowed peak before turning everything down (default 0.98)")
+    m.add_argument("--json", action="store_true", help="print JSON instead of text")
+    m.add_argument("--html", metavar="FILE", help="write an interactive HTML listening audit report")
+
+    v = sub.add_parser("verify", help="re-check mixes: mixture = sum of stems, bleed = recipe")
+    v.add_argument("folder", help="a folder written by 'mixforge make' (or one mix)")
+    v.add_argument("--json", action="store_true", help="print JSON instead of text")
+    v.add_argument("--html", metavar="FILE", help="write an interactive HTML listening audit report")
+
+    a = ap.parse_args(argv)
+    if a.cmd not in ("make", "verify"):
+        ap.print_help()
+        return 2
+    try:
+        if a.cmd == "make":
+            res = make_dataset(
+                Path(a.source), Path(a.out), count=a.count, seconds=a.seconds, gain_range=tuple(a.gain_range),
+                gains_db=_gains(a.gain), bleed=[parse_bleed(b) for b in (a.bleed or [])], seed=a.seed,
+                subtype=a.subtype, sr=a.sr, exclude=tuple(a.exclude) if a.exclude else DEFAULT_EXCLUDE,
+                peak_limit=a.peak, max_songs=a.max_songs)
+            if a.html:
+                v_res = verify_folder(Path(a.out))
+                html_content = to_html(v_res, out_path=Path(a.html), base_dir=Path(a.out))
+                Path(a.html).parent.mkdir(parents=True, exist_ok=True)
+                Path(a.html).write_text(html_content, encoding="utf-8")
+            if a.json:
+                print(json.dumps({"out": str(res.out), "songs": res.songs, "mixes": res.mixes, "notes": res.notes}, indent=2))
+            else:
+                print(f"wrote {len(res.mixes)} mix(es) from {res.songs} song(s) to {res.out}")
+                for n in res.notes:
+                    print(f"note: {n}")
+                if a.html:
+                    print(f"wrote HTML report to {a.html}")
+                print(f"check them with: mixforge verify {res.out}")
+            return 0
+        res = verify_folder(Path(a.folder))
+    except (MixforgeError, OSError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    if a.html:
+        html_content = to_html(res, out_path=Path(a.html), base_dir=Path(a.folder))
+        Path(a.html).parent.mkdir(parents=True, exist_ok=True)
+        Path(a.html).write_text(html_content, encoding="utf-8")
+    if a.json:
+        print(json.dumps({"ok": res.ok, "checks": [{k: v for k, v in vars(c).items() if k != "path"} for c in res.checks]}, indent=2))
+    else:
+        for c in res.checks:
+            print(f"{'PASS' if c.ok else 'FAIL'}  {c.mix}")
+            for p in c.problems:
+                print(f"      {p}")
+        bad = sum(not c.ok for c in res.checks)
+        print(f"{len(res.checks) - bad} of {len(res.checks)} mixes OK")
+        if a.html:
+            print(f"wrote HTML report to {a.html}")
+    return 0 if res.ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mixforge_audio-0.1.0/src/mixforge/core.py

@@ -0,0 +1,168 @@
+"""The mixing itself: gains, clipping guard, cropping, and bleed. No file access here."""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy import signal
+
+from ._version import __version__
+
+
+class MixforgeError(ValueError):
+    """A problem the user can fix (bad input or option). The CLI shows it without a traceback."""
+
+
+@dataclass(frozen=True)
+class Bleed:
+    """Leak part of `source` into `target`.
+
+    `db` is the leak level relative to the source stem as it sits in the mix:
+    -20 means the leak is 10 times quieter than the source (amplitude), -6 about half.
+    `lowpass_hz` optionally removes the highs from the leak (real bleed is often duller).
+    """
+    source: str
+    target: str
+    db: float
+    lowpass_hz: float | None = None
+
+
+_BLEED_RE = re.compile(
+    r"\s*([^>:@]+?)\s*>\s*([^>:@]+?)\s*:\s*([-+]?\d+(?:\.\d+)?)\s*(?:@\s*(\d+(?:\.\d+)?))?\s*")
+
+
+def parse_bleed(text: str) -> Bleed:
+    """Parse 'drums>vocals:-26' or 'drums>vocals:-26@4000' (optional low-pass in Hz)."""
+    m = _BLEED_RE.fullmatch(text)
+    if not m:
+        raise MixforgeError(f"bad bleed {text!r}: use SOURCE>TARGET:DB, e.g. drums>vocals:-26 "
+                            "(optionally @LOWPASS_HZ, e.g. drums>vocals:-26@4000)")
+    src, dst, db, lp = m.groups()
+    return Bleed(src, dst, float(db), float(lp) if lp else None)
+
+
+def leak_signal(source: np.ndarray, db: float, lowpass_hz: float | None, sr: int) -> np.ndarray:
+    """The audio that leaks: the source, scaled by `db`, optionally low-passed. Shape (samples, channels)."""
+    leak = np.asarray(source, dtype=np.float64) * (10.0 ** (db / 20.0))
+    if lowpass_hz is not None:
+        if not (0 < lowpass_hz < sr / 2):
+            raise MixforgeError(f"bleed low-pass {lowpass_hz} Hz must be between 0 and half the sample rate ({sr / 2:g})")
+        sos = signal.butter(4, lowpass_hz, btype="low", fs=sr, output="sos")
+        leak = signal.sosfilt(sos, leak, axis=0)
+    return leak
+
+
+def _rms(x: np.ndarray) -> float:
+    return float(np.sqrt(np.mean(np.square(x)))) if x.size else 0.0
+
+
+def _db(x: float) -> float | None:
+    return round(20.0 * math.log10(x), 4) if x > 1e-12 else None
+
+
+@dataclass
+class MixResult:
+    mixture: np.ndarray                  # (samples, channels)
+    stems: dict[str, np.ndarray]         # the answer key: clean stems exactly as they sit in the mixture
+    leaky: dict[str, np.ndarray] | None  # same stems with the requested bleed added (None if no bleed)
+    recipe: dict
+    sr: int
+
+
+def make_mix(stems: dict[str, np.ndarray], sr: int, *, gains_db: dict[str, float] | None = None,
+             gain_range: tuple[float, float] = (0.0, 0.0), bleed=(), seconds: float | None = None,
+             seed=0, peak_limit: float = 0.98, song: str = "", notes=()) -> MixResult:
+    """Mix `stems` (name -> array of shape (samples,) or (samples, channels), all the same shape).
+
+    The mixture is the exact sum of the returned stems. If that sum would be louder than `peak_limit`,
+    every stem and the mixture are scaled down together, so the sum still holds.
+    """
+    if len(stems) < 2:
+        raise MixforgeError("need at least 2 stems to make a mix")
+    arrs = {}
+    for name, a in stems.items():
+        a = np.asarray(a)                        # converted to float64 only after cropping (saves memory on long songs)
+        arrs[name] = a[:, None] if a.ndim == 1 else a
+    shapes = {a.shape for a in arrs.values()}
+    if len(shapes) != 1:
+        raise MixforgeError(f"all stems must have the same length and channels, got {sorted(shapes)}")
+    names = sorted(arrs)
+    n, ch = next(iter(shapes))
+    lo, hi = gain_range
+    if lo > hi:
+        raise MixforgeError(f"gain range {lo}..{hi} is backwards")
+    gains_db = dict(gains_db or {})
+    for k in gains_db:
+        if k not in arrs:
+            raise MixforgeError(f"gain given for unknown stem {k!r} (stems: {', '.join(names)})")
+    bleed = list(bleed)
+    seen = set()
+    for b in bleed:
+        for end in (b.source, b.target):
+            if end not in arrs:
+                raise MixforgeError(f"bleed uses unknown stem {end!r} (stems: {', '.join(names)})")
+        if b.source == b.target:
+            raise MixforgeError(f"bleed from {b.source!r} into itself makes no sense")
+        if (b.source, b.target) in seen:
+            raise MixforgeError(f"bleed {b.source}>{b.target} given twice")
+        seen.add((b.source, b.target))
+        if b.lowpass_hz is not None and not (0 < b.lowpass_hz < sr / 2):
+            raise MixforgeError(f"bleed low-pass {b.lowpass_hz} Hz must be between 0 and half the sample rate ({sr / 2:g})")
+
+    rng = np.random.default_rng(seed)
+    notes = list(notes)
+
+    # crop one aligned window out of every stem
+    offset, n_use = 0, n
+    if seconds is not None:
+        want = int(round(seconds * sr))
+        if want <= 0:
+            raise MixforgeError("--seconds must be positive")
+        if n > want:
+            offset = int(rng.integers(0, n - want + 1))
+            n_use = want
+        else:
+            notes.append(f"song is {n / sr:.2f} s, shorter than the {seconds:g} s asked for; used all of it")
+
+    # gains (drawn in sorted-name order so a seed always gives the same result)
+    gain_used = {}
+    for name in names:
+        g = rng.uniform(lo, hi)
+        gain_used[name] = float(gains_db[name]) if name in gains_db else round(float(g), 4)
+    gained = {name: arrs[name][offset:offset + n_use].astype(np.float64) * (10.0 ** (gain_used[name] / 20.0))
+              for name in names}
+
+    mixture = sum(gained[name] for name in names)
+    peak = float(np.abs(mixture).max()) if mixture.size else 0.0
+    scale = min(1.0, peak_limit / peak) if peak > 0 else 1.0
+    if scale < 1.0:
+        gained = {k: v * scale for k, v in gained.items()}
+        mixture = sum(gained[name] for name in names)
+        notes.append(f"mix would clip; everything scaled by {20 * math.log10(scale):.2f} dB")
+
+    leaky, bleed_rec = None, []
+    if bleed:
+        leaky = {name: gained[name].copy() for name in names}
+        for b in bleed:
+            leak = leak_signal(gained[b.source], b.db, b.lowpass_hz, sr)
+            leaky[b.target] = leaky[b.target] + leak
+            bleed_rec.append({
+                "source": b.source, "target": b.target, "requested_db": b.db, "lowpass_hz": b.lowpass_hz,
+                "measured_db_vs_source": _db(_rms(leak) / _rms(gained[b.source])) if _rms(gained[b.source]) > 0 else None,
+                "leak_vs_target_db": _db(_rms(leak) / _rms(gained[b.target])) if _rms(gained[b.target]) > 0 else None,
+            })
+
+    recipe = {
+        "mixforge": __version__, "song": song, "seed": list(seed) if isinstance(seed, (list, tuple)) else seed,
+        "sample_rate": sr, "channels": ch, "samples": int(n_use), "seconds": round(n_use / sr, 6),
+        "offset_samples": offset, "source_samples": int(n),
+        "peak_limit": peak_limit, "peak_scale": scale,
+        "stems": {name: {"gain_db": gain_used[name],
+                         "rms_dbfs": _db(_rms(gained[name])), "silent": _rms(gained[name]) == 0.0}
+                  for name in names},
+        "bleed": bleed_rec,
+        "notes": notes,
+    }
+    return MixResult(mixture, gained, leaky, recipe, sr)