@mthines/reaper-mcp 0.19.0 → 0.70.2

package/sidecar/verify.py

@@ -0,0 +1,224 @@
+"""
+Checks an agent can run on the result of an edit (verify_edit).
+
+The agent cannot listen, so after an edit it compares the edited audio with the
+audio from before the edit. Two checks held up across a vocal and a bass in the
+experiment behind the tool (github.com/mthines/reaper-mcp issue 69):
+
+* Compensated null: estimate the delay (sub-sample), gain and polarity between the
+  two, remove them, and measure what is left. A plain null test calls a pure 4 ms
+  shift or a -3 dB gain "damage"; the compensated one reports them as numbers and
+  leaves only what changed besides them (noise, a splice, a different waveform).
+* Discontinuity: the largest sample-to-sample jump against a high percentile. A hard
+  splice or a click scores far above anything a clean edit produces. Judged against
+  the reference's own score, so a source that is naturally spiky is not flagged.
+
+Pitch, formant and transient checks were source-dependent in the experiment (they
+need a pitch range and a baseline per source), so they are not part of this module.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+# Compensated null: residual (dB below the reference) for an edit that should be transparent
+NULL_OK_DB = -50.0
+NULL_WARN_DB = -35.0
+# Discontinuity: a score is a clear click from this value up, and relative to the reference's own score
+CLICK_FAIL_SCORE = 8.0
+CLICK_FAIL_RATIO = 2.5
+CLICK_WARN_SCORE = 6.0
+CLICK_WARN_RATIO = 2.0
+
+SILENCE = 1e-6
+
+
+def _mono(audio: np.ndarray) -> np.ndarray:
+    """(channels, samples) or (samples,) to float64 mono."""
+    a = np.asarray(audio, dtype=np.float64)
+    return a if a.ndim == 1 else a.mean(axis=0)
+
+
+def _channels(audio: np.ndarray) -> np.ndarray:
+    """(channels, samples) float64, whatever the input shape."""
+    a = np.asarray(audio, dtype=np.float64)
+    return a[None, :] if a.ndim == 1 else a
+
+
+def _db(x: float, floor: float = -150.0) -> float:
+    return float(max(floor, 10.0 * np.log10(max(x, 1e-15))))
+
+
+def _fractional_delay(x: np.ndarray, lag: float) -> np.ndarray:
+    """Delay x by `lag` samples (negative = advance) with an FFT phase ramp."""
+    spectrum = np.fft.rfft(x)
+    freqs = np.fft.rfftfreq(len(x))
+    return np.fft.irfft(spectrum * np.exp(-2j * np.pi * freqs * lag), len(x))
+
+
+def compensated_null(reference: np.ndarray, edited: np.ndarray, sample_rate: int,
+                     max_lag_ms: float = 20.0) -> dict[str, Any]:
+    """
+    Delay (ms; positive = the edit is later), gain (dB), polarity and the residual
+    (dB relative to the reference) once those are removed. The inputs are cut to the
+    shorter one's length; the lag margin at both ends is left out of the residual.
+    """
+    ref_ch, edit_ch = _channels(reference), _channels(edited)
+    ref, edit = _mono(reference), _mono(edited)
+    n = min(len(ref), len(edit))
+    ref, edit = ref[:n], edit[:n]
+    # Delay and gain come from the mono sum. When both have the same channels the residual is measured on each,
+    # so swapping left and right (or any change only to the stereo image) is not hidden by the sum.
+    per_channel = ref_ch.shape[0] == edit_ch.shape[0] and ref_ch.shape[0] > 1
+    if n < int(0.1 * sample_rate):
+        return {"error": "Audio too short: need at least 0.1 s"}
+    if np.max(np.abs(ref_ch)) < SILENCE:
+        return {"error": "The reference is silent over this range"}
+    if np.max(np.abs(edit_ch)) < SILENCE:
+        return {"error": "The edited audio is silent over this range"}
+
+    lag_max = max(1, int(sample_rate * max_lag_ms / 1000.0))
+    size = 1 << (2 * n - 1).bit_length()
+    corr = np.fft.irfft(np.fft.rfft(edit, size) * np.conj(np.fft.rfft(ref, size)), size)
+    window = np.concatenate([corr[-lag_max:], corr[: lag_max + 1]])  # lags -lag_max..+lag_max
+    peak = int(np.argmax(np.abs(window)))
+    lag = float(peak - lag_max)
+    if 0 < peak < len(window) - 1:  # parabolic refinement of the correlation peak
+        a, b, c = np.abs(window[peak - 1]), np.abs(window[peak]), np.abs(window[peak + 1])
+        denom = a - 2 * b + c
+        if abs(denom) > 1e-12:
+            lag += 0.5 * (a - c) / denom
+
+    aligned = _fractional_delay(edit, -lag)  # undo the delay: bring the edit back onto the reference
+    gain = float(np.dot(ref, aligned) / (np.dot(aligned, aligned) + 1e-15))
+    margin = lag_max * 2
+    span = slice(margin, n - margin) if n > 4 * margin else slice(0, n)
+    if per_channel:
+        pairs = [(r[:n], _fractional_delay(e[:n], -lag)) for r, e in zip(ref_ch, edit_ch)]
+        residual_power = float(np.mean([np.mean((r[span] - gain * a[span]) ** 2) for r, a in pairs]))
+        ref_power = float(np.mean([np.mean(r[span] ** 2) for r, _ in pairs])) + 1e-15
+    else:
+        residual_power = float(np.mean((ref - gain * aligned)[span] ** 2))
+        ref_power = float(np.mean(ref[span] ** 2)) + 1e-15
+    return {
+        "delayMs": round(1000.0 * lag / sample_rate, 3),
+        # gain that maps the edit back to the reference; the edit is 1/gain times as loud
+        "gainDb": round(-20.0 * np.log10(abs(gain) + 1e-15), 2),
+        "polarityInverted": bool(gain < 0),
+        "residualDb": round(_db(residual_power / ref_power), 1),
+        # The residual is relative to this: with a quiet reference, rounding noise of a 16-bit file can set it
+        "referenceRmsDb": round(_db(ref_power), 1),
+    }
+
+
+def discontinuity_score(audio: np.ndarray, edge_samples: int = 0) -> dict[str, Any]:
+    """
+    Largest second difference against its 99.5th percentile, and where it happens.
+    The first and last `edge_samples` are left out: the ends of a rendered window are
+    not edit points (a delayed copy starts with a step there that is not a click).
+    """
+    x = _mono(audio)
+    if len(x) < 16 or np.max(np.abs(x)) < SILENCE:
+        return {"score": None, "atSample": None}
+    d2 = np.abs(np.diff(x, 2))
+    offset = edge_samples if len(d2) > 4 * edge_samples + 16 else 0
+    inner = d2[offset: len(d2) - offset]
+    scale = float(np.percentile(inner, 99.5))
+    if scale < 1e-12:  # a pure DC or a perfectly smooth signal: any jump is an outlier
+        scale = 1e-12
+    k = int(np.argmax(inner))
+    return {"score": round(float(inner[k] / scale), 2), "atSample": offset + k + 1}
+
+
+_VERDICT_RANK = {"unknown": 0, "ok": 1, "warn": 2, "fail": 3}
+
+
+def _worst_channel(reference: np.ndarray, edited: np.ndarray, edge_samples: int) -> tuple[dict, dict, int | None]:
+    """
+    Discontinuity of the channel that scores highest in the edit, with the reference's score for the same channel.
+    A click on one channel, or opposite clicks on left and right, would shrink or cancel in a mono sum.
+    Channel counts that differ are compared as mono sums.
+    """
+    ref_ch, edit_ch = _channels(reference), _channels(edited)
+    if ref_ch.shape[0] != edit_ch.shape[0]:
+        ref_ch, edit_ch = _mono(reference)[None, :], _mono(edited)[None, :]
+    best: tuple[dict, dict, int | None] | None = None
+    best_key: tuple[int, float] | None = None
+    for index, (ref, edit) in enumerate(zip(ref_ch, edit_ch)):
+        edit_disc, ref_disc = discontinuity_score(edit, edge_samples), discontinuity_score(ref, edge_samples)
+        if edit_disc["score"] is None:
+            continue
+        # Worst verdict first, then the biggest jump over the channel's own reference: a naturally spiky,
+        # unchanged channel must not hide a click on the other one.
+        rank = _VERDICT_RANK[_click_verdict(edit_disc["score"], ref_disc["score"])]
+        ratio = edit_disc["score"] / max(ref_disc["score"] or 1.0, 1.0)
+        if best_key is None or (rank, ratio) > best_key:
+            best, best_key = (edit_disc, ref_disc, index if len(edit_ch) > 1 else None), (rank, ratio)
+    return best or (discontinuity_score(edit_ch[0]), discontinuity_score(ref_ch[0]), None)
+
+
+def _click_verdict(edit_score: float | None, ref_score: float | None) -> str:
+    if edit_score is None:
+        return "unknown"
+    ratio = edit_score / max(ref_score or 1.0, 1.0)
+    if edit_score >= CLICK_FAIL_SCORE and ratio >= CLICK_FAIL_RATIO:
+        return "fail"
+    if edit_score >= CLICK_WARN_SCORE and ratio >= CLICK_WARN_RATIO:
+        return "warn"
+    return "ok"
+
+
+def _null_verdict(residual_db: float, expect: str) -> str:
+    if expect != "identical":
+        return "info"
+    if residual_db <= NULL_OK_DB:
+        return "ok"
+    return "warn" if residual_db <= NULL_WARN_DB else "fail"
+
+
+def verify_edit(reference: np.ndarray, edited: np.ndarray, sample_rate: int, *,
+                expect: str = "identical", time_scale: float = 1.0,
+                max_lag_ms: float = 20.0) -> dict[str, Any]:
+    """
+    Run the checks. `expect` is "identical" (the edit should leave the sound alone apart
+    from level, delay and polarity: alignment, gain, a split, a crossfade) or "changed"
+    (EQ, compression, stretch: the null residual is reported without a verdict).
+    `time_scale` != 1 means the edit changed the timing (a stretch), so the two cannot
+    be nulled against each other and only the discontinuity check runs.
+    """
+    if expect not in ("identical", "changed"):
+        return {"error": f"expect must be 'identical' or 'changed', got {expect!r}"}
+    ref_len, edit_len = np.asarray(reference).shape[-1], np.asarray(edited).shape[-1]
+    if min(ref_len, edit_len) < int(0.1 * sample_rate):
+        return {"error": "Audio too short: need at least 0.1 s"}
+    for name, audio in (("reference", reference), ("edited audio", edited)):
+        if np.max(np.abs(audio)) < SILENCE:
+            return {"error": f"The {name} is silent over this range"}
+    if abs(time_scale - 1.0) <= 1e-6 and abs(ref_len - edit_len) > sample_rate * max_lag_ms / 1000.0:
+        return {"error": f"The reference is {ref_len / sample_rate:.2f} s and the edited audio {edit_len / sample_rate:.2f} s: "
+                         "they must cover the same range (cut the reference file to the window, or use referenceTrack)"}
+    checks: dict[str, Any] = {}
+
+    edge = int(sample_rate * max_lag_ms / 1000.0)
+    edit_disc, ref_disc, channel = _worst_channel(reference, edited, edge)
+    checks["discontinuity"] = {
+        "verdict": _click_verdict(edit_disc["score"], ref_disc["score"]),
+        "score": edit_disc["score"],
+        "referenceScore": ref_disc["score"],
+        "atSeconds": None if edit_disc["atSample"] is None else round(edit_disc["atSample"] / sample_rate, 3),
+        **({"channel": channel} if channel is not None else {}),
+    }
+
+    if abs(time_scale - 1.0) > 1e-6:
+        checks["null"] = {"verdict": "skipped", "reason": "timing changed (timeScale != 1): a waveform null needs the same timing"}
+    else:
+        null = compensated_null(reference, edited, sample_rate, max_lag_ms)
+        if "error" in null:
+            return null
+        checks["null"] = {"verdict": _null_verdict(null["residualDb"], expect), **null}
+
+    verdicts = [c["verdict"] for c in checks.values()]
+    overall = "fail" if "fail" in verdicts else "warn" if "warn" in verdicts else "ok"
+    return {"verdict": overall, "expect": expect, "sampleRate": sample_rate, "checks": checks}

package/sidecar/voice_render.py

@@ -0,0 +1,295 @@
+"""Offline GM SoundFont rendering through an optional native FluidSynth library."""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import math
+import os
+import re
+import shutil
+from contextlib import ExitStack, contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+import numpy as np
+import soundfile as sf
+
+SAMPLE_RATE = 22050
+BLOCK_SIZE = 4096
+NOT_INSTALLED = (
+    "FluidSynth native library is not installed or could not be loaded. "
+    "Install it with 'brew install fluid-synth' on macOS or "
+    "'sudo apt install libfluidsynth3' on Debian/Ubuntu. "
+    "On Windows, install FluidSynth and add its DLL directory to PATH. "
+    "Supply your own local GM .sf2 via soundfontPath; no SoundFont is downloaded."
+)
+
+
+def _number(value: Any, field: str, low: float, high: float, *, integer: bool = False) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{field} must be a finite number")
+    if not low <= value <= high or not math.isfinite(value):
+        raise ValueError(f"{field} must be finite and between {low} and {high}")
+    if integer and value != int(value):
+        raise ValueError(f"{field} must be an integer")
+    return value
+
+
+def _validate_score(params: dict[str, Any]) -> None:
+    duration = _number(params["durationSeconds"], "durationSeconds", 0, 240)
+    if duration <= 0:
+        raise ValueError("durationSeconds must be greater than zero")
+    tracks = params["tracks"]
+    if not isinstance(tracks, list) or not 1 <= len(tracks) <= 8:
+        raise ValueError("tracks must contain 1 to 8 tracks")
+    names: set[str] = set()
+    total_notes = 0
+    for track in tracks:
+        if not isinstance(track, dict):
+            raise ValueError("tracks must contain objects")
+        name = track.get("name")
+        if not isinstance(name, str) or not re.fullmatch(r"[a-z][a-z0-9_-]{0,63}", name) or name == "mix":
+            raise ValueError("track name must be a lowercase filename slug, not 'mix'")
+        if name in names:
+            raise ValueError("track name must be unique")
+        names.add(name)
+        _number(track.get("channel"), "channel", 0, 15, integer=True)
+        _number(track.get("program"), "program", 0, 127, integer=True)
+        _number(track.get("gain"), "gain", 0, 1)
+        notes = track.get("notes")
+        if not isinstance(notes, list):
+            raise ValueError("notes must be an array")
+        total_notes += len(notes)
+        if total_notes > 20000:
+            raise ValueError("notes must total at most 20000 across all tracks")
+        for note in notes:
+            _validate_note(note, duration)
+
+
+def _validate_note(note: Any, duration: float) -> None:
+    if not isinstance(note, dict):
+        raise ValueError("notes must contain objects")
+    start = _number(note.get("time"), "time", 0, duration)
+    length = _number(note.get("duration"), "duration", 0, duration)
+    if start >= duration:
+        raise ValueError("note time must be before durationSeconds")
+    if length <= 0 or start + length > duration + 1e-9:
+        raise ValueError("note duration must be positive and end within durationSeconds")
+    _number(note.get("pitch"), "pitch", 0, 127, integer=True)
+    _number(note.get("velocity"), "velocity", 1, 127, integer=True)
+
+
+def _absolute_path(value: Any, field: str) -> Path:
+    if not isinstance(value, str) or not value or "\0" in value:
+        raise ValueError(f"{field} must be an absolute path without NUL bytes")
+    path = Path(value)
+    if not path.is_absolute() or ".." in path.parts:
+        raise ValueError(f"{field} must be an absolute path without '..'")
+    return path
+
+
+def _validate_paths(params: dict[str, Any]) -> tuple[Path, Path]:
+    font = _absolute_path(params["soundfontPath"], "soundfontPath")
+    if font.suffix.lower() != ".sf2" or not font.is_file():
+        raise ValueError("soundfontPath must point to an existing .sf2 file")
+    out = _absolute_path(params["outDir"], "outDir")
+    if os.path.lexists(out):
+        raise ValueError("outDir already exists; use a new directory")
+    if not out.parent.is_dir():
+        raise ValueError("outDir parent directory must already exist")
+    return font, out
+
+
+def _native() -> Any:
+    candidates = [ctypes.util.find_library("fluidsynth"), "libfluidsynth.so.3", "libfluidsynth.dylib",
+                  "/opt/homebrew/lib/libfluidsynth.dylib", "/usr/local/lib/libfluidsynth.dylib",
+                  "libfluidsynth-3.dll", "libfluidsynth.dll"]
+    for candidate in candidates:
+        if not candidate:
+            continue
+        try:
+            lib = ctypes.CDLL(candidate)
+            break
+        except OSError:
+            continue
+    else:
+        raise RuntimeError(NOT_INSTALLED)
+    ptr, integer, string = ctypes.c_void_p, ctypes.c_int, ctypes.c_char_p
+    signatures = {
+        "new_fluid_settings": (ptr, []),
+        "delete_fluid_settings": (None, [ptr]),
+        "fluid_settings_setnum": (integer, [ptr, string, ctypes.c_double]),
+        "fluid_settings_setint": (integer, [ptr, string, integer]),
+        "new_fluid_synth": (ptr, [ptr]),
+        "delete_fluid_synth": (None, [ptr]),
+        "fluid_synth_sfload": (integer, [ptr, string, integer]),
+        "fluid_synth_program_select": (integer, [ptr, integer, integer, integer, integer]),
+        "fluid_synth_noteon": (integer, [ptr, integer, integer, integer]),
+        "fluid_synth_noteoff": (integer, [ptr, integer, integer]),
+        "fluid_synth_write_float": (integer, [ptr, integer, ptr, integer, integer, ptr, integer, integer]),
+    }
+    try:
+        for name, (result, args) in signatures.items():
+            function = getattr(lib, name)
+            function.restype = result
+            function.argtypes = args
+    except AttributeError as exc:
+        raise RuntimeError(f"{NOT_INSTALLED} The library lacks a required FluidSynth function.") from exc
+    return lib
+
+
+@contextmanager
+def _synth(lib: Any, font: Path, track: dict[str, Any]) -> Iterator[Any]:
+    settings = lib.new_fluid_settings()
+    if not settings:
+        raise RuntimeError("FluidSynth could not allocate settings")
+    synth = None
+    try:
+        if lib.fluid_settings_setnum(settings, b"synth.sample-rate", SAMPLE_RATE) != 0:
+            raise RuntimeError("FluidSynth could not set its sample rate")
+        lib.fluid_settings_setnum(settings, b"synth.gain", 0.2)
+        lib.fluid_settings_setint(settings, b"synth.reverb.active", 0)
+        lib.fluid_settings_setint(settings, b"synth.chorus.active", 0)
+        synth = lib.new_fluid_synth(settings)
+        if not synth:
+            raise RuntimeError("FluidSynth could not allocate an offline synthesizer")
+        font_id = lib.fluid_synth_sfload(synth, os.fsencode(font), 1)
+        if font_id < 0:
+            raise RuntimeError("FluidSynth could not load soundfontPath as a SoundFont")
+        channel, program = int(track["channel"]), int(track["program"])
+        bank = 128 if channel == 9 else 0
+        if lib.fluid_synth_program_select(synth, channel, font_id, bank, program) != 0:
+            raise RuntimeError(f"SoundFont has no bank {bank} program {program} for track '{track['name']}'")
+        # No audio or MIDI driver is created. Samples only leave through write_float.
+        yield synth
+    finally:
+        if synth:
+            lib.delete_fluid_synth(synth)
+        lib.delete_fluid_settings(settings)
+
+
+def _events(notes: list[dict[str, Any]], frames: int) -> list[tuple[int, int, int, int, int]]:
+    events = []
+    for index, note in enumerate(notes):
+        start = min(frames - 1, round(note["time"] * SAMPLE_RATE))
+        end = min(frames, max(start + 1, round((note["time"] + note["duration"]) * SAMPLE_RATE)))
+        pitch = int(note["pitch"])
+        # Offs sort before ons at an identical sample, including adjacent repeats.
+        events.append((start, 1, index, pitch, int(note["velocity"])))
+        events.append((end, 0, index, pitch, 0))
+    return sorted(events)
+
+
+def _write_samples(lib: Any, synth: Any, output: sf.SoundFile, frames: int, gain: float) -> None:
+    while frames:
+        count = min(BLOCK_SIZE, frames)
+        block = np.empty((count, 2), dtype=np.float32)
+        if lib.fluid_synth_write_float(synth, count, block.ctypes.data, 0, 2, block.ctypes.data, 1, 2) != 0:
+            raise RuntimeError("FluidSynth failed while rendering audio samples")
+        block *= gain
+        if not np.isfinite(block).all():
+            raise RuntimeError("FluidSynth rendered non-finite audio samples")
+        output.write(block)
+        frames -= count
+
+
+def _write_track(lib: Any, font: Path, path: Path, track: dict[str, Any], frames: int) -> None:
+    channel = int(track["channel"])
+    with _synth(lib, font, track) as synth, sf.SoundFile(
+        path, "w", samplerate=SAMPLE_RATE, channels=2, format="WAV", subtype="FLOAT",
+    ) as output:
+        position = 0
+        active: dict[int, int] = {}
+        for frame, on, index, pitch, velocity in _events(track["notes"], frames):
+            _write_samples(lib, synth, output, frame - position, track["gain"])
+            position = frame
+            if on:
+                if lib.fluid_synth_noteon(synth, channel, pitch, velocity) != 0:
+                    raise RuntimeError(f"FluidSynth could not play pitch {pitch} on track '{track['name']}'")
+                active[pitch] = index
+            elif active.get(pitch) == index:
+                # An older, overlapping repeat must not turn off the newer note.
+                lib.fluid_synth_noteoff(synth, channel, pitch)
+                del active[pitch]
+        _write_samples(lib, synth, output, frames - position, track["gain"])
+
+
+def _mixed_blocks(paths: list[Path]) -> Iterator[tuple[np.ndarray, float]]:
+    with ExitStack() as stack:
+        sources = [stack.enter_context(sf.SoundFile(path)) for path in paths]
+        frames = len(sources[0])
+        for start in range(0, frames, BLOCK_SIZE):
+            mixed = np.zeros((min(BLOCK_SIZE, frames - start), 2), dtype=np.float32)
+            stem_peak = 0.0
+            for source in sources:
+                block = source.read(len(mixed), dtype="float32", always_2d=True)
+                stem_peak = max(stem_peak, float(np.max(np.abs(block))))
+                mixed += block
+            yield mixed, stem_peak
+
+
+def _apply_gain(path: Path, gain: float) -> None:
+    if gain == 1:
+        return
+    with sf.SoundFile(path, "r+") as source:
+        for start in range(0, len(source), BLOCK_SIZE):
+            source.seek(start)
+            block = source.read(BLOCK_SIZE, dtype="float32", always_2d=True)
+            block *= gain
+            source.seek(start)
+            source.write(block)
+
+
+def _finish_mix(paths: list[Path], mix_path: Path) -> tuple[float, float]:
+    peak = 0.0
+    for block, stem_peak in _mixed_blocks(paths):
+        peak = max(peak, stem_peak, float(np.max(np.abs(block))))
+    # Cover float32 rounding across all eight stems, including cancellation.
+    gain = min(1.0, 0.9 * (1 - 1e-5) / peak) if peak else 1.0
+    for path in paths:
+        _apply_gain(path, gain)
+    mix_peak = 0.0
+    with sf.SoundFile(mix_path, "w", samplerate=SAMPLE_RATE, channels=2, format="WAV", subtype="FLOAT") as output:
+        for block, _ in _mixed_blocks(paths):
+            output.write(block)
+            mix_peak = max(mix_peak, float(np.max(np.abs(block))))
+    return gain, mix_peak
+
+
+def render(params: dict[str, Any]) -> dict[str, Any]:
+    """Render isolated GM stems with common attenuation and a sample-exact summed mix.
+
+    Memory is independent of duration and stem count, apart from the bounded note
+    events and one native synth/SoundFont. Audio is streamed in 4096-frame blocks.
+    ``durationSeconds`` includes release tails; all files have the same length,
+    rounded up to the next sample. Silence has ``peakDb: None`` for JSON safety.
+    """
+    if not isinstance(params, dict):
+        raise ValueError("render params must be an object")
+    if not {"soundfontPath", "outDir", "durationSeconds", "tracks"} <= params.keys():
+        raise ValueError("soundfontPath, outDir, durationSeconds and tracks are required")
+    _validate_score(params)
+    font, out = _validate_paths(params)
+    lib = _native()
+    frames = math.ceil(params["durationSeconds"] * SAMPLE_RATE)
+    # mkdir is atomic. If another caller wins the race, never clean up its folder.
+    try:
+        out.mkdir()
+    except FileExistsError as exc:
+        raise ValueError("outDir already exists; use a new directory") from exc
+    try:
+        paths = [out / f"{track['name']}.wav" for track in params["tracks"]]
+        for path, track in zip(paths, params["tracks"]):
+            _write_track(lib, font, path, track, frames)
+        gain, peak = _finish_mix(paths, out / "mix.wav")
+        return {
+            "sampleRate": SAMPLE_RATE, "durationSeconds": frames / SAMPLE_RATE,
+            "gain": gain, "peakDb": 20 * math.log10(peak) if peak else None,
+            "mixPath": str(out / "mix.wav"),
+            "stems": [{"name": track["name"], "path": str(path)} for track, path in zip(params["tracks"], paths)],
+            "engine": "FluidSynth", "soundfontPath": str(font),
+        }
+    except BaseException:
+        shutil.rmtree(out)
+        raise