afterglow/assets/audio.py

Part of Afterglow.

"""Procedural audio for Afterglow: synthesized SFX + per-world ambient music.

No copyrighted samples: every clip is generated at runtime with
``simvx.core.AudioSynth`` (oscillators + ADSR + per-source filters) or
``AudioClip.tone``. Clips are pure numpy data baked into ``AudioClip``s, so
they play on either backend (desktop / web) with no file I/O.

Bus routing
-----------
The engine ships three built-in buses with the chain ``SFX -> Master`` and
``Music -> Master`` (see ``simvx.core.audio_bus``). This module never plays
anything itself: it only builds clips and tells the caller which bus each
belongs on, so a single Master volume slider controls everything and Music
can be ducked independently.

    SFX    bus -> short one-shots (jump, dash, shatter, ...)
    Music  bus -> the looping ambient bed (one variant per world)

Wiring (game / UI layer)::

    from afterglow.assets import audio

    player = AudioPlayer(stream=audio.get_sfx("jump"), bus=audio.SFX_BUS)
    self.add_child(player)
    player.play()

    music = AudioPlayer(stream=audio.build_music("glade"), bus=audio.MUSIC_BUS)
    music.loop = True
    self.add_child(music)
    music.play()

The sim emits event tags (``'jump'``, ``'dash'``, ``'crystal'``, ``'orb'``,
``'shard'``, ``'death'``, ``'land'``, ``'spring'``, ...); map those tags to
``get_sfx(name)`` in the view/audio layer. Menu UI uses ``"menu_move"`` /
``"menu_confirm"``.
"""

from __future__ import annotations

from functools import cache

import numpy as np

from simvx.core import ADSR, AudioClip, AudioSynth, Exponential, Linear, LowPass, Oscillator

# Built-in bus names (case-sensitive, must match simvx.core.audio_bus).
SFX_BUS = "SFX"
MUSIC_BUS = "Music"
MASTER_BUS = "Master"

# Equal-tempered reference: A4 = 440 Hz. Semitone ratio for melodic offsets.
_A4 = 440.0
_SEMI = 2.0 ** (1.0 / 12.0)


def _note(semitones_from_a4: float) -> float:
    """Frequency of a note `semitones_from_a4` semitones above (or below) A4."""
    return _A4 * (_SEMI**semitones_from_a4)


