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

audio_as_code/physical.py

@@ -0,0 +1,189 @@
+"""Sample-free physical/modal approximations, implemented with NumPy only.
+
+The string uses a passive Karplus-Strong feedback loop with phase-compensated
+fractional delay. Bar and bell presets sum the impulse responses of damped modes.
+All excitations are generated here; no recordings or measured impulse responses.
+See docs/synthesis.md for equations, scope, and references.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from types import MappingProxyType
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .acoustics import colored_noise, nyquist_gain, resonant_body, struck_mode
+from .instruments import require_instrument
+from .model import Tone
+
+
+@dataclass(frozen=True)
+class ModalProfile:
+    ratios: tuple[float, ...]
+    amplitudes: tuple[float, ...]
+    lifetimes: tuple[float, ...]
+
+
+_MODAL_PROFILES = MappingProxyType(
+    {
+        # Approximate tuned wooden bar; higher modes die away much sooner.
+        "marimba": ModalProfile((1, 4, 10, 17), (1, 0.32, 0.12, 0.04), (1, 0.32, 0.14, 0.08)),
+        # Designed inharmonic chime, not a model fitted to a particular bell.
+        "bell": ModalProfile(
+            (1, 2, 2.756, 4.07, 5.404, 6.81),
+            (1, 0.38, 0.32, 0.22, 0.12, 0.08),
+            (1, 0.8, 0.65, 0.5, 0.4, 0.3),
+        ),
+    }
+)
+
+
+def _string(
+    frequency: float,
+    frames: int,
+    rate: int,
+    seed: int,
+    brightness: float,
+    decay: float,
+    position: float,
+) -> NDArray[np.float64]:
+    omega = 2 * math.pi * frequency / rate
+    # A passive one-zero filter dissipates high frequencies on every round trip.
+    damping = 0.3 - brightness * 0.25
+    damping_response = (1 - damping) + damping * np.exp(-1j * omega)
+    damping_phase = -float(np.angle(damping_response))
+    delay = max(1, math.floor((2 * math.pi - damping_phase) / omega))
+    residual = max(0.0, 2 * math.pi - damping_phase - delay * omega)
+    # Solve the linear interpolator's phase at the fundamental, rather than
+    # assuming its group delay equals its interpolation weight at every pitch.
+    fractional = math.sin(residual) / (math.sin(omega - residual) + math.sin(residual))
+    fractional = min(1.0, max(0.0, fractional))
+    interpolation_response = (1 - fractional) + fractional * np.exp(-1j * omega)
+    target_loss = math.exp(-math.log(1000) / (frequency * decay))
+    filter_loss = abs(damping_response * interpolation_response)
+    loop_gain = min(0.9999, target_loss / max(filter_loss, 1e-12))
+    coefficients = loop_gain * np.array(
+        [
+            (1 - damping) * (1 - fractional),
+            damping * (1 - fractional) + (1 - damping) * fractional,
+            damping * fractional,
+        ]
+    )
+
+    rng = np.random.Generator(np.random.PCG64(seed))
+    excitation = rng.uniform(-1, 1, delay)
+    excitation -= np.roll(excitation, max(1, round(position * delay)))
+    # Shape a code-generated pluck, emphasizing low string modes while retaining
+    # the noise burst's transient. This spectrum is generated afresh per note.
+    harmonics = np.arange(delay // 2 + 1)
+    spectrum = np.fft.rfft(excitation)
+    spectrum *= 1 / (1 + (harmonics / (5 + brightness * 24)) ** 2)
+    excitation = np.fft.irfft(spectrum, n=delay)
+    location = np.arange(delay) / delay
+    displacement = np.where(
+        location <= position, location / position, (1 - location) / (1 - position)
+    )
+    excitation = 0.65 * excitation + 0.55 * (displacement - np.mean(displacement))
+    excitation += 0.3 * np.sin(2 * np.pi * location)
+    excitation -= np.mean(excitation)
+    peak = float(np.max(np.abs(excitation)))
+    if peak:
+        excitation *= 0.8 / peak
+
+    padding = delay + 2
+    history = np.zeros(frames + padding)
+    initial = min(delay, frames)
+    history[padding : padding + initial] = excitation[:initial]
+    # A block never exceeds the shortest delay, so every feedback read refers
+    # to an already-computed block. No Python loop per individual audio sample.
+    for start in range(padding, len(history), delay):
+        stop = min(len(history), start + delay)
+        history[start:stop] += (
+            coefficients[0] * history[start - delay : stop - delay]
+            + coefficients[1] * history[start - delay - 1 : stop - delay - 1]
+            + coefficients[2] * history[start - delay - 2 : stop - delay - 2]
+        )
+    signal = history[padding:]
+    # Body modes are driven by the vibrating string, not an independent knock.
+    t = np.arange(frames) / rate
+    signal += (
+        0.009 * brightness * colored_noise(frames, rate, seed + 1, 1600, 8000) * np.exp(-t / 0.006)
+    )
+    return resonant_body(
+        signal, rate, ((110, 0.19, 0.45), (205, 0.12, 0.35), (430, 0.075, 0.2)), wet=0.22
+    )
+
+
+def _modes(
+    instrument: str,
+    frequency: float,
+    frames: int,
+    rate: int,
+    brightness: float,
+    decay: float,
+) -> NDArray[np.float64]:
+    t = np.arange(frames, dtype=np.float64) / rate
+    profile = _MODAL_PROFILES[instrument]
+    signal = np.zeros(frames)
+    total_weight = 0.0
+    for index, (ratio, amplitude, lifetime) in enumerate(
+        zip(profile.ratios, profile.amplitudes, profile.lifetimes, strict=True)
+    ):
+        amplitude *= 1 if index == 0 else 0.15 + brightness * 1.7
+        total_weight += amplitude
+        if frequency * ratio >= rate * 0.49:
+            continue
+        if instrument == "marimba":
+            contact = min(0.65 / frequency, 0.0035 * (1.2 - 0.8 * brightness))
+            response = struck_mode(
+                t, frequency * ratio, math.log(1000) / (decay * lifetime), contact
+            )
+        else:
+            envelope = np.exp(-math.log(1000) * t / (decay * lifetime))
+            partial = np.sin(2 * np.pi * frequency * ratio * t)
+            split = frequency * ratio * (1 + 0.0006 * (index + 1))
+            partial = 0.8 * partial + 0.2 * np.sin(2 * np.pi * split * t) * nyquist_gain(
+                split, rate
+            )
+            response = partial * envelope * (1 - np.exp(-t / 0.001))
+        signal += amplitude * response * nyquist_gain(frequency * ratio, rate)
+    return signal * (0.9 / total_weight) if total_weight else signal
+
+
+def synthesize(
+    instrument: str,
+    frequency: float,
+    frames: int,
+    rate: int,
+    seed: int,
+    velocity: float,
+    tone: Tone | None,
+) -> NDArray[np.float64]:
+    instrument_info = require_instrument(instrument)
+    if instrument not in {"guitar", "marimba", "bell"}:
+        raise ValueError(f"{instrument!r} does not use the original physical/modal engine")
+    settings = tone or Tone()
+    if frequency >= rate / 2:
+        return np.zeros(frames)
+    brightness = min(1.0, settings.brightness * 0.75 + velocity * 0.25)
+    decay = (
+        settings.decay_seconds
+        if settings.decay_seconds is not None
+        else instrument_info.default_decay_seconds
+    )
+    if decay is None:
+        raise ValueError(f"{instrument!r} has no default decay configured")
+    if instrument_info.engine == "string":
+        return _string(
+            frequency,
+            frames,
+            rate,
+            seed,
+            brightness,
+            decay,
+            settings.pluck_position if settings.pluck_position is not None else 0.22,
+        )
+    return _modes(instrument, frequency, frames, rate, brightness, decay)

audio_as_code/render.py

@@ -0,0 +1,230 @@
+"""Deterministic, in-process synthesis. No audio device, API key, or DAW needed."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass
+from importlib.metadata import version
+from pathlib import Path
+
+import numpy as np
+
+from ._audio import Audio, _metrics, _write_wav, analyze_wav
+from ._export_rules import MAX_RENDER_SECONDS
+from ._export_rules import note_frame as _note_frame
+from ._paths import check_paths
+from ._voices import _voice
+from .automation import automation_values
+from .effects import apply_effects
+from .model import Song, Track, midi_pitch
+
+PEAK_CEILING = 0.95
+
+
+@dataclass(frozen=True)
+class RenderResult:
+    audio: Audio
+    report: dict
+
+
+def _note_seed(song_seed: int, track_name: str, note_index: int) -> int:
+    """Track-local seeds keep noise unchanged when an unrelated track is added."""
+    data = f"{song_seed}:{track_name}:{note_index}".encode()
+    return int.from_bytes(hashlib.sha256(data).digest()[:8], "little")
+
+
+def _track_audio(song: Song, track: Track, frames: int) -> Audio:
+    if (
+        song.tempo_map
+        or song.automation
+        or track.automation
+        or any(effect.mix for effect in track.effects)
+        or track.release_seconds
+        or track.pedal
+        or any(note.release_seconds for note in track.notes)
+    ):
+        return _expressive_track_audio(song, track, frames)
+    result = np.zeros((frames, 2), dtype=np.float32)
+    angle = (track.pan + 1) * np.pi / 4
+    left, right = math.cos(angle), math.sin(angle)
+    for index, note in enumerate(track.notes):
+        start = _note_frame(song, note.start)
+        end = min(frames, _note_frame(song, note.start + note.duration))
+        if end <= start or track.gain == 0:
+            continue
+        seed = _note_seed(song.seed, track.name, index)
+        voice = _voice(
+            track.instrument,
+            midi_pitch(note.pitch),
+            end - start,
+            song.sample_rate,
+            seed,
+            note.velocity,
+            track.tone,
+        )
+        voice *= note.velocity * track.gain * song.master_gain
+        result[start:end, 0] += voice * left
+        result[start:end, 1] += voice * right
+    return result
+
+
+def _expressive_track_audio(song: Song, track: Track, frames: int) -> Audio:
+    mono = np.zeros(frames, dtype=np.float32)
+    for index, note in enumerate(track.notes):
+        start = _note_frame(song, note.start)
+        held_end = _note_frame(song, song.note_gate_end(track, note))
+        release = song.note_release_seconds(track, note)
+        end = min(frames, held_end + round(release * song.sample_rate))
+        if held_end <= start:
+            continue
+        seed = _note_seed(song.seed, track.name, index)
+        voice = _voice(
+            track.instrument,
+            midi_pitch(note.pitch),
+            end - start,
+            song.sample_rate,
+            seed,
+            note.velocity,
+            track.tone,
+            held_frames=held_end - start if end > held_end else None,
+        )
+        mono[start:end] += voice * note.velocity
+    result = np.zeros((frames, 2), dtype=np.float32)
+    lanes = {lane.parameter: lane for lane in track.automation}
+    for start in range(0, frames, 65536):
+        stop = min(frames, start + 65536)
+        gain = (
+            automation_values(song, lanes["gain"], start, stop) if "gain" in lanes else track.gain
+        )
+        pan = automation_values(song, lanes["pan"], start, stop) if "pan" in lanes else track.pan
+        angle = (pan + 1) * np.pi / 4
+        result[start:stop, 0] = mono[start:stop] * gain * np.cos(angle)
+        result[start:stop, 1] = mono[start:stop] * gain * np.sin(angle)
+    del mono
+    result = apply_effects(result, track.effects, song.sample_rate)
+    for start in range(0, frames, 65536):
+        stop = min(frames, start + 65536)
+        if song.automation:
+            gain = automation_values(song, song.automation[0], start, stop)
+            result[start:stop] *= gain[:, None]
+        else:
+            result[start:stop] *= song.master_gain
+    return result
+
+
+def _canonical_score(song: Song) -> dict:
+    """Omit additive defaults from hashing to preserve existing score identities."""
+    data = song.model_dump(mode="json")
+    for key in ("tempo_map", "automation", "effects"):
+        if not data[key]:
+            del data[key]
+    for track in data["tracks"]:
+        for key in ("automation", "effects", "release_seconds", "pedal"):
+            if not track[key]:
+                del track[key]
+        for note in track["notes"]:
+            if note["release_seconds"] is None:
+                del note["release_seconds"]
+    return data
+
+
+def render_audio(song: Song, *, normalize: bool = True) -> RenderResult:
+    """Render stereo float32 audio and measurements. Limit: five minutes per call.
+
+    Normalization only attenuates to a 0.95 peak ceiling; it never boosts a quiet mix.
+    Floating-point output remains unclipped when normalization is disabled.
+    """
+    # Revalidate even if a caller used Pydantic's unchecked construction/copy escape hatches.
+    song = Song.model_validate(song.model_dump())
+    if song.render_seconds > MAX_RENDER_SECONDS:
+        raise ValueError(f"offline renders are limited to {MAX_RENDER_SECONDS} seconds")
+    frames = round(song.render_seconds * song.sample_rate)
+    if frames < 1:
+        raise ValueError("song is shorter than one audio sample")
+    mix = np.zeros((frames, 2), dtype=np.float32)
+    for track in song.tracks:
+        mix += _track_audio(song, track, frames)
+    mix = apply_effects(mix, song.effects, song.sample_rate)
+    if not np.all(np.isfinite(mix)):
+        raise ValueError("render produced non-finite samples; lower score gains or effect levels")
+    before = _metrics(mix, song.sample_rate)
+    attenuation = min(1.0, PEAK_CEILING / before["peak"]) if normalize and before["peak"] else 1.0
+    mix *= attenuation
+    warnings = []
+    if before["silent"]:
+        warnings.append("The render is silent; check notes, pitch range, and track/master gains.")
+    if attenuation < 1:
+        warnings.append(
+            "The mix exceeded the peak ceiling and was attenuated; consider lowering gains."
+        )
+    if not normalize and before["clipped_samples"]:
+        warnings.append("The mix exceeds full scale; WAV export will hard-clip these samples.")
+    if any(
+        _note_frame(song, song.note_gate_end(track, note)) - _note_frame(song, note.start) < 3
+        for track in song.tracks
+        for note in track.notes
+    ):
+        warnings.append("Some notes are too short for the audio sample grid and may be silent.")
+    canonical = json.dumps(_canonical_score(song), sort_keys=True, separators=(",", ":"))
+    report = {
+        "engine_version": version("audio-as-code"),
+        "numpy_version": np.__version__,
+        "score_sha256": hashlib.sha256(canonical.encode()).hexdigest(),
+        "title": song.title,
+        "tracks": len(song.tracks),
+        "notes": sum(len(track.notes) for track in song.tracks),
+        "seed": song.seed,
+        "normalize": normalize,
+        "score_duration_seconds": song.seconds,
+        "tail_seconds": max(0.0, song.render_seconds - song.seconds),
+        "effects": {
+            "master": [effect.model_dump() for effect in song.effects],
+            "tracks": {
+                track.name: [effect.model_dump() for effect in track.effects]
+                for track in song.tracks
+                if track.effects
+            },
+        },
+        "gain_applied": attenuation,
+        "before_gain": before,
+        "audio": _metrics(mix, song.sample_rate),
+        "warnings": warnings,
+    }
+    return RenderResult(mix, report)
+
+
+def render(
+    song: Song, path: str | Path, *, normalize: bool = True, stems_dir: str | Path | None = None
+) -> dict:
+    """Write a 16-bit stereo WAV. Optional stems share the mix's attenuation."""
+    song = Song.model_validate(song.model_dump())
+    destination = Path(path)
+    stem_paths = []
+    if stems_dir is not None:
+        # Use numeric filenames; track names never become filesystem paths.
+        stem_paths = [Path(stems_dir) / f"{index + 1:02d}.wav" for index in range(len(song.tracks))]
+    check_paths(
+        [destination, *stem_paths],
+        [stems_dir] if stems_dir is not None else [],
+        conflict_message="mix and stem outputs must not have the same path or file",
+    )
+    result = render_audio(song, normalize=normalize)
+    _write_wav(destination, result.audio, song.sample_rate)
+    report = {**result.report, "output": str(destination), "stems": []}
+    report["wav"] = analyze_wav(destination)
+    if stem_paths and song.effects:
+        report["warnings"].append(
+            "Stems include track effects and master gain automation, but omit master effects; "
+            "their sum will differ from the processed mix."
+        )
+    for track, stem_path in zip(song.tracks, stem_paths, strict=False):
+        stem = _track_audio(song, track, len(result.audio))
+        stem *= result.report["gain_applied"]
+        _write_wav(stem_path, stem, song.sample_rate)
+        metrics = _metrics(stem, song.sample_rate)
+        report["stems"].append({"track": track.name, "path": str(stem_path), "audio": metrics})
+        if metrics["clipped_samples"]:
+            report["warnings"].append(f"Stem {track.name!r} exceeds full scale and was clipped.")
+    return report