shrike/audio.py

Part of SHRIKE.

"""SHRIKE's audio: every sound synthesised at load, and the mix the power state drives.

There are no audio files. Each cue is rendered into a numpy buffer when the
director enters the tree and handed to the engine as an ``AudioClip``, so the
whole soundtrack ships as arithmetic.

The mix is diegetic. Running the generator adds a room-tone hum whose loudness
IS the signature warning; silent running low-passes the entire mix down to hull
creaks and, if the Shrike is out there, its sonar ping; low oxygen tightens that
same filter and puts your own breathing in the foreground; the T-30 klaxon ducks
the bed and lets a heartbeat through. Spatial cues (spawn chevrons, the ping)
pan toward the thing that made them.

Every cue also reaches the HUD as a caption on the :attr:`~AudioDirector.audio_cue`
signal, because a mechanic carried by sound must never be hearing-gated. The
player's three mixer sliders arrive through :meth:`AudioDirector.set_bus_volumes`
and trim what the cue table authored rather than replacing it.

The noise beds and sweeps are rendered with vectorised numpy rather than
``AudioSynth``'s per-source filters and pink noise, which are per-sample Python
loops sized for sub-second effects; the tonal cues use ``AudioSynth`` directly.
"""

import math
from dataclasses import dataclass

import numpy as np

from simvx.core import (
    ADSR,
    AudioBusLayout,
    AudioClip,
    AudioPlayer,
    AudioSynth,
    Exponential,
    Linear,
    LowPassFilter,
    Node,
    Oscillator,
    Signal,
    Vec3,
)

from . import balance
from .power import SignalWiring
from .runtime import Groups, SignalNames

# ============================================================================
# Mix constants
#
# These are presentation numbers rather than balance ones, so they live here
# rather than in balance.py; the two that gate gameplay readings
# (O2_LOW_WARNING_SECONDS, KILL_COMBO_WINDOW_S) come from balance.
# ============================================================================

SAMPLE_RATE = 48000
#: Fixed seed so every boot renders a byte-identical bank.
NOISE_SEED = 7717

#: Round-robin one-shot voices. Deep enough for a busy wave, shallow enough to
#: bound the node count.
ONE_SHOT_VOICES = 12

#: The hum's loudness at zero signature and at SIGNATURE_MAX. This ramp is the
#: warning: players learn the sector's danger by ear before reading the border.
HUM_QUIET_DB = -34.0
HUM_LOUD_DB = -8.0

#: Ducking at T-30: the music bed drops, the ambience drops less, and the
#: heartbeat comes in over the hole.
DUCK_MUSIC_DB = -18.0
DUCK_AMBIENCE_DB = -10.0

#: Master low-pass cutoffs. Silent running is the tighter of the two, so when
#: both apply the mix takes the lower.
SILENT_RUNNING_CUTOFF_HZ = 520.0
LOW_O2_CUTOFF_HZ = 1100.0
MASTER_LOWPASS_Q = 0.9

#: Kill pitch ladder: one semitone per kill inside balance.KILL_COMBO_WINDOW_S.
KILL_LADDER_SEMITONE = 2.0 ** (1.0 / 12.0)
KILL_LADDER_MAX_STEPS = 8

#: Pan buckets a positional cue snaps to, and the offset from the ship in world
#: units that reads as a hard pan.
PAN_BUCKETS = (-1.0, -0.5, 0.0, 0.5, 1.0)
PAN_FULL_WIDTH = 36.0

#: Seconds between sonar pings while silent running with the Shrike in-sector.
SONAR_PING_INTERVAL_S = 3.5

#: Two-tone klaxon shape.
KLAXON_SLOT_S = 0.3
KLAXON_HIGH_HZ = 466.0
KLAXON_LOW_HZ = 349.0

#: The three mixer sliders, as bus names. Every cue plays on one of them and
#: ``Master`` multiplies the lot, so a settings screen owns the whole mix with
#: three numbers and the cue table keeps its authored balance untouched.
BUS_MASTER = "Master"
BUS_SFX = "SFX"
BUS_MUSIC = "Music"
#: Decibels a bus is trimmed to at a slider of zero. Far enough down to be
#: silence at any sane master, and finite so the arithmetic stays real.
BUS_SILENT_DB = -80.0

#: How a panned caption names the side the sound came from. Screen words rather
#: than arrows or brackets: a caption track is prose about a sound, and every
#: piece of punctuation in it has been read as scaffolding by somebody.
CAPTION_LEFT = "LEFT"
CAPTION_RIGHT = "RIGHT"


# ============================================================================
# The cue catalogue
# ============================================================================


@dataclass(frozen=True)
class Cue:
    """One sound: its id, its caption, and how it sits in the mix.

    ``caption`` is the line the HUD's caption track prints for this sound,
    written in small caps as a diegetic phrase. It carries no glyphs, brackets
    or asterisks, which read as placeholder text that shipped by mistake; the
    caption plate is what says "this is a sound".
    """

    id: str
    caption: str
    duration: float
    gain_db: float
    loop: bool = False
    bus: str = BUS_SFX


