@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/audio/audio.d.ts

@@ -0,0 +1,733 @@
+import { type OccludableVoice, type OcclusionOptions } from './occlusion.js';
+import type { Send } from './send.js';
+import { type SpriteSchedule, type SpriteSheet } from './sprites.js';
+import { type OfflineContextFactory, type SoundSpec } from './synth.js';
+import { AudioZones } from './zones.js';
+export declare const BUS_NAMES: readonly ['master', 'music', 'sfx', 'ui'];
+export type BusName = (typeof BUS_NAMES)[number];
+/** Buses a sound can play on (everything feeds master). */
+export type OutputBus = Exclude<BusName, 'master'>;
+export interface BusSettings {
+    /** Slider position 0..1 (mapped to gain with a squared curve). */
+    volume: number;
+    muted: boolean;
+}
+export type MixerSettings = Record<BusName, BusSettings>;
+export declare const DEFAULT_MIXER: Readonly<MixerSettings>;
+/** Clamp and fill gaps so any (possibly hand-edited) object becomes valid settings. */
+export declare function sanitizeMixer(input: unknown): MixerSettings;
+/** Effective linear gain for a bus. */
+export declare function busGain(s: BusSettings): number;
+/**
+ * - `locked`: waiting for a user gesture (or no context yet).
+ * - `running`: playing.
+ * - `suspended`: unlocked but paused (tab hidden or `suspend()`).
+ * - `unavailable`: no WebAudio in this browser; everything is a silent no-op.
+ */
+export type AudioState = 'locked' | 'running' | 'suspended' | 'unavailable';
+export interface AudioPlayOptions {
+    /** Default `sfx` for `play`, `music` for `loop`. */
+    bus?: OutputBus;
+    /** Linear gain on top of the bus. Default 1. */
+    gain?: number;
+    /** Playback rate (1 = original, 2 = octave up). Default 1. */
+    rate?: number;
+    /** Cents. */
+    detune?: number;
+    /**
+     * 2D stereo position, -1 (left) .. 1 (right), through a `StereoPannerNode`. The shorthand
+     * for a flat game (a sound from the left of the board). Ignored when `at` is set.
+     */
+    pan?: number;
+    /**
+     * World position `[x, y, z]` of the emitter. Routes the voice through a pooled `PannerNode`
+     * (distance and direction relative to `audio.listener`); move it with `Voice.setPosition`.
+     * Read once at play time (the array is not kept). Takes precedence over `pan`.
+     */
+    at?: ArrayLike<number>;
+    /** How a voice with `at` attenuates and pans. Ignored without `at`. */
+    spatial?: SpatialOptions;
+    /** Seconds from now. */
+    delay?: number;
+    /** Seconds to fade in. Default 0 for one-shots, 0.5 for loops. */
+    fadeIn?: number;
+}
+/** A playing (or pending) sound. Every method is safe to call at any time. */
+export interface Voice {
+    /** Stop, optionally fading out over `fade` seconds. */
+    stop(fade?: number): void;
+    setGain(gain: number, ramp?: number): void;
+    setRate(rate: number, ramp?: number): void;
+    /**
+     * Move a spatial voice (one played with `at`) to world `(x, y, z)`. Writes the voice's own
+     * `PannerNode` in place, so it is safe to call every frame. No-op on a non-spatial voice;
+     * on a voice still waiting to start, the position is kept and applied at start.
+     */
+    setPosition(x: number, y: number, z: number): void;
+    /** Point a spatial voice's cone (`spatial.cone`) along `(x, y, z)`. Same rules as `setPosition`. */
+    setDirection(x: number, y: number, z: number): void;
+    /**
+     * Make a spatial voice read its position from `target.world` (a 3×4 row-major world matrix,
+     * translation at floats 3, 7 and 11, such as a `Transform`'s) on every `audio.update(dt)`,
+     * so the game stops copying positions. `null` stops following. No-op on a non-spatial voice.
+     */
+    follow(target: {
+        readonly world: ArrayLike<number>;
+    } | null): void;
+    /**
+     * Route a copy of this voice into an effect: a parallel path from the voice's output (after
+     * its gain and panner) through a send gain of `amount` into `input`, a `Send` (its `input`)
+     * or any `AudioNode`. The dry path to the bus is untouched. Calling again with the same
+     * `input` ramps the amount over `ramp` seconds (default 0.05); `amount` 0 disconnects it and
+     * frees the gain. At most `MAX_VOICE_SENDS` (4) inputs per voice; the fifth throws a
+     * `RangeError`. Torn down with the voice. No-op on an inert voice.
+     */
+    sendTo(input: AudioNode | Send, amount: number, ramp?: number): void;
+    /**
+     * Insert one pooled `BiquadFilterNode` of `kind` between the voice's gain and its panner or
+     * bus (ws/audio-4), ramping `cutoff` (Hz) and `q` over `ramp` seconds (default 0.05); calling
+     * again retunes it, `null` removes it and returns the node to the pool. Independent of the
+     * occlusion lowpass: an occluded voice with a filter has two biquads in series. No-op on an
+     * inert voice; set before start, it is applied at start.
+     */
+    filter(kind: VoiceFilterKind | null, opts?: VoiceFilterOptions): void;
+    /** World position of a spatial voice as last set or followed (zeros on a non-spatial voice). */
+    readonly position: ArrayLike<number>;
+    readonly playing: boolean;
+    /** Live sends (`sendTo` inputs with a non-zero amount). */
+    readonly sendCount: number;
+    /** The last answer of `audio.occlusion.probe` for this voice, 0 clear .. 1 occluded (0 when unprobed). */
+    readonly occlusion: number;
+    /**
+     * The Doppler multiplier on the playback rate as of the last `audio.update` (1 without
+     * `spatial.doppler`, and on every voice the mixer did not start; diagnostics).
+     */
+    readonly doppler: number;
+}
+/** `Voice.filter` kinds (the `BiquadFilterNode` types a voice offers). */
+export type VoiceFilterKind = 'lowpass' | 'highpass' | 'bandpass';
+export interface VoiceFilterOptions {
+    /** Hz. Default 1000. */
+    cutoff?: number;
+    /** Resonance. Default 1. */
+    q?: number;
+    /** Seconds the cutoff and Q ramp over. Default 0.05. */
+    ramp?: number;
+}
+/** m/s, the Doppler reference (`SpatialOptions.doppler`). */
+export declare const SPEED_OF_SOUND = 343;
+/** m/s: a move faster than this between two `update`s is a teleport, not a velocity. */
+export declare const DEFAULT_MAX_DOPPLER_SPEED = 100;
+/** Sends one voice can hold at once (`Voice.sendTo`). */
+export declare const MAX_VOICE_SENDS = 4;
+/** `stopAll` as an options object (the positional `stopAll(fade?, bus?)` form still works). */
+export interface StopAllOptions {
+    /** Seconds to fade out. Default 0. */
+    fade?: number;
+    /** Only this bus. */
+    bus?: OutputBus;
+    /** Buses left playing, e.g. `['music']` to keep the score through a scene change. */
+    except?: readonly BusName[];
+}
+/** `audio.pause` options. */
+export interface PauseOptions {
+    /** Buses that keep playing. Default `['ui']` (menu clicks stay audible). `master` never ramps. */
+    keep?: readonly OutputBus[];
+}
+/**
+ * Internal: write `value` to an AudioParam as a linear ramp over `ramp` seconds from `t`,
+ * cancelling what was scheduled (a step when `ramp` is 0).
+ */
+export declare function rampParamTo(param: AudioParam, value: number, t: number, ramp: number): void;
+/**
+ * Internal: the parallel sends behind `Voice.sendTo`, one per voice, shared by the mixer's own
+ * voices and music stems. `attach` names the node to tap once it exists; sends set before that
+ * are built then. Each live send is one `GainNode`: tap → gain → input.
+ */
+export declare class VoiceSends {
+    private readonly taps;
+    private from;
+    private ctx;
+    /** True once `attach` ran (the sends are in the graph). */
+    get attached(): boolean;
+    /** Live sends. */
+    get count(): number;
+    /** The voice's output node is known: build the sends set so far. */
+    attach(ctx: AudioContext, from: AudioNode): void;
+    /** The voice's output node changed (a filter went in or out): move the taps to `from`. */
+    retarget(from: AudioNode): void;
+    set(target: AudioNode | Send, amount: number, ramp: number): void;
+    private build;
+    private remove;
+    /** Disconnect and drop every send (the voice ended). */
+    dispose(): void;
+}
+/** Anything with a 3×4 world matrix a voice can follow (`Voice.follow`). */
+export interface AudioFollowTarget {
+    readonly world: ArrayLike<number>;
+    /** A counter that moves whenever `world` may have (a `Transform.changed`); lets the follower skip the read. */
+    readonly changed?: number;
+}
+/** Distance model of a spatial voice (`PannerNode.distanceModel`). */
+export type Rolloff = 'linear' | 'inverse' | 'exponential';
+/** Directional emitter: full gain inside `inner`, `outerGain` beyond `outer` (degrees, whole angle). */
+export interface ConeOptions {
+    /** Degrees. Default 360. */
+    inner?: number;
+    /** Degrees. Default 360. */
+    outer?: number;
+    /** Linear gain outside the outer cone. Default 0. */
+    outerGain?: number;
+}
+/** Attenuation and panning of a voice played with `AudioPlayOptions.at`. */
+export interface SpatialOptions {
+    /** Distance (world units) at which attenuation starts. Default 1. */
+    refDistance?: number;
+    /** Distance beyond which the voice gets no quieter. Default 10000. */
+    maxDistance?: number;
+    /** Distance model. Default `'inverse'`. */
+    rolloff?: Rolloff;
+    /** How fast the model attenuates. Default 1 (WebAudio clamps it to 0..1 for `linear`). */
+    rolloffFactor?: number;
+    /** `'equalpower'` (default, cheap) or `'HRTF'` (binaural, for headphones and headsets). */
+    panningModel?: PanningModelType;
+    /** Directional emitter. Omit for an omnidirectional one. */
+    cone?: ConeOptions;
+    /** Cone direction `[x, y, z]`. Default `[1, 0, 0]` (the WebAudio default). */
+    direction?: ArrayLike<number>;
+    /**
+     * Doppler factor (ws/audio-4): 0 (default) off; 1 the textbook shift
+     * `(c - v_listener·n) / (c - v_emitter·n)` with `c = SPEED_OF_SOUND`, applied as a
+     * `playbackRate` multiplier on top of `setRate`. Velocities come from successive
+     * `setPosition` / `follow` and `listener.set` / `fromCamera` calls per `audio.update(dt)`.
+     */
+    doppler?: number;
+    /**
+     * m/s above which a move between two updates counts as a teleport and resets the velocity
+     * instead of chirping. Default `DEFAULT_MAX_DOPPLER_SPEED` (100).
+     */
+    maxDopplerSpeed?: number;
+    /** Probe this voice through `audio.occlusion` (ws/audio-4). Default true when a probe is set. */
+    occlude?: boolean;
+}
+/** Anything with a world→view matrix and an eye position, such as the renderer's `Camera`. */
+export interface CameraLike {
+    /** Column-major world→view matrix (16 numbers). */
+    readonly view: ArrayLike<number>;
+    /** Eye position in world space. */
+    readonly position: ArrayLike<number>;
+}
+/**
+ * Where the ears are: one per `AudioEngine` (`audio.listener`), written to the context's
+ * `AudioListener`. Safe before unlock: the pose is kept and applied when the context exists.
+ * Every method writes in place and allocates nothing, so call `fromCamera` every frame.
+ */
+export declare class SpatialListener {
+    private readonly engine;
+    /** px, py, pz, fx, fy, fz, ux, uy, uz. */
+    private readonly pose;
+    /** Current pose, read-only (change it with `set` or `fromCamera`). */
+    readonly position: ArrayLike<number>;
+    readonly forward: ArrayLike<number>;
+    readonly up: ArrayLike<number>;
+    /** Position at the previous `audio.update`, and the velocity derived from it (m/s). */
+    private readonly prev;
+    private hasPrev;
+    private readonly vel;
+    /** Velocity over the last `audio.update(dt)` (ws/audio-4), read-only; zeros after a teleport. */
+    readonly velocity: ArrayLike<number>;
+    /** m/s above which a move between updates resets the velocity (a teleport). Default 100. */
+    maxSpeed: number;
+    /** Built by `AudioEngine`; reach it as `audio.listener`. */
+    constructor(engine: AudioEngine);
+    /** Place the listener at `position`, facing `forward`, with `up` (default `[0, 1, 0]`). */
+    set(position: ArrayLike<number>, forward: ArrayLike<number>, up?: ArrayLike<number>): void;
+    /**
+     * Follow a camera: position from `camera.position`, forward and up from the view matrix
+     * (forward is minus its third row, up its second; the view looks down -z).
+     */
+    fromCamera(camera: CameraLike): void;
+    /** Internal (`audio.update`): derive the velocity from the move since the last call. */
+    tick(dt: number): void;
+    /** Write the pose to the context's listener (on every change, and when the context is built). */
+    apply(): void;
+}
+type SoundSource = SoundSpec | (() => Promise<AudioBuffer>);
+declare class VoiceImpl implements Voice, OccludableVoice {
+    private readonly engine;
+    readonly loop: boolean;
+    private readonly opts;
+    private readonly onEnd;
+    /** A sprite clip's range, or null for the whole buffer. */
+    private readonly schedule;
+    private src;
+    private gainNode;
+    private stopped;
+    private targetGain;
+    private rate;
+    private ended;
+    private panner;
+    /** The node after the filters (panner or stereo panner), or null when the chain ends at the bus. */
+    private out;
+    /** `out` is connected to the bus (done once; `relink` never breaks that link). */
+    private outWired;
+    private bus_;
+    /** The last node before the bus (gain, filter, panner or stereo panner): what the sends tap. */
+    private tail;
+    private sends;
+    /** `audio.pause` set the playback rate to 0; `rate` keeps the value to restore. */
+    private frozen;
+    /** Emitter position and cone direction (kept for a voice that has not started yet). */
+    private readonly spatial;
+    private readonly pos;
+    private target;
+    /** `target.changed` at the last `syncFollow`; a target without one is read every update. */
+    private followSeen;
+    private dx;
+    private dy;
+    private dz;
+    /** `Voice.filter`: the pooled biquad and what it was last asked for (applied at start). */
+    private userFilter;
+    private userKind;
+    private userCutoff;
+    private userQ;
+    /** Occlusion: the pooled lowpass and the last probe (ws/audio-4). */
+    private occFilter;
+    private occAmount;
+    private occGain;
+    private occApplied;
+    occlusionProbedAt: number;
+    /** Doppler: the previous position per update, and the multiplier on `rate`. */
+    private readonly prevPos;
+    private hasPrev;
+    private dopplerRate;
+    constructor(engine: AudioEngine, loop: boolean, opts: AudioPlayOptions, onEnd: (v: VoiceImpl) => void, 
+    /** A sprite clip's range, or null for the whole buffer. */
+    schedule?: SpriteSchedule | null);
+    get playing(): boolean;
+    get position(): ArrayLike<number>;
+    get started(): boolean;
+    get bus(): OutputBus;
+    get occlusion(): number;
+    /** Internal: a spatial voice `audio.occlusion` may probe (`spatial.occlude` not false). */
+    get occludable(): boolean;
+    /** The Doppler multiplier on `rate` as of the last `audio.update` (1 without `spatial.doppler`; diagnostics). */
+    get doppler(): number;
+    /** Internal: `spatial.doppler` above 0. */
+    get dopplerFactor(): number;
+    /** Create nodes and start. Returns false if it can't (no context). */
+    start(buffer: AudioBuffer): boolean;
+    /**
+     * (Re)wire gain → [user filter] → [occlusion lowpass] → [panner | stereo panner] → bus and
+     * point the sends at the new tail. Only the links that can change are touched.
+     */
+    private relink;
+    filter(kind: VoiceFilterKind | null, o?: VoiceFilterOptions): void;
+    /** Internal (`OcclusionScheduler`): ramp the lowpass and the voice gain to the probe's answer. */
+    applyOcclusion(amount: number, cutoff: number, gain: number, ramp: number): void;
+    /**
+     * Internal (`audio.update`): the emitter's velocity from its move since the last update, and
+     * the Doppler ratio against the listener's, written to `playbackRate` when it changed.
+     */
+    syncDoppler(dt: number, listener: SpatialListener): void;
+    stop(fade?: number): void;
+    sendTo(input: AudioNode | Send, amount: number, ramp?: number): void;
+    /** Live sends (tests, diagnostics). */
+    get sendCount(): number;
+    /** Internal: whether this voice's `playbackRate` accepts 0 (null before it has a source). */
+    rateZeroAllowed(): boolean | null;
+    /** Internal (`audio.pause`): hold the source at rate 0, keeping `rate` for `thawRate`. */
+    freezeRate(ramp: number): void;
+    /** Internal (`audio.unpause`): back to the rate the game set. */
+    thawRate(ramp: number): void;
+    setGain(gain: number, ramp?: number): void;
+    setRate(rate: number, ramp?: number): void;
+    setPosition(x: number, y: number, z: number): void;
+    follow(target: AudioFollowTarget | null): void;
+    /**
+     * Internal: copy the followed matrix's translation into the panner. A target with a
+     * `changed` counter (a `Transform`) is read only when it moved since the last sync.
+     */
+    syncFollow(): void;
+    setDirection(x: number, y: number, z: number): void;
+}
+/** Master limiter (a `DynamicsCompressorNode` between master and the output). */
+export interface LimiterOptions {
+    /** dB. Default -1. */
+    threshold?: number;
+    /** dB. Default 0 (hard knee). */
+    knee?: number;
+    /** Default 20. */
+    ratio?: number;
+    /** Seconds. Default 0.003. */
+    attack?: number;
+    /** Seconds. Default 0.25. */
+    release?: number;
+}
+export declare const DEFAULT_LIMITER: Readonly<Required<LimiterOptions>>;
+/** Shared convolution reverb: per-bus sends into one procedural room, returned to master. */
+export interface ReverbOptions {
+    /** Impulse length in seconds. Default 2. */
+    seconds?: number;
+    /** Tail shape: `(1 - t)^decay`. Higher = shorter, drier. Default 3. */
+    decay?: number;
+    /** Impulse noise seed. Default 1. */
+    seed?: number;
+    /** Wet return level into master (linear). Default 1. */
+    wet?: number;
+    /** Send level per bus (linear, 0 = dry). Default music 0.2, sfx 0.25, ui 0. */
+    sends?: Partial<Record<OutputBus, number>>;
+}
+export declare const DEFAULT_REVERB_SENDS: Readonly<Record<OutputBus, number>>;
+export interface AudioEngineOptions {
+    /** Create the realtime context. Called lazily, inside a user gesture. */
+    createContext?: () => AudioContext;
+    /** Offline renderer factory (tests). */
+    createOffline?: OfflineContextFactory;
+    /** Initial mixer settings (e.g. from a save). */
+    settings?: unknown;
+    /**
+     * Master limiter that catches stacked one-shots before they clip. Default on
+     * (`DEFAULT_LIMITER`); `false` connects master straight to the output.
+     */
+    limiter?: boolean | LimiterOptions;
+    /** Optional shared reverb (off by default). Change later with `setReverb`. */
+    reverb?: ReverbOptions | null;
+}
+export interface AttachAudioOptions {
+    /** Where to listen for the unlocking gesture. Default `window`. */
+    target?: EventTarget;
+    /** Suspend while the tab is hidden. Default true. */
+    pauseWhenHidden?: boolean;
+}
+export declare class AudioEngine {
+    private ctx;
+    private _state;
+    private buses;
+    private _settings;
+    private readonly sounds;
+    private readonly deferred;
+    private readonly active;
+    private readonly stateListeners;
+    private readonly settingsListeners;
+    private readonly createContext;
+    private readonly createOffline;
+    private detachFns;
+    /** Gesture listeners: armed while audio should run but the browser won't let it. */
+    private gestureTarget;
+    private gesturesArmed;
+    private userSuspended;
+    private hidden;
+    private _halted;
+    private readonly limiterOpts;
+    private limiterNode;
+    private reverbOpts;
+    /** The base sends (what the game set); the zones add `zoneSends` on top (`max`). */
+    private reverbSends;
+    private readonly zoneSends;
+    private readonly effectiveSends;
+    private readonly appliedSends;
+    private reverbNodes;
+    private _zones;
+    /** Spatial voices following a matrix (`Voice.follow`), synced in `update`. */
+    private readonly followers;
+    /** Panners of ended spatial voices, reused by the next ones (cleared with the context). */
+    private readonly pannerPool;
+    /** Biquads of ended voices' filters and occlusion lowpasses, reused the same way. */
+    private readonly biquadPool;
+    /**
+     * The game's occlusion probe (ws/audio-4), or null for none. Set it once; every spatial voice
+     * (unless `spatial.occlude` is false) is then probed round-robin from `update`.
+     */
+    occlusion: OcclusionOptions | null;
+    private readonly occluder;
+    /** Started spatial voices the probe may ask about, in start order. */
+    private readonly occludable;
+    /** Started voices with a Doppler factor. */
+    private readonly dopplers;
+    /** Sprite sheets by name (`defineSprites`); the buffer itself is a sound of the same name. */
+    private readonly spriteSheets;
+    private readonly scratchSchedule;
+    private _listener;
+    /** Externally owned voices (`register`): music stems, a game's own players. */
+    private readonly registered;
+    private _paused;
+    private readonly pausedList;
+    private _pausedRate;
+    /** Whether this context's `playbackRate` accepts 0, once a voice told us. */
+    private rateZeroOk;
+    /** Registered voices frozen by `pause`, with the rate to restore. */
+    private readonly frozenExternal;
+    /**
+     * Per-bus keyed multipliers on the settings gain (`setBusScale`: the duckers). Parallel
+     * key/value arrays, searched linearly (a bus has a handful of keys), so a per-frame
+     * `setBusScale` on an existing key allocates nothing. `scales` caches each bus's product.
+     */
+    private readonly scaleKeys;
+    private readonly scaleValues;
+    private readonly scales;
+    constructor(opts?: AudioEngineOptions);
+    get state(): AudioState;
+    /** The realtime context, once created (after the first gesture). */
+    get context(): AudioContext | null;
+    get settings(): Readonly<MixerSettings>;
+    /** Where spatial voices are heard from. A 3D game calls `audio.listener.fromCamera(camera)` each frame. */
+    get listener(): SpatialListener;
+    /**
+     * Regions that drive ambient loops and reverb sends by listener position. Built on first use;
+     * advanced by `update(dt)`.
+     */
+    get zones(): AudioZones;
+    /**
+     * Per-frame bookkeeping: the zones (weights, ambient gains, reverb sends) and the followers
+     * (`Voice.follow`). `createGame`'s loop calls it after input, before the scenes. Safe before
+     * unlock and when audio is unavailable: the numbers still move, nothing plays.
+     */
+    update(dt: number): void;
+    /** Internal: a voice starts or stops following a matrix. */
+    trackFollower(v: VoiceImpl, on: boolean): void;
+    /** Internal: a spatial voice started; it joins the occlusion and Doppler rounds it asks for. */
+    trackSpatial(v: VoiceImpl): void;
+    private untrackSpatial;
+    /** Idle panners waiting for the next spatial voice (tests, diagnostics). */
+    get pooledPanners(): number;
+    /** Idle biquads waiting for the next `Voice.filter` or occluded voice (tests, diagnostics). */
+    get pooledFilters(): number;
+    /** Voices `occlusion.probe` may be asked about (tests, diagnostics). */
+    get occludedVoiceCount(): number;
+    /**
+     * The page lifecycle's flag (ws/audio-4): `true` suspends the context while the app is hidden
+     * or backgrounded, `false` brings back whatever the user state is (`suspend()` still holds it
+     * suspended; otherwise it resumes). `attach({ pauseWhenHidden })` and `createGame`'s host
+     * lifecycle call this; a game with its own lifecycle source can too. Independent of `pause()`.
+     */
+    background(hidden: boolean): void;
+    /** True while `background(true)` holds (the document hidden or the app in the background). */
+    get inBackground(): boolean;
+    /** True after `halt()`: silent for good. */
+    get halted(): boolean;
+    onStateChange(fn: (s: AudioState) => void): () => void;
+    onSettingsChange(fn: (s: Readonly<MixerSettings>) => void): () => void;
+    private setState;
+    /**
+     * Listen for the first user gesture to unlock audio, and pause while hidden. Returns detach.
+     *
+     * Phones take audio away again after unlock: iOS interrupts the context for a call, Siri or
+     * an alarm (state `interrupted`) and may leave it suspended after an app switch; Android
+     * suspends it in the background. Whenever the context is not running but should be, the
+     * gesture listeners are re-armed so the next tap brings sound back, and `pageshow` / `focus`
+     * try a resume without one.
+     */
+    attach(opts?: AttachAudioOptions): () => void;
+    detach(): void;
+    private readonly onGesture;
+    private armGestures;
+    private disarmGestures;
+    /**
+     * Create/resume the context. Must run inside a user-gesture handler the first time
+     * (`attach` does this for you). Resolves true once audio is running.
+     */
+    unlock(): Promise<boolean>;
+    private isPaused;
+    private onContextState;
+    /** Pause all audio (e.g. game paused). Pair with `resume()`. */
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    private syncSuspension;
+    /**
+     * Fall silent for good, e.g. when the page can no longer run (GPU device lost) and only a
+     * reload helps. Stops every voice, drops loops waiting for unlock, removes the gesture and
+     * visibility listeners and suspends the context. After this, `unlock`, `resume`, `play`,
+     * `loop` and `prepare` do nothing, so no timer or tab switch can bring sound back.
+     */
+    halt(): Promise<void>;
+    /** Close the context and drop everything. */
+    dispose(): Promise<void>;
+    private buildBuses;
+    /**
+     * Internal: a `PannerNode` set up from `opts`, from the pool when one is idle. Null where the
+     * context has no panner (the voice then plays unspatialised, straight into its bus).
+     */
+    acquirePanner(opts: SpatialOptions | undefined): PannerNode | null;
+    /** Internal: take back an ended voice's (disconnected) panner. Dropped if its context is gone. */
+    releasePanner(p: PannerNode): void;
+    /** Internal: a `BiquadFilterNode` from the pool, or a new one. Null where the context has none. */
+    acquireBiquad(): BiquadFilterNode | null;
+    /** Internal: take back a (disconnected) biquad. Dropped if its context is gone. */
+    releaseBiquad(f: BiquadFilterNode): void;
+    /** The master limiter node, once the context exists (null when disabled or unsupported). */
+    get limiter(): DynamicsCompressorNode | null;
+    /** Current reverb settings (`null` = off). */
+    get reverb(): Readonly<ReverbOptions> | null;
+    /**
+     * Turn the shared reverb on (or rebuild it with a new room), or off with `null`. Safe before
+     * unlock: it is built with the buses. Rebuilding renders a new impulse, so do it rarely
+     * (scene changes), not per frame. Sends given here replace the matching current sends.
+     */
+    setReverb(opts: ReverbOptions | null): void;
+    /**
+     * Change one bus's base reverb send (linear, ramped). Remembered while reverb is off. The
+     * zones (`audio.zones`) raise the effective send above it, never below.
+     */
+    setReverbSend(bus: OutputBus, level: number): void;
+    /** Internal: the zones' contribution to one bus's send; `max(base, zone)` reaches the graph. */
+    setZoneReverbSend(bus: OutputBus, level: number): void;
+    /** Write `max(base, zone)` to the send node when it moved by more than 1e-3 (or `force`). */
+    private applySend;
+    /** Base send levels per bus (what `setReverbSend` and the reverb options set). */
+    get reverbSendLevels(): Readonly<Record<OutputBus, number>>;
+    /** What reaches the reverb per bus: `max(base, zones)`. The same object every call. */
+    get effectiveReverbSendLevels(): Readonly<Record<OutputBus, number>>;
+    private buildReverb;
+    private teardownReverb;
+    /** Internal: the GainNode for a bus, once the context exists. */
+    busNode(name: BusName): GainNode | null;
+    /** What a bus gain should be when nothing holds it: the settings gain times its scale. */
+    private busTarget;
+    private applyBus;
+    /**
+     * Multiply a bus's settings gain by `scale` (0..1) under `key` (default `'default'`),
+     * approached with time constant `timeConstant` seconds (default 0.015). A bus keeps one scale
+     * per key and its effective scale is the product of them all, so two duckers on one bus
+     * combine instead of fighting. The bus gain is always `busGain(settings[bus]) × product`, so
+     * `setVolume` and `setMuted` keep composing with it. The engine owns the write: while `pause`
+     * holds the bus or `inBackground` is true the scale is only stored, and `unpause` /
+     * `background(false)` ramp to the scaled gain; set before the context exists, the bus is
+     * built at it. `createDucker` drives this with a key of its own.
+     */
+    setBusScale(bus: BusName, scale: number, timeConstant?: number, key?: string): void;
+    /**
+     * Remove `key`'s scale from `bus` (a no-op for a key never set), ramping to the product of
+     * the keys left with time constant `timeConstant` (default 0.015). `Ducker.dispose` calls it.
+     */
+    clearBusScale(bus: BusName, key: string, timeConstant?: number): void;
+    /**
+     * `key`'s `setBusScale` multiplier on `bus` (1 for a key never set or cleared), or, with
+     * `key` omitted, the bus's effective scale: the product of all its keys (1 by default).
+     */
+    busScale(bus: BusName, key?: string): number;
+    /** Recompute a bus's product of keyed scales and write the bus if it changed. */
+    private updateBusScale;
+    /**
+     * The pause-menu recipe: ramp every output bus except `keep` (default `['ui']`, so menu
+     * clicks stay audible) to silence over 50 ms and hold the voices on those buses still by
+     * setting their playback rate to 0, where the context's `playbackRate` allows it (every
+     * current browser; elsewhere the voices keep running under the muted bus). `unpause` ramps
+     * the bus gains back to the mixer settings and the rates back to what the game set. Music
+     * stems pause the same way through their registered voices. The context keeps running
+     * (`suspend()` is the other tool); `master` never ramps. Idempotent.
+     */
+    pause(opts?: PauseOptions): void;
+    /** Undo `pause`: bus gains back to the settings (times any `setBusScale`), voice rates back to the game's. */
+    unpause(): void;
+    /** True between `pause` and `unpause`. */
+    get paused(): boolean;
+    /** The buses `pause` silenced (empty while not paused). The same array every call. */
+    get pausedBuses(): readonly OutputBus[];
+    /**
+     * Which pause path ran: true when the paused voices' playback rates were set to 0 as well
+     * (they resume where they stopped), false when the context refuses rate 0 and the buses were
+     * only muted (the voices keep running). False while not paused.
+     */
+    get pausedRate(): boolean;
+    /** Internal: whether `pause` silenced this bus. */
+    isBusPaused(bus: BusName): boolean;
+    private emitSettings;
+    setVolume(bus: BusName, volume: number): void;
+    setMuted(bus: BusName, muted: boolean): void;
+    toggleMuted(bus: BusName): boolean;
+    /** Replace all settings (sanitized), e.g. after loading a save. */
+    applySettings(settings: unknown): void;
+    /**
+     * Register a named sound from a spec (rendered lazily or via `prepare`) or an async buffer
+     * factory. `maxVoices` caps simultaneous plays of this sound (oldest is stolen). Default 8.
+     */
+    define(name: string, source: SoundSource, opts?: {
+        maxVoices?: number;
+    }): void;
+    has(name: string): boolean;
+    /**
+     * Register a sprite sheet (ws/audio-4): one buffer (or a factory for it) and named
+     * `[startMs, lengthMs]` ranges. `play('name#clip')` and `loop('name#clip')` then play one range
+     * (a loop repeats between the clip's `loopPoints`, or its whole range); `play('name')` still
+     * plays the whole buffer. `maxVoices` caps the sheet's simultaneous plays, every clip counted.
+     */
+    defineSprites(name: string, sheet: SpriteSheet, opts?: {
+        maxVoices?: number;
+    }): void;
+    /** The sprite sheet registered under `name`, if any. */
+    spriteSheet(name: string): SpriteSheet | null;
+    /** Render (or fetch) the buffer for a sound. Needs no gesture. Cached. */
+    load(name: string): Promise<AudioBuffer>;
+    /** Render several (default: all) defined sounds up front. Call at boot or behind a loading screen. */
+    prepare(names?: readonly string[]): Promise<void>;
+    /** Rendered buffer if ready. */
+    buffer(name: string): AudioBuffer | null;
+    /**
+     * Fire a one-shot. Dropped (returns an inert voice) while audio is locked, suspended or
+     * unavailable: a click sound arriving seconds late after unlock would be wrong.
+     */
+    play(sound: string | AudioBuffer, opts?: AudioPlayOptions): Voice;
+    /**
+     * Start a loop (music, ambience). If audio is still locked, it starts as soon as it unlocks.
+     * Stop it with `voice.stop(fade)`.
+     */
+    loop(sound: string | AudioBuffer, opts?: AudioPlayOptions): Voice;
+    private startVoice;
+    private startDeferred;
+    /**
+     * Stop every voice the mixer knows (its own and the registered ones, so music stems too),
+     * with an optional fade, or only those on `bus`. The options form adds `except`:
+     * `stopAll({ except: ['music'] })` clears the effects and keeps the score.
+     */
+    stopAll(fade?: number | StopAllOptions, bus?: OutputBus): void;
+    /**
+     * The live voices (playing or waiting to start, not yet stopped or ended) on `bus`, or on
+     * every bus when `bus` is omitted or `master`. A voice leaves the list the moment `stop` is
+     * called or its source ends. Allocates one array per call; `forEachVoice` allocates nothing.
+     */
+    voices(bus?: BusName): readonly Voice[];
+    /** `voices(bus)` without the array: `fn(voice, bus)` for each live voice. */
+    forEachVoice(bus: BusName | undefined, fn: (voice: Voice, bus: BusName) => void): void;
+    /**
+     * Put an externally owned voice (anything implementing `Voice`) on the mixer's books, so
+     * `voices`, `voiceCount`, `stopAll` and `pause` see it; `createMusic` does this for each
+     * playing stem. A registered voice with a numeric `rate` property has its rate frozen by
+     * `pause` and restored by `unpause`. Returns the unregister; a voice whose `playing` is false
+     * is skipped meanwhile.
+     */
+    register(voice: Voice, bus: BusName): () => void;
+    /** Number of live voices: `voices().length` without the array. */
+    get voiceCount(): number;
+}
+/** `createVoiceAdapter` options. */
+export interface VoiceAdapterOptions {
+    /** The raw source: a buffer or oscillator source, a media element source, a worklet. */
+    source: AudioNode;
+    /** Bus the adapter's gain feeds. Default `sfx`. */
+    bus?: OutputBus;
+    /** Linear gain to start at. Default 1. */
+    gain?: number;
+    /** Called once the voice is stopped (after its fade) or `end()` ran. */
+    onEnd?: () => void;
+    /** Put the voice on the mixer's books (`audio.register`). Default true. */
+    register?: boolean;
+}
+/** The `Voice` `createVoiceAdapter` returns; `rate` lets `audio.pause` freeze and restore it. */
+export interface VoiceAdapter extends Voice {
+    rate: number;
+    /** The gain node between the source and the bus. */
+    readonly gainNode: GainNode | null;
+    /** Internal to the owner: the source ended on its own; tear down without a fade. */
+    end(): void;
+}
+/**
+ * A `Voice` over a raw `AudioNode` another owner runs (ws/audio-4): source → gain → bus, with
+ * `setGain`, `stop(fade)` (ramps the gain, stops a scheduled source at the fade's end, else
+ * disconnects it then), `setRate` (writes the source's `playbackRate` when it has one, so
+ * `audio.pause` freezes it), `sendTo` and `filter` on the same pool as the mixer's voices. Not
+ * spatial: `setPosition`, `follow` and `occlusion` are inert. Registered with the mixer unless
+ * `register` is false, so `voices`, `stopAll` and `pause` see it. Null context: an inert voice.
+ */
+export declare function createVoiceAdapter(audio: AudioEngine, opts: VoiceAdapterOptions): VoiceAdapter;
+export {};