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

audio_as_code/__init__.py

@@ -0,0 +1,44 @@
+"""Compose, validate, render, and inspect music as code."""
+
+from .inspection import inspect_score
+from .instruments import get_instrument, instrument_catalog, list_instruments
+from .midi import export_midi
+from .model import (
+    Automation,
+    AutomationPoint,
+    Delay,
+    Note,
+    PedalEvent,
+    Reverb,
+    Song,
+    TempoChange,
+    Tone,
+    Track,
+    midi_pitch,
+)
+from .pattern import Pattern
+from .render import analyze_wav, render, render_audio
+
+__version__ = "0.1.0"
+__all__ = [
+    "Automation",
+    "AutomationPoint",
+    "Delay",
+    "Note",
+    "Pattern",
+    "PedalEvent",
+    "Reverb",
+    "Song",
+    "TempoChange",
+    "Tone",
+    "Track",
+    "analyze_wav",
+    "export_midi",
+    "get_instrument",
+    "inspect_score",
+    "instrument_catalog",
+    "list_instruments",
+    "midi_pitch",
+    "render",
+    "render_audio",
+]

audio_as_code/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

audio_as_code/_audio.py

@@ -0,0 +1,87 @@
+"""PCM WAV encoding and signal measurements, independent of score and synthesis."""
+
+from __future__ import annotations
+
+import math
+import wave
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+Audio = NDArray[np.float32]
+
+
+def _metrics(audio: Audio, rate: int) -> dict:
+    peak = float(np.max(np.abs(audio))) if audio.size else 0.0
+    rms = float(np.sqrt(np.mean(np.square(audio, dtype=np.float64)))) if audio.size else 0.0
+    return {
+        "sample_rate": rate,
+        "channels": audio.shape[1],
+        "frames": len(audio),
+        "duration_seconds": len(audio) / rate,
+        "peak": peak,
+        "rms": rms,
+        "peak_dbfs": 20 * math.log10(peak) if peak > 0 else None,
+        "rms_dbfs": 20 * math.log10(rms) if rms > 0 else None,
+        "clipped_samples": int(np.count_nonzero(np.abs(audio) >= 1)),
+        "silent": peak == 0,
+    }
+
+
+def _write_wav(path: Path, audio: Audio, rate: int) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    pcm = np.clip(np.rint(audio * 32768), -32768, 32767).astype("<i2")
+    with wave.open(str(path), "wb") as stream:
+        stream.setnchannels(2)
+        stream.setsampwidth(2)
+        stream.setframerate(rate)
+        stream.writeframes(pcm.tobytes())
+
+
+def analyze_wav(path: str | Path) -> dict:
+    """Measure a 16-bit PCM WAV in blocks. These are signal checks, not music criticism."""
+    peak = 0
+    squares = 0.0
+    count = 0
+    clipped = 0
+    try:
+        stream = wave.open(str(path), "rb")
+    except RuntimeError as error:
+        # The stdlib RIFF parser can raise RuntimeError when an ancillary
+        # chunk declares a seek beyond its enclosing chunk.
+        raise wave.Error("WAV is malformed: invalid RIFF chunk layout") from error
+    with stream:
+        if stream.getsampwidth() != 2 or stream.getcomptype() != "NONE":
+            raise ValueError("analysis supports uncompressed 16-bit PCM WAV files")
+        channels, rate, frames = stream.getnchannels(), stream.getframerate(), stream.getnframes()
+        if rate <= 0:
+            raise ValueError("WAV sample rate must be positive")
+        # A frame contains one sample per channel, and the channel count comes
+        # from the file. Bound bytes as well as frames before allocating float64
+        # analysis buffers; retain the existing mono/stereo block sizes.
+        block_frames = min(65536, max(1, 131072 // channels))
+        while data := stream.readframes(block_frames):
+            if len(data) % (2 * channels):
+                raise ValueError("WAV is truncated or malformed: incomplete PCM frame")
+            pcm = np.frombuffer(data, dtype="<i2").astype(np.float64)
+            count += pcm.size
+            peak = max(peak, float(np.max(np.abs(pcm))))
+            squares += float(np.sum(pcm * pcm))
+            clipped += int(np.count_nonzero((pcm >= 32767) | (pcm <= -32768)))
+    if count != frames * channels:
+        raise ValueError("WAV is truncated: actual samples do not match the file header")
+    rms = math.sqrt(squares / count) / 32768 if count else 0.0
+    amplitude = peak / 32768
+    return {
+        "sample_rate": rate,
+        "channels": channels,
+        "frames": frames,
+        "duration_seconds": frames / rate,
+        "peak": amplitude,
+        "rms": rms,
+        "peak_dbfs": 20 * math.log10(amplitude) if amplitude else None,
+        "rms_dbfs": 20 * math.log10(rms) if rms else None,
+        "full_scale_samples": clipped,
+        "silent": peak == 0,
+    }

audio_as_code/_export_rules.py

@@ -0,0 +1,32 @@
+"""Shared output limits and event mapping for inspection and exporters."""
+
+from __future__ import annotations
+
+from .instruments import DRUM_NOTES
+from .model import Note, Song, Track, midi_pitch
+
+MAX_RENDER_SECONDS = 300
+TICKS_PER_BEAT = 480
+MAX_MIDI_TICK = 0x0FFFFFFF
+MAX_MELODIC_TRACKS = 15
+
+
+def note_frame(song: Song, beat: float) -> int:
+    # Retain the original arithmetic order on legacy rounding boundaries.
+    if not song.tempo_map:
+        return round(beat * (song.sample_rate * 60 / song.bpm))
+    return round(song.beat_to_seconds(beat) * song.sample_rate)
+
+
+def midi_tick(beat: float) -> int:
+    return round(beat * TICKS_PER_BEAT)
+
+
+def midi_note_ticks(note: Note, end_tick: int) -> tuple[int, int]:
+    return midi_tick(note.start), min(end_tick, midi_tick(note.start + note.duration))
+
+
+def midi_export_pitch(track: Track, pitch: int | str) -> int:
+    if track.instrument in DRUM_NOTES and track.instrument != "drum_machine":
+        return DRUM_NOTES[track.instrument]
+    return midi_pitch(pitch)

audio_as_code/_orchestra_profiles.py

@@ -0,0 +1,188 @@
+"""Hand-designed coefficients for the shared orchestra synthesis models.
+
+Keep playable IDs and discovery metadata in instruments.py. These immutable
+profiles supply the spectra, resonances and damping used by orchestra.py.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+
+
+@dataclass(frozen=True)
+class StringProfile:
+    position: float
+    stiffness: float
+    damping: float
+    tilt: float
+    body: tuple[tuple[float, float, float], ...]
+    pickup: float | None = None
+    detune: float = 0
+
+
+STRINGS = MappingProxyType(
+    {
+        "electric_guitar": StringProfile(0.16, 0.000025, 0.13, 1.1, (), 0.18),
+        "bass_guitar": StringProfile(0.24, 0.00007, 0.2, 1.3, (), 0.27),
+        "harp": StringProfile(
+            0.32, 0.000015, 0.09, 1.55, ((190, 0.05, 0.07), (420, 0.025, 0.04)), detune=1.5
+        ),
+        "ukulele": StringProfile(
+            0.25, 0.000004, 0.3, 1.7, ((270, 0.07, 0.04), (590, 0.035, 0.025))
+        ),
+        "banjo": StringProfile(
+            0.12, 0.00004, 0.27, 0.9, ((410, 0.09, 0.06), (660, 0.06, 0.035), (1080, 0.035, 0.02))
+        ),
+        "harpsichord": StringProfile(0.09, 0.00002, 0.12, 0.85, ((230, 0.025, 0.025),), detune=2.5),
+    }
+)
+
+
+@dataclass(frozen=True)
+class HeldProfile:
+    partials: tuple[float, ...]
+    attack: float
+    formants: tuple[tuple[float, float, float], ...]
+    noise_band: tuple[float, float]
+    bow_noise: float = 0
+
+
+# Formants are center Hz, bandwidth Hz, and gain. These are designed spectra,
+# not fitted body responses. Instruments retain different spectra and onsets.
+HELD = MappingProxyType(
+    {
+        "violin": HeldProfile(
+            (1, 0.7, 0.55, 0.42, 0.3, 0.26, 0.2, 0.16, 0.13, 0.1, 0.08, 0.06),
+            0.065,
+            ((470, 230, 0.6), (2800, 900, 1.5)),
+            (900, 6500),
+            0.025,
+        ),
+        "viola": HeldProfile(
+            (1, 0.75, 0.45, 0.34, 0.3, 0.18, 0.15, 0.1, 0.08),
+            0.085,
+            ((320, 170, 0.75), (2200, 700, 1.2)),
+            (600, 5000),
+            0.022,
+        ),
+        "cello": HeldProfile(
+            (1, 0.85, 0.45, 0.28, 0.25, 0.16, 0.12, 0.09, 0.07),
+            0.105,
+            ((180, 100, 0.8), (900, 380, 0.7), (1800, 700, 0.65)),
+            (400, 4200),
+            0.025,
+        ),
+        "double_bass": HeldProfile(
+            (1, 0.65, 0.35, 0.3, 0.18, 0.12, 0.1, 0.07),
+            0.14,
+            ((95, 65, 0.75), (600, 300, 0.8)),
+            (220, 2700),
+            0.035,
+        ),
+        "flute": HeldProfile(
+            (1, 0.17, 0.07, 0.03, 0.012), 0.07, ((1500, 1200, 0.12),), (900, 6500)
+        ),
+        "clarinet": HeldProfile(
+            (1, 0.055, 0.65, 0.045, 0.35, 0.035, 0.17, 0.025, 0.08, 0.01, 0.03),
+            0.035,
+            ((1400, 900, 0.25),),
+            (1400, 6500),
+        ),
+        "saxophone": HeldProfile(
+            (1, 0.85, 0.58, 0.42, 0.29, 0.2, 0.14, 0.1, 0.07, 0.04),
+            0.045,
+            ((900, 600, 0.8), (2600, 900, 0.4)),
+            (800, 5500),
+        ),
+        "oboe": HeldProfile(
+            (1, 1.1, 0.95, 0.8, 0.6, 0.38, 0.25, 0.18, 0.1, 0.07),
+            0.045,
+            ((1500, 650, 1.3),),
+            (1700, 7000),
+        ),
+        "bassoon": HeldProfile(
+            (1, 0.9, 0.7, 0.45, 0.28, 0.19, 0.13, 0.08),
+            0.065,
+            ((500, 300, 1.2), (1500, 650, 0.3)),
+            (700, 4200),
+        ),
+        "trumpet": HeldProfile(
+            (1, 0.85, 0.8, 0.72, 0.55, 0.4, 0.28, 0.19, 0.12, 0.08, 0.04, 0.02),
+            0.035,
+            ((1800, 1200, 0.55),),
+            (900, 5500),
+        ),
+        "trombone": HeldProfile(
+            (1, 0.85, 0.67, 0.48, 0.35, 0.25, 0.17, 0.1, 0.07),
+            0.055,
+            ((800, 650, 0.6),),
+            (500, 4000),
+        ),
+        "french_horn": HeldProfile(
+            (1, 0.6, 0.28, 0.14, 0.08, 0.04, 0.025), 0.085, ((650, 450, 0.3),), (400, 3200)
+        ),
+        "tuba": HeldProfile(
+            (1, 0.7, 0.42, 0.23, 0.13, 0.07, 0.04), 0.115, ((330, 280, 0.6),), (250, 2500)
+        ),
+        "organ": HeldProfile(
+            (1, 0.55, 0.18, 0.32, 0.04, 0.08, 0.02, 0.12), 0.022, (), (1200, 6000)
+        ),
+        "theremin": HeldProfile((1, 0.16, 0.045, 0.012), 0.08, (), (1000, 3000)),
+    }
+)
+
+
+@dataclass(frozen=True)
+class ResonatorProfile:
+    ratios: tuple[float, ...]
+    amplitudes: tuple[float, ...]
+    lifetimes: tuple[float, ...]
+    strike: float
+    tremolo: float = 0
+
+
+RESONATORS = MappingProxyType(
+    {
+        "electric_piano": ResonatorProfile(
+            (1, 2, 4.01, 7.03, 10.1),
+            (1, 0.28, 0.22, 0.09, 0.025),
+            (1, 0.65, 0.2, 0.1, 0.055),
+            0.006,
+            0.08,
+        ),
+        "xylophone": ResonatorProfile(
+            (1, 3, 6, 10), (1, 0.45, 0.2, 0.08), (1, 0.45, 0.23, 0.12), 0.03
+        ),
+        "vibraphone": ResonatorProfile(
+            (1, 4, 10, 16.8), (1, 0.22, 0.065, 0.02), (1, 0.7, 0.35, 0.2), 0.008, 0.24
+        ),
+        "glockenspiel": ResonatorProfile(
+            (1, 2.756, 5.404, 8.933, 13.34),
+            (1, 0.4, 0.23, 0.12, 0.05),
+            (1, 0.7, 0.48, 0.3, 0.18),
+            0.018,
+        ),
+        "toms": ResonatorProfile(
+            (1, 1.594, 2.136, 2.296, 2.653, 2.918),
+            (1, 0.4, 0.22, 0.12, 0.09, 0.07),
+            (1, 0.72, 0.52, 0.37, 0.28, 0.2),
+            0.055,
+        ),
+        "congas": ResonatorProfile(
+            (1, 1.5, 2.05, 2.65, 3.4), (1, 0.55, 0.27, 0.13, 0.08), (1, 0.8, 0.5, 0.28, 0.17), 0.085
+        ),
+        "bongos": ResonatorProfile(
+            (1, 1.59, 2.14, 2.65, 3.12),
+            (1, 0.48, 0.25, 0.15, 0.08),
+            (1, 0.6, 0.42, 0.26, 0.14),
+            0.11,
+        ),
+        "timpani": ResonatorProfile(
+            (1, 1.5, 2, 2.48, 2.95, 3.48),
+            (1, 0.55, 0.3, 0.18, 0.1, 0.07),
+            (1, 0.85, 0.6, 0.42, 0.28, 0.18),
+            0.035,
+        ),
+    }
+)

audio_as_code/_paths.py

@@ -0,0 +1,36 @@
+"""Shared, read-only path checks before CLI and Python exports write artifacts."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+
+def check_paths(
+    paths: Sequence[str | Path],
+    directories: Sequence[str | Path] = (),
+    *,
+    conflict_message: str = "score input, output, report, and stem paths must be distinct",
+) -> None:
+    """Reject known conflicts without creating files or output directories.
+
+    These checks do not reserve paths or guarantee later filesystem writes succeed.
+    """
+    resolved = [Path(path).resolve() for path in paths]
+    for index, path in enumerate(resolved):
+        if path.is_dir():
+            raise ValueError(f"expected a file path, got a directory: {path}")
+        for other in resolved[:index]:
+            if path == other or (path.exists() and other.exists() and path.samefile(other)):
+                raise ValueError(conflict_message)
+            if path in other.parents or other in path.parents:
+                raise ValueError("a file path cannot also be an output directory")
+    for directory in [
+        *(path.parent for path in resolved),
+        *(Path(path).resolve() for path in directories),
+    ]:
+        if directory in resolved:
+            raise ValueError("a file path cannot also be an output directory")
+        for parent in [directory, *directory.parents]:
+            if parent.exists() and not parent.is_dir():
+                raise ValueError(f"output directory is blocked by an existing file: {parent}")

audio_as_code/_voices.py

@@ -0,0 +1,173 @@
+"""Instrument dispatch and note envelopes; scheduling and mixing live in render."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._audio import Audio
+from .acoustics import colored_noise, nyquist_gain
+from .extended import EXTENDED_INSTRUMENTS
+from .extended import synthesize as synthesize_extended
+from .instruments import KIT_NOTES, PHYSICAL_INSTRUMENTS
+from .model import Tone
+from .orchestra import EXTRA_INSTRUMENTS
+from .orchestra import synthesize as synthesize_orchestra
+from .physical import synthesize
+
+_HARMONICS = {
+    "sine": [(1, 1)],
+    "triangle": [(n, (-1) ** ((n - 1) // 2) / n**2) for n in range(1, 16, 2)],
+    "pluck": [(n, 1 / n**1.6) for n in range(1, 9)],
+    "bass": [(1, 1), (2, 0.35), (3, 0.12)],
+    "pad": [(1, 1), (2, 0.25), (3, 0.12), (4, 0.06)],
+}
+
+_ATTACK_SECONDS = {
+    "pad": 0.08,
+    "guitar": 0.001,
+    "marimba": 0.0005,
+    "piano": 0.0005,
+    "xylophone": 0.0005,
+    "glockenspiel": 0.0005,
+    "mandolin": 0.001,
+    "kalimba": 0.0005,
+    "celesta": 0.0005,
+    "recorder": 0.003,
+}
+
+_RELEASE_SECONDS = {
+    "pad": 0.15,
+    "guitar": 0.065,
+    "electric_guitar": 0.055,
+    "bass_guitar": 0.07,
+    "harp": 0.12,
+    "ukulele": 0.045,
+    "banjo": 0.035,
+    "harpsichord": 0.04,
+    "piano": 0.12,
+    "electric_piano": 0.09,
+    "marimba": 0.055,
+    "bell": 0.12,
+    "xylophone": 0.035,
+    "vibraphone": 0.12,
+    "glockenspiel": 0.1,
+    "violin": 0.09,
+    "viola": 0.11,
+    "cello": 0.13,
+    "double_bass": 0.16,
+    "flute": 0.08,
+    "clarinet": 0.055,
+    "saxophone": 0.075,
+    "oboe": 0.065,
+    "bassoon": 0.08,
+    "trumpet": 0.055,
+    "trombone": 0.075,
+    "french_horn": 0.1,
+    "tuba": 0.13,
+    "organ": 0.06,
+    "theremin": 0.1,
+    "timpani": 0.12,
+    "cymbal": 0.1,
+    "tambourine": 0.045,
+    "mandolin": 0.06,
+    "kalimba": 0.08,
+    "celesta": 0.1,
+    "recorder": 0.055,
+}
+
+
+def _electronic_voice(
+    instrument: str, frequency: float, frames: int, rate: int, seed: int, velocity: float
+) -> NDArray[np.float64]:
+    """Generate the original harmonic voices and electronic drum sounds."""
+    t = np.arange(frames, dtype=np.float64) / rate
+    if instrument == "kick":
+        # Analytic integral of an exponential pitch sweep; independent of sample rate.
+        sweep = 60 + 60 * velocity
+        phase = 2 * np.pi * (48 * t + sweep * (1 - np.exp(-35 * t)) / 35)
+        signal = np.sin(phase) * np.exp(-9 * t)
+        signal += (
+            0.035 * velocity * colored_noise(frames, rate, seed, 1800, 9000) * np.exp(-t / 0.006)
+        )
+    elif instrument in {"snare", "hat"}:
+        if instrument == "snare":
+            noise = colored_noise(frames, rate, seed, 1100, 9500)
+            body = 0.32 * np.sin(2 * np.pi * 185 * t) * np.exp(-t / 0.045) + 0.14 * np.sin(
+                2 * np.pi * 330 * t
+            ) * np.exp(-t / 0.028)
+            rattle = (
+                0.72
+                * noise
+                * (1 + 0.18 * np.sin(2 * np.pi * 83 * t))
+                * np.exp(-t / (0.055 + 0.025 * velocity))
+            )
+            signal = body + rattle
+        else:
+            noise = colored_noise(frames, rate, seed, 4500, 16000)
+            metal = (
+                sum(
+                    np.sin(2 * np.pi * f * t) * nyquist_gain(f, rate)
+                    for f in (3170, 4211, 5783, 7139, 9323)
+                )
+                / 5
+            )
+            signal = (0.65 * noise + 0.12 * metal) * np.exp(-t / (0.018 + 0.01 * velocity))
+    else:
+        # Finite harmonic sums avoid the unbounded harmonics of naive square/saw waves.
+        phase = 2 * np.pi * frequency * t
+        harmonics = _HARMONICS[instrument]
+        signal = np.zeros(frames)
+        weight = 0.0
+        for harmonic, amplitude in harmonics:
+            if frequency * harmonic >= rate / 2:
+                continue
+            partial = np.sin(phase * harmonic) * amplitude
+            if instrument == "pluck":
+                partial *= np.exp(-t * (2.5 + harmonic * 0.8))
+            signal += partial
+            weight += abs(amplitude)
+        if weight:
+            signal /= weight
+        if instrument == "bass":
+            signal *= 0.65 + 0.35 * np.exp(-6 * t)
+    return signal
+
+
+def _voice(
+    instrument: str,
+    pitch: int,
+    frames: int,
+    rate: int,
+    seed: int,
+    velocity: float = 0.8,
+    tone: Tone | None = None,
+    held_frames: int | None = None,
+) -> Audio:
+    if instrument == "drum_machine":
+        return _voice(
+            KIT_NOTES[pitch], pitch, frames, rate, seed, velocity, held_frames=held_frames
+        )
+    frequency = 440 * 2 ** ((pitch - 69) / 12)
+    if instrument in EXTENDED_INSTRUMENTS:
+        signal = synthesize_extended(instrument, frequency, frames, rate, seed, velocity, tone)
+    elif instrument in EXTRA_INSTRUMENTS:
+        signal = synthesize_orchestra(instrument, frequency, frames, rate, seed, velocity, tone)
+    elif instrument in PHYSICAL_INSTRUMENTS:
+        signal = synthesize(instrument, frequency, frames, rate, seed, velocity, tone)
+    else:
+        signal = _electronic_voice(instrument, frequency, frames, rate, seed, velocity)
+
+    # Every voice begins and ends at zero. Envelope fits even very short notes.
+    attack_seconds = _ATTACK_SECONDS.get(instrument, 0.003)
+    release_seconds = _RELEASE_SECONDS.get(instrument, 0.02)
+    attack = min(max(1, round(attack_seconds * rate)), max(1, (held_frames or frames) // 3))
+    release = (
+        frames - held_frames
+        if held_frames is not None
+        else min(max(1, round(release_seconds * rate)), max(1, frames // 3))
+    )
+    signal[:attack] *= np.linspace(0, 1, attack)
+    release_curve = 0.5 + 0.5 * np.cos(np.linspace(0, np.pi, release)) if release > 1 else 0
+    signal[-release:] *= release_curve
+    return signal.astype(np.float32)

audio_as_code/acoustics.py

@@ -0,0 +1,126 @@
+"""Small deterministic DSP helpers. Every response is calculated from equations."""
+
+from __future__ import annotations
+
+import math
+from functools import lru_cache
+
+import numpy as np
+from numpy.typing import NDArray
+
+Signal = NDArray[np.float64]
+
+
+def struck_mode(t: Signal, frequency: float, damping: float, contact: float) -> Signal:
+    """Damped sine driven by a unit-area, finite raised-cosine force pulse.
+
+    Integrate continuously, then sample: even sub-sample contact times retain
+    their area. After contact the mode rings freely at its original frequency.
+    Positive unit-area forcing keeps the result bounded by the impulse response.
+    This is prescribed one-way forcing, not a nonlinear hammer/contact solver.
+    """
+    pole = complex(-damping, 2 * np.pi * frequency)
+    pulse_frequency = 2 * np.pi / contact
+    attacking = t < contact
+    u = t[attacking]
+    response = np.zeros(len(t), dtype=np.complex128)
+    released = 0j
+    for weight, offset in ((1, 0), (-0.5, pulse_frequency), (-0.5, -pulse_frequency)):
+        denominator = pole - 1j * offset
+        # expm1 avoids cancellation for short contacts and low modes. All real
+        # exponents are nonpositive, including very short decay settings.
+        integral = np.expm1(denominator * u) / denominator
+        response[attacking] += weight * np.exp(1j * offset * u) * integral
+        released += (
+            weight * np.exp(1j * offset * contact) * np.expm1(denominator * contact) / denominator
+        )
+    response[~attacking] = released * np.exp(pole * (t[~attacking] - contact))
+    return response.imag / contact
+
+
+def nyquist_gain(frequency: Signal | float, rate: int) -> Signal | float:
+    """Cosine shoulder leaves room for envelope/modulation sidebands."""
+    fraction = np.clip((frequency / rate - 0.45) / 0.04, 0, 1)
+    return 0.5 + 0.5 * np.cos(np.pi * fraction)
+
+
+def colored_noise(frames: int, rate: int, seed: int, low: float, high: float) -> Signal:
+    if frames == 0:
+        return np.zeros(0)
+    noise = np.random.Generator(np.random.PCG64(seed)).standard_normal(frames)
+    frequencies = np.fft.rfftfreq(frames, 1 / rate)
+    shape = (frequencies / max(low, 1)) ** 2
+    shape = shape / (1 + shape) / (1 + (frequencies / high) ** 4)
+    shape *= nyquist_gain(frequencies, rate)
+    return np.fft.irfft(np.fft.rfft(noise) * shape, n=frames) * 0.3
+
+
+def modulate_noise(
+    noise: Signal, phase: Signal, maximum_frequency: float, rate: int, depth: float
+) -> Signal:
+    """Add pitch-synchronous texture without folding the noise sidebands.
+
+    Only the modulated component is low-passed. The original breath/friction
+    noise keeps its full bandwidth. A cosine shoulder below the sideband limit
+    leaves space for the slowly evolving phase used by acoustic voices.
+    """
+    cutoff = 0.49 * rate - maximum_frequency
+    if not len(noise) or cutoff <= 0 or depth == 0:
+        return noise
+    bins = np.fft.rfftfreq(len(noise), 1 / rate)
+    shoulder = np.clip((bins / cutoff - 0.9) / 0.1, 0, 1)
+    gain = 0.5 + 0.5 * np.cos(np.pi * shoulder)
+    band_limited = np.fft.irfft(np.fft.rfft(noise) * gain, n=len(noise))
+    return noise + depth * band_limited * np.sin(phase)
+
+
+def slow_variation(t: Signal, seed: int, speed: float = 1) -> Signal:
+    """Bounded smooth variation with a duration-independent seeded trajectory."""
+    rng = np.random.Generator(np.random.PCG64(seed))
+    frequencies = rng.uniform([0.37, 0.91, 1.9], [0.7, 1.5, 2.7]) * speed
+    phases = rng.uniform(-np.pi, np.pi, 3)
+    return sum(
+        weight * np.sin(2 * np.pi * f * t + phase)
+        for weight, f, phase in zip((0.55, 0.3, 0.15), frequencies, phases, strict=True)
+    )
+
+
+@lru_cache(maxsize=48)
+def _body_kernel(rate: int, modes: tuple[tuple[float, float, float], ...]) -> Signal:
+    """Analytic damped modes: frequency Hz, T60 seconds, relative gain."""
+    frames = max(2, math.ceil(min(0.35, max(mode[1] for mode in modes)) * rate))
+    t = np.arange(frames) / rate
+    kernel = np.zeros(frames)
+    for frequency, decay, gain in modes:
+        if frequency < 0.49 * rate:
+            mode = np.sin(2 * np.pi * frequency * t) * np.exp(-math.log(1000) * t / decay)
+            mode /= max(float(np.sum(np.abs(mode))), 1e-12)
+            kernel += gain * mode
+    fade = min(frames, max(2, round(0.01 * rate)))
+    kernel[-fade:] *= 0.5 + 0.5 * np.cos(np.linspace(0, np.pi, fade))
+    kernel /= max(float(np.sum(np.abs(kernel))), 1e-12)
+    kernel.flags.writeable = False
+    return kernel
+
+
+def resonant_body(
+    signal: Signal, rate: int, modes: tuple[tuple[float, float, float], ...], wet: float = 0.2
+) -> Signal:
+    """Causal, bounded coloration driven by the voice, with no recorded IR.
+
+    Block overlap-add computes linear convolution; it never wraps the end of
+    a note onto its attack. The score's note gate still limits the output tail.
+    """
+    if not modes or not len(signal) or wet == 0:
+        return signal
+    kernel = _body_kernel(rate, modes)
+    size = 1 << (max(4096, 2 * len(kernel)) - 1).bit_length()
+    block = size - len(kernel) + 1
+    response = np.fft.rfft(kernel, n=size)
+    result = np.zeros(len(signal))
+    for start in range(0, len(signal), block):
+        part = signal[start : start + block]
+        convolved = np.fft.irfft(np.fft.rfft(part, n=size) * response, n=size)
+        end = min(len(signal), start + len(part) + len(kernel) - 1)
+        result[start:end] += convolved[: end - start]
+    return (1 - wet) * signal + wet * result