CUES: dict[str, Cue] = {
    "generator_hum": Cue("generator_hum", "GENERATOR HUM", 2.0, HUM_QUIET_DB, loop=True),
    "hull_creak": Cue("hull_creak", "HULL CREAKS", 4.0, -22.0, loop=True),
    "heartbeat": Cue("heartbeat", "HEARTBEAT", 1.0, -10.0, loop=True),
    "breathing": Cue("breathing", "LABOURED BREATHING", 4.0, -14.0, loop=True),
    "klaxon": Cue("klaxon", "KLAXON", 1.2, -14.0),
    "sonar_ping": Cue("sonar_ping", "SONAR PING", 1.2, -10.0),
    "groan": Cue("groan", "DISTANT GROAN", 3.0, -8.0),
    "weapon_fire": Cue("weapon_fire", "SHOT", 0.12, -14.0),
    "kill": Cue("kill", "KILL CHIME", 0.22, -10.0),
    "spool_stutter": Cue("spool_stutter", "SPOOL STUTTERS", 0.35, -10.0),
    "spawn_chevron": Cue("spawn_chevron", "HOSTILES INBOUND", 0.3, -12.0),
    "mortar_whistle": Cue("mortar_whistle", "WHISTLE", 1.6, -13.0),
    "signature_locked": Cue("signature_locked", "SIGNATURE LOCKED", 0.9, -12.0),
    "tear_in": Cue("tear_in", "IT TEARS IN", 1.6, -9.0),
    "lantern_burn": Cue("lantern_burn", "LANTERN BURN", 1.1, -9.0),
}

#: Cues the mix state machine holds open, in the order they are created.
LOOP_CUES = tuple(cue.id for cue in CUES.values() if cue.loop)
#: Loops the T-30 duck pulls down. The heartbeat is what the duck makes room for.
AMBIENCE_CUES = ("generator_hum", "hull_creak", "breathing")

#: Telegraph stage to cue, for the strict ladder in hunter.py.
TELEGRAPH_CUES = {"t60": "groan", "t30": "klaxon", "t0": "tear_in"}


def _clamp_gain(value: float) -> float:
    """A slider reading clamped to the 0..1 fraction the mixer accepts."""
    return 0.0 if value < 0.0 else 1.0 if value > 1.0 else float(value)


def _gain_db(fraction: float) -> float:
    """A linear volume fraction as decibels, with zero as :data:`BUS_SILENT_DB`."""
    fraction = _clamp_gain(fraction)
    return BUS_SILENT_DB if fraction <= 0.0 else max(BUS_SILENT_DB, 20.0 * math.log10(fraction))


def subtitle(cue: str, pan: float = 0.0) -> str:
    """The caption line for *cue*, naming the side a panned sound came from.

    Small caps, no punctuation around it: the caption plate the HUD draws under
    the line is the convention that marks a caption track, and brackets around
    it would read as an unfinished placeholder instead.
    """
    caption = CUES[cue].caption
    if pan <= -0.4:
        return f"{caption}, {CAPTION_LEFT}"
    if pan >= 0.4:
        return f"{caption}, {CAPTION_RIGHT}"
    return caption


# ============================================================================
# Synthesis helpers (mono float32, all vectorised)
# ============================================================================


def _samples(duration: float) -> int:
    return max(1, int(duration * SAMPLE_RATE))


def _time(duration: float) -> np.ndarray:
    return np.arange(_samples(duration), dtype=np.float32) / SAMPLE_RATE


def _sweep(freq_hz: np.ndarray) -> np.ndarray:
    """Phase-continuous sine over a per-sample frequency curve."""
    phase = 2.0 * np.pi * np.cumsum(np.asarray(freq_hz, dtype=np.float64)) / SAMPLE_RATE
    return np.sin(phase).astype(np.float32)


def _smooth(signal: np.ndarray, window: int) -> np.ndarray:
    """Boxcar low-pass via a cumulative sum: O(n) and fully vectorised."""
    if window <= 1:
        return signal
    padded = np.concatenate((np.zeros(window, dtype=np.float64), signal.astype(np.float64)))
    running = np.cumsum(padded)
    return ((running[window:] - running[:-window]) / window).astype(np.float32)


def _normalise(signal: np.ndarray, peak: float = 1.0) -> np.ndarray:
    largest = float(np.max(np.abs(signal))) if signal.size else 0.0
    if largest <= 1e-9:
        return signal.astype(np.float32)
    return (signal * (peak / largest)).astype(np.float32)


