audio-as-code 0.1.0__py3-none-any.whl

audio_as_code/automation.py

@@ -0,0 +1,40 @@
+"""Beat-domain automation evaluated on the audio sample clock."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .model import Automation, Song
+
+
+def _point_times(song: Song, beats: np.ndarray) -> np.ndarray:
+    """Convert ordered knots in one tempo sweep, preserving integration order."""
+    changes = iter(song.tempo_map)
+    change = next(changes, None)
+    seconds, previous, bpm = 0.0, 0.0, song.bpm
+    times = []
+    for beat in beats:
+        while change is not None and change.beat <= beat:
+            seconds += (change.beat - previous) * 60 / bpm
+            previous, bpm = change.beat, change.bpm
+            change = next(changes, None)
+        times.append(seconds + (beat - previous) * 60 / bpm)
+    return np.array(times)
+
+
+def automation_values(song: Song, lane: Automation, start: int, stop: int) -> np.ndarray:
+    """Absolute values, linear in beats or stepped; endpoints hold before/after the lane."""
+    points = lane.points
+    beats = np.array([point.beat for point in points])
+    values = np.array([point.value for point in points])
+    times = np.arange(start, stop, dtype=np.float64) / song.sample_rate
+    if lane.interpolation == "step":
+        point_times = _point_times(song, beats)
+        indices = np.searchsorted(point_times, times, side="right") - 1
+        return values[np.maximum(indices, 0)]
+    # Add tempo boundaries as interpolation knots so a straight line in beats
+    # keeps its musical slope when the number of seconds per beat changes.
+    knots = np.unique(np.concatenate((beats, [change.beat for change in song.tempo_map])))
+    knot_values = np.interp(knots, beats, values)
+    knot_times = _point_times(song, knots)
+    return np.interp(times, knot_times, knot_values)

audio_as_code/cli.py

@@ -0,0 +1,171 @@
+"""Every successful command emits JSON. Failures emit JSON to stderr and exit 2."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import wave
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from . import __version__
+from ._paths import check_paths as _check_paths
+from .demo import demo_song
+from .inspection import inspect_score
+from .instruments import ENGINES, FAMILIES, instrument_catalog
+from .midi import export_midi
+from .model import Song
+from .render import analyze_wav, render
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise ArgumentError(f"{self.prog}: {message}")
+
+
+class ArgumentError(ValueError):
+    """An invalid CLI invocation, with the existing operation_failed contract."""
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = Parser(
+        prog="aac",
+        description="Audio as Code: compose, render, and inspect music locally.",
+        epilog="Success: JSON on stdout, exit 0. Errors: JSON on stderr, exit 2. "
+        "Run 'aac COMMAND --help' for command options.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=json.dumps({"version": __version__}),
+        help="Print the installed engine version as JSON and exit",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    instruments = commands.add_parser("instruments", help="Discover voices, families, and engines")
+    instruments.add_argument("--all", action="store_true", help="Include planned instruments")
+    instruments.add_argument("--family", choices=[family.id for family in FAMILIES])
+    instruments.add_argument("--engine", choices=[engine.id for engine in ENGINES])
+    demo = commands.add_parser("demo", help="Write an example JSON score")
+    demo.add_argument("-o", "--output", default="demo.json", help="Score path (default: demo.json)")
+    schema = commands.add_parser("schema", help="Print the versioned JSON Schema")
+    schema.add_argument("-o", "--output", help="Write schema to a file instead of stdout")
+    validate = commands.add_parser("validate", help="Validate a JSON score")
+    validate.add_argument("score", help="Path to a UTF-8 JSON score")
+    inspect = commands.add_parser("inspect", help="Inspect score facts and static export readiness")
+    inspect.add_argument("score", help="Path to a UTF-8 JSON score; does not render or write files")
+    wav = commands.add_parser("render", help="Render a score to stereo PCM WAV")
+    wav.add_argument("score", help="Path to a UTF-8 JSON score (render limit: 300 seconds)")
+    wav.add_argument("-o", "--output", required=True, help="Destination 16-bit stereo WAV")
+    wav.add_argument("--stems", metavar="DIRECTORY", help="Write numbered per-track WAV files")
+    wav.add_argument(
+        "--no-normalize", action="store_true", help="Disable peak attenuation; loud mixes may clip"
+    )
+    wav.add_argument("--report", help="Also save the JSON render report to this path")
+    midi = commands.add_parser("midi", help="Export a score as a type-1 MIDI file")
+    midi.add_argument("score", help="Path to a UTF-8 JSON score")
+    midi.add_argument("-o", "--output", required=True, help="Destination type-1 MIDI file")
+    analyze = commands.add_parser("analyze", help="Measure a 16-bit PCM WAV file")
+    analyze.add_argument("audio", help="Path to an existing 16-bit PCM WAV file")
+    return parser
+
+
+def _write_json(path: str, data: dict) -> None:
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(json.dumps(data, indent=2, allow_nan=False) + "\n", encoding="utf-8")
+
+
+def _error_hint(error: Exception) -> str:
+    if isinstance(error, ArgumentError):
+        return "Run aac --help or aac COMMAND --help to check arguments."
+    if isinstance(error, FileNotFoundError):
+        return "Check the input path and current working directory; quote paths containing spaces."
+    if isinstance(error, PermissionError):
+        return "Choose a writable output directory and close applications holding the file open."
+    if isinstance(error, (wave.Error, EOFError)):
+        return "Use an intact 16-bit PCM WAV file, such as one produced by aac render."
+    return "Check the message and command options; for score inputs, run aac validate first."
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        args = _parser().parse_args(argv)
+        if args.command == "instruments":
+            result = instrument_catalog(
+                family=args.family, engine=args.engine, include_planned=args.all
+            )
+        elif args.command == "demo":
+            _check_paths([args.output])
+            song = demo_song()
+            song.save(args.output)
+            result = {"output": args.output, "title": song.title}
+        elif args.command == "schema":
+            result = Song.model_json_schema()
+            if args.output:
+                _check_paths([args.output])
+                _write_json(args.output, result)
+                result = {"output": args.output, "schema_version": "1"}
+        elif args.command == "analyze":
+            result = analyze_wav(args.audio)
+        else:
+            song = Song.load(args.score)
+            if args.command == "validate":
+                result = {
+                    "valid": True,
+                    "schema_version": song.schema_version,
+                    "title": song.title,
+                    "bpm": song.bpm,
+                    "beats": song.beats,
+                    "duration_seconds": song.seconds,
+                    "render_duration_seconds": song.render_seconds,
+                    "tracks": len(song.tracks),
+                    "notes": sum(len(t.notes) for t in song.tracks),
+                }
+            elif args.command == "inspect":
+                result = inspect_score(song)
+            elif args.command == "midi":
+                _check_paths([args.score, args.output])
+                result = export_midi(song, args.output)
+            else:
+                paths = [args.score, args.output]
+                if args.report:
+                    paths.append(args.report)
+                if args.stems:
+                    paths.extend(
+                        Path(args.stems) / f"{i + 1:02d}.wav" for i in range(len(song.tracks))
+                    )
+                _check_paths(paths, [args.stems] if args.stems else [])
+                result = render(
+                    song, args.output, normalize=not args.no_normalize, stems_dir=args.stems
+                )
+                if args.report:
+                    _write_json(args.report, result)
+        print(json.dumps(result, indent=2, ensure_ascii=True, allow_nan=False))
+        return 0
+    except ValidationError as error:
+        issues = [
+            {"path": list(item["loc"]), "message": item["msg"], "type": item["type"]}
+            for item in error.errors(include_url=False)
+        ]
+        print(
+            json.dumps(
+                {
+                    "error": "invalid_score",
+                    "issues": issues,
+                    "hint": "Correct the issue paths, then run aac validate again. "
+                    "Use aac schema for the score contract.",
+                }
+            ),
+            file=sys.stderr,
+        )
+        return 2
+    except (OSError, ValueError, wave.Error, EOFError) as error:
+        print(
+            json.dumps(
+                {"error": "operation_failed", "message": str(error), "hint": _error_hint(error)}
+            ),
+            file=sys.stderr,
+        )
+        return 2

audio_as_code/demo.py

@@ -0,0 +1,106 @@
+"""A small, original arrangement generated entirely from the public score API."""
+
+from .model import Song, Track
+from .pattern import Pattern
+
+
+def demo_song() -> Song:
+    # Eight bars: Am7 / Fmaj7 / Cmaj7 / G, then a melodic variation.
+    chords = [
+        ["A3", "C4", "E4", "G4"],
+        ["F3", "A3", "C4", "E4"],
+        ["C3", "E3", "G3", "B3"],
+        ["G3", "B3", "D4", "G4"],
+    ]
+    pads = Pattern.sequence(chords, step=4, gate=0.95, velocity=0.55).repeat(2)
+    bass = Pattern.sequence(
+        [
+            "A2",
+            None,
+            "E3",
+            "A2",
+            "F2",
+            None,
+            "C3",
+            "F2",
+            "C2",
+            None,
+            "G2",
+            "C3",
+            "G2",
+            None,
+            "D3",
+            "G2",
+        ],
+        gate=0.72,
+        velocity=0.8,
+    ).repeat(2)
+    melody = Pattern.sequence(
+        [
+            "E5",
+            None,
+            "C5",
+            "B4",
+            "A4",
+            None,
+            "C5",
+            "E5",
+            "A4",
+            "G4",
+            None,
+            "E4",
+            "G4",
+            None,
+            "B4",
+            "D5",
+        ],
+        step=0.5,
+        gate=0.65,
+        velocity=0.7,
+    )
+    variation = Pattern.sequence(
+        [
+            "E5",
+            "G5",
+            None,
+            "E5",
+            "C5",
+            "B4",
+            "A4",
+            None,
+            "G4",
+            None,
+            "A4",
+            "B4",
+            "D5",
+            "B4",
+            "G4",
+            None,
+        ],
+        step=0.5,
+        gate=0.7,
+        velocity=0.74,
+    )
+    kick = Pattern.sequence([36, None, 36, None], gate=0.4, velocity=0.9).repeat(8)
+    snare = Pattern.sequence([None, 38, None, 38], gate=0.28, velocity=0.7).repeat(8)
+    hat = Pattern.sequence([42, 42, 42, 42], step=0.5, gate=0.16, velocity=0.45).repeat(16)
+    return Song(
+        title="First Light",
+        bpm=104,
+        beats=32,
+        seed=7,
+        tracks=(
+            Track(name="Warm chords", instrument="pad", gain=0.34, pan=-0.25, notes=pads.notes),
+            Track(name="Bass", instrument="bass", gain=0.65, notes=bass.notes),
+            Track(
+                name="Melody",
+                instrument="pluck",
+                gain=0.52,
+                pan=0.3,
+                notes=melody.at(8) + variation.at(24),
+            ),
+            Track(name="Kick", instrument="kick", gain=0.85, notes=kick.notes),
+            Track(name="Snare", instrument="snare", gain=0.48, pan=-0.08, notes=snare.notes),
+            Track(name="Hi-hat", instrument="hat", gain=0.34, pan=0.35, notes=hat.notes),
+        ),
+    )

audio_as_code/effects.py

@@ -0,0 +1,85 @@
+"""Bounded, deterministic effects made entirely from code-generated delay networks."""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .model import Delay, Effect, Reverb
+
+Audio = NDArray[np.float32]
+
+
+def effects_tail(effects: tuple[Effect, ...]) -> float:
+    return sum(
+        (
+            effect.time_seconds * (effect.repeats if effect.feedback else 1)
+            if isinstance(effect, Delay)
+            else effect.decay_seconds + 0.1
+        )
+        for effect in effects
+        if effect.mix
+    )
+
+
+def _reverb_kernel(effect: Reverb, rate: int, channel: int) -> NDArray[np.float64]:
+    """Four decaying combs and two short finite all-pass diffusers, analytically generated."""
+    frames = math.ceil((effect.decay_seconds + 0.1) * rate) + 1
+    impulse = np.zeros(frames)
+    for seconds in (0.0297, 0.0371, 0.0411, 0.0437):
+        delay = max(1, round((seconds + channel * 0.0013) * rate))
+        positions = np.arange(delay, frames, delay)
+        gains = np.power(10.0, -3 * positions / (rate * effect.decay_seconds))
+        impulse[positions] += gains / 4
+    # Finite expansion of (-g + z^-d)/(1 - g*z^-d); twelve repeats per diffuser.
+    for seconds in (0.0031, 0.0053):
+        delay = max(1, round((seconds + channel * 0.0002) * rate))
+        source = impulse.copy()
+        impulse *= -0.5
+        for repeat in range(1, 13):
+            offset = repeat * delay
+            if offset >= frames:
+                break
+            impulse[offset:] += source[:-offset] * (0.75 * 0.5 ** (repeat - 1))
+    fade = min(frames, max(2, round(0.01 * rate)))
+    impulse[-fade:] *= np.linspace(1, 0, fade)
+    return impulse
+
+
+def _convolve(source: Audio, kernel: NDArray[np.float64]) -> Audio:
+    """Overlap-add convolution keeps working memory independent of song duration."""
+    block = 1 << max(16, (len(kernel) - 1).bit_length())
+    size = block * 2
+    spectrum = np.fft.rfft(kernel, n=size)
+    result = np.zeros(len(source), dtype=np.float32)
+    for start in range(0, len(source), block):
+        chunk = source[start : start + block]
+        filtered = np.fft.irfft(np.fft.rfft(chunk, n=size) * spectrum, n=size)
+        count = min(len(source) - start, len(chunk) + len(kernel) - 1)
+        result[start : start + count] += filtered[:count].astype(np.float32)
+    return result
+
+
+def apply_effects(audio: Audio, effects: tuple[Effect, ...], rate: int) -> Audio:
+    """Apply a serial chain to an already tail-padded stereo buffer."""
+    for effect in effects:
+        if effect.mix == 0:
+            continue
+        wet = np.zeros_like(audio)
+        if isinstance(effect, Delay):
+            for repeat in range(1, effect.repeats + 1):
+                if repeat > 1 and effect.feedback == 0:
+                    break
+                offset = round(effect.time_seconds * repeat * rate)
+                if offset >= len(audio):
+                    break
+                wet[offset:] += audio[:-offset] * effect.feedback ** (repeat - 1)
+        else:
+            for channel in range(2):
+                wet[:, channel] = _convolve(
+                    audio[:, channel], _reverb_kernel(effect, rate, channel)
+                )
+        audio = audio * (1 - effect.mix) + wet * effect.mix
+    return audio

audio_as_code/extended.py

@@ -0,0 +1,283 @@
+"""Paired strings, cantilever lamellae, struck bars and a recorder jet spectrum.
+
+All excitations and resonator responses are generated from equations. Parameters
+are designed rather than fitted to recordings. See docs/extended-instruments.md
+for the physical motivation and the deliberately limited model boundaries.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .acoustics import (
+    colored_noise,
+    modulate_noise,
+    nyquist_gain,
+    resonant_body,
+    slow_variation,
+    struck_mode,
+)
+from .instruments import require_instrument
+from .model import Tone
+
+Signal = NDArray[np.float64]
+EXTENDED_INSTRUMENTS = frozenset({"mandolin", "kalimba", "celesta", "recorder"})
+
+
+def _mandolin(
+    frequency: float,
+    t: Signal,
+    rate: int,
+    seed: int,
+    brightness: float,
+    decay: float,
+    position: float,
+    detune: float,
+) -> Signal:
+    """Two-string modal pairs with shared bridge stiffness and radiation loss.
+
+    The symmetric stiffness matrix gives stable real normal modes. Damping is
+    projected onto each mode; off-diagonal dissipative coupling is neglected.
+    detune is the TOTAL uncoupled-string separation in cents, not +/- detune.
+    """
+    rng = np.random.Generator(np.random.PCG64(seed))
+    signal = np.zeros(len(t))
+    excitation = np.array([1.0, rng.uniform(0.88, 0.96)])
+    radiation = np.array([1.0, 1.0])
+    total = 0.0
+    stiffness = 0.000018 * (1 + frequency / 600)
+    for harmonic in range(1, 33):
+        center = frequency * harmonic * math.sqrt((1 + stiffness * harmonic**2) / (1 + stiffness))
+        uncoupled = np.array([2 ** (-detune / 2400), 2 ** (detune / 2400)])
+        # A small common-bridge restoring term separates bright and dark modes.
+        coupling = 0.00035 / (1 + harmonic * 0.08)
+        eigenvalues, vectors = np.linalg.eigh(np.diag(uncoupled**2) + coupling * np.ones((2, 2)))
+        ratios = np.sqrt(eigenvalues)
+        # Preserve the written pitch as the geometric center of the mode pair.
+        ratios /= math.sqrt(ratios[0] * ratios[1])
+        pluck = math.sin(math.pi * harmonic * position) / harmonic**1.2
+        pluck *= math.exp(-(harmonic - 1) / (3.0 + 15 * brightness))
+        pluck *= rng.uniform(0.98, 1.02)
+        for index, ratio in enumerate(ratios):
+            mode = vectors[:, index]
+            bridge = float(mode @ radiation)
+            amplitude = pluck * float(mode @ excitation) * bridge
+            total += abs(amplitude)
+            f = center * ratio
+            if f >= rate * 0.49:
+                continue
+            loss = (0.45 + 0.42 * bridge**2) * (1 + 0.12 * (harmonic - 1) ** 1.2)
+            signal += (
+                amplitude
+                * np.sin(2 * np.pi * f * t)
+                * np.exp(-math.log(1000) * loss * t / decay)
+                * nyquist_gain(f, rate)
+            )
+    if total:
+        signal *= 0.86 / total
+    # A very short generated pick scrape drives the same body as the strings.
+    signal += (
+        0.018 * brightness * colored_noise(len(t), rate, seed + 1, 1700, 8000) * np.exp(-t / 0.005)
+    )
+    return resonant_body(
+        signal,
+        rate,
+        ((310, 0.11, 0.45), (650, 0.075, 0.35), (1550, 0.045, 0.2)),
+        wet=0.18,
+    )
+
+
+def _kalimba(
+    frequency: float,
+    t: Signal,
+    rate: int,
+    seed: int,
+    brightness: float,
+    decay: float,
+) -> Signal:
+    """Finite thumb-contact forcing of fixed-free lamella modes and a wooden box."""
+    # Squared roots of cos(beta)*cosh(beta)=-1, relative to the first root.
+    roots = (1.87510407, 4.69409113, 7.85475744, 10.99554073)
+    amplitudes = (1.0, 0.26, 0.095, 0.035)
+    lifetimes = (1.0, 0.22, 0.085, 0.04)
+    contact = min(0.42 / frequency, 0.00055 * (1.3 - 0.9 * brightness))
+    rng = np.random.Generator(np.random.PCG64(seed))
+    signal = np.zeros(len(t))
+    total = 0.0
+    for index, (root, amplitude, lifetime) in enumerate(
+        zip(roots, amplitudes, lifetimes, strict=True)
+    ):
+        f = frequency * (root / roots[0]) ** 2
+        amplitude *= (1 if index == 0 else 0.3 + 1.4 * brightness) * rng.uniform(0.98, 1.02)
+        total += amplitude
+        if f < rate * 0.49:
+            signal += (
+                amplitude
+                * struck_mode(
+                    t,
+                    f,
+                    math.log(1000) / (decay * lifetime),
+                    contact,
+                )
+                * nyquist_gain(f, rate)
+            )
+    signal *= 0.86 / total
+    # A thumb/metal contact transient, not a sampled click or a buzz attachment.
+    signal += (
+        0.012 * brightness * colored_noise(len(t), rate, seed + 1, 900, 6500) * np.exp(-t / 0.003)
+    )
+    return resonant_body(
+        signal,
+        rate,
+        ((185, 0.18, 0.45), (430, 0.10, 0.35), (1100, 0.045, 0.2)),
+        wet=0.22,
+    )
+
+
+def _celesta(
+    frequency: float,
+    t: Signal,
+    rate: int,
+    seed: int,
+    brightness: float,
+    decay: float,
+) -> Signal:
+    """Felt-hammer forcing of free-free metal-bar modes and a pitch-matched box."""
+    # First four non-rigid roots of cos(beta)*cosh(beta)=1.
+    roots = (4.73004074, 7.85320462, 10.99560784, 14.13716549)
+    amplitudes = (1.0, 0.48, 0.23, 0.11)
+    lifetimes = (1.0, 0.62, 0.30, 0.16)
+    contact = min(0.55 / frequency, 0.0034 * (1.2 - 0.85 * brightness))
+    rng = np.random.Generator(np.random.PCG64(seed))
+    signal = np.zeros(len(t))
+    total = 0.0
+    for index, (root, amplitude, lifetime) in enumerate(
+        zip(roots, amplitudes, lifetimes, strict=True)
+    ):
+        f = frequency * (root / roots[0]) ** 2
+        amplitude *= (1 if index == 0 else 0.35 + 1.3 * brightness) * rng.uniform(0.985, 1.015)
+        total += amplitude
+        if f < rate * 0.49:
+            signal += (
+                amplitude
+                * struck_mode(
+                    t,
+                    f,
+                    math.log(1000) / (decay * lifetime),
+                    contact,
+                )
+                * nyquist_gain(f, rate)
+            )
+    signal *= 0.9 / total
+    # The resonator is driven by bar motion. It is an analytic one-way response,
+    # not an independent ringing oscillator or measured instrument response.
+    return resonant_body(
+        signal,
+        rate,
+        ((frequency, 0.22, 1.0), (frequency * 2.02, 0.085, 0.16)),
+        wet=0.24,
+    )
+
+
+def _recorder(
+    frequency: float,
+    t: Signal,
+    rate: int,
+    seed: int,
+    brightness: float,
+    settings: dict,
+) -> Signal:
+    """Band-limited jet-source harmonics with an idealized bore/radiation filter.
+
+    The jet waveform is Fourier-analyzed on a phase grid, then reconstructed
+    only with audible partials. No nonlinear audio-rate waveshaper can alias.
+    This is a prescribed source/filter model, not a self-oscillating jet solver.
+    """
+    depth = settings["vibrato_depth_cents"]
+    vibrato_rate = settings["vibrato_rate_hz"]
+    motion = slow_variation(t, seed, 0.6)
+    vibrato = (
+        depth * (1 - np.exp(-np.maximum(t - 0.08, 0) / 0.22)) * np.sin(2 * np.pi * vibrato_rate * t)
+    )
+    settling = -2.0 * np.exp(-t / 0.018)
+    frequencies = frequency * 2 ** ((vibrato + settling + 0.35 * motion) / 1200)
+    phase = np.zeros(len(t))
+    phase[1:] = 2 * np.pi * np.cumsum((frequencies[:-1] + frequencies[1:]) * 0.5) / rate
+    theta = 2 * np.pi * np.arange(2048) / 2048
+    drive = 0.85 + 1.6 * brightness
+    offset = 0.10 + 0.18 * brightness
+    jet = np.tanh(drive * (np.sin(theta) + offset))
+    coefficients = np.fft.rfft(jet) / len(theta)
+    signal = np.zeros(len(t))
+    total = 0.0
+    pressure = 1 + 0.018 * motion
+    # The pitch-scaled bore roll-off and fixed radiation shelf are designed
+    # envelopes, without fingering-dependent impedances or measured formants.
+    cutoff = 3.0 + 5.0 * brightness
+    for harmonic in range(1, 21):
+        coefficient = 2 * coefficients[harmonic]
+        transfer = harmonic**0.35 / math.sqrt(1 + (harmonic / cutoff) ** 4)
+        transfer /= math.sqrt(1 + (frequency * harmonic / 8500) ** 2)
+        amplitude = abs(coefficient) * transfer
+        total += amplitude
+        if float(np.min(frequencies)) * harmonic >= rate * 0.49:
+            continue
+        onset = 1 - np.exp(-t / (0.012 + harmonic * 0.0015))
+        signal += (
+            amplitude
+            * onset
+            * pressure
+            * np.cos(harmonic * phase + np.angle(coefficient))
+            * nyquist_gain(frequencies * harmonic, rate)
+        )
+    if total:
+        signal *= 0.79 / total
+    breath = settings["breath"]
+    if breath:
+        noise = colored_noise(len(t), rate, seed + 1, 1200, 7500)
+        noise = modulate_noise(noise, phase, float(np.max(frequencies)) + 2, rate, 0.18)
+        envelope = (1 - np.exp(-t / 0.003)) * (0.55 + 0.8 * np.exp(-t / 0.045))
+        signal += 0.15 * breath * noise * envelope * pressure
+    return signal
+
+
+def synthesize(
+    instrument: str,
+    frequency: float,
+    frames: int,
+    rate: int,
+    seed: int,
+    velocity: float,
+    tone: Tone | None,
+) -> Signal:
+    """Return generated float64 mono; the renderer applies note gates and gain."""
+    if instrument not in EXTENDED_INSTRUMENTS:
+        raise ValueError(f"No extended model for {instrument!r}")
+    info = require_instrument(instrument)
+    if frames < 1 or frequency >= rate / 2:
+        return np.zeros(frames, dtype=np.float64)
+    tone = tone or Tone()
+    settings = dict(info.default_tone)
+    settings.update({key: value for key, value in tone.model_dump().items() if value is not None})
+    brightness = min(1.0, settings["brightness"] * 0.75 + velocity * 0.25)
+    decay = settings.get("decay_seconds", info.default_decay_seconds)
+    t = np.arange(frames, dtype=np.float64) / rate
+    if instrument == "mandolin":
+        return _mandolin(
+            frequency,
+            t,
+            rate,
+            seed,
+            brightness,
+            decay,
+            settings["pluck_position"],
+            settings["detune_cents"],
+        )
+    if instrument == "kalimba":
+        return _kalimba(frequency, t, rate, seed, brightness, decay)
+    if instrument == "celesta":
+        return _celesta(frequency, t, rate, seed, brightness, decay)
+    return _recorder(frequency, t, rate, seed, brightness, settings)