def _edge_fade(data: np.ndarray, channels: int, sample_rate: int, ms: float) -> np.ndarray:
    """Multiply a short raised-cosine fade onto both ends of an interleaved buffer.

    Guarantees the buffer starts and ends at exact silence so a one-shot never
    clicks on its first/last sample, and (for a looping bed) the splice point is
    truly silent. Operates in place on a per-frame basis across both channels.
    """
    frames = data.size // channels
    n = min(int(sample_rate * ms / 1000.0), frames // 2)
    if n <= 0:
        return data
    ramp = (0.5 - 0.5 * np.cos(np.linspace(0.0, np.pi, n, dtype=np.float32))).astype(np.float32)
    view = data.reshape(frames, channels)
    view[:n] *= ramp[:, None]
    view[-n:] *= ramp[::-1][:, None]
    return data


def _shape(clip: AudioClip, *, fade_ms: float = 3.0) -> AudioClip:
    """Apply a short clickless edge fade to a baked one-shot clip (in place)."""
    data = np.asarray(clip.backend_data, dtype=np.float32)
    _edge_fade(data, clip.channels or 2, clip.sample_rate or 48000, fade_ms)
    return clip


# ===========================================================================
# SFX library: name -> builder. Each returns a short one-shot AudioClip.
# ===========================================================================


def _sfx_jump() -> AudioClip:
    # Quick upward chirp: a soft triangle blip with a fast pluck envelope.
    # Triangle (not square) so the launch reads as gentle, not buzzy.
    s = AudioSynth()
    s.add(Oscillator.triangle(_note(3)), gain=0.30, envelope=ADSR(decay=0.09, sustain=0.0, release=0.04))
    s.add(Oscillator.sine(_note(15)), gain=0.12, envelope=ADSR(decay=0.05, sustain=0.0, release=0.03))
    return _shape(s.bake(duration=0.16))


def _sfx_dash() -> AudioClip:
    # Airy whoosh: filtered noise with a fast swell-and-fall.
    s = AudioSynth()
    s.add(Oscillator.noise.white(seed=7), envelope=Linear(start=1.0, end=0.0), filter=LowPass(1900.0), gain=0.30)
    s.add(Oscillator.saw(_note(7)), envelope=ADSR(attack=0.005, decay=0.12, sustain=0.0, release=0.05), gain=0.10)
    return _shape(s.bake(duration=0.22))


def _sfx_crystal_shatter() -> AudioClip:
    # Bright shimmer: stacked high sines with a short ringing decay + tick.
    s = AudioSynth()
    for n, g, pan in ((24, 0.15, -0.3), (28, 0.12, 0.3), (31, 0.09, 0.0)):
        s.add(Oscillator.sine(_note(n)), envelope=Exponential(start=1.0, end=0.02), gain=g, pan=pan)
    s.add(
        Oscillator.noise.white(seed=11),
        envelope=ADSR(attack=0.001, decay=0.03, sustain=0.0, release=0.02),
        filter=LowPass(5000.0),
        gain=0.07,
    )
    return _shape(s.bake(duration=0.45))


def _sfx_glow_orb() -> AudioClip:
    # Warm bloom: soft triangle swell, a "lighting up" cue.
    s = AudioSynth()
    s.add(Oscillator.triangle(_note(12)), envelope=ADSR(attack=0.06, decay=0.2, sustain=0.4, release=0.25), gain=0.26)
    s.add(Oscillator.sine(_note(19)), envelope=ADSR(attack=0.08, decay=0.2, sustain=0.3, release=0.25), gain=0.12)
    return _shape(s.bake(duration=0.6))


def _sfx_shard() -> AudioClip:
    # Reward arpeggio: two ascending bell-like sines.
    s = AudioSynth()
    s.add(Oscillator.sine(_note(16)), envelope=ADSR(attack=0.002, decay=0.18, sustain=0.0, release=0.08), gain=0.22)
    s.add(Oscillator.sine(_note(23)), envelope=ADSR(attack=0.12, decay=0.18, sustain=0.0, release=0.1), gain=0.18)
    return _shape(s.bake(duration=0.5))


def _sfx_death() -> AudioClip:
    # Falling descent: a saw sliding down via a long pluck + low thump.
    s = AudioSynth()
    s.add(Oscillator.saw(_note(-5)), envelope=Exponential(start=1.0, end=0.04), filter=LowPass(1400.0), gain=0.26)
    s.add(Oscillator.sine(_note(-17)), gain=0.16, envelope=ADSR(decay=0.25, sustain=0.0, release=0.1))
    return _shape(s.bake(duration=0.5))


def _sfx_land() -> AudioClip:
    # Soft thud: low filtered noise burst.
    s = AudioSynth()
    s.add(
        Oscillator.noise.white(seed=3),
        envelope=ADSR(attack=0.001, decay=0.05, sustain=0.0, release=0.03),
        filter=LowPass(650.0),
        gain=0.26,
    )
    s.add(Oscillator.sine(_note(-19)), gain=0.18, envelope=ADSR(decay=0.06, sustain=0.0, release=0.03))
    return _shape(s.bake(duration=0.12))


def _sfx_spring() -> AudioClip:
    # Boing: soft triangle blip the ear reads as a launch (no buzzy square).
    s = AudioSynth()
    s.add(Oscillator.triangle(_note(0)), gain=0.28, envelope=ADSR(decay=0.14, sustain=0.0, release=0.06))
    s.add(Oscillator.sine(_note(12)), gain=0.14, envelope=ADSR(decay=0.1, sustain=0.0, release=0.05))
    return _shape(s.bake(duration=0.24))


def _sfx_menu_move() -> AudioClip:
    # Tiny soft tick for cursor movement. A plucked triangle (not a raw sine
    # tone) so it reads as a UI blip, and synth-baked so it shares the 48 kHz
    # sample rate of every other clip and the SFX bus (no resample pitch shift).
    s = AudioSynth()
    s.add(Oscillator.triangle(_note(7)), gain=0.16, envelope=ADSR(decay=0.05, sustain=0.0, release=0.02))
    return _shape(s.bake(duration=0.07))


def _sfx_menu_confirm() -> AudioClip:
    # Two-note confirm chime.
    s = AudioSynth()
    s.add(Oscillator.triangle(_note(12)), envelope=ADSR(attack=0.002, decay=0.1, sustain=0.0, release=0.05), gain=0.24)
    s.add(Oscillator.triangle(_note(19)), envelope=ADSR(attack=0.07, decay=0.12, sustain=0.0, release=0.06), gain=0.20)
    return _shape(s.bake(duration=0.3))


# Registry of SFX builders. ``get_sfx`` validates against these keys.
_SFX_BUILDERS = {
    "jump": _sfx_jump,
    "dash": _sfx_dash,
    "crystal_shatter": _sfx_crystal_shatter,
    "glow_orb": _sfx_glow_orb,
    "shard": _sfx_shard,
    "death": _sfx_death,
    "land": _sfx_land,
    "spring": _sfx_spring,
    "menu_move": _sfx_menu_move,
    "menu_confirm": _sfx_menu_confirm,
}

SFX_NAMES = tuple(_SFX_BUILDERS)


@cache
def get_sfx(name: str) -> AudioClip:
    """Return the cached SFX clip for `name` (one of ``SFX_NAMES``).

    Built lazily on first request and memoised, so repeated plays share a
    single baked buffer. Route the player to ``SFX_BUS``.
    """
    try:
        builder = _SFX_BUILDERS[name]
    except KeyError:
        raise KeyError(f"unknown SFX {name!r}; valid names: {', '.join(SFX_NAMES)}") from None
    return builder()


# ===========================================================================
# Ambient music: one looping bed per world. Routed to MUSIC_BUS.
# ===========================================================================

# Per-world mood. Each entry: root note (semitones from A4) + a small chord/
# pad set layered over a slow drone, plus a low-pass cutoff for warmth.
# The clip is a soft, quiet ambient bed (target RMS ~0.10-0.12) with a master
# fade in/out applied to the whole baked buffer (``_LOOP_FADE_MS``) so the loop
# splice point is exact silence: an AudioPlayer with ``loop=True`` repeats with
# no click even though the individual voices never perfectly phase-align.
_WORLD_MOODS = {
    # The Glade: gentle, open, major-ish. Bright pad over a soft drone.
    "glade": {"root": -9, "chord": (0, 4, 7, 12), "cutoff": 2600.0, "bars": 8.0},
    # The Caverns: low, hollow, minor. Darker drone, narrower top.
    "caverns": {"root": -21, "chord": (0, 3, 7, 10), "cutoff": 1300.0, "bars": 8.0},
    # The Spire: tense, suspended, shimmering highs.
    "spire": {"root": -2, "chord": (0, 5, 7, 14), "cutoff": 3200.0, "bars": 8.0},
}

WORLD_IDS = tuple(_WORLD_MOODS)

# Loop length: one drone cycle == half a bar at this tempo, so `bars` bars of
# pad sit on a whole number of drone cycles -> click-free loop point.
_BAR_SECONDS = 2.0

# Master fade applied to each end of the whole baked bed, in milliseconds. Long
# enough that the silent splice point is inaudible against the slow ambient pad.
_LOOP_FADE_MS = 180.0

# --- Melodic loop layered over the pad -------------------------------------
# The pad alone reads as one held chord, so we add an actual tune: a pentatonic
# melody + a simple bass, arranged over a 4-section (8-bar) chord-root
# progression. Eighth note = a quarter of a 2.0 s bar.
_EIGHTH = _BAR_SECONDS / 8.0  # 0.25 s
_SECTION = _BAR_SECONDS * 2.0  # 2 bars per progression section
_PENTA = {
    "glade": (0, 2, 4, 7, 9),  # major pentatonic: bright, open
    "caverns": (0, 3, 5, 7, 10),  # minor pentatonic: hollow, moody
    "spire": (0, 2, 3, 7, 9),  # suspended-ish: tense
}
# Chord root offset (semitones added to the mood root) for each 2-bar section.
_PROG = {
    "glade": (0, 7, 5, 7),
    "caverns": (0, -2, 3, -2),
    "spire": (0, 5, 3, 7),
}
# 16 eighth-note slots per 2-bar section; values index the pentatonic scale
# (>=5 wraps up an octave), -1 is a rest. These are singable phrases: stepwise
# motion with rests to breathe and a resolution back toward the tonic, NOT random
# leaps. The chord-root progression (_PROG) re-colours the same phrase per section.
_MOTIF = {
    # The Glade: gentle, flowing, rises then settles home.
    "glade": (0, -1, 2, 4, 3, -1, 2, -1, 4, -1, 3, 2, 0, -1, 0, -1),
    # The Caverns: sparse + contemplative; long held notes between rests.
    "caverns": (0, -1, -1, 2, -1, -1, 3, -1, 2, -1, -1, 1, -1, -1, 0, -1),
    # The Spire: tense climb that eases back down to the tonic.
    "spire": (0, 2, 3, -1, 4, -1, 3, 2, 0, -1, 2, 3, 2, -1, 0, -1),
}
# Keep the melody in a comfortable mid register (the old +octave read as shrill,
# random high tinkling). Caverns lifts one octave off its very deep drone root.
_MELODY_OCT = {"glade": 0, "caverns": 12, "spire": 0}


def _scale_semis(scale: tuple[int, ...], degree: int) -> int:
    """Semitone offset for a pentatonic ``degree`` (wrapping octaves)."""
    octave, idx = divmod(degree, len(scale))
    return scale[idx] + 12 * octave


def _pluck_into(
    mix,
    sr: int,
    freq: float,
    t0: float,
    dur: float,
    gain: float,
    *,
    wave: str = "sine",
    pan: float = 0.0,
    tau: float = 0.18,
) -> None:
    """Add one plucked note (fast attack, exponential decay) into ``mix`` (frames, ch)."""
    f0 = int(t0 * sr)
    n = int(dur * sr)
    if n <= 0 or f0 >= mix.shape[0]:
        return
    end = min(f0 + n, mix.shape[0])
    n = end - f0
    t = np.arange(n, dtype=np.float32) / sr
    if wave == "triangle":
        ph = (freq * t) % 1.0
        w = 2.0 * np.abs(2.0 * ph - 1.0) - 1.0
    else:
        w = np.sin(2.0 * np.pi * freq * t)
    env = (1.0 - np.exp(-t / 0.006)) * np.exp(-t / tau)
    sig = (w * env * gain).astype(np.float32)
    if mix.shape[1] >= 2:
        angle = (pan + 1.0) * (np.pi / 4.0)
        mix[f0:end, 0] += sig * float(np.cos(angle))
        mix[f0:end, 1] += sig * float(np.sin(angle))
    else:
        mix[f0:end, 0] += sig


def _add_melody(data, sr: int, frames: int, ch: int, world_id: str, root: float) -> None:
    """Layer a pentatonic melody + bass over the baked pad buffer in place."""
    scale = _PENTA.get(world_id, _PENTA["glade"])
    prog = _PROG.get(world_id, _PROG["glade"])
    motif = _MOTIF.get(world_id, _MOTIF["glade"])
    mel_oct = _MELODY_OCT.get(world_id, 12)
    mix = np.zeros((frames, ch), dtype=np.float32)
    for section in range(4):
        base = root + prog[section]
        t_sec = section * _SECTION
        for slot, deg in enumerate(motif):
            if deg < 0:
                continue
            freq = _note(base + mel_oct + _scale_semis(scale, deg))
            pan = -0.25 if slot % 2 else 0.25
            _pluck_into(mix, sr, freq, t_sec + slot * _EIGHTH, 0.55, 0.13, wave="triangle", pan=pan, tau=0.24)
        # Bass: root note every half-bar (beats 1 and 3 of each bar).
        for beat in (0.0, 1.0, 2.0, 3.0):
            freq = _note(base - 12)
            _pluck_into(mix, sr, freq, t_sec + beat * (_BAR_SECONDS / 2.0), 0.9, 0.075, wave="sine", tau=0.38)
    data.reshape(frames, ch)[:] += mix


def _build_music(world_id: str) -> AudioClip:
    try:
        mood = _WORLD_MOODS[world_id]
    except KeyError:
        raise KeyError(f"unknown world {world_id!r}; valid ids: {', '.join(WORLD_IDS)}") from None

    root = float(mood["root"])
    chord = mood["chord"]
    cutoff = float(mood["cutoff"])
    duration = float(mood["bars"]) * _BAR_SECONDS

    s = AudioSynth()
    # Soft, quiet ambient bed. Gains are deliberately low (~half the old bed) so
    # the looping pad sits UNDER gameplay as atmosphere, never a loud held tone.
    # Pad is now a FAINT backing wash (cut to ~40% of the old levels) so the
    # melody + bass added later are the foreground, not a dominant held chord.
    s.add(Oscillator.sine(_note(root - 12)), filter=LowPass(cutoff), gain=0.028)
    s.add(Oscillator.triangle(_note(root)), filter=LowPass(cutoff), gain=0.016)
    # Chord pad: detuned sines spread across the stereo field for width.
    spread = (-0.5, -0.18, 0.18, 0.5)
    for i, semi in enumerate(chord):
        pan = spread[i % len(spread)]
        s.add(Oscillator.sine(_note(root + semi), phase=0.3 * i), filter=LowPass(cutoff), gain=0.012, pan=pan)
        # Slight detune layer (+ a few cents) for a warm chorus shimmer.
        s.add(Oscillator.sine(_note(root + semi + 0.06)), filter=LowPass(cutoff), gain=0.008, pan=-pan)
    # Faint top shimmer for air.
    s.add(Oscillator.sine(_note(root + chord[-1] + 12)), filter=LowPass(cutoff), gain=0.006)
    clip = s.bake(duration=duration)
    data = np.asarray(clip.backend_data, dtype=np.float32)
    ch = clip.channels or 2
    sr = clip.sample_rate or 48000
    # Gentle, whole-cycle tremolo so the pad slowly breathes instead of reading as
    # one static held tone. One full LFO period spans the whole loop, so the
    # amplitude at the splice point matches and the loop stays click-free.
    frames = data.size // ch
    lfo_period = duration  # exactly one breath per loop -> seamless at the splice
    t = np.arange(frames, dtype=np.float32) / sr
    tremolo = (0.82 + 0.18 * (0.5 - 0.5 * np.cos(2.0 * np.pi * t / lfo_period))).astype(np.float32)
    data.reshape(frames, ch)[:] *= tremolo[:, None]
    # Layer an actual melody + bass over the (now gently breathing) pad so the
    # music has movement and a tune, not just a sustained chord.
    _add_melody(data, sr, frames, ch, world_id, root)
    # Keep peaks in range after summing melody + pad.
    peak = float(np.abs(data).max()) if data.size else 0.0
    if peak > 0.95:
        data *= 0.95 / peak
    # Master fade in/out across the whole buffer guarantees an exactly silent
    # splice point regardless of per-voice phase, so loop=True never clicks.
    _edge_fade(data, ch, sr, _LOOP_FADE_MS)
    return clip


@cache
def build_music(world_id: str) -> AudioClip:
    """Return the cached ambient loop for `world_id` (one of ``WORLD_IDS``).

    Designed to loop seamlessly: play through an ``AudioPlayer`` with
    ``loop=True`` routed to ``MUSIC_BUS``.
    """
    return _build_music(world_id)


__all__ = [
    "SFX_BUS",
    "MUSIC_BUS",
    "MASTER_BUS",
    "SFX_NAMES",
    "WORLD_IDS",
    "get_sfx",
    "build_music",
]