@mthines/reaper-mcp 0.19.0 → 0.70.2

package/sidecar/tests/test_verify.py

@@ -0,0 +1,243 @@
+"""
+Tests for sidecar/verify.py (verify_edit): what the agent is told about an edit.
+
+Run with the sidecar venv:
+    ~/.reaper-mcp/sidecar-venv/bin/python -m pytest apps/reaper-mcp-server/sidecar/tests -q
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+import verify  # noqa: E402
+
+SR = 44100
+
+
+@pytest.fixture(scope="module")
+def source() -> np.ndarray:
+    """3 s of voiced-like material: harmonics under a moving envelope plus a little breath noise."""
+    rng = np.random.default_rng(7)
+    t = np.arange(3 * SR) / SR
+    f0 = 140 + 25 * np.sin(2 * np.pi * 0.7 * t)
+    phase = 2 * np.pi * np.cumsum(f0) / SR
+    voiced = sum(np.sin(h * phase) / h for h in range(1, 12))
+    envelope = 0.5 + 0.5 * np.sin(2 * np.pi * 1.3 * t) ** 2
+    breath = np.convolve(rng.standard_normal(len(t)), np.ones(8) / 8, mode="same") * 0.05
+    return (0.2 * (envelope * voiced + breath)).astype(np.float64)
+
+
+def shifted(x: np.ndarray, ms: float) -> np.ndarray:
+    n = int(round(SR * ms / 1000))
+    return np.concatenate([np.zeros(n), x])[: len(x)]
+
+
+def test_an_untouched_copy_passes_with_nothing_to_report(source):
+    result = verify.verify_edit(source, source.copy(), SR)
+    assert result["verdict"] == "ok"
+    assert result["checks"]["null"]["residualDb"] <= -100
+    assert result["checks"]["null"]["delayMs"] == 0
+    assert result["checks"]["null"]["gainDb"] == 0
+
+
+def test_a_gain_change_is_reported_as_a_number_not_as_damage(source):
+    result = verify.verify_edit(source, source * 10 ** (-3 / 20), SR)
+    null = result["checks"]["null"]
+    assert result["verdict"] == "ok"
+    assert null["gainDb"] == pytest.approx(-3.0, abs=0.05)
+    assert null["residualDb"] <= -60
+
+
+def test_a_pure_shift_is_reported_as_its_delay_and_passes(source):
+    result = verify.verify_edit(source, shifted(source, 4.0), SR)
+    null = result["checks"]["null"]
+    assert result["verdict"] == "ok"
+    assert null["delayMs"] == pytest.approx(4.0, abs=0.05)
+    assert null["residualDb"] <= -50
+
+
+def test_the_reference_level_is_reported_so_a_noise_floor_residual_can_be_read_in_context(source):
+    quiet = source * 10 ** (-40 / 20)
+    rounded = np.round(quiet * 32768) / 32768  # a 16-bit bounce of the quiet take
+    null = verify.verify_edit(quiet, rounded, SR)["checks"]["null"]
+    loud = verify.verify_edit(source, np.round(source * 32768) / 32768, SR)["checks"]["null"]
+    assert null["referenceRmsDb"] < loud["referenceRmsDb"] - 30
+    assert null["residualDb"] > loud["residualDb"] + 30  # the same rounding is a far bigger share of a quiet take
+
+
+def test_a_fractional_sample_shift_is_found(source):
+    n = 37.4  # samples
+    edited = np.fft.irfft(np.fft.rfft(source) * np.exp(-2j * np.pi * np.fft.rfftfreq(len(source)) * n), len(source))
+    null = verify.verify_edit(source, edited, SR)["checks"]["null"]
+    assert null["delayMs"] == pytest.approx(1000 * n / SR, abs=0.02)
+    assert null["residualDb"] <= -40
+
+
+def test_a_polarity_flip_is_reported_and_passes(source):
+    result = verify.verify_edit(source, -source, SR)
+    assert result["verdict"] == "ok"
+    assert result["checks"]["null"]["polarityInverted"] is True
+
+
+def test_added_noise_fails_an_edit_that_should_be_transparent(source):
+    noise = np.random.default_rng(1).standard_normal(len(source))
+    noisy = source + noise * np.sqrt(np.mean(source**2) / 10 ** (25 / 10) / np.mean(noise**2))
+    result = verify.verify_edit(source, noisy, SR)
+    assert result["verdict"] == "fail"
+    assert result["checks"]["null"]["residualDb"] == pytest.approx(-25, abs=1.5)
+
+
+def test_the_same_difference_is_only_reported_when_the_edit_is_meant_to_change_the_sound(source):
+    noise = np.random.default_rng(1).standard_normal(len(source)) * 0.01
+    result = verify.verify_edit(source, source + noise, SR, expect="changed")
+    assert result["checks"]["null"]["verdict"] == "info"
+    assert result["verdict"] == "ok"
+    assert result["checks"]["null"]["residualDb"] > verify.NULL_OK_DB
+
+
+def test_a_hard_splice_is_flagged_where_it_happens(source):
+    spliced = source.copy()
+    cut = len(source) // 2
+    spliced[cut:] *= 0.5
+    spliced[cut : cut + 8] += 0.2
+    result = verify.verify_edit(source, spliced, SR, expect="changed")
+    disc = result["checks"]["discontinuity"]
+    assert result["verdict"] == "fail"
+    assert disc["verdict"] == "fail"
+    assert disc["atSeconds"] == pytest.approx(cut / SR, abs=0.002)
+
+
+def test_material_that_is_naturally_spiky_is_not_blamed_for_its_own_spikes():
+    rng = np.random.default_rng(3)
+    spiky = rng.standard_normal(3 * SR) * 0.01
+    spiky[::SR // 4] += 0.5  # four hits a second, in the reference and in the edit
+    result = verify.verify_edit(spiky, spiky * 0.9, SR)
+    assert result["checks"]["discontinuity"]["verdict"] == "ok"
+
+
+def test_a_delayed_copy_of_material_that_starts_abruptly_is_not_called_a_click():
+    t = np.arange(3 * SR) / SR
+    abrupt = 0.3 * np.sin(2 * np.pi * 200 * t + 1.2)  # starts mid-wave, so a delayed copy starts with a step
+    result = verify.verify_edit(abrupt, shifted(abrupt, 5.0), SR)
+    assert result["checks"]["discontinuity"]["verdict"] == "ok"
+    assert result["checks"]["null"]["delayMs"] == pytest.approx(5.0, abs=0.05)
+
+
+def _stereo_tone(seed: int = 2) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    t = np.arange(3 * SR) / SR
+    tone = 0.2 * np.sin(2 * np.pi * 220 * t) + 0.01 * rng.standard_normal(len(t))
+    return np.stack([tone, tone])
+
+
+def test_a_click_on_one_channel_is_found_and_the_channel_is_named():
+    reference = _stereo_tone()
+    clicked = reference.copy()
+    clicked[1, len(reference[0]) // 2] += 0.5
+    disc = verify.verify_edit(reference, clicked, SR, expect="changed")["checks"]["discontinuity"]
+    assert disc["verdict"] == "fail"
+    assert disc["channel"] == 1
+    assert disc["atSeconds"] == pytest.approx(1.5, abs=0.002)
+
+
+def test_opposite_clicks_on_left_and_right_do_not_cancel_out():
+    reference = _stereo_tone()
+    clicked = reference.copy()
+    k = len(reference[0]) // 2
+    clicked[0, k] += 0.5
+    clicked[1, k] -= 0.5
+    assert verify.verify_edit(reference, clicked, SR, expect="changed")["checks"]["discontinuity"]["verdict"] == "fail"
+
+
+def test_a_spiky_unchanged_channel_does_not_hide_a_click_on_the_other():
+    t = np.arange(3 * SR) / SR
+    left = 0.2 * np.sin(2 * np.pi * 220 * t)
+    left[::9000] += 0.5  # naturally spiky, identical in the edit
+    right = 0.2 * np.sin(2 * np.pi * 330 * t) + 0.002 * np.random.default_rng(4).standard_normal(len(t))
+    clicked = right.copy()
+    clicked[SR:] += 0.3  # a step
+    disc = verify.verify_edit(np.stack([left, right]), np.stack([left, clicked]), SR, expect="changed")["checks"]["discontinuity"]
+    assert disc["verdict"] == "fail"
+    assert disc["channel"] == 1
+
+
+def test_a_clean_stereo_edit_names_no_channel_problem():
+    reference = _stereo_tone()
+    result = verify.verify_edit(reference, reference * 0.7, SR)
+    assert result["verdict"] == "ok"
+    assert result["checks"]["discontinuity"]["verdict"] == "ok"
+
+
+def test_a_stretch_skips_the_null_and_still_checks_for_clicks(source):
+    stretched = source[: int(len(source) / 1.1)].copy()
+    clean = verify.verify_edit(source, stretched, SR, time_scale=1.1)
+    assert clean["checks"]["null"]["verdict"] == "skipped"
+    assert clean["verdict"] == "ok"
+
+    stretched[len(stretched) // 2 :] *= 0.4
+    stretched[len(stretched) // 2 : len(stretched) // 2 + 6] += 0.25
+    assert verify.verify_edit(source, stretched, SR, time_scale=1.1)["verdict"] == "fail"
+
+
+def test_a_stereo_gain_change_passes_and_is_reported_in_dB(source):
+    stereo = np.stack([source, source * 0.8])
+    result = verify.verify_edit(stereo, stereo * 0.5, SR)
+    assert result["checks"]["null"]["gainDb"] == pytest.approx(-6.0, abs=0.05)
+    assert result["verdict"] == "ok"
+
+
+def test_swapping_left_and_right_is_not_hidden_by_the_mono_sum():
+    rng = np.random.default_rng(5)
+    left = np.convolve(rng.standard_normal(2 * SR), np.ones(16) / 16, mode="same") * 0.2
+    right = np.convolve(rng.standard_normal(2 * SR), np.ones(16) / 16, mode="same") * 0.2
+    result = verify.verify_edit(np.stack([left, right]), np.stack([right, left]), SR)
+    assert result["verdict"] == "fail"
+    assert result["checks"]["null"]["residualDb"] > verify.NULL_WARN_DB
+
+
+def test_a_mono_edit_of_a_stereo_reference_is_compared_on_the_sum(source):
+    result = verify.verify_edit(np.stack([source, source]), source, SR)
+    assert result["verdict"] == "ok"
+
+
+@pytest.mark.parametrize("which", ["reference", "edited"])
+def test_silence_is_refused_with_a_reason(source, which):
+    silent = np.zeros_like(source)
+    args = (silent, source) if which == "reference" else (source, silent)
+    assert "silent" in verify.verify_edit(*args, SR)["error"]
+
+
+def test_too_short_audio_is_refused(source):
+    assert "too short" in verify.verify_edit(source[:1000], source[:1000], SR)["error"]
+
+
+def test_an_unknown_expectation_is_refused(source):
+    assert "expect" in verify.verify_edit(source, source, SR, expect="better")["error"]
+
+
+def test_a_silent_edit_is_refused_even_when_the_timing_changed(source):
+    assert "silent" in verify.verify_edit(source, np.zeros(int(len(source) / 1.1)), SR, time_scale=1.1)["error"]
+
+
+def test_a_reference_covering_another_range_is_refused_not_failed(source):
+    longer = np.concatenate([source[: 5 * SR // 2], source])
+    assert "same range" in verify.verify_edit(longer, source, SR)["error"]
+
+
+def test_a_polarity_flip_of_one_channel_fails_instead_of_being_called_silent():
+    reference = _stereo_tone()
+    flipped = reference.copy()
+    flipped[1] *= -1  # the mono sum of the edit cancels to nothing
+    result = verify.verify_edit(reference, flipped, SR)
+    assert "error" not in result
+    assert result["verdict"] == "fail"
+
+
+def test_empty_audio_is_refused_as_too_short():
+    assert "too short" in verify.verify_edit(np.zeros(0), np.zeros(0), SR)["error"]

package/sidecar/tests/test_voice_render.py

@@ -0,0 +1,268 @@
+"""Public validation and opt-in native SoundFont rendering checks."""
+
+from __future__ import annotations
+
+import ctypes.util
+import os
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+
+def request(tmp_path, **overrides):
+    font = tmp_path / "fixture.sf2"
+    if not font.exists():
+        font.write_bytes(b"validation only, not a SoundFont")
+    return {
+        "soundfontPath": str(font),
+        "outDir": str(tmp_path / "render"),
+        "durationSeconds": 2,
+        "tracks": [{
+            "name": "melody", "channel": 0, "program": 0, "gain": 0.8,
+            "notes": [{"time": 0, "duration": 0.5, "pitch": 60, "velocity": 100}],
+        }],
+        **overrides,
+    }
+
+
+@pytest.mark.parametrize("params", [None, [], "render", 42, {}])
+def test_refuses_a_malformed_request_without_creating_output(tmp_path, params):
+    from voice_render import render
+
+    with pytest.raises(ValueError):
+        render(params)
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.parametrize("field,value", [
+    ("durationSeconds", 0), ("durationSeconds", 241),
+    ("durationSeconds", float("nan")), ("durationSeconds", float("inf")),
+    ("durationSeconds", True), ("durationSeconds", "2"),
+    ("tracks", []), ("tracks", {}), ("tracks", [None]),
+    ("name", "../escape"), ("name", "/absolute"), ("name", "mix"),
+    ("name", "Melody"), ("name", "bad\\path"), ("name", ""),
+    ("channel", -1), ("channel", 16), ("channel", True), ("channel", 0.5),
+    ("program", -1), ("program", 128), ("program", "0"),
+    ("gain", -0.1), ("gain", 1.1), ("gain", float("nan")),
+    ("notes", None), ("notes", [None]),
+    ("time", -1), ("time", float("inf")), ("time", 2),
+    ("duration", 0), ("duration", -1), ("duration", 2.1),
+    ("duration", float("nan")),
+    ("pitch", -1), ("pitch", 128), ("pitch", 60.5),
+    ("velocity", 0), ("velocity", 128), ("velocity", True),
+])
+def test_refuses_invalid_score_fields_before_writing(tmp_path, field, value):
+    from voice_render import render
+
+    params = request(tmp_path)
+    target = params
+    if field in {"name", "channel", "program", "gain", "notes"}:
+        target = params["tracks"][0]
+    if field in {"time", "duration", "pitch", "velocity"}:
+        target = params["tracks"][0]["notes"][0]
+    target[field] = value
+    with pytest.raises(ValueError, match=field):
+        render(params)
+    assert not (tmp_path / "render").exists()
+    assert sorted(p.name for p in tmp_path.iterdir()) == ["fixture.sf2"]
+
+
+@pytest.mark.parametrize("case", ["font-relative", "font-missing", "font-directory", "font-extension",
+                                  "out-relative", "out-parent", "out-traversal", "out-existing", "out-symlink",
+                                  "font-nul", "out-nul"])
+def test_refuses_unsafe_paths_and_preserves_existing_files(tmp_path, case):
+    from voice_render import render
+
+    params = request(tmp_path)
+    sentinel = tmp_path / "keep.txt"
+    sentinel.write_text("user data")
+    if case == "font-relative":
+        params["soundfontPath"] = "fixture.sf2"
+    elif case == "font-missing":
+        params["soundfontPath"] = str(tmp_path / "missing.sf2")
+    elif case == "font-directory":
+        (tmp_path / "directory.sf2").mkdir()
+        params["soundfontPath"] = str(tmp_path / "directory.sf2")
+    elif case == "font-extension":
+        params["soundfontPath"] = str(sentinel)
+    elif case == "out-relative":
+        params["outDir"] = "render"
+    elif case == "out-parent":
+        params["outDir"] = str(tmp_path / "missing" / "render")
+    elif case == "out-traversal":
+        params["outDir"] = str(tmp_path / ".." / "render")
+    elif case == "out-existing":
+        params["outDir"] = str(tmp_path)
+    elif case == "out-symlink":
+        (tmp_path / "render").symlink_to(tmp_path / "missing-directory")
+    elif case == "font-nul":
+        params["soundfontPath"] += "\0.sf2"
+    else:
+        params["outDir"] += "\0"
+    before = sorted(p.name for p in tmp_path.iterdir())
+    with pytest.raises(ValueError, match="soundfontPath|outDir"):
+        render(params)
+    assert sorted(p.name for p in tmp_path.iterdir()) == before
+    assert sentinel.read_text() == "user data"
+
+
+@pytest.fixture
+def soundfont():
+    """Opt in with REAPER_MCP_TEST_SOUNDFONT=/absolute/path/to/a/GM.sf2."""
+    path = os.environ.get("REAPER_MCP_TEST_SOUNDFONT")
+    if not path or not ctypes.util.find_library("fluidsynth"):
+        pytest.skip("set REAPER_MCP_TEST_SOUNDFONT and install libfluidsynth for native checks")
+    return path
+
+
+def test_renders_stereo_float_stems_that_sum_to_the_mix(tmp_path, soundfont):
+    from voice_render import render
+
+    params = request(tmp_path, soundfontPath=soundfont)
+    params["tracks"].append({
+        "name": "drums", "channel": 9, "program": 0, "gain": 0.4,
+        "notes": [{"time": 0.6, "duration": 0.1, "pitch": 36, "velocity": 110}],
+    })
+    result = render(params)
+    assert result["engine"] == "FluidSynth"
+    assert result["soundfontPath"] == soundfont
+    assert result["sampleRate"] == 22050
+    assert result["durationSeconds"] == 2
+    assert 0 < result["gain"] <= 1
+    assert [s["name"] for s in result["stems"]] == ["melody", "drums"]
+    assert sorted(p.name for p in (tmp_path / "render").iterdir()) == ["drums.wav", "melody.wav", "mix.wav"]
+    stems = [sf.read(s["path"], dtype="float32")[0] for s in result["stems"]]
+    mix, sr = sf.read(result["mixPath"], dtype="float32")
+    assert sr == 22050 and mix.shape == (44100, 2)
+    assert all(sf.info(s["path"]).subtype == "FLOAT" for s in result["stems"])
+    assert sf.info(result["mixPath"]).subtype == "FLOAT"
+    assert all(np.max(np.abs(stem)) > 0.001 for stem in stems)
+    assert np.max(np.abs(stems[1][:int(0.6 * sr)])) == 0
+    assert np.max(np.abs(stems[0][int(0.51 * sr):int(0.6 * sr)])) > 0, "note releases are retained"
+    np.testing.assert_array_equal(mix, np.sum(stems, axis=0, dtype=np.float32))
+    peak = float(np.max(np.abs(mix)))
+    assert peak <= 0.9
+    assert result["peakDb"] == pytest.approx(20 * np.log10(peak), abs=1e-5)
+
+
+def test_common_attenuation_preserves_stem_balance_at_the_peak_ceiling(tmp_path, soundfont):
+    from voice_render import render
+
+    notes = [{"time": 0, "duration": 0.7, "pitch": pitch, "velocity": 127} for pitch in range(36, 84)]
+    tracks = [{"name": f"part{i}", "channel": 0, "program": 19,
+               "gain": 0.25 if i == 1 else 1, "notes": notes} for i in range(8)]
+    result = render(request(tmp_path, soundfontPath=soundfont, tracks=tracks, durationSeconds=1))
+    stems = [sf.read(s["path"], dtype="float32")[0] for s in result["stems"]]
+    mix = sf.read(result["mixPath"], dtype="float32")[0]
+    assert 0 < result["gain"] < 1, "the loud eight-part chord needs attenuation"
+    assert 0.89 < np.max(np.abs(mix)) <= 0.9
+    np.testing.assert_allclose(stems[1], stems[0] * 0.25, atol=1e-7)
+    np.testing.assert_array_equal(mix, np.sum(stems, axis=0, dtype=np.float32))
+
+
+def test_adjacent_and_overlapping_repeats_stay_audible_until_their_own_noteoff(tmp_path, soundfont):
+    from voice_render import render
+
+    params = request(tmp_path, soundfontPath=soundfont)
+    # A sustaining GM organ, not a patch whose natural decay could mimic noteoff.
+    params["tracks"][0].update(program=16, notes=[
+        {"time": 0.1, "duration": 0.4, "pitch": 60, "velocity": 100},
+        {"time": 0.5, "duration": 0.4, "pitch": 60, "velocity": 100},
+        {"time": 0.7, "duration": 0.5, "pitch": 60, "velocity": 100},
+    ])
+    result = render(params)
+    audio, sr = sf.read(result["mixPath"])
+    held = np.sqrt(np.mean(audio[int(0.75 * sr):int(0.85 * sr)] ** 2))
+    after_old_off = np.sqrt(np.mean(audio[int(1.0 * sr):int(1.1 * sr)] ** 2))
+    assert held > 0.001
+    assert np.sqrt(np.mean(audio[int(0.55 * sr):int(0.65 * sr)] ** 2)) > 0.001
+    assert after_old_off > held * 0.5, "the older repeat's 0.9 s noteoff must not silence the new note"
+    assert np.max(np.abs(audio[:int(0.1 * sr)])) == 0
+    assert np.sqrt(np.mean(audio[int(1.8 * sr):] ** 2)) < held * 0.1
+
+
+@pytest.mark.parametrize("case", ["track-count", "total-notes", "duplicate-name", "invalid-last-track"])
+def test_validates_the_whole_bounded_score_before_any_output(tmp_path, case):
+    from voice_render import render
+
+    params = request(tmp_path)
+    track = params["tracks"][0]
+    if case == "track-count":
+        params["tracks"] = [{**track, "name": f"part{i}"} for i in range(9)]
+    elif case == "total-notes":
+        params["tracks"] = [{**track, "name": f"part{i}", "notes": track["notes"] * 10001} for i in range(2)]
+    elif case == "duplicate-name":
+        params["tracks"].append(dict(track))
+    else:
+        params["tracks"].append({**track, "name": "bass", "gain": float("inf")})
+    with pytest.raises(ValueError):
+        render(params)
+    assert not (tmp_path / "render").exists()
+
+
+@pytest.mark.skipif(not ctypes.util.find_library("fluidsynth"), reason="libfluidsynth is not installed")
+def test_failed_soundfont_load_removes_only_the_new_output_folder(tmp_path):
+    from voice_render import render
+
+    params = request(tmp_path)
+    sentinel = tmp_path / "keep.txt"
+    sentinel.write_text("user data")
+    for _ in range(2):
+        with pytest.raises(RuntimeError, match="SoundFont|soundfontPath"):
+            render(params)
+        assert not (tmp_path / "render").exists()
+        assert sentinel.read_text() == "user data"
+        assert (tmp_path / "fixture.sf2").read_bytes() == b"validation only, not a SoundFont"
+
+
+def test_silent_parts_remain_silent_with_json_safe_metadata(tmp_path, soundfont):
+    from voice_render import render
+
+    params = request(tmp_path, soundfontPath=soundfont, durationSeconds=1.00001)
+    params["tracks"][0]["gain"] = 0
+    params["tracks"].append({**params["tracks"][0], "name": "harmony", "gain": 1, "notes": []})
+    result = render(params)
+    assert result["gain"] == 1 and result["peakDb"] is None
+    assert result["durationSeconds"] == 22051 / 22050
+    for path in [result["mixPath"], *(s["path"] for s in result["stems"])]:
+        audio, sr = sf.read(path)
+        assert audio.shape == (22051, 2) and sr == 22050
+        assert np.count_nonzero(audio) == 0
+
+
+def test_a_write_failure_removes_partial_stems_and_allows_a_clean_retry(tmp_path, soundfont, monkeypatch):
+    from voice_render import render
+
+    params = request(tmp_path, soundfontPath=soundfont)
+    params["tracks"].append({**params["tracks"][0], "name": "bass"})
+    open_wav = sf.SoundFile
+
+    def disk_full(path, mode="r", *args, **kwargs):
+        if Path(path).name == "bass.wav" and mode == "w":
+            assert (tmp_path / "render" / "melody.wav").is_file()
+            raise OSError("No space left on device")
+        return open_wav(path, mode, *args, **kwargs)
+
+    # Only the output-file boundary fails. FluidSynth is real throughout.
+    with monkeypatch.context() as patch:
+        patch.setattr(sf, "SoundFile", disk_full)
+        with pytest.raises(OSError, match="No space left"):
+            render(params)
+    assert not (tmp_path / "render").exists()
+    assert (tmp_path / "fixture.sf2").is_file()
+    result = render(params)
+    assert all(Path(s["path"]).is_file() for s in result["stems"])
+
+
+@pytest.mark.skipif(bool(ctypes.util.find_library("fluidsynth")), reason="libfluidsynth is installed")
+def test_missing_native_library_explains_installation_without_creating_output(tmp_path):
+    from voice_render import render
+
+    with pytest.raises(RuntimeError, match="brew install fluid-synth.*apt install libfluidsynth3"):
+        render(request(tmp_path))
+    assert not (tmp_path / "render").exists()

package/sidecar/tests/test_voice_sketch.py

@@ -0,0 +1,140 @@
+"""Synthetic sources with known pitches/timing, independent of the detector."""
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from voice_sketch import transcribe
+from server import dispatch
+
+SR = 22050
+
+
+def tone(pitch, seconds):
+    t = np.arange(int(seconds * SR)) / SR
+    f = 440 * 2 ** ((pitch - 69) / 12)
+    # Strong second harmonic catches octave mistakes on a voice-like signal.
+    return (0.24 * np.sin(2 * np.pi * f * t) + 0.3 * np.sin(4 * np.pi * f * t)).astype(np.float32)
+
+
+def test_hummed_phrase_keeps_pitch_order_repeated_notes_and_silences():
+    audio = np.zeros((1, SR * 5), dtype=np.float32)
+    for start, pitch in [(0.23, 57), (0.97, 60), (1.72, 64), (2.48, 64), (3.98, 59)]:
+        sound = tone(pitch, 0.4)
+        audio[0, int(start * SR):int(start * SR) + len(sound)] = sound
+    result = transcribe(audio, SR, mode="melody", bpm=120)
+    assert [n["pitch"] for n in result["melody"]] == [57, 60, 64, 64, 59]
+    assert result["drums"] == []
+    beats = [n["beat"] for n in result["melody"]]
+    assert beats == pytest.approx([0, 1.5, 3, 4.5, 7.5], abs=0.25)
+    assert all(a["beat"] + a["lengthBeats"] <= b["beat"] for a, b in zip(result["melody"], result["melody"][1:]))
+    coarse = transcribe(audio, SR, mode="melody", bpm=60, grid=1)
+    # Key evidence belongs to the voice, not to notes discarded by a coarse grid.
+    assert coarse["chroma"] == pytest.approx(result["chroma"])
+
+
+def percussion(times, length=18):
+    audio = np.zeros((1, SR * length), dtype=np.float32)
+    rng = np.random.default_rng(17)
+    for i, start in enumerate(times):
+        t = np.arange(int(0.08 * SR)) / SR
+        # Low-frequency kicks alternate with mid-band noise snares. Unfiltered
+        # white noise is high-frequency dominated and represents a hat instead.
+        noise = np.convolve(rng.normal(0, 0.3, len(t)), np.ones(5) / 5, mode="same")
+        sound = (np.sin(2 * np.pi * 75 * t) if i % 2 == 0 else noise) * np.exp(-t * 55)
+        pos = int(start * SR)
+        audio[0, pos:pos + len(t)] += sound
+    return audio
+
+
+def test_stable_tempo_streamlines_jitter_without_inventing_a_melody():
+    times = [0.3 + i * 0.5 + (0.012 if i % 3 == 0 else -0.009) for i in range(32)]
+    result = transcribe(percussion(times), SR, mode="drums")
+    assert result["tempo"]["bpm"] == pytest.approx(120, abs=2)
+    assert len(result["tempo"]["segments"]) == 1
+    assert result["melody"] == []
+    assert {n["pitch"] for n in result["drums"]} >= {36, 38}
+    assert len(result["drums"]) == pytest.approx(32, abs=2)
+    assert all(n["beat"] * 4 == round(n["beat"] * 4) for n in result["drums"])
+
+
+def test_sustained_large_tempo_change_is_kept_but_manual_bpm_stays_fixed():
+    times = list(np.arange(0.3, 8.3, 0.6)) + list(np.arange(8.3, 24.3, 0.4))
+    audio = percussion(times, length=25)
+    result = transcribe(audio, SR, mode="drums")
+    bpms = [s["bpm"] for s in result["tempo"]["segments"]]
+    assert len(bpms) >= 2
+    assert any(abs(b - 100) < 4 for b in bpms)
+    assert any(abs(b - 150) < 4 for b in bpms)
+    fixed = transcribe(audio, SR, mode="drums", bpm=110)
+    assert [s["bpm"] for s in fixed["tempo"]["segments"]] == [110]
+
+
+def test_silence_and_unreliable_tempo_do_not_make_up_music():
+    with pytest.raises(ValueError, match="No audible content"):
+        transcribe(np.zeros((1, SR)), SR, bpm=120)
+    with pytest.raises(ValueError, match="Supply bpm"):
+        transcribe(tone(60, 1)[None, :], SR, mode="melody")
+    result = transcribe(tone(60, 1)[None, :], SR, bpm=100)
+    assert [n["pitch"] for n in result["melody"]] == [60]
+    assert result["drums"] == []
+
+
+def test_mixed_voice_keeps_a_pitched_layer_and_overlapping_percussion():
+    audio = percussion(np.arange(0.2, 6.2, 0.5), length=7)
+    for start, pitch in [(0.6, 57), (2.6, 62), (4.6, 60)]:
+        sound = tone(pitch, 1.2)
+        pos = int(start * SR)
+        audio[0, pos:pos + len(sound)] += sound
+    result = transcribe(audio, SR, bpm=120)
+    assert {n["pitch"] for n in result["melody"]} >= {57, 60, 62}
+    assert len(result["drums"]) >= 6
+    assert any(m["time"] <= d["time"] < m["time"] + m["duration"]
+               for m in result["melody"] for d in result["drums"])
+
+
+@pytest.mark.parametrize("mode", ["auto", "melody"])
+def test_same_pitch_syllables_keep_short_silent_gaps(mode):
+    audio = np.zeros((1, SR * 3), dtype=np.float32)
+    starts = [0.2, 0.7, 1.2, 1.7, 2.2]
+    for start in starts:
+        sound = tone(60, 0.48)
+        pos = int(start * SR)
+        audio[0, pos:pos + len(sound)] = sound
+    result = transcribe(audio, SR, mode=mode, bpm=120)
+    assert [n["pitch"] for n in result["melody"]] == [60] * 5
+    assert [n["time"] for n in result["melody"]] == pytest.approx(starts, abs=0.03)
+    assert [n["beat"] for n in result["melody"]] == [0, 1, 2, 3, 4]
+
+
+def test_percussion_attacks_do_not_rearticulate_a_held_hummed_note():
+    audio = np.zeros((1, SR * 3), dtype=np.float32)
+    sound = tone(60, 2.6)
+    audio[0, int(0.2 * SR):int(0.2 * SR) + len(sound)] = sound
+    burst_times = [0.7, 1.2, 1.7, 2.2]
+    t = np.arange(int(0.04 * SR)) / SR
+    burst = 0.65 * np.sin(2 * np.pi * 6000 * t) * np.exp(-t * 60)
+    for start in burst_times:
+        pos = int(start * SR)
+        audio[0, pos:pos + len(burst)] += burst
+    result = transcribe(audio, SR, bpm=120)
+    assert [n["pitch"] for n in result["melody"]] == [60]
+    assert result["melody"][0]["duration"] == pytest.approx(2.6, abs=0.1)
+    assert [n["time"] for n in result["drums"]] == pytest.approx(burst_times, abs=0.05)
+
+
+def test_rpc_validates_range_before_reading_and_reports_file_times(tmp_path):
+    import soundfile as sf
+    path = tmp_path / "sketch.wav"
+    sf.write(path, np.r_[np.zeros(SR), tone(62, 1), np.zeros(SR)], SR)
+    request = {"jsonrpc": "2.0", "id": 7, "method": "transcribe_voice_sketch",
+               "params": {"path": str(path), "startTime": 1, "endTime": 2, "bpm": 100, "mode": "melody"}}
+    result = json.loads(dispatch(json.dumps(request)))
+    assert result["result"]["startTime"] == 1
+    assert result["result"]["melody"][0]["time"] >= 1
+    assert result["result"]["melody"][0]["pitch"] == 62
+    request["params"]["endTime"] = 200
+    assert "120" in json.loads(dispatch(json.dumps(request)))["error"]["message"]