@mthines/reaper-mcp 0.19.0 → 0.70.2

package/sidecar/chords.py

@@ -0,0 +1,96 @@
+"""
+Chord recognition for the reaper-mcp sidecar, with lv-chordia (MIT): a large-vocabulary
+recognizer that returns chord segments with Harte labels ("C:maj", "A:min7", "C:maj/3",
+"N" for no chord, "X" for unknown).
+
+Opt-in: installed by `reaper-mcp setup-sidecar --with-chords`. The labels are passed on
+as they are; the TypeScript tool maps them onto the bar/beat grid and its chord names.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+from typing import Any
+
+import analysis
+
+VOCABULARIES = ("submission", "ismir2017", "full")
+NOT_INSTALLED = ("The chord model is not installed. Run: reaper-mcp setup-sidecar --with-chords "
+                 "(installs lv-chordia, ~135 MB)")
+
+
+def _load_error() -> str | None:
+    """None when the recognizer imports; else why not ("" when lv-chordia is not installed at all)."""
+    try:
+        import lv_chordia.chord_recognition  # type: ignore  # noqa: F401
+    except ModuleNotFoundError as exc:
+        return "" if exc.name == "lv_chordia" else str(exc)
+    except Exception as exc:  # noqa: BLE001 — any failure while loading means the model is unusable
+        return str(exc) or type(exc).__name__
+    return None
+
+
+def status() -> dict[str, Any]:
+    """Whether the model loads, and what to do when it does not. A package that is there but fails
+    to import (a dependency missing) counts as not installed, so `auto` falls back to the templates."""
+    if is_installed():
+        return {"installed": True, "message": ""}
+    error = _load_error()
+    if not error:
+        return {"installed": False, "message": NOT_INSTALLED}
+    return {"installed": False, "message": f"The chord model is installed but does not load ({error}). "
+                                           "Reinstall it: reaper-mcp setup-sidecar --with-chords"}
+
+
+def is_installed() -> bool:
+    return _load_error() is None
+
+
+def _recognize(path: str, vocabulary: str) -> list[dict[str, Any]]:
+    from lv_chordia.chord_recognition import chord_recognition  # type: ignore
+
+    return list(chord_recognition(audio_path=path, chord_dict_name=vocabulary) or [])
+
+
+def recognize(path: str, start: float = 0.0, end: float | None = None,
+              vocabulary: str = "submission") -> dict[str, Any]:
+    """
+    Chord segments of [start, end) of `path`, in seconds of the file:
+    {segments: [{start, end, label}], durationSeconds, vocabulary, seconds}.
+    A range is cut to a temporary WAV first (the model reads whole files).
+    """
+    if vocabulary not in VOCABULARIES:
+        raise ValueError(f"Unknown vocabulary {vocabulary}. Use {', '.join(VOCABULARIES)}")
+    if not is_installed():
+        raise RuntimeError(status()["message"])
+    t0 = time.time()
+    source, offset, temp = path, 0.0, None
+    if start > 0 or end is not None:
+        import soundfile as sf  # type: ignore
+
+        audio, sr = analysis.load_audio(path, start, end)
+        if audio.shape[1] == 0:
+            raise ValueError("The range holds no audio")
+        fd, temp = tempfile.mkstemp(suffix=".wav", prefix="reaper-mcp-chords-")
+        os.close(fd)
+        sf.write(temp, audio.T, sr, subtype="FLOAT")
+        source, offset = temp, start
+    try:
+        raw = _recognize(source, vocabulary)
+    finally:
+        if temp:
+            try:
+                os.remove(temp)
+            except OSError:
+                pass
+    segments = []
+    for seg in raw:
+        a, b = float(seg["start_time"]), float(seg["end_time"])
+        if b <= a:
+            continue
+        segments.append({"start": round(a + offset, 3), "end": round(b + offset, 3), "label": str(seg["chord"])})
+    duration = (segments[-1]["end"] - offset) if segments else 0.0
+    return {"segments": segments, "durationSeconds": round(duration, 3), "vocabulary": vocabulary,
+            "seconds": round(time.time() - t0, 2)}

package/sidecar/mixcheck.py

@@ -0,0 +1,295 @@
+"""
+Mix checks for the reaper-mcp sidecar: loudness over time, stereo correlation
+per band, and frequency masking between tracks.
+
+Same conventions as analysis.py: float32 numpy arrays shaped (channels, frames),
+numpy and torch only, results bounded in size whatever the input length.
+Levels used for balance decisions are perceived (K-weighted, LU / kDb), per
+knowledge/reference/perceived-loudness.md.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+import analysis
+
+# ---------------------------------------------------------------------------
+# Loudness curve
+# ---------------------------------------------------------------------------
+
+# A curve never returns more points than this, whatever the length.
+CURVE_POINTS = 240
+
+
+def _lufs_series(powers: np.ndarray) -> np.ndarray:
+    with np.errstate(divide="ignore"):
+        return np.where(powers > 0, -0.691 + 10.0 * np.log10(np.maximum(powers, 1e-30)), -math.inf)
+
+
+def _bucket(values: np.ndarray, points: int) -> np.ndarray:
+    """Downsample to at most `points` values, keeping each bucket's maximum (a peak is never lost)."""
+    if values.size <= points:
+        return values
+    edges = np.linspace(0, values.size, points + 1).astype(int)
+    return np.array([values[a:b].max() for a, b in zip(edges[:-1], edges[1:])])
+
+
+def _floor(values: np.ndarray) -> list[float]:
+    return [round(float(max(v, analysis.SILENCE_LUFS)), 1) for v in values]
+
+
+def loudness_curve(audio: np.ndarray, sample_rate: int, target_lufs: float | None = None,
+                   tolerance_lu: float = 1.0, points: int = CURVE_POINTS) -> dict[str, Any]:
+    """
+    Short-term (3 s) and momentary (400 ms) loudness over time, bucketed to at most
+    `points` values each (bucket maximum), with the loudest and quietest short-term
+    windows and, with a target, the spans whose short-term loudness exceeds it.
+    """
+    weighted = analysis.k_weight(audio, sample_rate)
+    integrated = analysis.integrated_loudness(audio, sample_rate, weighted)
+    duration = audio.shape[1] / sample_rate
+    st_hop = 0.5
+    st = _lufs_series(analysis._block_powers(weighted, sample_rate, 3.0, st_hop))
+    mom = _lufs_series(analysis._block_powers(weighted, sample_rate, 0.4, 0.1))
+    tp = analysis.true_peak(audio, sample_rate)
+
+    result: dict[str, Any] = {
+        "durationSeconds": round(duration, 2),
+        "integratedLufs": analysis._round(integrated if math.isfinite(integrated) else analysis.SILENCE_LUFS, 2),
+        "truePeakDbtp": analysis._round(analysis._db(tp), 2),
+        "loudnessRangeLu": analysis._round(analysis.loudness_range(audio, sample_rate, weighted), 1),
+    }
+    if math.isfinite(integrated):
+        result["plrDb"] = analysis._round(analysis._db(tp) - integrated, 1)
+
+    if mom.size:
+        m = _bucket(mom, points)
+        result["momentary"] = {"step": round(duration / m.size, 3), "lufs": _floor(m)}
+        result["maxMomentaryLufs"] = analysis._round(float(mom.max()) if np.isfinite(mom.max()) else None, 1)
+    if st.size:
+        s = _bucket(st, points)
+        result["shortTerm"] = {"step": round(duration / s.size, 3), "lufs": _floor(s)}
+        audible = np.where(np.isfinite(st) & (st > analysis.ABSOLUTE_GATE_LUFS))[0]
+        if audible.size:
+            loud, quiet = audible[np.argmax(st[audible])], audible[np.argmin(st[audible])]
+            result["loudest"] = {"start": round(loud * st_hop, 1), "end": round(loud * st_hop + 3, 1),
+                                 "lufs": round(float(st[loud]), 1)}
+            result["quietest"] = {"start": round(quiet * st_hop, 1), "end": round(quiet * st_hop + 3, 1),
+                                  "lufs": round(float(st[quiet]), 1)}
+    else:
+        result["warning"] = "Shorter than one 3 s short-term window: only momentary loudness is reported"
+
+    if target_lufs is not None and st.size:
+        result["targetLufs"] = target_lufs
+        over = st > target_lufs + tolerance_lu
+        spans: list[dict[str, Any]] = []
+        i = 0
+        while i < over.size and len(spans) < 20:
+            if over[i]:
+                j = i
+                while j + 1 < over.size and over[j + 1]:
+                    j += 1
+                spans.append({"start": round(i * st_hop, 1), "end": round(j * st_hop + 3, 1),
+                              "maxLufs": round(float(st[i:j + 1].max()), 1)})
+                i = j + 1
+            else:
+                i += 1
+        result["overTarget"] = spans
+        result["overTargetSeconds"] = round(float(over.sum()) * st_hop, 1)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Stereo correlation per band
+# ---------------------------------------------------------------------------
+
+STEREO_BANDS: list[tuple[str, float, float]] = [
+    ("low", 20, 120),
+    ("lowMid", 120, 500),
+    ("mid", 500, 2000),
+    ("high", 2000, 8000),
+    ("air", 8000, 20000),
+]
+BAND_SERIES_POINTS = 60
+STEREO_FFT = 4096
+
+
+def _stereo_spectra(audio: np.ndarray, n_fft: int = STEREO_FFT) -> tuple[np.ndarray, np.ndarray]:
+    import torch  # type: ignore
+
+    x = torch.from_numpy(np.ascontiguousarray(audio[:2], dtype=np.float32))
+    if x.shape[1] < n_fft:
+        x = torch.nn.functional.pad(x, (0, n_fft - x.shape[1]))
+    spec = torch.stft(x, n_fft=n_fft, hop_length=n_fft // 2, window=torch.hann_window(n_fft),
+                      return_complex=True, center=False).numpy()
+    return spec[0], spec[1]
+
+
+def band_correlation(audio: np.ndarray, sample_rate: int) -> dict[str, Any]:
+    """
+    Per band: energy-weighted correlation (+1 mono, 0 wide, <0 out of phase), the worst
+    ~1 s window, the share of time below 0, side-to-mid level, and a bucketed series.
+    Low end below 0 is what collapses in mono; a flag says so.
+    """
+    if audio.shape[0] < 2:
+        raise ValueError("Needs a stereo source: this one has 1 channel")
+    left, right = _stereo_spectra(audio)
+    freqs = np.fft.rfftfreq(STEREO_FFT, 1.0 / sample_rate)
+    frame_s = (STEREO_FFT // 2) / sample_rate
+    # ~1 s windows of frames for the worst-window and time-share figures
+    per_window = max(1, int(round(1.0 / frame_s)))
+    cross = (left * np.conj(right)).real
+    pl, pr = np.abs(left) ** 2, np.abs(right) ** 2
+    mid_p, side_p = np.abs(left + right) ** 2 / 4, np.abs(left - right) ** 2 / 4
+
+    bands: list[dict[str, Any]] = []
+    flags: list[str] = []
+    for name, lo, hi in STEREO_BANDS:
+        sel = (freqs >= lo) & (freqs < min(hi, sample_rate / 2))
+        if not sel.any():
+            continue
+        c, a, b = cross[sel].sum(axis=0), pl[sel].sum(axis=0), pr[sel].sum(axis=0)
+        energy = a + b
+        total = energy.sum()
+        if total <= 1e-12:
+            bands.append({"band": name, "fromHz": lo, "toHz": hi, "silent": True})
+            continue
+        overall = float(c.sum() / math.sqrt(a.sum() * b.sum())) if a.sum() > 0 and b.sum() > 0 else 0.0
+        n = c.size // per_window
+        windows: list[float] = []
+        weights: list[float] = []
+        for k in range(max(n, 1)):
+            sl = slice(k * per_window, (k + 1) * per_window if n else c.size)
+            wa, wb = a[sl].sum(), b[sl].sum()
+            if wa > 0 and wb > 0:
+                windows.append(float(c[sl].sum() / math.sqrt(wa * wb)))
+                weights.append(float(energy[sl].sum()))
+        w = np.array(windows)
+        loud = np.array(weights) > total / max(len(weights), 1) * 0.01  # ignore near-silent windows
+        audible = w[loud] if loud.any() else w
+        side, mid = side_p[sel].sum(), mid_p[sel].sum()
+        row: dict[str, Any] = {
+            "band": name, "fromHz": lo, "toHz": hi,
+            "correlation": round(overall, 3),
+            "worst": round(float(audible.min()), 3) if audible.size else None,
+            "negativeShare": round(float((audible < 0).mean()), 3) if audible.size else 0.0,
+            "sideToMidDb": analysis._round(10 * math.log10(side / mid), 1) if side > 0 and mid > 0 else None,
+            "series": [round(float(v), 2) for v in _bucket_mean(w, BAND_SERIES_POINTS)],
+        }
+        bands.append(row)
+        if name == "low" and (overall < 0.5 or row["negativeShare"] > 0.1):
+            flags.append("low end is wide or out of phase: it loses level in mono — narrow it below ~120 Hz")
+        elif overall < 0:
+            words = {"lowMid": "the low mids", "mid": "the mids", "high": "the highs", "air": "the air band"}.get(name, name)
+            flags.append(f"{words} ({lo:g}–{hi:g} Hz) out of phase overall (correlation {overall:.2f}): it cancels in mono")
+    return {"bands": bands, "windowSeconds": round(per_window * frame_s, 2), "flags": flags,
+            "durationSeconds": round(audio.shape[1] / sample_rate, 2)}
+
+
+def _bucket_mean(values: np.ndarray, points: int) -> np.ndarray:
+    if values.size <= points:
+        return values
+    edges = np.linspace(0, values.size, points + 1).astype(int)
+    return np.array([values[a:b].mean() for a, b in zip(edges[:-1], edges[1:])])
+
+
+# ---------------------------------------------------------------------------
+# Masking between tracks
+# ---------------------------------------------------------------------------
+
+# Third-octave centres from 40 Hz to 16 kHz, and the nominal labels engineers use (IEC 61260)
+MASK_CENTERS = 1000.0 * 2.0 ** (np.arange(-14, 13) / 3.0)
+MASK_LABELS = [40, 50, 63, 80, 100, 125, 160, 200, 250, 315, 400, 500, 630, 800, 1000, 1250, 1600,
+               2000, 2500, 3150, 4000, 5000, 6300, 8000, 10000, 12500, 16000]
+MASK_FFT = 4096
+# Two tracks mask each other in a band when both are active and within this many dB
+MASK_CLOSE_DB = 6.0
+# A band is active for a track in a frame when within this of the track's own loudest band-frame
+MASK_ACTIVE_DB = 30.0
+MAX_CONFLICTS = 10
+
+
+def _k_gain_db(freqs: np.ndarray, sample_rate: int) -> np.ndarray:
+    """K-weighting magnitude response at `freqs` (dB), from analysis's own coefficients."""
+    z = np.exp(-2j * np.pi * freqs / sample_rate)
+    h = np.ones_like(z)
+    for b, a in analysis._k_weighting_coeffs(sample_rate):
+        h *= (b[0] + b[1] * z + b[2] * z * z) / (a[0] + a[1] * z + a[2] * z * z)
+    return 20 * np.log10(np.maximum(np.abs(h), 1e-12))
+
+
+def _band_levels(audio: np.ndarray, sample_rate: int) -> np.ndarray:
+    """Perceived (K-weighted) third-octave levels in dB, shape (bands, frames)."""
+    power, freqs = analysis._stft_power(audio, sample_rate, MASK_FFT)
+    k = 10 ** (_k_gain_db(freqs, sample_rate) / 10)
+    power = power * k[:, None]
+    out = np.empty((MASK_CENTERS.size, power.shape[1]))
+    for i, c in enumerate(MASK_CENTERS):
+        sel = (freqs >= c / 2 ** (1 / 6)) & (freqs < c * 2 ** (1 / 6))
+        e = power[sel].sum(axis=0) if sel.any() else np.zeros(power.shape[1])
+        out[i] = 10 * np.log10(np.maximum(e, 1e-15))
+    return out
+
+
+def masking(tracks: list[tuple[str, np.ndarray]], sample_rate: int) -> dict[str, Any]:
+    """
+    Where tracks compete for the same third-octave bands at the same time.
+
+    Per pair and band, `score` is the share of frames in which both tracks are active
+    and within MASK_CLOSE_DB of each other (0..1). Conflicts are the highest-scoring
+    pair/band cells, each with which track to cut there: the one for which the band
+    matters less (further below that track's own loudest band).
+    """
+    if len(tracks) < 2:
+        raise ValueError("Needs at least 2 tracks")
+    levels = [_band_levels(a, sample_rate) for _, a in tracks]
+    frames = min(lv.shape[1] for lv in levels)
+    levels = [lv[:, :frames] for lv in levels]
+    active = []
+    profile = []
+    for lv in levels:
+        peak = lv.max()
+        active.append((lv > peak - MASK_ACTIVE_DB) & (lv > -100))
+        # Each band's typical level relative to the track's loudest band (its own spectrum shape)
+        mean_db = 10 * np.log10(np.maximum((10 ** (lv / 10)).mean(axis=1), 1e-15))
+        profile.append(mean_db - mean_db.max())
+
+    pairs: list[dict[str, Any]] = []
+    cells: list[tuple[float, float, int, int, int]] = []
+    for i in range(len(tracks)):
+        for j in range(i + 1, len(tracks)):
+            both = active[i] & active[j]
+            close = both & (np.abs(levels[i] - levels[j]) <= MASK_CLOSE_DB)
+            score = close.sum(axis=1) / frames if frames else np.zeros(MASK_CENTERS.size)
+            pairs.append({"a": tracks[i][0], "b": tracks[j][0],
+                          "scores": [round(float(s), 2) for s in score],
+                          "overall": round(float(score.mean()), 3)})
+            for k, s in enumerate(score):
+                if s >= 0.2:
+                    # Ties (a tone also leaks into the next band) go to the louder band
+                    level = float(np.mean((levels[i][k] + levels[j][k])[both[k]])) if both[k].any() else -300.0
+                    cells.append((round(float(s), 2), level, i, j, k))
+
+    cells.sort(reverse=True)
+    conflicts = []
+    for s, _, i, j, k in cells[:MAX_CONFLICTS]:
+        both = active[i][k] & active[j][k]
+        diff = float(np.median(levels[i][k][both] - levels[j][k][both])) if both.any() else 0.0
+        # Cut the track for which this band is less central to its own sound
+        cut, keep = (i, j) if profile[i][k] < profile[j][k] else (j, i)
+        conflicts.append({
+            "a": tracks[i][0], "b": tracks[j][0], "hz": MASK_LABELS[k], "score": s,
+            "levelDiffDb": round(diff, 1),
+            "suggestion": f"cut {tracks[cut][0]} around {MASK_LABELS[k]} Hz (it matters more to {tracks[keep][0]})",
+        })
+    return {
+        "bandsHz": MASK_LABELS,
+        "tracks": [name for name, _ in tracks],
+        "pairs": pairs,
+        "conflicts": conflicts,
+        "frameSeconds": round((MASK_FFT // 2) / sample_rate, 3),
+    }

package/sidecar/requirements-chords.txt

@@ -0,0 +1,6 @@
+# Chord recognition (detect_chords engine "model") — opt-in: reaper-mcp setup-sidecar --with-chords
+# lv-chordia (MIT): a large-vocabulary chord recognizer (CNN + CRF, Harte labels such as C:maj, A:min7, C:maj/3).
+# Reuses the sidecar's torch; adds librosa and its weights (~135 MB download, ~400 MB installed).
+lv-chordia==1.1.0
+# lv-chordia imports pydub, which needs the audioop module Python 3.13 removed from the standard library
+audioop-lts==0.2.2; python_version >= "3.13"

package/sidecar/requirements-separation.txt

@@ -0,0 +1,3 @@
+# Source separation (separate_stems) — opt-in: reaper-mcp setup-sidecar --with-separation
+# Demucs (Meta, MIT). Its audio I/O is not used (the sidecar reads and writes with soundfile).
+demucs==4.0.1

package/sidecar/requirements.txt

@@ -0,0 +1,17 @@
+# Audiobox Aesthetics perceptual quality model (Meta, CC-BY 4.0)
+# https://huggingface.co/facebook/audiobox-aesthetics
+audiobox-aesthetics>=0.0.4
+
+# PyTorch (required by audiobox-aesthetics; CPU build is fine for inference)
+torch>=2.2.0
+torchaudio>=2.2.0
+
+# HuggingFace Hub for model weight management
+huggingface_hub>=0.23.0
+
+# audiobox_aesthetics.utils imports requests without declaring it, and
+# huggingface_hub 2.x no longer pulls it in
+requests>=2.31.0
+
+# soundfile for audio duration check (lightweight, no heavy deps)
+soundfile>=0.12.1

package/sidecar/separation.py

@@ -0,0 +1,142 @@
+"""
+Source separation (stems from a mix) for the reaper-mcp sidecar, with Demucs
+(Meta, MIT licence): htdemucs gives drums, bass, other and vocals; htdemucs_6s
+adds guitar and piano.
+
+Opt-in: installed by `reaper-mcp setup-sidecar --with-separation` (demucs and
+the model weights, ~80 MB per model, cached by torch hub). Audio goes in and
+out through soundfile; demucs's own torchaudio-based I/O is never used
+(torchaudio 2.9+ moved load/save to torchcodec).
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import sys
+import time
+from typing import Any
+
+import numpy as np
+
+import analysis
+
+MODELS = {
+    "htdemucs": ["drums", "bass", "other", "vocals"],
+    "htdemucs_6s": ["drums", "bass", "other", "vocals", "guitar", "piano"],
+}
+NOT_INSTALLED = ("Stem separation is not installed. Run: reaper-mcp setup-sidecar --with-separation "
+                 "(installs Demucs and its model, ~80 MB)")
+
+_models: dict[str, Any] = {}
+
+
+def is_installed() -> bool:
+    try:
+        import demucs.apply  # noqa: F401  type: ignore
+        import demucs.pretrained  # noqa: F401  type: ignore
+    except Exception:  # noqa: BLE001
+        return False
+    return True
+
+
+def _device() -> str:
+    import torch  # type: ignore
+
+    if os.environ.get("REAPER_MCP_SEPARATION_DEVICE"):
+        return os.environ["REAPER_MCP_SEPARATION_DEVICE"]
+    if torch.cuda.is_available():
+        return "cuda"
+    if getattr(torch.backends, "mps", None) and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def _model(name: str) -> Any:
+    if name not in _models:
+        from demucs.pretrained import get_model  # type: ignore
+
+        model = get_model(name)
+        model.eval()
+        _models[name] = model
+    return _models[name]
+
+
+def separate(path: str, out_dir: str, model_name: str = "htdemucs", stems: list[str] | None = None,
+             start: float = 0.0, end: float | None = None, max_seconds: float | None = None) -> dict[str, Any]:
+    """
+    Split [start, end) of `path` into stems written to `out_dir/<stem>.wav` (32-bit float, never clipped;
+    the model's sample rate, stereo). `stems` keeps only those (the others are not
+    written). Returns each written stem with its path, peak and loudness.
+    """
+    if model_name not in MODELS:
+        raise ValueError(f"Unknown model {model_name}. Use {', '.join(MODELS)}")
+    wanted = stems or MODELS[model_name]
+    unknown = [s for s in wanted if s not in MODELS[model_name]]
+    if unknown:
+        raise ValueError(f"{model_name} has no stem {', '.join(unknown)}: it gives {', '.join(MODELS[model_name])}")
+    if not is_installed():
+        raise RuntimeError(NOT_INSTALLED)
+
+    import soundfile as sf  # type: ignore
+    import torch  # type: ignore
+    import torchaudio.functional as F  # type: ignore
+    from demucs.apply import apply_model  # type: ignore
+
+    audio, sr = analysis.load_audio(path, start, end)
+    if audio.shape[1] < sr:
+        raise ValueError("Audio too short: need at least 1 s")
+    if max_seconds and audio.shape[1] / sr > max_seconds + 0.5:
+        raise ValueError(f"Audio is {audio.shape[1] / sr:.0f} s: max {max_seconds:.0f} s per call (pass startTime/endTime)")
+    model = _model(model_name)
+    started = time.time()  # after the model load: the speed is the separation's own
+    wav = torch.from_numpy(audio)
+    if wav.shape[0] == 1:
+        wav = wav.repeat(2, 1)
+    wav = wav[:2]
+    if sr != model.samplerate:
+        wav = F.resample(wav, sr, model.samplerate)
+    # Demucs's own normalisation (as its CLI): zero mean, unit deviation of the mono mix
+    ref = wav.mean(0)
+    mean, std = ref.mean(), ref.std()
+    if float(std) < 1e-8:
+        raise ValueError("The audio is silent: nothing to separate")
+    wav = (wav - mean) / std
+
+    device = _device()
+    fallback: dict[str, str] = {}
+    try:
+        with torch.no_grad():
+            sources = apply_model(model, wav[None], device=device, split=True, overlap=0.25, progress=False)[0]
+    except Exception as exc:  # noqa: BLE001
+        if device == "cpu":
+            raise
+        # An op the accelerator lacks: CPU always works. Labelled apart from a plain CPU run,
+        # so the fallback shows in the speed metric and the answer.
+        fallback = {"fallbackFrom": device, "fallbackError": str(exc)[:300]}
+        print(f"separate: {device} failed, falling back to CPU: {exc}", file=sys.stderr, flush=True)
+        device = "cpu_fallback"
+        with torch.no_grad():
+            sources = apply_model(model, wav[None], device="cpu", split=True, overlap=0.25, progress=False)[0]
+    sources = sources * std + mean
+
+    os.makedirs(out_dir, exist_ok=True)
+    written = []
+    for name, src in zip(model.sources, sources):
+        if name not in wanted:
+            continue
+        data = src.cpu().numpy().astype(np.float32)
+        out = os.path.join(out_dir, f"{name}.wav")
+        sf.write(out, data.T, model.samplerate, subtype="FLOAT")  # a stem can peak above 0 dBFS
+        peak = float(np.abs(data).max(initial=0.0))
+        lufs = analysis.integrated_loudness(data, model.samplerate)
+        written.append({
+            "stem": name, "path": out,
+            "peakDbfs": analysis._round(analysis._db(peak), 1),
+            "lufs": analysis._round(lufs, 1) if math.isfinite(lufs) else None,
+        })
+    return {
+        "model": model_name, "sampleRate": int(model.samplerate), "device": device,
+        "seconds": round(audio.shape[1] / sr, 2), "processingSeconds": round(time.time() - started, 1),
+        "stems": written, "outDir": out_dir, **fallback,
+    }