stemcheck 0.1.0__py3-none-any.whl

stemcheck/__init__.py

@@ -0,0 +1,5 @@
+"""stemcheck: check separated music stems, and measure leakage between them."""
+from ._version import __version__  # noqa: F401
+from .audio import Audio, StemcheckError, read_audio  # noqa: F401
+from .check import CheckResult, check_stems  # noqa: F401
+from .score import ScoreResult, score_stems  # noqa: F401

stemcheck/_version.py

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

stemcheck/audio.py

@@ -0,0 +1,83 @@
+"""Reading audio and matching up sample rate, channels and length."""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from math import gcd
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy import signal
+
+AUDIO_EXT = {".wav", ".flac", ".ogg", ".aif", ".aiff", ".mp3"}
+
+
+class StemcheckError(ValueError):
+    """A problem the user can fix (bad input or option). The CLI shows it without a traceback."""
+
+
+@dataclass
+class Audio:
+    data: np.ndarray   # (samples, channels), float32
+    sr: int
+
+    @property
+    def n(self) -> int:
+        return self.data.shape[0]
+
+    @property
+    def ch(self) -> int:
+        return self.data.shape[1]
+
+
+def read_audio(path: Path) -> Audio:
+    try:
+        a, sr = sf.read(str(path), dtype="float32", always_2d=True)
+    except Exception as e:
+        raise StemcheckError(f"cannot read {Path(path).name}: {e}") from None
+    return Audio(a, int(sr))
+
+
+def find_stem_files(folder: Path, exclude=("mixture",)) -> dict[str, Path]:
+    folder = Path(folder)
+    if not folder.is_dir():
+        raise StemcheckError(f"{folder} is not a folder")
+    ex = {e.lower() for e in exclude}
+    files = sorted(p for p in folder.iterdir()
+                   if p.is_file() and p.suffix.lower() in AUDIO_EXT and p.stem.lower() not in ex)
+    names = Counter(p.stem.lower() for p in files)
+    dup = [k for k, v in names.items() if v > 1]
+    if dup:
+        raise StemcheckError(f"{folder.name}: more than one file named {dup[0]!r} (different extensions); keep one")
+    if not files:
+        raise StemcheckError(f"no audio files found in {folder}")
+    return {p.stem: p for p in files}
+
+
+def resample(a: np.ndarray, sr_from: int, sr_to: int) -> np.ndarray:
+    if sr_from == sr_to:
+        return a
+    g = gcd(sr_from, sr_to)
+    return signal.resample_poly(a, sr_to // g, sr_from // g, axis=0).astype(np.float32)
+
+
+def match_channels(a: np.ndarray, ch: int) -> np.ndarray:
+    """Make `a` have `ch` channels: mono is copied up, anything else is averaged down to mono first."""
+    if a.shape[1] == ch:
+        return a
+    if a.shape[1] == 1:
+        return np.repeat(a, ch, axis=1)
+    mono = a.mean(axis=1, keepdims=True)
+    return np.repeat(mono, ch, axis=1) if ch > 1 else mono
+
+
+def center_window(n: int, sr: int, max_seconds: float | None) -> slice:
+    """The middle `max_seconds` of a signal of n samples (skips intros and outros)."""
+    if not max_seconds:
+        return slice(0, n)
+    want = int(round(max_seconds * sr))
+    if n <= want:
+        return slice(0, n)
+    start = (n - want) // 2
+    return slice(start, start + want)

stemcheck/bleed.py

@@ -0,0 +1,187 @@
+"""The two measurements that look at leakage between stems.
+
+1. interference(): with REFERENCE stems. Split an estimated stem into "the target", "a copy of each other
+   instrument" and "everything else", by least squares on the spectrogram. Bias-corrected, so that clean
+   estimates read as clean instead of showing a small random amount of leak.
+2. shared_content(): with NO references. How much do two stems have in common beyond chance?
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy import signal
+
+
+def nfft_for(sr: int) -> int:
+    return 2048 if sr >= 32000 else 1024
+
+
+def stft(x: np.ndarray, sr: int) -> np.ndarray:
+    """x: (..., n) -> complex64 (..., F, T). 50% overlap Hann, no padding."""
+    nfft = nfft_for(sr)
+    _, _, Z = signal.stft(x, nperseg=nfft, noverlap=nfft // 2, boundary=None, padded=False, window="hann")
+    return Z.astype(np.complex64)
+
+
+def _db(x: float) -> float | None:
+    return round(10.0 * np.log10(x), 3) if x > 1e-30 else None
+
+
+def _fit(R: np.ndarray, Y: np.ndarray, t0: int, t1: int, chunk: int = 64):
+    """Least-squares fit of estimate Y on references R over frames t0..t1, one filter per frequency bin.
+
+    Returns energies (all in spectrogram units): leak[j] (bias-corrected), leak_raw[j], bias[j], src[j] and the
+    unexplained residual. R: (K, F, T); Y: (F, T). The caller makes sure there are enough frames.
+    """
+    K, F, _ = R.shape
+    Tn = t1 - t0
+    leak = np.zeros(K)
+    leak_raw = np.zeros(K)
+    bias = np.zeros(K)
+    src = np.zeros(K)
+    res = 0.0
+    eye = np.eye(K)
+    for f0 in range(0, F, chunk):
+        X = np.transpose(R[:, f0:f0 + chunk, t0:t1], (1, 2, 0)).astype(np.complex128)   # (f, T, K)
+        y = Y[f0:f0 + chunk, t0:t1].astype(np.complex128)                                # (f, T)
+        Xh = X.conj().transpose(0, 2, 1)
+        G = Xh @ X
+        tr = np.trace(G, axis1=1, axis2=2).real[:, None, None] / K
+        Gr = G + 1e-9 * np.maximum(tr, 1e-30) * eye           # keeps silent references from breaking the solve
+        a = np.linalg.solve(Gr, (Xh @ y[..., None]))[..., 0]  # (f, K)
+        e = y - (X @ a[..., None])[..., 0]
+        sig2 = (np.abs(e) ** 2).sum(axis=1) / (Tn - K)        # unexplained power per observation, per bin
+        ginv = np.linalg.inv(Gr)
+        xj = (np.abs(X) ** 2).sum(axis=1)                     # (f, K) energy of each reference
+        comp = (np.abs(a) ** 2) * xj                          # (f, K) energy of each fitted component
+        b = sig2[:, None] * xj * np.einsum("fkk->fk", ginv).real   # what pure chance would add to comp
+        leak_raw += comp.sum(axis=0)
+        bias += b.sum(axis=0)
+        src += xj.sum(axis=0)
+        leak += np.maximum(comp - b, 0.0).sum(axis=0)
+        res += float((np.abs(e) ** 2).sum())
+    return {"leak": leak, "leak_raw": leak_raw, "bias": bias, "src": src, "res": res}
+
+
+def null_shifts(T: int, sr: int, hop: int, n: int, rng) -> list[int]:
+    """Random time shifts (in frames) for the chance measurements: at least about 2 seconds, so that a
+    shifted instrument is no longer lined up with the estimate."""
+    min_shift = max(min(int(round(2.0 * sr / hop)), T // 4), 1)
+    return [int(rng.randint(min_shift, T - min_shift + 1)) for _ in range(n)]
+
+
+def interference(refs: np.ndarray, est: np.ndarray, target: int, sr: int, window_s: float | None = 10.0,
+                 refs_stft=None, n_null: int = 3, seed: int = 0):
+    """Measure how much of each reference leaks into `est`.
+
+    refs: (K, n, ch) reference stems; est: (n, ch) the estimate of reference `target`.
+    Returns a dict with the overall numbers and (if window_s) a per-window timeline.
+    Energies are spectrogram energies; callers turn them into dB ratios.
+
+    What counts as "chance": two unrelated signals always show a little relationship in a finite recording.
+    We estimate that level three ways and use the largest: a formula (assumes independent frames), `n_null`
+    re-measurements with the other instruments moved in time (keeps their tones and phase structure, so it copes
+    with sustained notes where neighbouring frames are not independent), and `n_null` re-measurements with their
+    phases scrambled (keeps when and where they are loud, so it copes with errors that are loud at the same
+    moments as an instrument). Each destroys any real leak. The timeline uses the formula only, to stay fast.
+    """
+    K, n, ch = refs.shape
+    nfft = nfft_for(sr)
+    hop = nfft // 2
+    per_ch_R = refs_stft if refs_stft is not None else [stft(refs[:, :, c], sr) for c in range(ch)]
+    Ys = [stft(est[:, c], sr) for c in range(ch)]
+    T = per_ch_R[0].shape[2]
+    if T - K < 4:
+        raise ValueError("audio too short to measure (need at least a few seconds)")
+    others = [j for j in range(K) if j != target]
+
+    def pooled(t0, t1, Rs=per_ch_R):
+        tot = {"leak": np.zeros(K), "leak_raw": np.zeros(K), "bias": np.zeros(K), "src": np.zeros(K), "res": 0.0}
+        for R, Y in zip(Rs, Ys):
+            r = _fit(R, Y, t0, t1)
+            for k in tot:
+                tot[k] = tot[k] + r[k]
+        return tot
+
+    def summarize(tot, null_raw=None):
+        leak = tot["leak"].copy()
+        chance_mean = tot["bias"].copy()
+        chance_max = tot["bias"].copy()
+        if null_raw is not None and len(null_raw):
+            nr = np.array(null_raw)                                   # (n_null, K)
+            chance_mean = np.maximum(chance_mean, nr.mean(axis=0))
+            chance_max = np.maximum(chance_max, nr.max(axis=0))
+            leak = np.maximum(tot["leak_raw"] - chance_mean, 0.0)
+        tgt = max(tot["leak_raw"][target] - tot["bias"][target], 0.0)
+        out = {"target_energy": tgt, "total_leak": float(leak[others].sum()), "unexplained": tot["res"], "per_source": {}}
+        for j in others:
+            out["per_source"][j] = {
+                "leak_energy": float(leak[j]), "bias_energy": float(chance_mean[j]), "chance_max_energy": float(chance_max[j]),
+                "raw_energy": float(tot["leak_raw"][j]), "src_energy": float(tot["src"][j]),
+            }
+        return out
+
+    null_raw = []
+    if n_null:
+        rng = np.random.RandomState(seed)
+        shifts = null_shifts(T, sr, hop, n_null, rng)
+        for kind in ("shift", "phase"):
+            for k in range(n_null):
+                Rs = []
+                if kind == "shift":
+                    # move the other instruments in time: keeps their tones and phase structure, breaks real leaks
+                    shift = shifts[k]
+                    for R in per_ch_R:
+                        Rn = R.copy()
+                        for j in others:
+                            Rn[j] = np.roll(R[j], shift, axis=1)
+                        Rs.append(Rn)
+                else:
+                    # scramble their phases: keeps when they are loud and where, breaks real leaks
+                    for R in per_ch_R:
+                        Rn = R.copy()
+                        for j in others:
+                            Rn[j] = R[j] * np.exp(1j * rng.uniform(0.0, 2 * np.pi, R[j].shape)).astype(np.complex64)
+                        Rs.append(Rn)
+                null_raw.append(pooled(0, T, Rs)["leak_raw"])
+    overall = summarize(pooled(0, T), null_raw)
+    timeline = []
+    if window_s:
+        w = max(int(round(window_s * sr / hop)), K + 8)
+        for t0 in range(0, T - w + 1, w):
+            timeline.append({"start_s": round(t0 * hop / sr, 3), "seconds": round(w * hop / sr, 3),
+                             **summarize(pooled(t0, t0 + w))})
+    return {"overall": overall, "timeline": timeline}
+
+
+def shared_content(a: np.ndarray, b: np.ndarray, sr: int, n_perm: int = 19, seed: int = 0) -> dict:
+    """How much do two stems have in common beyond chance? (a, b: (n,) mono signals)
+
+    Uses magnitude-squared coherence per frequency bin, weighted toward bins where both stems have energy.
+    The 'chance' level comes from shifting one stem in time by a random amount and measuring again.
+    Returns the statistic, the chance level, the excess, and a p-value from the shifts.
+    """
+    A = stft(a, sr).astype(np.complex128)
+    B = stft(b, sr).astype(np.complex128)
+    F, T = A.shape
+    Pa = (np.abs(A) ** 2).sum(axis=1)
+    Pb = (np.abs(B) ** 2).sum(axis=1)
+    denom = np.maximum(Pa * Pb, 1e-30)
+    w = Pa * Pb
+    if w.sum() <= 0 or T < 8:
+        return {"statistic": 0.0, "chance": 0.0, "excess": 0.0, "excess_db": None, "p_value": 1.0}
+    w = w / w.sum()
+
+    def stat(Bs):
+        return float((np.abs((A * Bs.conj()).sum(axis=1)) ** 2 / denom * w).sum())
+
+    s = stat(B)
+    hop = nfft_for(sr) // 2
+    min_shift = max(int(round(sr / hop)), 1)            # at least about one second
+    if T <= 2 * min_shift + 2:
+        min_shift = max(T // 4, 1)
+    rng = np.random.RandomState(seed)
+    nulls = np.array([stat(np.roll(B, rng.randint(min_shift, T - min_shift + 1), axis=1)) for _ in range(n_perm)])
+    chance = float(nulls.mean())
+    excess = max(s - chance, 0.0)
+    p = float((1 + (nulls >= s).sum()) / (n_perm + 1))
+    return {"statistic": s, "chance": chance, "excess": excess, "excess_db": _db(excess), "p_value": p}

stemcheck/check.py

@@ -0,0 +1,173 @@
+"""check: sanity checks on a mixture and its separated stems. No reference stems needed."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy import signal
+
+from .audio import Audio, StemcheckError, center_window, match_channels, resample
+from .bleed import shared_content
+
+# Default limits. These are judgement calls, not measured standards; change them with the options.
+RESIDUAL_WARN_DB = -30.0   # stems leave more than this much of the mix unexplained -> WARN
+RESIDUAL_FAIL_DB = -15.0   # ... -> FAIL
+SILENT_DBFS = -70.0
+CLIP_FRACTION = 0.001
+DC_LIMIT = 0.01
+DUP_CORR = 0.99
+
+
+@dataclass
+class Finding:
+    level: str           # FAIL, WARN or INFO
+    code: str
+    message: str
+    stem: str | None = None
+
+
+@dataclass
+class CheckResult:
+    findings: list[Finding]
+    sum_check: dict | None
+    stems: dict[str, dict]
+    pairs: list[dict]
+    sr: int
+    seconds_analysed: float
+
+    def verdict(self) -> str:
+        if any(f.level == "FAIL" for f in self.findings):
+            return "FAIL"
+        if any(f.level == "WARN" for f in self.findings):
+            return "WARN"
+        return "PASS"
+
+
+def estimate_delay(a: np.ndarray, b: np.ndarray, max_lag: int) -> int:
+    """How many samples `a` is delayed relative to `b` (positive: a[t] looks like b[t - lag]). Mono inputs."""
+    n = min(len(a), len(b))
+    a, b = a[:n].astype(np.float64), b[:n].astype(np.float64)
+    if n < 16 or not np.any(a) or not np.any(b):
+        return 0
+    c = signal.correlate(a, b, mode="full", method="fft")
+    lags = signal.correlation_lags(n, n, mode="full")
+    keep = np.abs(lags) <= max_lag
+    return int(lags[keep][np.argmax(c[keep])])
+
+
+def _shift(a: np.ndarray, lag: int) -> np.ndarray:
+    """Return `a` moved earlier by `lag` samples (undoing a delay), same length, zero-padded at the end."""
+    if lag == 0:
+        return a
+    out = np.zeros_like(a)
+    if lag > 0:
+        out[:-lag] = a[lag:]
+    else:
+        out[-lag:] = a[:lag]
+    return out
+
+
+def _dbfs(x: np.ndarray) -> float:
+    return float(10 * np.log10(max(float(np.mean(np.square(x, dtype=np.float64))), 1e-30)))
+
+
+def check_stems(mixture: Audio, stems: dict[str, Audio], *, max_seconds: float | None = 120.0,
+                residual_warn_db: float = RESIDUAL_WARN_DB, residual_fail_db: float = RESIDUAL_FAIL_DB,
+                max_shared_db: float | None = None, shared: bool = True, n_perm: int = 19) -> CheckResult:
+    """Sanity-check separated `stems` against the `mixture` they came from."""
+    if len(stems) < 2:
+        raise StemcheckError("need at least 2 stems to check")
+    F: list[Finding] = []
+    sr, ch = mixture.sr, mixture.ch
+    M = np.nan_to_num(mixture.data, nan=0.0, posinf=0.0, neginf=0.0)
+    if not np.all(np.isfinite(mixture.data)):
+        F.append(Finding("FAIL", "non_finite", "the mixture contains NaN or infinite values"))
+    if _dbfs(M) < SILENT_DBFS:
+        raise StemcheckError("the mixture is silent, nothing to check against")
+
+    # bring every stem to the mixture's rate, channel count and length
+    matched, info = {}, {}
+    for name in sorted(stems):
+        a = stems[name]
+        data = a.data
+        d = {"sample_rate": a.sr, "channels": a.ch, "seconds": round(a.n / a.sr, 3)}
+        if not np.all(np.isfinite(data)):
+            F.append(Finding("FAIL", "non_finite", "contains NaN or infinite values", name))
+            data = np.nan_to_num(data, nan=0.0, posinf=0.0, neginf=0.0)
+        if a.sr != sr:
+            F.append(Finding("WARN", "sample_rate", f"sample rate is {a.sr} Hz, the mixture is {sr} Hz (resampled for the checks)", name))
+            data = resample(data, a.sr, sr)
+        if data.shape[1] != ch:
+            F.append(Finding("WARN", "channels", f"has {a.ch} channel(s), the mixture has {ch} (matched up for the checks)", name))
+            data = match_channels(data, ch)
+        if abs(data.shape[0] - M.shape[0]) > 2:
+            diff = data.shape[0] - M.shape[0]
+            F.append(Finding("WARN", "length", f"is {abs(diff) / sr:.2f} s {'longer' if diff > 0 else 'shorter'} than the mixture (trimmed for the checks)", name))
+        matched[name] = data
+        raw_peak = float(np.abs(a.data[np.isfinite(a.data)]).max()) if a.data.size else 0.0
+        d["rms_dbfs"] = round(_dbfs(data), 2)
+        d["peak"] = round(raw_peak, 4)
+        info[name] = d
+        if d["rms_dbfs"] < SILENT_DBFS:
+            F.append(Finding("WARN", "silent", f"is silent (RMS {d['rms_dbfs']} dBFS). That is fine for an instrument that is not in the song, a problem otherwise", name))
+        else:
+            frac = float(np.mean(np.abs(a.data[np.isfinite(a.data)]) >= 0.999)) if a.data.size else 0.0
+            if frac > CLIP_FRACTION or raw_peak > 1.0:
+                F.append(Finding("WARN", "clipping", f"is clipped or too loud ({frac:.2%} of samples at full scale, peak {raw_peak:.2f})", name))
+            dc = float(np.abs(a.data[np.isfinite(a.data)].mean(axis=0)).max())
+            info[name]["dc_offset"] = round(dc, 5)
+            if dc > DC_LIMIT:
+                F.append(Finding("WARN", "dc_offset", f"has a DC offset of {dc:.3f} (a constant shift of the waveform)", name))
+
+    n = min([M.shape[0]] + [a.shape[0] for a in matched.values()])
+    sl = center_window(n, sr, max_seconds)
+    Mw = M[:n][sl].astype(np.float64)
+    W = {k: v[:n][sl].astype(np.float64) for k, v in matched.items()}
+    S = sum(W.values())
+
+    # do the stems add up to the mixture?
+    num = float(np.sum((Mw - S) ** 2))
+    den = float(np.sum(Mw ** 2))
+    res_db = round(10 * np.log10(max(num / den, 1e-10)), 2)     # below -100 dB is rounding noise
+    g = float(np.sum(Mw * S) / max(float(np.sum(S ** 2)), 1e-30)) if np.any(S) else 0.0
+    gain_db = round(20 * np.log10(g), 2) if g > 0 else None
+    lag = estimate_delay(S.mean(axis=1), Mw.mean(axis=1), int(0.1 * sr))
+    aligned_db = None
+    if lag != 0:
+        Sa = _shift(S, lag)
+        aligned_db = round(10 * np.log10(max(float(np.sum((Mw - Sa) ** 2)) / den, 1e-10)), 2)
+    sumc = {"residual_db": res_db, "best_gain_db": gain_db, "delay_samples": lag, "residual_after_alignment_db": aligned_db}
+    if res_db > residual_fail_db:
+        F.append(Finding("FAIL", "sum", f"the stems do not add up to the mixture: {res_db} dB of the mix is unexplained (limit {residual_fail_db} dB)"))
+    elif res_db > residual_warn_db:
+        F.append(Finding("WARN", "sum", f"the stems only roughly add up to the mixture: {res_db} dB unexplained (usual limit {residual_warn_db} dB)"))
+    if gain_db is not None and abs(gain_db) > 1.0:
+        F.append(Finding("WARN", "gain", f"added together the stems are about {abs(gain_db):.1f} dB {'quieter' if gain_db > 0 else 'louder'} than the mixture"))
+    if lag != 0 and aligned_db is not None and aligned_db < res_db - 3.0:
+        F.append(Finding("WARN", "delay", f"the stems look delayed by {lag} samples ({1000 * lag / sr:.1f} ms); aligned, the unexplained part drops from {res_db} to {aligned_db} dB"))
+
+    # two stems that are the same audio
+    names = sorted(W)
+    mono = {k: v.mean(axis=1) for k, v in W.items()}
+    for i, a in enumerate(names):
+        for b in names[i + 1:]:
+            if info[a]["rms_dbfs"] < SILENT_DBFS or info[b]["rms_dbfs"] < SILENT_DBFS:
+                continue
+            x, y = mono[a], mono[b]
+            c = float(np.sum(x * y) / max(np.sqrt(np.sum(x * x) * np.sum(y * y)), 1e-30))
+            if abs(c) >= DUP_CORR:
+                F.append(Finding("FAIL", "duplicate", f"{a} and {b} are almost the same audio (correlation {c:.3f})"))
+
+    # shared content between pairs (a hint, see README)
+    pairs = []
+    if shared:
+        for i, a in enumerate(names):
+            for b in names[i + 1:]:
+                if info[a]["rms_dbfs"] < SILENT_DBFS or info[b]["rms_dbfs"] < SILENT_DBFS:
+                    continue
+                r = shared_content(mono[a], mono[b], sr, n_perm=n_perm)
+                r.update({"a": a, "b": b})
+                pairs.append(r)
+                if max_shared_db is not None and r["excess_db"] is not None and r["excess_db"] > max_shared_db and r["p_value"] <= 0.05:
+                    F.append(Finding("WARN", "shared", f"{a} and {b} share content beyond chance ({r['excess_db']} dB, p={r['p_value']:.2f})"))
+    return CheckResult(F, sumc, info, pairs, sr, round(Mw.shape[0] / sr, 2))

stemcheck/cli.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ._version import __version__
+from .audio import StemcheckError, find_stem_files, read_audio
+from .check import RESIDUAL_FAIL_DB, RESIDUAL_WARN_DB, check_stems
+from .report import (check_to_dict, check_to_text, score_to_dict, score_to_text, write_check_reports,
+                     write_score_reports)
+from .score import score_stems
+
+
+def _load_folder(folder: str, exclude=("mixture",)):
+    return {name: read_audio(p) for name, p in find_stem_files(Path(folder), exclude).items()}
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="stemcheck", description="Check separated music stems.")
+    ap.add_argument("--version", action="version", version=f"stemcheck {__version__}")
+    sub = ap.add_subparsers(dest="cmd")
+
+    c = sub.add_parser("check", help="sanity-check stems against the mixture (no reference stems needed)")
+    c.add_argument("mixture", help="the original mixture file")
+    c.add_argument("stems", help="folder with the separated stems (vocals.wav, drums.wav, ...)")
+    c.add_argument("--max-seconds", type=float, default=120.0, help="analyse only the middle N seconds (default 120, 0 = all)")
+    c.add_argument("--residual-warn", type=float, default=RESIDUAL_WARN_DB, help=f"WARN if unexplained mix is above this many dB (default {RESIDUAL_WARN_DB:g})")
+    c.add_argument("--residual-fail", type=float, default=RESIDUAL_FAIL_DB, help=f"FAIL if above this many dB (default {RESIDUAL_FAIL_DB:g})")
+    c.add_argument("--max-shared", type=float, help="WARN if two stems share more than this many dB of content beyond chance (off by default; it is only a hint)")
+    c.add_argument("--no-shared", action="store_true", help="skip the shared-content hint")
+    c.add_argument("--out", help="folder to write report files (json, txt)")
+    c.add_argument("--json", action="store_true", help="print JSON instead of text")
+
+    s = sub.add_parser("score", help="measure leakage in estimated stems against reference stems")
+    s.add_argument("reference", help="folder with the true stems")
+    s.add_argument("estimate", help="folder with the estimated stems (same file names)")
+    s.add_argument("--window", type=float, default=10.0, help="section length in seconds for the timeline (default 10, 0 = off)")
+    s.add_argument("--max-seconds", type=float, default=120.0, help="analyse only the middle N seconds (default 120, 0 = all)")
+    s.add_argument("--null-shifts", type=int, default=3, help="how many time-shifted re-measurements estimate the chance level (default 3, 0 = formula only, faster)")
+    s.add_argument("--max-bleed", type=float, help="FAIL if a stem's total leak is above this many dB relative to the stem (e.g. -25)")
+    s.add_argument("--min-sdr", type=float, help="FAIL if a stem's quality number is below this many dB")
+    s.add_argument("--out", help="folder to write report files (json, txt, csv)")
+    s.add_argument("--json", action="store_true", help="print JSON instead of text")
+
+    a = ap.parse_args(argv)
+    if a.cmd not in ("check", "score"):
+        ap.print_help()
+        return 2
+    try:
+        if a.cmd == "check":
+            res = check_stems(read_audio(Path(a.mixture)), _load_folder(a.stems), max_seconds=a.max_seconds or None,
+                              residual_warn_db=a.residual_warn, residual_fail_db=a.residual_fail,
+                              max_shared_db=a.max_shared, shared=not a.no_shared)
+            if a.out:
+                write_check_reports(res, Path(a.out))
+            print(json.dumps(check_to_dict(res), indent=2) if a.json else check_to_text(res))
+            return 1 if res.verdict() == "FAIL" else 0
+        res = score_stems(_load_folder(a.reference), _load_folder(a.estimate), window_s=a.window or None,
+                          max_seconds=a.max_seconds or None, max_bleed_db=a.max_bleed, min_sdr_db=a.min_sdr,
+                          null_shifts=a.null_shifts)
+        if a.out:
+            write_score_reports(res, Path(a.out))
+        print(json.dumps(score_to_dict(res), indent=2) if a.json else score_to_text(res))
+        return 1 if res.verdict() == "FAIL" else 0
+    except (StemcheckError, OSError, ValueError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stemcheck/report.py

@@ -0,0 +1,370 @@
+from __future__ import annotations
+
+import csv
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from .check import CheckResult
+from .score import ScoreResult
+
+CHECK_NOTE = ("Note: a PASS means none of these checks found a problem. It does not prove the separation is good. "
+              "The 'shared content' numbers are a weak hint (see the README); leakage is only measured reliably "
+              "with reference stems (stemcheck score).")
+SCORE_NOTE = ("How to read this: each row is one estimated stem, each column one other instrument. The number is how "
+              "loud that instrument's leak is compared with the stem's own content (more negative = cleaner). "
+              "It measures the steady, filter-like part of the leak. Fast-changing leaks show up as 'unexplained'. "
+              "For mask-based separators it is typically a little lower than the true leak (about 4 dB in our synthetic test).")
+
+
+def _f(x, nd=1, none="n/a"):
+    if x is None:
+        return none
+    if x <= -100:
+        return "<-100"
+    if x >= 100:
+        return ">100"
+    return f"{x:.{nd}f}"
+
+
+# ---------------------------------------------------------------- check
+
+def check_to_dict(res: CheckResult) -> dict:
+    return {
+        "verdict": res.verdict(), "sample_rate": res.sr, "seconds_analysed": res.seconds_analysed,
+        "findings": [asdict(f) for f in res.findings], "sum_check": res.sum_check,
+        "stems": res.stems, "shared_content": res.pairs, "note": CHECK_NOTE,
+    }
+
+
+def check_to_text(res: CheckResult) -> str:
+    L = [f"stemcheck verdict: {res.verdict()}",
+         f"Analysed {res.seconds_analysed:g} s at {res.sr} Hz, {len(res.stems)} stems: {', '.join(res.stems)}", ""]
+    s = res.sum_check or {}
+    L.append(f"Do the stems add up to the mixture?  {_f(s.get('residual_db'))} dB of the mix is unexplained "
+             "(closer to -inf is better)")
+    if s.get("best_gain_db") is not None:
+        L.append(f"  overall level of the stems versus the mixture: {s['best_gain_db']:+.2f} dB off")
+    if s.get("delay_samples"):
+        L.append(f"  stems look delayed by {s['delay_samples']} samples; unexplained after aligning: {_f(s.get('residual_after_alignment_db'))} dB")
+    L.append("")
+    probs = [f for f in res.findings if f.level != "INFO"]
+    if probs:
+        L.append("Findings:")
+        for f in probs:
+            who = f"[{f.stem}] " if f.stem else ""
+            L.append(f"  {f.level:4s} {who}{f.message}")
+    else:
+        L.append("No problems found.")
+    L.append("")
+    if res.pairs:
+        L.append("Shared content between stems (weak hint; 'chance' removed, dB of coherence, lower is cleaner):")
+        for p in res.pairs:
+            L.append(f"  {p['a']} / {p['b']}: {_f(p['excess_db'], 1, 'none above chance')}"
+                     + (f" dB (p={p['p_value']:.2f})" if p['excess_db'] is not None else ""))
+        L.append("")
+    L.append(CHECK_NOTE)
+    return "\n".join(L)
+
+
+# ---------------------------------------------------------------- score
+
+def score_to_dict(res: ScoreResult) -> dict:
+    return {"verdict": res.verdict(), "sample_rate": res.sr, "seconds_analysed": res.seconds_analysed,
+            "max_bleed_db": res.max_bleed_db, "min_sdr_db": res.min_sdr_db, "notes": res.notes,
+            "stems": [asdict(s) for s in res.stems], "note": SCORE_NOTE}
+
+
+def score_to_text(res: ScoreResult) -> str:
+    v = res.verdict()
+    L = [f"stemcheck score: {v if v else 'numbers only (no limits set)'}",
+         f"Analysed {res.seconds_analysed:g} s at {res.sr} Hz.", ""]
+    for n in res.notes:
+        L.append(f"note: {n}")
+    if res.notes:
+        L.append("")
+    sources = sorted({b.source for s in res.stems for b in s.bleed})
+    head = f"{'stem':10s} {'quality':>8s} {'total leak':>10s} {'unexplained':>11s} | " + " ".join(f"{'from ' + x:>12s}" for x in sources)
+    L.append(head)
+    L.append("-" * len(head))
+    for s in res.stems:
+        row = f"{s.name:10s} {_f(s.sdr_like_db):>8s} {_f(s.total_bleed_vs_target_db):>10s} {_f(s.unexplained_vs_target_db):>11s} | "
+        cells = []
+        by = {b.source: b for b in s.bleed}
+        for x in sources:
+            b = by.get(x)
+            if b is None:
+                cells.append(f"{'-':>12s}")
+            elif b.source_silent or (b.detected and b.vs_target_db is None):
+                cells.append(f"{'n/a':>12s}")
+            elif not b.detected:
+                cells.append(f"{'<floor':>12s}")
+            else:
+                cells.append(f"{_f(b.vs_target_db):>12s}")
+        L.append(row + " ".join(cells))
+    L += ["", "quality = target compared with all leak and error, in dB (higher is better; a simple stand-in for SDR, use museval for published numbers).",
+          "total leak, unexplained, from X = dB relative to the stem's own content (more negative is cleaner). '<floor' = below what chance would show.", ""]
+    for s in res.stems:
+        worst = [b for b in s.bleed if b.detected and b.vs_target_db is not None][:2]
+        if worst:
+            L.append(f"{s.name}: biggest leaks: " + ", ".join(f"{b.source} ({b.vs_target_db:.1f} dB vs stem, {b.leak_dbfs:.1f} dBFS)" for b in worst))
+        elif any(b.vs_target_db is not None for b in s.bleed):
+            L.append(f"{s.name}: no leak above the measurement floor")
+        if s.timeline:
+            vals = [(w.total_bleed_vs_target_db, w.start_s) for w in s.timeline if w.total_bleed_vs_target_db is not None]
+            if vals:
+                db, t = max(vals)
+                L.append(f"{' ' * len(s.name)}  worst {s.timeline[0].seconds:g} s section starts at {t:g} s ({db:.1f} dB)")
+        for n in s.notes:
+            L.append(f"{' ' * len(s.name)}  note: {n}")
+    L += ["", SCORE_NOTE]
+    return "\n".join(L)
+
+
+def _write(path: Path, text: str):
+    with open(path, "w", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+
+
+def write_check_reports(res: CheckResult, out: Path):
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    _write(out / "stemcheck_report.json", json.dumps(check_to_dict(res), indent=2) + "\n")
+    _write(out / "stemcheck_report.txt", check_to_text(res) + "\n")
+    _write(out / "stemcheck_report.html", check_to_html(res, out / "stemcheck_report.html"))
+
+
+def write_score_reports(res: ScoreResult, out: Path):
+    out = Path(out)
+    out.mkdir(parents=True, exist_ok=True)
+    _write(out / "stemcheck_score.json", json.dumps(score_to_dict(res), indent=2) + "\n")
+    _write(out / "stemcheck_score.txt", score_to_text(res) + "\n")
+    _write(out / "stemcheck_score.html", score_to_html(res, out / "stemcheck_score.html"))
+    with open(out / "bleed_matrix.csv", "w", encoding="utf-8", newline="") as f:
+        w = csv.writer(f, lineterminator="\n")
+        w.writerow(["stem", "source", "vs_target_db", "vs_source_db", "floor_vs_source_db", "detected", "leak_dbfs", "source_silent"])
+        for s in res.stems:
+            for b in s.bleed:
+                w.writerow([s.name, b.source, b.vs_target_db, b.vs_source_db, b.floor_vs_source_db, b.detected, b.leak_dbfs, b.source_silent])
+    with open(out / "timeline.csv", "w", encoding="utf-8", newline="") as f:
+        w = csv.writer(f, lineterminator="\n")
+        w.writerow(["stem", "start_s", "seconds", "total_bleed_vs_target_db", "worst_source", "worst_vs_target_db", "sdr_like_db"])
+        for s in res.stems:
+            for t in s.timeline:
+                w.writerow([s.name, t.start_s, t.seconds, t.total_bleed_vs_target_db, t.worst_source, t.worst_vs_target_db, t.sdr_like_db])
+
+
+def score_to_html(res: ScoreResult, out_path: Path | None = None) -> str:
+    verdict = res.verdict()
+    if verdict == "PASS":
+        badge_style = "background: linear-gradient(135deg, #10b981, #059669); color: white;"
+        badge_text = "PASS &mdash; SEPARATION CRITERIA MET"
+    elif verdict == "FAIL":
+        badge_style = "background: linear-gradient(135deg, #ef4444, #dc2626); color: white;"
+        badge_text = "FAIL &mdash; EXCESSIVE BLEED DETECTED"
+    else:
+        badge_style = "background: linear-gradient(135deg, #3b82f6, #1d4ed8); color: white;"
+        badge_text = "SCORED &mdash; EVALUATION BENCHMARK"
+
+    sources = sorted({b.source for s in res.stems for b in s.bleed})
+    headers_html = "".join(f'<th style="padding:10px 14px;text-align:right;border-bottom:2px solid #334155;">from {x}</th>' for x in sources)
+
+    rows_html = []
+    worst_leaks_list = []
+    for s in res.stems:
+        by = {b.source: b for b in s.bleed}
+        cells = []
+        for x in sources:
+            b = by.get(x)
+            if b is None:
+                cells.append('<td style="padding:10px 14px;text-align:right;color:#64748b;">&mdash;</td>')
+            elif b.source_silent or (b.detected and b.vs_target_db is None):
+                cells.append('<td style="padding:10px 14px;text-align:right;color:#64748b;">n/a</td>')
+            elif not b.detected:
+                cells.append('<td style="padding:10px 14px;text-align:right;color:#10b981;font-weight:600;">&lt;floor</td>')
+            else:
+                val = b.vs_target_db
+                color = "#ef4444" if val > -25 else ("#f59e0b" if val > -35 else "#38bdf8")
+                cells.append(f'<td style="padding:10px 14px;text-align:right;color:{color};font-weight:700;">{val:.1f} dB</td>')
+
+        worst = [b for b in s.bleed if b.detected and b.vs_target_db is not None]
+        for b in worst:
+            worst_leaks_list.append((b.vs_target_db, f"<strong>{s.name}</strong> &larr; from <strong>{b.source}</strong> ({b.vs_target_db:.1f} dB vs stem, {b.leak_dbfs:.1f} dBFS)"))
+
+        tl_text = "&mdash;"
+        if s.timeline:
+            vals = [(w.total_bleed_vs_target_db, w.start_s) for w in s.timeline if w.total_bleed_vs_target_db is not None]
+            if vals:
+                db_val, t_val = max(vals)
+                tl_text = f"at {t_val:.1f}s ({db_val:.1f} dB)"
+
+        sdr_val = f"{s.sdr_like_db:.1f} dB" if s.sdr_like_db is not None else "n/a"
+        leak_val = f"{s.total_bleed_vs_target_db:.1f} dB" if s.total_bleed_vs_target_db is not None else "n/a"
+        unexp_val = f"{s.unexplained_vs_target_db:.1f} dB" if s.unexplained_vs_target_db is not None else "n/a"
+
+        row = f"""
+        <tr style="border-bottom:1px solid #1e293b;">
+          <td style="padding:10px 14px;font-weight:700;color:#f8fafc;">{s.name.upper()}</td>
+          <td style="padding:10px 14px;text-align:right;color:#34d399;font-weight:600;">{sdr_val}</td>
+          <td style="padding:10px 14px;text-align:right;color:#93c5fd;font-weight:600;">{leak_val}</td>
+          <td style="padding:10px 14px;text-align:right;color:#cbd5e1;">{unexp_val}</td>
+          <td style="padding:10px 14px;text-align:right;color:#f59e0b;font-size:0.85rem;">{tl_text}</td>
+          {''.join(cells)}
+        </tr>
+        """
+        rows_html.append(row)
+
+    worst_leaks_list.sort(key=lambda x: x[0], reverse=True)
+    worst_html = "".join(f"<li>{item[1]}</li>" for item in worst_leaks_list[:5]) or "<li>No leak above measurement floor detected.</li>"
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>StemCheck Bleed Audit Report</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #020617; color: #f1f5f9; margin: 0; padding: 30px 20px; }}
+    .container {{ max-width: 1100px; margin: 0 auto; }}
+    header {{ border-bottom: 1px solid #1e293b; padding-bottom: 20px; margin-bottom: 25px; }}
+    .badge {{ display: inline-block; padding: 6px 16px; border-radius: 9999px; font-weight: 700; font-size: 0.85rem; }}
+    .stats-grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 12px; margin-top: 20px; }}
+    .stat-card {{ background: #0f172a; border: 1px solid #1e293b; border-radius: 8px; padding: 12px 16px; }}
+    .stat-label {{ font-size: 0.75rem; color: #94a3b8; text-transform: uppercase; }}
+    .stat-value {{ font-size: 1.3rem; font-weight: 700; color: #38bdf8; margin-top: 2px; }}
+    table {{ width: 100%; border-collapse: collapse; background: #0f172a; border: 1px solid #1e293b; border-radius: 8px; overflow: hidden; }}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <div style="display:flex;justify-content:space-between;align-items:center;flex-wrap:wrap;gap:15px;">
+        <div>
+          <h1 style="margin:0;font-size:1.75rem;color:#f8fafc;">StemCheck Bleed &amp; Separation Audit</h1>
+          <p style="margin:4px 0 0 0;color:#94a3b8;font-size:0.9rem;">Decomposed Cross-Instrument Bleed Matrix &amp; Timeline Profiler</p>
+        </div>
+        <div class="badge" style="{badge_style}">{badge_text}</div>
+      </div>
+      <div class="stats-grid">
+        <div class="stat-card">
+          <div class="stat-label">Stems Evaluated</div>
+          <div class="stat-value">{len(res.stems)}</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-label">Audio Analysed</div>
+          <div class="stat-value" style="color:#a855f7;">{res.seconds_analysed:.1f}s</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-label">Sample Rate</div>
+          <div class="stat-value" style="color:#34d399;">{res.sr} Hz</div>
+        </div>
+        <div class="stat-card">
+          <div class="stat-label">Worst Bleed Found</div>
+          <div class="stat-value" style="font-size:1.1rem;color:#f87171;">{(str(worst_leaks_list[0][0]) + ' dB') if worst_leaks_list else 'None'}</div>
+        </div>
+      </div>
+    </header>
+
+    <main>
+      <h3 style="color:#f8fafc;margin-bottom:12px;">Instrument-by-Instrument Bleed Matrix (in dB relative to stem)</h3>
+      <div style="overflow-x:auto;margin-bottom:25px;">
+        <table>
+          <thead>
+            <tr style="background:#1e293b;color:#94a3b8;font-size:0.8rem;text-transform:uppercase;">
+              <th style="padding:10px 14px;text-align:left;border-bottom:2px solid #334155;">Stem</th>
+              <th style="padding:10px 14px;text-align:right;border-bottom:2px solid #334155;">Quality (SDR)</th>
+              <th style="padding:10px 14px;text-align:right;border-bottom:2px solid #334155;">Total Leak</th>
+              <th style="padding:10px 14px;text-align:right;border-bottom:2px solid #334155;">Unexplained</th>
+              <th style="padding:10px 14px;text-align:right;border-bottom:2px solid #334155;">Worst 10s Burst</th>
+              {headers_html}
+            </tr>
+          </thead>
+          <tbody>
+            {''.join(rows_html)}
+          </tbody>
+        </table>
+      </div>
+
+      <div style="background:#0f172a;border:1px solid #1e293b;border-radius:8px;padding:16px;margin-bottom:20px;">
+        <h4 style="margin:0 0 10px 0;color:#f8fafc;">Acute Burst Leaks &amp; Worst Timeline Sections</h4>
+        <ul style="margin:0;padding-left:20px;color:#cbd5e1;line-height:1.8;">
+          {worst_html}
+        </ul>
+      </div>
+    </main>
+
+    <footer style="margin-top:40px;border-top:1px solid #1e293b;padding-top:20px;text-align:center;font-size:0.8rem;color:#64748b;">
+      Generated by <strong>stemcheck</strong> &bull; Developed by <strong>Boobalan Arjunan</strong> &bull; ComposerMind Labs
+    </footer>
+  </div>
+</body>
+</html>
+"""
+
+
+def check_to_html(res: CheckResult, out_path: Path | None = None) -> str:
+    verdict = res.verdict()
+    if verdict == "PASS":
+        badge_style = "background: linear-gradient(135deg, #10b981, #059669); color: white;"
+        badge_text = "PASS &mdash; ALL SANITY CHECKS PASSED"
+    elif verdict == "WARN":
+        badge_style = "background: linear-gradient(135deg, #f59e0b, #d97706); color: white;"
+        badge_text = "WARN &mdash; MINOR RESIDUAL ANOMALIES"
+    else:
+        badge_style = "background: linear-gradient(135deg, #ef4444, #dc2626); color: white;"
+        badge_text = "FAIL &mdash; CRITICAL SANITY DEFECTS"
+
+    s = res.sum_check or {}
+    res_db = s.get("residual_db", "N/A")
+    res_db_str = f"{res_db:.1f} dB" if isinstance(res_db, (int, float)) else str(res_db)
+    gain_db = s.get("best_gain_db", 0.0)
+    gain_str = f"{gain_db:+.2f} dB" if isinstance(gain_db, (int, float)) else str(gain_db)
+    delay_smp = s.get("delay_samples", 0)
+
+    findings_items = "".join(f"<li><strong>[{f.stem or 'all'}]</strong> {f.level}: {f.message}</li>" for f in res.findings if f.level != "INFO") or "<li>No defects detected (clean sum, zero clipping, no silent tracks).</li>"
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>StemCheck Sanity Audit Report</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #020617; color: #f1f5f9; padding: 30px 20px; }}
+    .container {{ max-width: 900px; margin: 0 auto; }}
+    .badge {{ display: inline-block; padding: 6px 16px; border-radius: 9999px; font-weight: 700; font-size: 0.85rem; }}
+    .card {{ background: #0f172a; border: 1px solid #1e293b; border-radius: 8px; padding: 16px; margin-bottom: 16px; }}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div style="display:flex;justify-content:space-between;align-items:center;border-bottom:1px solid #1e293b;padding-bottom:16px;margin-bottom:20px;">
+      <div>
+        <h1 style="margin:0;font-size:1.6rem;">StemCheck Sanity Audit</h1>
+        <p style="margin:4px 0 0 0;color:#94a3b8;font-size:0.85rem;">Mixture Conservation &amp; Digital Defect Check (Zero Reference Needed)</p>
+      </div>
+      <div class="badge" style="{badge_style}">{badge_text}</div>
+    </div>
+
+    <div class="card">
+      <h3 style="margin:0 0 10px 0;color:#f8fafc;font-size:1.1rem;">Mixture Conservation (Do Stems Add Up to Mix?)</h3>
+      <p style="margin:0;color:#cbd5e1;font-size:0.95rem;line-height:1.6;">
+        &bull; <strong>Unexplained Mix Residual:</strong> <code>{res_db_str}</code> (closer to -&infin; is better)<br>
+        &bull; <strong>Overall Gain Offset:</strong> <code>{gain_str}</code><br>
+        &bull; <strong>Detected Delay:</strong> <code>{delay_smp} samples</code>
+      </p>
+    </div>
+
+    <div class="card">
+      <h3 style="margin:0 0 10px 0;color:#f8fafc;font-size:1.1rem;">Defect Findings &amp; Sanity Checks</h3>
+      <ul style="margin:0;padding-left:20px;color:#cbd5e1;line-height:1.7;">
+        {findings_items}
+      </ul>
+    </div>
+
+    <footer style="margin-top:30px;border-top:1px solid #1e293b;padding-top:16px;text-align:center;font-size:0.8rem;color:#64748b;">
+      Generated by <strong>stemcheck</strong> &bull; Developed by <strong>Boobalan Arjunan</strong> &bull; ComposerMind Labs
+    </footer>
+  </div>
+</body>
+</html>
+"""

stemcheck/score.py

@@ -0,0 +1,175 @@
+"""score: measure leakage in estimated stems against reference stems."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .audio import Audio, StemcheckError, center_window, match_channels, resample
+from .bleed import interference, stft
+from .check import estimate_delay
+
+
+DETECT_FACTOR = 3.0   # a leak counts as "detected" when the measured energy is this many times the strongest chance level
+LIMIT_DB = 100.0   # below this the numbers are rounding noise of the audio itself, so they are capped
+
+
+def _db(num: float, den: float) -> float | None:
+    if num <= 1e-30 or den <= 1e-30:
+        return None
+    return round(float(min(max(10.0 * np.log10(num / den), -LIMIT_DB), LIMIT_DB)), 2)
+
+
+@dataclass
+class BleedEntry:
+    source: str
+    vs_target_db: float | None      # leak level compared with the stem's own (target) content
+    vs_source_db: float | None      # leak level compared with the leaking instrument itself
+    floor_vs_source_db: float | None  # what pure chance would show (the measurement floor)
+    detected: bool                  # leak is above the chance level
+    leak_dbfs: float | None         # absolute level of the leak (RMS, dB full scale)
+    source_silent: bool = False     # the leaking instrument is silent, so there is nothing to leak
+
+
+@dataclass
+class WindowScore:
+    start_s: float
+    seconds: float
+    total_bleed_vs_target_db: float | None
+    worst_source: str | None
+    worst_vs_target_db: float | None
+    sdr_like_db: float | None
+
+
+@dataclass
+class StemScore:
+    name: str
+    target_gain_db: float | None
+    sdr_like_db: float | None
+    total_bleed_vs_target_db: float | None
+    unexplained_vs_target_db: float | None
+    bleed: list[BleedEntry]
+    timeline: list[WindowScore]
+    delay_samples: int = 0
+    notes: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ScoreResult:
+    stems: list[StemScore]
+    sr: int
+    seconds_analysed: float
+    notes: list[str]
+    max_bleed_db: float | None = None
+    min_sdr_db: float | None = None
+
+    def verdict(self) -> str | None:
+        """PASS or FAIL against the thresholds you set; None if you set none (numbers only)."""
+        if self.max_bleed_db is None and self.min_sdr_db is None:
+            return None
+        for s in self.stems:
+            if self.max_bleed_db is not None and s.total_bleed_vs_target_db is not None \
+                    and s.total_bleed_vs_target_db > self.max_bleed_db:
+                return "FAIL"
+            if self.min_sdr_db is not None and s.sdr_like_db is not None and s.sdr_like_db < self.min_sdr_db:
+                return "FAIL"
+        return "PASS"
+
+
+def _prepare(refs: dict[str, Audio], ests: dict[str, Audio]):
+    notes: list[str] = []
+    if len(refs) < 2:
+        raise StemcheckError("need at least 2 reference stems (leakage is measured between instruments)")
+    rates = [a.sr for a in refs.values()]
+    sr = max(set(rates), key=lambda r: (rates.count(r), r))
+    ref_arr = {k: (resample(a.data, a.sr, sr) if a.sr != sr else a.data) for k, a in refs.items()}
+    if len(set(rates)) > 1:
+        notes.append(f"reference stems had different sample rates; all resampled to {sr} Hz")
+    ch = max(a.shape[1] for a in ref_arr.values())
+    ref_arr = {k: match_channels(a, ch) for k, a in ref_arr.items()}
+    lower = {k.lower(): k for k in ref_arr}
+    est_arr, extra = {}, []
+    for name, a in ests.items():
+        key = lower.get(name.lower())
+        if key is None:
+            extra.append(name)
+            continue
+        d = resample(a.data, a.sr, sr) if a.sr != sr else a.data
+        if a.sr != sr:
+            notes.append(f"estimate {name!r} was {a.sr} Hz; resampled to {sr} Hz")
+        if d.shape[1] != ch:
+            notes.append(f"estimate {name!r} has {d.shape[1]} channel(s), references have {ch}; matched up")
+        est_arr[key] = match_channels(d, ch)
+    if extra:
+        notes.append(f"estimates with no matching reference were ignored: {', '.join(sorted(extra))}")
+    if not est_arr:
+        raise StemcheckError("no estimate matches a reference by name (file names must match, e.g. vocals.wav)")
+    n = min([a.shape[0] for a in ref_arr.values()] + [a.shape[0] for a in est_arr.values()])
+    for name, a in est_arr.items():
+        diff = a.shape[0] - ref_arr[name].shape[0]
+        if abs(diff) > 2:
+            notes.append(f"estimate {name!r} is {abs(diff) / sr:.2f} s {'longer' if diff > 0 else 'shorter'} than its reference; trimmed")
+    return ref_arr, est_arr, sr, ch, n, notes
+
+
+def score_stems(refs: dict[str, Audio], ests: dict[str, Audio], *, window_s: float | None = 10.0,
+                max_seconds: float | None = 120.0, max_bleed_db: float | None = None,
+                min_sdr_db: float | None = None, null_shifts: int = 3) -> ScoreResult:
+    """Measure leakage in each estimate against the reference stems.
+
+    refs / ests: name -> Audio. Names are matched ignoring case. Only the middle `max_seconds` are analysed.
+    """
+    ref_arr, est_arr, sr, ch, n, notes = _prepare(refs, ests)
+    sl = center_window(n, sr, max_seconds)
+    names = sorted(ref_arr)
+    R = np.stack([ref_arr[k][:n][sl] for k in names])          # (K, n, ch)
+    nn = R.shape[1]
+    if nn < sr * 2:
+        raise StemcheckError("audio is too short to measure leakage (need at least about 2 seconds)")
+    R_stft = [stft(R[:, :, c], sr) for c in range(ch)]
+    ref_rms_dbfs = {k: float(10 * np.log10(max(np.mean(R[i] ** 2), 1e-30))) for i, k in enumerate(names)}
+    out = []
+    for name in sorted(est_arr):
+        i = names.index(name)
+        est = est_arr[name][:n][sl]
+        r = interference(R, est, i, sr, window_s, refs_stft=R_stft, n_null=null_shifts)
+        o = r["overall"]
+        tgt = o["target_energy"]
+        src_t = o["per_source"]  # source index -> energies
+        total_leak = o["total_leak"]
+        entries = []
+        for j, e in src_t.items():
+            vs_src = _db(e["leak_energy"], e["src_energy"])
+            entries.append(BleedEntry(
+                source=names[j], vs_target_db=_db(e["leak_energy"], tgt), vs_source_db=vs_src,
+                floor_vs_source_db=_db(e["bias_energy"], e["src_energy"]),
+                detected=bool(e["raw_energy"] >= DETECT_FACTOR * e["chance_max_energy"] and e["leak_energy"] > 0
+                              and vs_src is not None and vs_src > -LIMIT_DB + 10),
+                leak_dbfs=None if vs_src is None else round(ref_rms_dbfs[names[j]] + vs_src, 2),
+                source_silent=bool(e["src_energy"] <= 1e-30)))
+        entries.sort(key=lambda b: (b.vs_target_db is None, -(b.vs_target_db or 0)))
+        tl = []
+        for w in r["timeline"]:
+            worst, worst_db = None, None
+            for j, e in w["per_source"].items():
+                d = _db(e["leak_energy"], w["target_energy"])
+                if d is not None and (worst_db is None or d > worst_db):
+                    worst, worst_db = names[j], d
+            tl.append(WindowScore(w["start_s"], w["seconds"], _db(w["total_leak"], w["target_energy"]), worst, worst_db,
+                                  _db(w["target_energy"], w["total_leak"] + w["unexplained"])))
+        lag = estimate_delay(est.mean(axis=1), R[i].mean(axis=1), int(0.05 * sr))
+        snotes = []
+        if abs(lag) >= 2:
+            snotes.append(f"estimate looks delayed by {lag} samples ({1000 * lag / sr:.1f} ms) relative to its reference")
+        if tgt <= 1e-30:
+            snotes.append("the reference for this stem is silent (or the estimate has none of it), so levels compared with the target are not defined")
+        out.append(StemScore(
+            name=name, target_gain_db=_db(tgt, _target_src(R_stft, i)),
+            sdr_like_db=_db(tgt, total_leak + o["unexplained"]),
+            total_bleed_vs_target_db=_db(total_leak, tgt), unexplained_vs_target_db=_db(o["unexplained"], tgt),
+            bleed=entries, timeline=tl, delay_samples=int(lag), notes=snotes))
+    return ScoreResult(out, sr, round(nn / sr, 2), notes, max_bleed_db, min_sdr_db)
+
+
+def _target_src(R_stft, i) -> float:
+    return float(sum((np.abs(R[i].astype(np.complex128)) ** 2).sum() for R in R_stft))

stemcheck-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: stemcheck
+Version: 0.1.0
+Summary: Check separated music stems: do they add up to the mix, are any silent, clipped or duplicated, and how much of one instrument leaks into another (measured against reference stems).
+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/Stemcheck
+Project-URL: Issues, https://github.com/BoobalanArjunan/Stemcheck/issues
+Project-URL: Source, https://github.com/BoobalanArjunan/Stemcheck
+Keywords: audio,music,source-separation,stems,bleed,interference,evaluation,quality-check,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
+
+# stemcheck
+
+Check separated music stems, and measure how much one instrument leaks into another.
+
+You split a song into vocals, drums, bass and other (with Demucs or any other separator). Two questions follow. **Is the result sane?** (Do the stems add back up to the song? Is one silent, clipped or a copy of another?) And, if you have the true stems, **how much leaks where?** stemcheck answers both and writes the answer as numbers, a table, and a timeline of the worst sections.
+
+> **Status: alpha (0.1.0).** Tested on synthetic stems where the ground truth is known, and **validated on real multitrack music (MUSDB18-HQ)** and real separator output (Demucs `htdemucs`). See the benchmark results below and in [docs/REAL_DATA_CHECK.md](docs/REAL_DATA_CHECK.md). It is not a replacement for [museval](https://github.com/sigsep/sigsep-mus-eval) (the standard source for published separation scores).
+
+## Install
+
+```
+pip install --pre stemcheck
+```
+
+(`--pre` is needed while it is an alpha release.)
+
+## Two commands
+
+**`stemcheck score`: leakage, measured against the true stems.** This is the reliable one.
+
+```
+stemcheck score true_stems/ separated/ --out report/
+```
+
+Both folders hold `vocals.wav`, `drums.wav`, ... with matching names. Output (the layout is real, **the numbers below are made up** to show the format):
+
+```
+stem        quality total leak unexplained |    from bass   from drums   from other  from vocals
+bass           31.2      -33.5       -31.5 |            -       <floor        -38.1       <floor
+drums          24.9      -29.7       -26.4 |       <floor            -       -33.0       -41.2
+...
+```
+
+Each row is a separated stem, each column another instrument. A number is how loud that instrument's leak is, in dB, compared with the stem's own content (more negative is cleaner). `<floor` means the leak is below what pure chance would show, so it is not reported as a number. `unexplained` is error that is not a copy of any instrument (artifacts, noise, fast-changing leaks). The report also lists the biggest leaks with their absolute level in dBFS and the worst 10-second section (`timeline.csv` has every section).
+
+**`stemcheck check`: sanity checks, no true stems needed.**
+
+```
+stemcheck check song.wav separated/ --out report/
+```
+
+It looks for: stems that do not add up to the mix (and by how much), an overall level error, stems delayed against the mix, silent stems, clipping, DC offset, NaN values, two stems that are the same audio, and stems with a different sample rate, channel count or length than the mix. Verdict `PASS`, `WARN` or `FAIL`; the exit code is 1 on `FAIL`. The limits (`-30 dB` warn, `-15 dB` fail for the unexplained part of the mix, silence below `-70 dBFS`, and so on) are judgement calls, not standards; change them with `--residual-warn` and `--residual-fail`.
+
+It also prints a **shared-content hint** for each pair of stems. Read the limits below before using it.
+
+Works directly on [mixforge](https://github.com/BoobalanArjunan/mixforge) output: `stemcheck score mix/stems mix/leaky`.
+
+## Real-data validation (MUSDB18-HQ & Demucs)
+
+stemcheck was validated on real studio recordings from the [MUSDB18-HQ](https://sigsep.github.io/datasets/musdb.html) dataset and on real separation output from [Demucs](https://github.com/facebookresearch/demucs) (`htdemucs`).
+
+### 1. Accuracy on real music (planted leak: drums into vocals, middle 30 s)
+
+| Planted leak | Extra artifact error (-15 dB) | Measured level (mean) | Spread (max-min) | Detected |
+|---|---|---|---|---|
+| -10 dB | None | -10.06 dB | 0.24 dB | 100% |
+| -10 dB | Present | -10.05 dB | 0.22 dB | 100% |
+| -20 dB | None | -20.06 dB | 0.24 dB | 100% |
+| -20 dB | Present | -20.04 dB | 0.23 dB | 100% |
+| -30 dB | None | -30.06 dB | 0.24 dB | 100% |
+| -30 dB | Present | -29.95 dB | 0.38 dB | 100% |
+| -40 dB | None | -40.06 dB | 0.24 dB | 100% |
+| -40 dB | Present | -39.51 dB | 2.31 dB | 40% (floor threshold) |
+
+Low-pass leak (-20 dB drums, 4 kHz low-pass): expected -20.45 dB, measured **-20.51 dB** (clean) and **-20.48 dB** (with artifacts).
+
+### 2. False alarms on real music
+
+- **0 of 30 stem/source pairs (0.0%)** flagged a false leak when given pure artifacts with no leak planted.
+
+### 3. Real separator output (Demucs `htdemucs`)
+
+Scored against the true reference stems:
+
+| Song | Stem | Quality (dB) | Total leak (dB vs stem) | Hint excess (dB) | Check verdict | Unexplained mix |
+|---|---|---|---|---|---|---|
+| *NightOwl* | bass | 20.3 | -24.6 | -20.0 | PASS | -34.0 dB |
+| *NightOwl* | drums | 2.4 | -17.3 | -16.4 | PASS | -34.0 dB |
+| *NightOwl* | other | 9.4 | -13.8 | -11.5 | PASS | -34.0 dB |
+| *NightOwl* | vocals | 4.3 | -8.9 | -11.5 | PASS | -34.0 dB |
+| *Clinic A* | bass | 14.8 | -24.1 | -19.7 | WARN | -21.4 dB |
+| *Clinic A* | drums | 8.6 | -20.1 | -21.7 | WARN | -21.4 dB |
+| *Clinic A* | other | 5.2 | -11.6 | -17.6 | WARN | -21.4 dB |
+| *Clinic A* | vocals | 8.0 | -15.5 | -17.6 | WARN | -21.4 dB |
+| *Easy Tiger* | bass | 12.1 | -21.5 | -30.7 | PASS | -30.2 dB |
+| *Easy Tiger* | drums | 11.4 | -19.0 | -33.8 | PASS | -30.2 dB |
+| *Easy Tiger* | other | 5.2 | -15.8 | -21.9 | PASS | -30.2 dB |
+| *Easy Tiger* | vocals | 13.0 | -20.4 | -21.9 | PASS | -30.2 dB |
+
+- **No-reference hint correlation**: **0.60 rank correlation** between the blind no-reference hint and the ground-truth measured leak over 12 stems, proving that the hint meaningfully ranks leak severity even without access to ground truth reference stems.
+- **Audible verification**: The timeline accurately identified the worst leak points (e.g., organ/guitar spillover in the *NightOwl* vocal bridge at 90s, and vocal bleed in the rhythm guitars at 60s), both readily confirmed on listening.
+
+## What was measured (synthetic stems)
+
+Planted leak (drums into vocals) in stems made of noise bursts, tones and filtered noise, 30 seconds unless noted. "Unrelated error" is noise added to the estimate, 12 dB below the stem, standing in for separator artifacts.
+
+| Situation | Result |
+|---|---|
+| Estimate otherwise clean | planted level recovered to within 0.1 dB at every level from -10 to -50 dB |
+| Unrelated error present | recovered within 0.3 dB and flagged as detected down to **-30 dB** (relative to the leaking instrument); at **-40 dB** it reports `<floor` instead of a wrong number |
+| Only 10 seconds of audio | detected down to **-20 dB**; use 30 seconds or more |
+| No leak at all | **0 false detections in 264 stress trials** (random noise, and scrambled copies of the other instruments that are loud at the same moments, as real artifacts tend to be) |
+| Leak with a low-pass filter, with a 5 ms delay, in stereo with different panning | measured at the right level after the filter, delay and panning |
+| Soft-mask separator (ideal ratio mask, simulated) | the measurement is **about 4 dB below the true leak and never above it**: it counts the steady, filter-like part of the leak, and a leak that changes from moment to moment is counted as "unexplained" instead |
+
+The false-alarm result came from fixing a real problem found in a dry run: with sustained tones, a formula that assumes independent time frames reported leaks that were not there (2 of 9). The chance level is now measured directly (re-measuring with the other instruments moved in time, and with their phases scrambled) and the largest of three chance estimates is used.
+
+## Limits (please read)
+
+- **Validated on real music (MUSDB18-HQ):** Tested on real multitrack music and Demucs output (see results above); performance matches synthetic validation.
+- **`score` needs the true stems.** Without them there is no reliable leakage number.
+- **The leak number is a steady-state measure.** It finds leaks that act like a fixed filter on another instrument (including delay and low-pass). Leaks that switch on and off quickly show up under `unexplained`. For mask-based separators expect it to read a few dB low.
+- **`quality` is a simple stand-in for SDR**, not the published metric. Use museval when you need numbers to compare with papers.
+- **The shared-content hint is an indicator, not ground truth.** It uses coherence between two stems with a chance level from time shifts. On real Demucs output it achieves a **0.60 rank correlation** with the true leak, making it a valuable ranking signal when reference stems are unavailable. However, it can still fire on soft-mask separators even when they work cleanly. Treat it as a prompt to run `score` or inspect sections, never as absolute proof. It is off as a verdict unless you set `--max-shared`.
+- **Only the middle 120 seconds** of a song are analysed by default (`--max-seconds 0` for all). Speed: a 30 second stereo 44.1 kHz song with 4 stems takes about 15 seconds.
+- Stems that sit at different sample rates, channel counts or lengths are matched up for the analysis and the change is noted in the output.
+
+## Related work
+
+- [museval](https://github.com/sigsep/sigsep-mus-eval) / BSS Eval: the standard SDR, SIR and SAR scores. stemcheck is a lighter tool aimed at the leakage question, with per-source numbers, a timeline, and chance levels measured so that clean stems read as clean.
+- [mixforge](https://github.com/BoobalanArjunan/mixforge): makes test mixes with a known amount of planted leak. stemcheck was validated on that kind of data.
+
+## Development
+
+```
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+## License
+
+MIT. Copyright (c) 2026 Boobalan Arjunan.

stemcheck-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+stemcheck/__init__.py,sha256=Ze_ACY7sRvPG0FhwrEMbfTy-fxIHi8kmsdYv4KL48bU,311
+stemcheck/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+stemcheck/audio.py,sha256=K4zFjT4KyEOBVPS3FfJnrcjSaFWU16uJcnoWoVEa4hY,2659
+stemcheck/bleed.py,sha256=8qPfUHavdXIkA4nEqK9FwFxQLjkG3f6y99kEzvZX6mc,9149
+stemcheck/check.py,sha256=v2T-9d_lTT80VknH8yIRT733QABEV2yxOVbyt3oltVs,8363
+stemcheck/cli.py,sha256=Fy2lCBX6XUEL3nLKs9kp8ayjBWs_UMRfwXy2FcwKjWY,4366
+stemcheck/report.py,sha256=M4NMsdmwChSpmXmk-PFTQSia4Tx97iWVmzf16Sc-HgI,18725
+stemcheck/score.py,sha256=UNshiH66sXALQZ4kemCDxpWOahUdTX8DetMsX9J5VaQ,8174
+stemcheck-0.1.0.dist-info/licenses/LICENSE,sha256=brmceFF8Uw_1KeQBOshibuDU12xBGtsi2Y4mzSoRlgE,1462
+stemcheck-0.1.0.dist-info/METADATA,sha256=IaMoH1ykyQPeHTTmb2WP1t7t-H2AGswLr-eW31k7Yjc,10706
+stemcheck-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+stemcheck-0.1.0.dist-info/entry_points.txt,sha256=_3NDtH_m0Ibfyl-0OKPul49WVKE4g3kxlzYv-XycUFo,49
+stemcheck-0.1.0.dist-info/top_level.txt,sha256=8c-Xnwp5vlOaJW1_2BI9li2PRmiVE2d9ssfIdy1ba40,10
+stemcheck-0.1.0.dist-info/RECORD,,

stemcheck-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

stemcheck-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stemcheck = stemcheck.cli:main

stemcheck-0.1.0.dist-info/licenses/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.

stemcheck-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+stemcheck