def _fade_edges(signal: np.ndarray, seconds: float = 0.006) -> np.ndarray:
    """Taper both ends so a one-shot cannot click."""
    n = min(int(seconds * SAMPLE_RATE), signal.size // 2)
    if n <= 0:
        return signal
    ramp = np.linspace(0.0, 1.0, n, dtype=np.float32)
    out = signal.copy()
    out[:n] *= ramp
    out[-n:] *= ramp[::-1]
    return out


def _loopify(signal: np.ndarray, seconds: float = 0.15) -> np.ndarray:
    """Crossfade the tail into the head so a noise bed loops without a seam."""
    n = min(int(seconds * SAMPLE_RATE), signal.size // 3)
    if n <= 0:
        return signal
    ramp = np.linspace(0.0, 1.0, n, dtype=np.float32)
    head = signal[:n] * ramp + signal[-n:] * ramp[::-1]
    return np.concatenate((head, signal[n:-n])).astype(np.float32)


def _bake_mono(synth: AudioSynth, duration: float) -> np.ndarray:
    """Render an AudioSynth to a mono buffer this module can pan itself."""
    clip = synth.bake(duration, sample_rate=SAMPLE_RATE, channels=1)
    return np.asarray(clip.backend_data, dtype=np.float32)


def _stereo_clip(mono: np.ndarray, pan: float, name: str) -> AudioClip:
    """Interleave *mono* into a stereo clip at *pan*, matching AudioSynth's law."""
    left = mono * min(1.0, 1.0 - pan)
    right = mono * min(1.0, 1.0 + pan)
    interleaved = np.empty(mono.size * 2, dtype=np.float32)
    interleaved[0::2] = left
    interleaved[1::2] = right
    np.clip(interleaved, -1.0, 1.0, out=interleaved)
    return AudioClip.from_pcm(interleaved, sample_rate=SAMPLE_RATE, channels=2, name=name)


# ============================================================================
# Cue synthesis, one function per cue
# ============================================================================


def _generator_hum() -> np.ndarray:
    """A fat mains drone. 55 and 56 Hz beat once a second, so 2 s loops seamlessly."""
    synth = AudioSynth()
    synth.add(Oscillator.sine(55.0), gain=0.45)
    synth.add(Oscillator.sine(56.0), gain=0.30)
    synth.add(Oscillator.sine(110.0), gain=0.18)
    synth.add(Oscillator.triangle(220.0), gain=0.06)
    return _normalise(_bake_mono(synth, CUES["generator_hum"].duration), 0.9)


def _hull_creak() -> np.ndarray:
    """Metal under pressure: a smoothed noise bed with two slow tonal groans."""
    duration = CUES["hull_creak"].duration
    t = _time(duration)
    rng = np.random.default_rng(NOISE_SEED)
    bed = _smooth(rng.standard_normal(t.size).astype(np.float32), 260) * 5.0
    groan = 0.35 * np.sin(2.0 * np.pi * 47.0 * t) * (0.55 + 0.45 * np.sin(2.0 * np.pi * 0.25 * t))
    ticks = np.zeros(t.size, dtype=np.float32)
    for start_s, freq in ((0.9, 131.0), (2.6, 97.0)):
        start = int(start_s * SAMPLE_RATE)
        span = int(0.18 * SAMPLE_RATE)
        local = t[:span]
        ticks[start : start + span] += 0.4 * np.sin(2.0 * np.pi * freq * local) * np.exp(-local / 0.045)
    return _loopify(_normalise(bed + groan + ticks, 0.75))


def _heartbeat() -> np.ndarray:
    """Two chest thumps a second: a falling sub sweep plus a soft transient."""
    duration = CUES["heartbeat"].duration
    out = np.zeros(_samples(duration), dtype=np.float32)
    rng = np.random.default_rng(NOISE_SEED + 1)
    span = int(0.22 * SAMPLE_RATE)
    local = _time(0.22)
    for start_s, level in ((0.0, 1.0), (0.28, 0.72)):
        thump = _sweep(np.linspace(64.0, 34.0, span, dtype=np.float32)) * np.exp(-local / 0.055)
        knock = _smooth(rng.standard_normal(span).astype(np.float32), 120) * 3.0 * np.exp(-local / 0.012)
        start = int(start_s * SAMPLE_RATE)
        out[start : start + span] += level * (thump + 0.5 * knock)
    return _normalise(out, 0.85)


def _breathing() -> np.ndarray:
    """One breath cycle under a failing scrubber: inhale, hold, exhale, gap."""
    duration = CUES["breathing"].duration
    t = _time(duration)
    rng = np.random.default_rng(NOISE_SEED + 2)
    inhale = np.clip((t - 0.15) / 1.45, 0.0, 1.0) * np.clip((1.75 - t) / 0.35, 0.0, 1.0)
    exhale = np.clip((t - 2.05) / 0.25, 0.0, 1.0) * np.clip((3.6 - t) / 1.4, 0.0, 1.0)
    breath = _smooth(rng.standard_normal(t.size).astype(np.float32), 34) * 5.0
    voiced = 0.18 * np.sin(2.0 * np.pi * 187.0 * t)
    return _loopify(_normalise(breath * (inhale + 0.85 * exhale) + voiced * exhale, 0.8), 0.2)


def _klaxon() -> np.ndarray:
    """Two-tone alarm: a high slot and a low slot, gated so the tones separate."""
    duration = CUES["klaxon"].duration
    t = _time(duration)
    slot = np.floor(t / KLAXON_SLOT_S).astype(np.int32)
    freq = np.where(slot % 2 == 0, KLAXON_HIGH_HZ, KLAXON_LOW_HZ).astype(np.float32)
    phase = 2.0 * np.pi * np.cumsum(freq.astype(np.float64)) / SAMPLE_RATE
    tone = np.sin(phase) + 0.28 * np.sin(2.0 * phase) + 0.12 * np.sin(3.0 * phase)
    within = (t % KLAXON_SLOT_S) / KLAXON_SLOT_S
    gate = np.clip(np.minimum(within, 1.0 - within) / 0.08, 0.0, 1.0)
    return _normalise(tone.astype(np.float32) * gate.astype(np.float32), 0.95)


def _sonar_ping() -> np.ndarray:
    """A descending chirp and three decaying returns: something is looking for you."""
    duration = CUES["sonar_ping"].duration
    out = np.zeros(_samples(duration), dtype=np.float32)
    span = int(0.12 * SAMPLE_RATE)
    local = _time(0.12)
    ping = _sweep(np.linspace(1900.0, 950.0, span, dtype=np.float32)) * np.exp(-local / 0.04)
    for index, level in enumerate((1.0, 0.45, 0.2, 0.09)):
        start = int(index * 0.28 * SAMPLE_RATE)
        out[start : start + span] += ping * level
    return _normalise(out, 0.9)


def _groan() -> np.ndarray:
    """The T-60 sub-bass: a slow swell falling from 30 Hz to 18 Hz."""
    duration = CUES["groan"].duration
    t = _time(duration)
    rng = np.random.default_rng(NOISE_SEED + 3)
    freq = np.linspace(30.0, 18.0, t.size, dtype=np.float32)
    phase = 2.0 * np.pi * np.cumsum(freq.astype(np.float64)) / SAMPLE_RATE
    body = np.sin(phase) + 0.35 * np.sin(2.0 * phase) + 0.12 * np.sin(3.0 * phase)
    rumble = _smooth(rng.standard_normal(t.size).astype(np.float32), 420) * 4.0
    swell = np.sin(np.pi * t / duration) ** 1.4
    return _fade_edges(_normalise((body.astype(np.float32) + 0.35 * rumble) * swell, 0.95))


def _weapon_fire() -> np.ndarray:
    """A short bright zap: warm gold in the ear as well as on screen."""
    duration = CUES["weapon_fire"].duration
    synth = AudioSynth()
    synth.add(Oscillator.saw(720.0), envelope=ADSR(attack=0.001, decay=0.05, sustain=0.0, release=0.03), gain=0.5)
    synth.add(Oscillator.sine(1440.0), envelope=Exponential(start=1.0, end=0.02, power=2.0), gain=0.3)
    synth.add(Oscillator.noise.white(NOISE_SEED + 4), envelope=Exponential(start=0.6, end=0.01, power=3.0), gain=0.2)
    return _fade_edges(_normalise(_bake_mono(synth, duration), 0.9), 0.003)


def _kill() -> np.ndarray:
    """The ladder rung: a clean two-tone chime the combo pitches upward."""
    duration = CUES["kill"].duration
    synth = AudioSynth()
    synth.add(Oscillator.sine(523.0), envelope=Exponential(start=1.0, end=0.01, power=2.0), gain=0.55)
    synth.add(Oscillator.triangle(784.0), envelope=Exponential(start=0.7, end=0.01, power=2.6), gain=0.3)
    synth.add(Oscillator.sine(1046.0), envelope=Exponential(start=0.35, end=0.01, power=3.4), gain=0.15)
    return _fade_edges(_normalise(_bake_mono(synth, duration), 0.9), 0.004)


def _spool_stutter() -> np.ndarray:
    """The warp ring losing its grip: a falling sweep chopped six times."""
    duration = CUES["spool_stutter"].duration
    t = _time(duration)
    freq = np.linspace(900.0, 300.0, t.size, dtype=np.float32)
    tone = _sweep(freq)
    chop = (np.sin(2.0 * np.pi * 17.0 * t) > -0.2).astype(np.float32)
    return _fade_edges(_normalise(tone * chop * np.exp(-t / 0.22), 0.9))


def _spawn_chevron() -> np.ndarray:
    """The edge chevron: a rising chirp that tells you which way to look."""
    duration = CUES["spawn_chevron"].duration
    t = _time(duration)
    freq = np.linspace(420.0, 1420.0, t.size, dtype=np.float32)
    tone = _sweep(freq) + 0.25 * _sweep(freq * 2.0)
    return _fade_edges(_normalise(tone * np.exp(-t / 0.11), 0.9))


def _mortar_whistle() -> np.ndarray:
    """The incoming-shell scream: a falling whistle that swells as it drops."""
    duration = CUES["mortar_whistle"].duration
    t = _time(duration)
    fall = np.linspace(1350.0, 460.0, t.size, dtype=np.float32)
    vibrato = 1.0 + 0.014 * np.sin(2.0 * np.pi * 9.0 * t)
    freq = fall * vibrato.astype(np.float32)
    tone = _sweep(freq) + 0.3 * _sweep(freq * 2.0)
    swell = np.clip(t / (duration * 0.8), 0.0, 1.0) ** 1.5
    return _fade_edges(_normalise(tone * (0.3 + 0.7 * swell.astype(np.float32)), 0.9))


def _signature_locked() -> np.ndarray:
    """The stamp under SIGNATURE LOCKED: a low, final two-note fall."""
    duration = CUES["signature_locked"].duration
    synth = AudioSynth()
    synth.add(Oscillator.sine(110.0), envelope=ADSR(attack=0.004, decay=0.3, sustain=0.3, release=0.4), gain=0.5)
    synth.add(Oscillator.sine(73.0), envelope=Linear(start=1.0, end=0.0), gain=0.35)
    synth.add(Oscillator.triangle(220.0), envelope=Exponential(start=0.5, end=0.01, power=2.0), gain=0.2)
    return _fade_edges(_normalise(_bake_mono(synth, duration), 0.95))


def _tear_in() -> np.ndarray:
    """T-0: the sector opens. A sub plunge under a wall of rising noise."""
    duration = CUES["tear_in"].duration
    t = _time(duration)
    rng = np.random.default_rng(NOISE_SEED + 5)
    plunge = _sweep(np.linspace(210.0, 32.0, t.size, dtype=np.float32))
    tear = _smooth(rng.standard_normal(t.size).astype(np.float32), 60) * 4.0
    rise = np.clip(t / (duration * 0.7), 0.0, 1.0) ** 2.0
    return _fade_edges(_normalise(plunge * (1.0 - 0.4 * rise) + tear * rise, 0.98))


def _lantern_burn() -> np.ndarray:
    """The lantern opening on the hull: a hard onset into a searing wash.

    The burn does not borrow the klaxon, which is the sound of the ship's own
    alarm and says nothing about what is doing the burning. So it is a sound
    with no alarm in it at all: a bright band of noise that arrives at once and
    then holds and decays, under a high pair of tones beating against each
    other. Nothing in the mix rises the way this does, which is the point: the
    caption track names the animal instead of reporting a klaxon.
    """
    duration = CUES["lantern_burn"].duration
    t = _time(duration)
    rng = np.random.default_rng(NOISE_SEED + 6)
    # The wash: broadband noise smoothed just enough to lose its grain, with an
    # onset short enough to read as a beam that was already on when it arrived.
    wash = _smooth(rng.standard_normal(t.size).astype(np.float32), 12) * 3.0
    onset = np.clip(t / 0.015, 0.0, 1.0).astype(np.float32)
    decay = np.exp(-t / (duration * 0.42)).astype(np.float32)
    # The two tones, a shade apart so they beat rather than harmonise: light
    # that hurts, not a chord.
    shimmer = _sweep(np.full(t.size, 1580.0, dtype=np.float32)) + _sweep(np.full(t.size, 1633.0, dtype=np.float32))
    return _fade_edges(_normalise((wash + 0.35 * shimmer) * onset * decay, 0.97))


_BUILDERS = {
    "generator_hum": _generator_hum,
    "hull_creak": _hull_creak,
    "heartbeat": _heartbeat,
    "breathing": _breathing,
    "klaxon": _klaxon,
    "sonar_ping": _sonar_ping,
    "groan": _groan,
    "weapon_fire": _weapon_fire,
    "kill": _kill,
    "spool_stutter": _spool_stutter,
    "spawn_chevron": _spawn_chevron,
    "mortar_whistle": _mortar_whistle,
    "signature_locked": _signature_locked,
    "tear_in": _tear_in,
    "lantern_burn": _lantern_burn,
}


# ============================================================================
# AudioDirector
# ============================================================================


class AudioDirector(Node):
    """The run's single audio authority: singleton ``Services.AUDIO``.

    Bakes the cue bank on entry, plays one-shots through a round-robin voice
    pool, holds the looping beds open, and reconciles the mix whenever the power
    state, the oxygen state or the hunter ladder moves.

    Cue ids are a stable contract shared with the HUD's subtitle line:
    ``generator_hum``, ``hull_creak``, ``heartbeat``, ``breathing``, ``klaxon``,
    ``sonar_ping``, ``groan``, ``weapon_fire``, ``kill``, ``spool_stutter``,
    ``spawn_chevron``, ``mortar_whistle``, ``signature_locked``, ``tear_in``.
    Every play emits :attr:`audio_cue` with the cue id and its caption, so
    nothing this module does is audible only.

    The three mixer sliders arrive through :meth:`set_bus_volumes` and are
    applied on top of the authored per-cue gains, never into them: the cue table
    keeps the balance the mix was tuned to and the player scales the result.

    Wiring is deferred through :class:`~shrike.power.SignalWiring`: the hunter,
    the wave composer and the socketed generator all mount long after the
    director does, and the generator comes and goes with the socket.
    """

    #: (cue_id, caption). The HUD's caption track is the only consumer that must
    #: exist; anything wanting cue-accurate reactions may connect too.
    audio_cue = Signal(str, str)

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.generator_running = False
        self.silent_running = False
        self.low_oxygen = False
        self.ducked = False
        self.signature = 0.0
        self.kill_combo = 0
        self.last_cue: str | None = None
        self.last_pan = 0.0
        self._mono: dict[str, np.ndarray] = {}
        self._clips: dict[tuple[str, float], AudioClip] = {}
        self._voices: list[AudioPlayer] = []
        self._voice_index = 0
        self._loops: dict[str, AudioPlayer] = {}
        self._combo_timer = 0.0
        self._ping_timer = 0.0
        self._wiring = SignalWiring(self)
        self._lowpass: LowPassFilter | None = None
        self._music_base_db: float | None = None
        #: The player's three sliders as linear fractions of full volume.
        self._bus_gain: dict[str, float] = {BUS_MASTER: 1.0, BUS_SFX: 1.0, BUS_MUSIC: 1.0}

    # ------------------------------------------------------------------
    # Lifecycle
    # ------------------------------------------------------------------

    def on_ready(self):
        self._bake_bank()
        for index in range(ONE_SHOT_VOICES):
            self._voices.append(self.add_child(AudioPlayer(name=f"Voice{index}", bus=BUS_SFX)))
        for cue_id in LOOP_CUES:
            cue = CUES[cue_id]
            self._loops[cue_id] = self.add_child(
                AudioPlayer(
                    name=cue_id.title().replace("_", ""),
                    stream=self._clip(cue_id, 0.0),
                    loop=True,
                    bus=cue.bus,
                    volume_db=cue.gain_db,
                )
            )
        for signal_name, handler in (
            (SignalNames.GENERATOR_CHANGED, self._on_generator_changed),
            (SignalNames.SILENT_RUNNING_CHANGED, self._on_silent_running_changed),
            (SignalNames.O2_CHANGED, self._on_o2_changed),
            (SignalNames.SIGNATURE_CHANGED, self._on_signature_changed),
            (SignalNames.SIGNATURE_LOCKED, self._on_signature_locked),
            (SignalNames.ENEMY_KILLED, self._on_enemy_killed),
            (SignalNames.WEAPON_FIRED, self._on_weapon_fired),
            (SignalNames.WAVE_SPAWNED, self._on_wave_spawned),
            (SignalNames.SHELL_LAUNCHED, self._on_shell_launched),
            (SignalNames.HUNTER_TELEGRAPH, self._on_hunter_telegraph),
            (SignalNames.HUNTER_DEPARTED, self._on_hunter_departed),
            (SignalNames.WARP_SPOOL_INTERRUPTED, self._on_spool_interrupted),
        ):
            self._wiring.want(signal_name, handler)
        self._wiring.sweep()

    def on_exit_tree(self):
        """Hand the shared bus layout back exactly as it was found."""
        self._release_master_lowpass()
        if self._music_base_db is not None:
            layout = AudioBusLayout.get_default()
            if layout.has_bus(BUS_MUSIC):
                layout.get_bus(BUS_MUSIC).volume_db = self._music_base_db
            self._music_base_db = None

    def on_update(self, dt: float):
        self._wiring.poll(dt)
        if self._combo_timer > 0.0:
            self._combo_timer -= dt
            if self._combo_timer <= 0.0:
                self.kill_combo = 0
        self._tick_sonar(dt)

    # ------------------------------------------------------------------
    # Public surface
    # ------------------------------------------------------------------

    def play(self, cue: str, *, position: Vec3 | None = None) -> None:
        """Play *cue*, panned toward *position* when one is given.

        Loop cues start their bed; every cue emits its subtitle glyph.
        """
        spec = self._spec(cue)
        pan = self._pan_for(position)
        if spec.loop:
            self._set_loop(cue, True, pan=pan)
            return
        if cue == "kill":
            self._advance_kill_combo()
        player = self._voices[self._voice_index]
        self._voice_index = (self._voice_index + 1) % len(self._voices)
        player.stop()
        player.stream = self._clip(cue, pan)
        player.volume_db = self._volume_for(cue)
        player.pitch_scale = self.kill_pitch() if cue == "kill" else 1.0
        player.play()
        self._announce(cue, pan)

    def stop(self, cue: str) -> None:
        """Stop a looping cue. One-shots retire themselves."""
        if self._spec(cue).loop:
            self._set_loop(cue, False)

    def set_power_state(self, *, generator: bool, silent: bool) -> None:
        """Set the two power flags the mix is built on and reconcile it."""
        self.generator_running = bool(generator)
        self.silent_running = bool(silent)
        self._reconcile()

    def duck_to_heartbeat(self, active: bool) -> None:
        """Pull the bed down and let the heartbeat through (the T-30 duck)."""
        self.ducked = bool(active)
        self._reconcile()

    def set_bus_volumes(self, master: float = 1.0, sfx: float = 1.0, music: float = 1.0) -> None:
        """Set the player's three mixer sliders, as fractions from 0 to 1.

        The sliders are a trim laid over the authored mix rather than a rewrite
        of it: :data:`CUES` keeps the gains the balance pass tuned, and every
        voice's ``volume_db`` is the cue's own gain plus this trim. A slider at
        zero is :data:`BUS_SILENT_DB`, which is silence at any master setting.

        ``master`` multiplies the other two, so the effects bed answers both its
        own slider and the master, and so does the music bus.
        """
        self._bus_gain[BUS_MASTER] = _clamp_gain(master)
        self._bus_gain[BUS_SFX] = _clamp_gain(sfx)
        self._bus_gain[BUS_MUSIC] = _clamp_gain(music)
        self._reconcile()

    @property
    def bus_volumes(self) -> tuple[float, float, float]:
        """The three sliders as ``(master, sfx, music)``, for the settings screen."""
        return (self._bus_gain[BUS_MASTER], self._bus_gain[BUS_SFX], self._bus_gain[BUS_MUSIC])

    def bus_trim_db(self, bus: str) -> float:
        """Decibels the sliders add to anything playing on *bus*."""
        return _gain_db(self._bus_gain[BUS_MASTER] * self._bus_gain.get(bus, 1.0))

    @property
    def mix_state(self) -> str:
        """The mix in one word, most urgent first.

        ``"ducked"`` (the heartbeat has the floor), ``"silent"`` (the whole mix
        is low-passed to creaks), ``"strained"`` (low oxygen, breathing in
        front), ``"hum"`` (the generator's room tone is the loudest thing) or
        ``"clear"``.
        """
        if self.ducked:
            return "ducked"
        if self.silent_running:
            return "silent"
        if self.low_oxygen:
            return "strained"
        if self.generator_running:
            return "hum"
        return "clear"

    @property
    def master_cutoff_hz(self) -> float | None:
        """The active whole-mix low-pass cutoff, or None when the mix is open."""
        cutoffs = []
        if self.silent_running:
            cutoffs.append(SILENT_RUNNING_CUTOFF_HZ)
        if self.low_oxygen:
            cutoffs.append(LOW_O2_CUTOFF_HZ)
        return min(cutoffs) if cutoffs else None

    def kill_pitch(self) -> float:
        """Pitch multiplier for the next kill cue: a semitone per combo rung."""
        steps = min(KILL_LADDER_MAX_STEPS, max(0, self.kill_combo - 1))
        return min(2.0, KILL_LADDER_SEMITONE**steps)

    def is_playing(self, cue: str) -> bool:
        """True while a looping cue's bed is open."""
        player = self._loops.get(cue)
        return player is not None and player.is_playing()

    # ------------------------------------------------------------------
    # Cue bank
    # ------------------------------------------------------------------

    def _bake_bank(self) -> None:
        for cue_id, build in _BUILDERS.items():
            self._mono[cue_id] = build()
            self._clips[(cue_id, 0.0)] = _stereo_clip(self._mono[cue_id], 0.0, cue_id)

    def _clip(self, cue: str, pan: float) -> AudioClip:
        """The clip for *cue* at *pan*, baking the panned variant on first use."""
        key = (cue, pan)
        clip = self._clips.get(key)
        if clip is None:
            clip = _stereo_clip(self._mono[cue], pan, f"{cue}@{pan:+.1f}")
            self._clips[key] = clip
        return clip

    @staticmethod
    def _spec(cue: str) -> Cue:
        spec = CUES.get(cue)
        if spec is None:
            raise KeyError(f"unknown audio cue {cue!r}; known cues: {', '.join(sorted(CUES))}")
        return spec

    # ------------------------------------------------------------------
    # Mix state machine
    # ------------------------------------------------------------------

    def _reconcile(self) -> None:
        self._apply_master_lowpass()
        self._set_loop("generator_hum", self.generator_running)
        self._set_loop("hull_creak", self.silent_running)
        self._set_loop("breathing", self.low_oxygen)
        self._set_loop("heartbeat", self.ducked)
        for cue_id, player in self._loops.items():
            player.volume_db = self._volume_for(cue_id)
        self._apply_music_duck()

    def _volume_for(self, cue: str) -> float:
        """The volume a voice playing *cue* takes: authored gain plus the trims.

        The order matters. The cue's own gain is the mix as tuned, the duck is
        the game leaning on it, and the player's slider is last, so a pilot who
        pulls the effects down does not flatten the ramp that makes the hum a
        warning.
        """
        spec = CUES[cue]
        if cue == "generator_hum":
            fraction = min(1.0, max(0.0, self.signature / balance.SIGNATURE_MAX))
            level = HUM_QUIET_DB + (HUM_LOUD_DB - HUM_QUIET_DB) * fraction
        else:
            level = spec.gain_db
        if self.ducked and cue in AMBIENCE_CUES:
            level += DUCK_AMBIENCE_DB
        return level + self.bus_trim_db(spec.bus)

    def _apply_music_duck(self) -> None:
        layout = AudioBusLayout.get_default()
        if not layout.has_bus(BUS_MUSIC):
            return
        music = layout.get_bus(BUS_MUSIC)
        if self._music_base_db is None:
            self._music_base_db = float(music.volume_db)
        duck = DUCK_MUSIC_DB if self.ducked else 0.0
        music.volume_db = self._music_base_db + duck + self.bus_trim_db(BUS_MUSIC)

    def _apply_master_lowpass(self) -> None:
        cutoff = self.master_cutoff_hz
        if cutoff is None:
            self._release_master_lowpass()
            return
        if self._lowpass is None:
            self._lowpass = LowPassFilter(cutoff_hz=cutoff, q=MASTER_LOWPASS_Q)
            AudioBusLayout.get_default().get_bus(BUS_MASTER).add_effect(self._lowpass)
        else:
            self._lowpass.cutoff_hz = cutoff

    def _release_master_lowpass(self) -> None:
        if self._lowpass is None:
            return
        layout = AudioBusLayout.get_default()
        if layout.has_bus(BUS_MASTER):
            layout.get_bus(BUS_MASTER).remove_effect(self._lowpass)
        self._lowpass = None

    def _set_loop(self, cue: str, active: bool, *, pan: float = 0.0) -> None:
        player = self._loops.get(cue)
        if player is None:
            return
        if active and not player.is_playing():
            player.volume_db = self._volume_for(cue)
            player.play()
            self._announce(cue, pan)
        elif not active and player.is_playing():
            player.stop()

    def _announce(self, cue: str, pan: float) -> None:
        self.last_cue = cue
        self.last_pan = pan
        self.audio_cue.emit(cue, subtitle(cue, pan))

    # ------------------------------------------------------------------
    # Spatialisation and timers
    # ------------------------------------------------------------------

    def _pan_for(self, position: Vec3 | None) -> float:
        if position is None:
            return 0.0
        offset = (float(position.x) - self._listener_x()) / PAN_FULL_WIDTH
        offset = max(-1.0, min(1.0, offset))
        return min(PAN_BUCKETS, key=lambda bucket: abs(bucket - offset))

    def _listener_x(self) -> float:
        ship = self.tree.first(Groups.SHIP) if self.tree is not None else None
        return float(ship.position.x) if ship is not None else 0.0

    def _advance_kill_combo(self) -> None:
        self.kill_combo = self.kill_combo + 1 if self._combo_timer > 0.0 else 1
        self._combo_timer = balance.KILL_COMBO_WINDOW_S

    def _tick_sonar(self, dt: float) -> None:
        """While the mix is silent, the Shrike's own ping is what fills it."""
        hunter = self.tree.first(Groups.HUNTER) if self.silent_running else None
        if hunter is None:
            self._ping_timer = 0.0
            return
        self._ping_timer -= dt
        if self._ping_timer <= 0.0:
            self._ping_timer = SONAR_PING_INTERVAL_S
            self.play("sonar_ping", position=hunter.position)

    # ------------------------------------------------------------------
    # Signal handlers
    # ------------------------------------------------------------------

    def _on_generator_changed(self, running: bool) -> None:
        self.set_power_state(generator=bool(running), silent=self.silent_running)

    def _on_silent_running_changed(self, active: bool) -> None:
        self.set_power_state(generator=self.generator_running, silent=bool(active))

    def _on_o2_changed(self, current: float, maximum: float) -> None:
        seconds_left = float(current) / balance.O2_DRAIN_PER_S
        low = seconds_left < balance.O2_LOW_WARNING_SECONDS
        if low != self.low_oxygen:
            self.low_oxygen = low
            self._reconcile()

    def _on_signature_changed(self, value: float) -> None:
        self.signature = float(value)
        hum = self._loops.get("generator_hum")
        if hum is not None:
            hum.volume_db = self._volume_for("generator_hum")

    def _on_signature_locked(self) -> None:
        self.play("signature_locked")

    def _on_enemy_killed(self, archetype: str, position: Vec3, elite: bool) -> None:
        self.play("kill", position=position)

    def _on_weapon_fired(self, weapon_id: str) -> None:
        self.play("weapon_fire")

    def _on_wave_spawned(self, count: int) -> None:
        self.play("spawn_chevron")

    def _on_shell_launched(self, origin: Vec3, flight: float) -> None:
        """A bombardier shell is in the air; whistle from the tube that fired it."""
        self.play("mortar_whistle", position=origin)

    def _on_hunter_telegraph(self, stage: str) -> None:
        cue = TELEGRAPH_CUES.get(stage)
        if cue is None:
            return
        self.play(cue)
        if stage == "t30":
            self.duck_to_heartbeat(True)

    def _on_hunter_departed(self) -> None:
        self.duck_to_heartbeat(False)

    def _on_spool_interrupted(self, added_seconds: float) -> None:
        self.play("spool_stutter")


__all__ = [
    "AudioDirector",
    "BUS_MASTER",
    "BUS_MUSIC",
    "BUS_SFX",
    "BUS_SILENT_DB",
    "CUES",
    "Cue",
    "LOOP_CUES",
    "TELEGRAPH_CUES",
    "subtitle",
]