@adatechnology/game-audio 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,783 @@
+import { Vec3, AudioSink, TestableModule } from '@adatechnology/game-contracts';
+
+/** Deterministic mulberry32 generator; floats in [0, 1). The same generator the golden tool seeds `Math.random` with, so a team routine and its recipe draw the same numbers. */
+declare function createRng(seed: number): () => number;
+/** The seed of the stream called `name` (or numbered `name`): one seed gives each channel its own sequence, so one subject's sounds never shift another's. */
+declare function streamSeed(seed: number, name: string | number): number;
+declare function streamFor(seed: number, name: string | number): () => number;
+/** `min + random × (max − min)`: the form every team routine uses (`95 + Math.random() * 40`). */
+declare function drawBetween(random: () => number, min: number, max: number): number;
+
+/**
+ * Sound recipes are data. A recipe says which nodes a sound has and which numbers drive them; ranges are drawn when the sound is planned, in
+ * the order the fields are written (see `planSound`), so a recipe ported from a team routine draws its random numbers in the routine's order.
+ */
+declare const BUS_IDS: readonly ["weapons", "voices", "world", "ambience", "weather", "ui"];
+type BusId = (typeof BUS_IDS)[number];
+/** A named number: from `PlayOptions.params` or the recipe's `vars`, times `scale`, plus `add`. */
+type ParamRef = {
+    readonly param: string;
+    readonly scale?: number;
+    readonly add?: number;
+};
+/** A number, a `[min, max]` drawn uniformly (`min + random × (max − min)`), or a named number. */
+type Range = number | readonly [min: number, max: number] | ParamRef;
+/** Seconds from the layer start: a range, the layer `'duration'`, or `'0.6d'` (0.6 × the layer duration). */
+type Time = Range | 'duration' | `${number}d`;
+type Curve = 'linear' | 'exp';
+/**
+ * How an AudioParam moves:
+ * - `{ set }` assigns `.value`;
+ * - `{ set, to, curve, over }` assigns `.value`, then ramps to `to` at `over`;
+ * - `{ from }` calls `setValueAtTime(from)` at the start; with `to`, `curve` and `over` it then ramps to `to` (`'from'` is the value drawn for `from`: the art scene ramps a tone back to its own start when it gives no end).
+ */
+type Automation = {
+    readonly set: Range;
+    readonly to?: Range | 'from';
+    readonly curve?: Curve;
+    readonly over?: Time;
+} | {
+    readonly from: Range;
+    readonly to?: Range | 'from';
+    readonly curve?: Curve;
+    readonly over?: Time;
+};
+/**
+ * One gain point: time (seconds, or `'0.6d'`), value and how it is reached (`set` = `setValueAtTime`, or a ramp). The value is multiplied by the
+ * layer level (volume, distance and layer gain) except when the fourth item is `'fixed'` (the floor a ramp falls to, such as 0.001).
+ */
+type EnvelopePoint = readonly [time: number | `${number}d`, value: number, curve: 'set' | Curve] | readonly [time: number | `${number}d`, value: number, curve: 'set' | Curve, fixed: 'fixed'];
+type Envelope = readonly EnvelopePoint[];
+type FilterSpec = {
+    readonly type: BiquadFilterType;
+    readonly frequency: Automation;
+    readonly q?: Range;
+    /** The BiquadFilter gain (shelf and peaking types). */
+    readonly gain?: Range;
+    /** A gain node after the filter, for a parallel bank where each band has its own level (the game's scream formants). */
+    readonly level?: Range;
+};
+type FilterBank = {
+    readonly mode: 'serial' | 'parallel';
+    readonly bank: readonly FilterSpec[];
+};
+/** An LFO. `depth` is absolute, or a factor of the source start frequency. With `base`, gain modulation goes through its own gain stage (the game rotor). */
+type Modulator = {
+    readonly target: 'gain' | 'frequency';
+    /** Left out, the oscillator keeps its default (sine) and no type is set. */
+    readonly wave?: OscillatorType;
+    readonly rate: Range;
+    readonly depth: Range | {
+        readonly scaleOf: 'frequency';
+        readonly factor: number;
+    };
+    readonly base?: number;
+};
+/**
+ * Noise from the engine's seeded buffer. `offset` is where playback starts in it: `'random'` (random × `offsetScale`, default 1), `'fit'`
+ * (random × (buffer length − duration)) or seconds. `loop` sets the source to loop (the art scene sets it on every noise source).
+ */
+type NoiseSource = {
+    readonly kind: 'noise';
+    readonly offset?: 'random' | 'fit' | number;
+    readonly offsetScale?: number;
+    readonly loop?: boolean;
+};
+type OscSource = {
+    readonly kind: 'osc';
+    readonly wave: OscillatorType;
+    readonly frequency: Automation;
+};
+/** The art scene's `voice`: an oscillator with vibrato through formant bands, plus a band of breath noise, summed and boosted. */
+type FormantVoiceSource = {
+    readonly kind: 'formant_voice';
+    readonly wave: OscillatorType;
+    readonly frequency: Automation;
+    /** Vibrato rate, and depth as a factor of the start frequency. */
+    readonly vibrato: {
+        readonly rate: Range;
+        readonly depth: number;
+    };
+    readonly formants: readonly {
+        readonly frequency: Range;
+        readonly q: number;
+    }[];
+    readonly breath: {
+        readonly frequency: Range;
+        readonly q: number;
+        readonly gain: Range;
+    };
+    readonly mix: number;
+};
+type LayerSource = NoiseSource | OscSource | FormantVoiceSource;
+type Layer = {
+    /** Start, seconds after the sound starts. */
+    readonly at?: Range;
+    /** Overrides the recipe duration for this layer. */
+    readonly duration?: Range;
+    /** Seconds the source keeps running after the duration (the `+ 0.05` of the team routines). Default: the recipe's, else 0.05. */
+    readonly tail?: number;
+    /** The layer played `count` times, `spacing` seconds apart (the game's animal calls). */
+    readonly repeat?: {
+        readonly count: number;
+        readonly spacing: number;
+    };
+    /** Layer level before distance. Default 1. */
+    readonly gain?: Range;
+    /** Send to the reverb, 0..1 or more (the art scene uses up to 1.2). */
+    readonly wet?: number;
+    readonly source: LayerSource;
+    readonly filters?: FilterBank;
+    readonly modulators?: readonly Modulator[];
+    readonly envelope: Envelope;
+};
+/**
+ * Distance falloff of a sound's level:
+ * - `inverse_square`: `volume / (1 + d² × k)`; `cutoffK` also divides every lowpass cutoff by `1 + d × cutoffK` (the game's muffling);
+ * - `linear`: `max(0, 1 − d / range)`, silent at or below `minGain`;
+ * - `none`: no distance.
+ * `scale` multiplies the level (the game's boom is 1.4 at the source), and below `minGain` the sound is not played.
+ */
+type Falloff = {
+    readonly model: 'inverse_square';
+    readonly k: number;
+    readonly minGain?: number;
+    readonly cutoffK?: number;
+    readonly scale?: number;
+} | {
+    readonly model: 'linear';
+    readonly range: number;
+    readonly minGain?: number;
+    readonly scale?: number;
+} | {
+    readonly model: 'none';
+};
+/**
+ * The order the realizer creates and wires the nodes in. Each one is the order of the team routine it reproduces, so the trace of the SDK
+ * matches the trace of the team code node for node:
+ * - `layered` (default): the art scene's `sNoise`, `sTone` and `voice`; every layer has its own output stage (distance gain, pan, reverb send);
+ * - `burst`: the game's `sfx` (jogo L62089);
+ * - `scream`: the game's `grito` (L62128);
+ * - `groan`: the game's `voz` (L62143);
+ * - `boom`: the game's `boom` (L68278);
+ * - `static`: the game's `chiado` (L69998);
+ * - `chord`: the game's `buzina` (L70272);
+ * - `calls`: the game's `bichoSom` (L66625);
+ * - `siren`: the art scene's `siren` (L1369);
+ * - `weapon`: the weapon audio of the kit (`weapons-three`): per layer a filtered noise burst or an oscillator, then its own gain, chained to the bus.
+ * Every order but `layered` puts the level into the envelope and connects straight to the bus.
+ */
+declare const BUILD_ORDERS: readonly ["layered", "burst", "scream", "groan", "boom", "static", "chord", "calls", "siren", "weapon"];
+type BuildOrder = (typeof BUILD_ORDERS)[number];
+type SoundRecipe = {
+    readonly id: string;
+    readonly bus: BusId;
+    readonly order?: BuildOrder;
+    /** Named numbers drawn first, in the order written; layers read them with `{ param }`. */
+    readonly vars?: Readonly<Record<string, Range>>;
+    readonly duration?: Range;
+    readonly tail?: number;
+    readonly layers: readonly Layer[];
+    readonly falloff?: Falloff;
+    /** Stereo pan from the listener (the art scene's `panFor`). Only the `layered` order has an output stage to pan. */
+    readonly pan?: boolean;
+    /** Voice group for the limiter (`undead_voice`...). */
+    readonly group?: string;
+    /** Limiter priority; default from the bus (weapons > voices > world > ambience). */
+    readonly priority?: number;
+    /**
+     * The team routine creates nodes before it checks the level (the game's `bichoSom` creates its gain and filter first): a silent sound is kept as
+     * a plan with `silent: true` so the realizer repeats those nodes. Off by default.
+     */
+    readonly keepSilent?: boolean;
+    /** Where the numbers come from: `"jogo:L62128"`, `"cena:L1342"`, or `"sdk"` for values the kit chose. */
+    readonly sources: readonly string[];
+};
+/**
+ * The order the loop realizer creates the nodes in:
+ * - `game_loop`: the game's `loopSet` (L62109): gain and filter first, nodes created the first time the volume passes `startAbove`, gain from 0;
+ * - `chain_loop`: the art scene's loops in `initAudio` (L1314–1316): source, filters, gain at its starting volume, created when the loop opens.
+ */
+type LoopOrder = 'game_loop' | 'chain_loop';
+type LoopRecipe = {
+    readonly id: string;
+    readonly bus: BusId;
+    readonly order?: LoopOrder;
+    /** An oscillator loop may leave the frequency out: it starts at the default and `set({ frequency })` glides it (the game's motor). */
+    readonly source: (NoiseSource & {
+        readonly loop: true;
+    }) | {
+        readonly kind: 'osc';
+        readonly wave: OscillatorType;
+        readonly frequency?: Automation;
+        readonly loop: true;
+    };
+    readonly filters?: FilterBank;
+    readonly modulators?: readonly Modulator[];
+    /** `setTargetAtTime` time constants (jogo L62125–62126: 0.15 for the volume, 0.08 for the frequency). */
+    readonly smoothing?: {
+        readonly volume: number;
+        readonly frequency: number;
+    };
+    /** Nodes are created the first time the volume reaches this (jogo L62112: 0.002). */
+    readonly startAbove?: number;
+    /** Volume the gain starts at when the loop opens (`chain_loop`). */
+    readonly volume?: number;
+    readonly sources: readonly string[];
+};
+type SoundBank = {
+    readonly id: string;
+    readonly sounds?: readonly SoundRecipe[];
+    readonly loops?: readonly LoopRecipe[];
+};
+
+/** Where the ears are. `yaw` turns around y like a three.js camera: the right ear points at `(cos yaw, 0, −sin yaw)`. */
+type Listener = {
+    readonly position: Vec3;
+    readonly yaw: number;
+};
+type DistanceMode = 'xz' | '3d';
+declare const DEFAULT_LISTENER: Listener;
+/** The art scene clamps the pan to ±0.85 and never divides by less than 2 m (cena L1319). */
+declare const PAN_LIMIT = 0.85;
+declare const PAN_MIN_DISTANCE = 2;
+/** Distance from the listener: on the ground (`xz`, the teams' choice) or in 3D. */
+declare function listenerDistance(listener: Listener, position: Vec3, mode?: DistanceMode): number;
+/** The art scene's `panFor`: the side the sound is on, −0.85 (left) to 0.85 (right). No HRTF, for cost. */
+declare function panFor(listener: Listener, position: Vec3): number;
+
+/** How an AudioParam moves, with every number resolved and every time in seconds from the layer start. */
+type PlannedAutomation = {
+    /** Assigned to `.value`. */
+    readonly value?: number;
+    /** `setValueAtTime(from)` at the layer start. */
+    readonly from?: number;
+    /** Ramp target, reached `at` seconds after the layer start. */
+    readonly to?: number;
+    readonly curve?: Curve;
+    readonly at?: number;
+};
+type PlannedFilter = {
+    readonly type: BiquadFilterType;
+    readonly frequency: PlannedAutomation;
+    readonly q?: number;
+    readonly gain?: number;
+    readonly level?: number;
+};
+type PlannedModulator = {
+    readonly target: 'gain' | 'frequency';
+    readonly wave?: OscillatorType;
+    readonly rate: number;
+    readonly depth: number;
+    readonly base?: number;
+};
+type PlannedSource = {
+    readonly kind: 'noise';
+    readonly offset: number;
+    readonly loop: boolean;
+} | {
+    readonly kind: 'osc';
+    readonly wave: OscillatorType;
+    readonly frequency: PlannedAutomation;
+} | {
+    readonly kind: 'formant_voice';
+    readonly wave: OscillatorType;
+    readonly frequency: PlannedAutomation;
+    readonly vibrato: {
+        readonly rate: number;
+        readonly depth: number;
+    };
+    readonly formants: readonly {
+        readonly frequency: number;
+        readonly q: number;
+    }[];
+    readonly breath: {
+        readonly frequency: number;
+        readonly q: number;
+        readonly gain: number;
+        readonly offset: number;
+    };
+    readonly mix: number;
+};
+type PlannedEnvelopePoint = {
+    readonly time: number;
+    readonly value: number;
+    readonly curve: 'set' | Curve;
+};
+type PlannedLayer = {
+    readonly at: number;
+    readonly duration: number;
+    readonly tail: number;
+    /** Layer gain × the sound's level: in the envelope for every order but `layered`, in the output stage for `layered`. */
+    readonly level: number;
+    readonly wet?: number;
+    readonly source: PlannedSource;
+    readonly filters?: {
+        readonly mode: 'serial' | 'parallel';
+        readonly bank: readonly PlannedFilter[];
+    };
+    readonly modulators: readonly PlannedModulator[];
+    readonly envelope: readonly PlannedEnvelopePoint[];
+};
+/** A sound with every number decided: what the realizer builds, what goldens compare and what the bench sheet prints. */
+type SoundPlan = {
+    readonly id: string;
+    readonly bus: BusId;
+    readonly order: BuildOrder;
+    readonly group?: string;
+    readonly priority: number;
+    /** The level from volume and distance, before layer gains. */
+    readonly level: number;
+    readonly distance: number;
+    readonly pan?: number;
+    /** Too quiet to hear, kept only for a recipe with `keepSilent`. */
+    readonly silent: boolean;
+    /** Seconds until the last source stops. */
+    readonly length: number;
+    readonly layers: readonly PlannedLayer[];
+};
+type PlanInput = {
+    /** Where the numbers are drawn from. Default: a fresh stream with seed 1. */
+    readonly random?: () => number;
+    readonly volume?: number;
+    /** Distance in meters; overrides `position`. */
+    readonly distance?: number;
+    readonly position?: Vec3;
+    readonly listener?: Listener;
+    readonly distanceMode?: DistanceMode;
+    readonly params?: Readonly<Record<string, number>>;
+    /** 0..1 from the host's occlusion callback: gain × (1 − 0.5 × o), lowpass cutoffs × (1 − 0.6 × o). */
+    readonly occlusion?: number;
+    /** Length of the noise buffer, for `offset: 'fit'`. Default 1.5. */
+    readonly noiseSeconds?: number;
+};
+/**
+ * Turns a recipe into a plan: pure, Node-safe, the same plan for the same `random`. Numbers are drawn in this order: `vars` (in the order written),
+ * `duration`, then each layer in the order its fields are written, the noise start point last in its layer. A sound below its falloff's `minGain`
+ * gives `null` (or a silent plan with `keepSilent`) before any number is drawn.
+ */
+declare function planSound(recipe: SoundRecipe, input?: PlanInput): SoundPlan | null;
+
+/** The distance curves of the team routines, by name. Each recipe carries its own; these are the values to copy. */
+declare const DISTANCE_CURVES: {
+    /** The game's `sfx`: `vol / (1 + d² × 0.004)`, cutoff `/ (1 + d × 0.01)`, silent below 0.01 (jogo L62091–62092, L62101). */
+    readonly game_sfx: {
+        readonly model: "inverse_square";
+        readonly k: 0.004;
+        readonly cutoffK: 0.01;
+        readonly minGain: 0.01;
+    };
+    /** The game's `grito`: `1 / (1 + d² × 0.006)`, silent below 0.02 (jogo L62129–62130). */
+    readonly game_scream: {
+        readonly model: "inverse_square";
+        readonly k: 0.006;
+        readonly minGain: 0.02;
+    };
+    /** The game's `voz`: `1 / (1 + d² × 0.01)`, silent below 0.02 (jogo L62146–62147). */
+    readonly game_voice: {
+        readonly model: "inverse_square";
+        readonly k: 0.01;
+        readonly minGain: 0.02;
+    };
+    /** The game's `boom`: `1.4 / (1 + d² × 0.002)`, never silent (jogo L68280). */
+    readonly game_boom: {
+        readonly model: "inverse_square";
+        readonly k: 0.002;
+        readonly scale: 1.4;
+    };
+    /** The art scene's `outAt`: `vol / (1 + d² × 0.008)` (cena L1320). */
+    readonly art_scene: {
+        readonly model: "inverse_square";
+        readonly k: 0.008;
+    };
+    /** The game's animal calls: `max(0, 1 − d / 70) × 0.25`, silent at or below 0.005 (jogo L66627–66628). */
+    readonly animals: {
+        readonly model: "linear";
+        readonly range: 70;
+        readonly scale: 0.25;
+        readonly minGain: 0.005;
+    };
+};
+type DistanceCurveName = keyof typeof DISTANCE_CURVES;
+/** The level at `distance` for a sound at `volume`, before the recipe's envelope. */
+declare function falloffGain(falloff: Falloff | undefined, volume: number, distance: number): number;
+/** Whether a level is too quiet to play: below `minGain` (the game's `att < 0.01`), or at or below it for `linear` (the animal calls' `v <= 0.005`). */
+declare function isSilent(falloff: Falloff | undefined, gain: number): boolean;
+/** What every lowpass cutoff is divided by at `distance` (1 when the curve has no muffling). */
+declare function cutoffDivisor(falloff: Falloff | undefined, distance: number): number;
+
+/**
+ * Rules for a group of voices (`undead_voice`...). A request passes when every rule passes:
+ * - `maxConcurrent`: at most this many of the group play at once (`steal` replaces the group's oldest instead of refusing);
+ * - `cooldown`: seconds after an accepted voice before the next one (the game's `groanBudget`, jogo L66986 and L70472);
+ * - `maxDistance`: only voices nearer than this (the game's `d < 40`).
+ */
+type VoiceGroup = {
+    readonly maxConcurrent?: number;
+    readonly cooldown?: number;
+    readonly maxDistance?: number;
+    readonly steal?: boolean;
+    readonly sources?: readonly string[];
+};
+/** `undead_voice`: the art scene's five at once with the game's 0.25 s cooldown and 40 m. */
+declare const VOICE_GROUPS: Readonly<Record<string, VoiceGroup>>;
+/** Q7: weapons > voices > world > ambience; the interface above all, weather with the ambience. */
+declare const BUS_PRIORITY: Readonly<Record<BusId, number>>;
+declare const DEFAULT_MAX_VOICES = 32;
+declare function busPriority(bus: BusId): number;
+type VoiceRequest = {
+    readonly group?: string;
+    readonly priority: number;
+    /** Planned level; the global cap drops the lowest `priority × gain`. */
+    readonly gain: number;
+    readonly distance?: number;
+    /** Seconds the voice lasts. */
+    readonly length: number;
+};
+type VoiceRefusal = 'cooldown' | 'distance' | 'group_full' | 'global_full';
+type VoiceDecision = {
+    readonly accepted: true;
+    readonly id: number;
+    readonly evicted: readonly number[];
+} | {
+    readonly accepted: false;
+    readonly reason: VoiceRefusal;
+};
+type VoiceStats = {
+    readonly active: number;
+    readonly peak: number;
+    readonly dropped: number;
+    readonly maxVoices: number;
+};
+type VoiceManager = {
+    request(request: VoiceRequest): VoiceDecision;
+    /** Ends a voice early (stopped by the host). */
+    release(id: number): void;
+    /** Sets how long an accepted voice lasts (the engine admits a voice before its random length is drawn). */
+    setLength(id: number, seconds: number): void;
+    /** Moves time on: cooldowns count down and finished voices leave. Returns the ids that ended. */
+    advance(dt: number): number[];
+    setGroup(id: string, group: VoiceGroup | undefined): void;
+    stats(): VoiceStats;
+};
+type VoiceManagerOptions = {
+    /** Default `VOICE_GROUPS`. */
+    readonly groups?: Readonly<Record<string, VoiceGroup>>;
+    readonly maxVoices?: number;
+};
+/** The voice limiter: per-group rules, a global cap and priority dropping. Pure and time-driven (`advance`), so goldens script it frame by frame. */
+declare function createVoiceManager(options?: VoiceManagerOptions): VoiceManager;
+
+/** jogo L62112: a loop's nodes exist only once its volume reaches 0.002. */
+declare const LOOP_START_ABOVE = 0.002;
+/** jogo L62125–62126: `setTargetAtTime` time constants. */
+declare const LOOP_SMOOTHING: {
+    readonly volume: 0.15;
+    readonly frequency: 0.08;
+};
+/** What the realizer does for one `set`: create the nodes first (once), then glide the volume and, for an oscillator, the frequency. */
+type LoopAction = {
+    readonly create: boolean;
+    readonly volume: number;
+    readonly frequency?: number;
+};
+type LoopState = {
+    /** `null` while the loop has no nodes and the volume is still below the start threshold. */
+    set(state: {
+        readonly volume?: number;
+        readonly frequency?: number;
+    }): LoopAction | null;
+    /** Whether the nodes exist. */
+    readonly created: boolean;
+    /** The nodes were torn down (`stop`): the next audible `set` creates them again. */
+    reset(): void;
+};
+/**
+ * The game's `loopSet` as state: nodes on the first volume at or above `startAbove`, then every `set` glides. The volume set last is kept, so a
+ * `set` of only the frequency keeps the level. `chain_loop` recipes open with their nodes already made (`open` is true).
+ */
+declare function createLoopState(recipe: LoopRecipe, open?: boolean): LoopState;
+
+type BusSetting = {
+    readonly gain?: number;
+    readonly muted?: boolean;
+};
+/**
+ * A mixing chain. `master` → (compressor) → output; with `reverb`, a wet bus → convolver (an impulse from the engine's seed) → master. `noise` is
+ * the shared noise buffer: its length, and whether it is made with the chain (`eager`, the art scene) or by the first sound that needs it (`lazy`,
+ * the game). Buses sit under the master and have no node until one is changed.
+ */
+type MixProfile = {
+    readonly id: string;
+    readonly master: number;
+    readonly compressor?: {
+        readonly threshold: number;
+        readonly ratio: number;
+        readonly knee?: number;
+        readonly attack?: number;
+        readonly release?: number;
+    };
+    readonly reverb?: {
+        readonly seconds: number;
+        readonly decay: number;
+        readonly wet: number;
+    };
+    readonly noise: {
+        readonly seconds: number;
+        readonly create: 'lazy' | 'eager';
+    };
+    readonly buses?: Readonly<Partial<Record<BusId, BusSetting>>>;
+    readonly sources: readonly string[];
+};
+/** The two team chains: `game` (master 0.5, jogo L62080) and `art_scene` (compressor and reverb, cena L1305–1313). */
+declare const MIX_PROFILES: Readonly<Record<string, MixProfile>>;
+/** Q1: the kit plays through the art scene chain (compressor and reverb); `mix: 'game'` reverts. */
+declare const DEFAULT_MIX = "art_scene";
+/** A profile by id from `profiles`, or the profile itself. */
+declare function resolveMix(mix: string | MixProfile, profiles?: Readonly<Record<string, MixProfile>>): MixProfile;
+/** The gain a bus plays at: 0 when muted, its gain (default 1) otherwise. */
+declare function busGain(setting: BusSetting | undefined): number;
+
+type DeepPartial<TValue> = TValue extends readonly unknown[] ? TValue : TValue extends object ? {
+    readonly [Key in keyof TValue]?: DeepPartial<TValue[Key]>;
+} : TValue;
+/** Every sound and loop the engine knows, by id. Banks register in order; a later bank replaces an earlier recipe with the same id. */
+type SoundRegistry = {
+    register(bank: SoundBank): void;
+    /** Merged into the recipe by id (objects merge, arrays such as `layers` are replaced); an unknown id is ignored. */
+    patch(id: string, patch: DeepPartial<SoundRecipe> | DeepPartial<LoopRecipe>): void;
+    remove(id: string): void;
+    sound(id: string): SoundRecipe | undefined;
+    loop(id: string): LoopRecipe | undefined;
+    soundIds(): string[];
+    loopIds(): string[];
+    /** Which bank each id came from. */
+    bankOf(id: string): string | undefined;
+};
+declare function createSoundRegistry(banks?: readonly SoundBank[]): SoundRegistry;
+
+/** One row of the game's `sfx` table (jogo L62096–62100): lowpass cutoff, peak gain and seconds of a noise burst. */
+type NoiseClass = {
+    readonly id: string;
+    /** The name in the team code (`pistola`, `vidro`...). */
+    readonly team: string;
+    readonly bus: BusId;
+    readonly cutoff: number;
+    readonly gain: number;
+    readonly seconds: number;
+};
+/** The 12 game classes, in the table's order. */
+declare const GAME_SFX_CLASSES: readonly NoiseClass[];
+/** What the game plays for a name it does not know: `[1000, 0.5, 0.1]`. */
+declare const GAME_SFX_FALLBACK: NoiseClass;
+/**
+ * A class as a recipe: noise from a random point, the class lowpass (muffled by distance), the peak set at once and an exponential fall to 0.001 over
+ * the class seconds, stopped 0.05 s later; the game's distance curve, silent below 0.01. Built in the game's `sfx` order (`burst`).
+ */
+declare function noiseClassRecipe(row: NoiseClass, id?: string): SoundRecipe;
+/** The game's classes as a bank (`sfx_pistol`... and `sfx_unknown`). Subject banks pick their own classes from `GAME_SFX_CLASSES`. */
+declare const GAME_SFX_BANK: SoundBank;
+
+declare const LIBRARY_SOUNDS: readonly SoundRecipe[];
+declare const LIBRARY_LOOPS: readonly LoopRecipe[];
+declare const LIBRARY_BANK: SoundBank;
+
+/** A continuous sound: `set` glides the volume and, for an oscillator, the frequency; `stop` tears the nodes down. */
+type AudioLoopHandle = {
+    set(state: {
+        readonly volume?: number;
+        readonly frequency?: number;
+    }): void;
+    stop(): void;
+};
+
+type PlayOptions = {
+    readonly position?: Vec3;
+    /** Meters; overrides `position` for the distance (not for the pan). */
+    readonly distance?: number;
+    readonly volume?: number;
+    readonly params?: Readonly<Record<string, number>>;
+    /** This sound's own stream: same seed, same sound. */
+    readonly seed?: number;
+    /** Seconds from now. */
+    readonly delay?: number;
+    /** A named stream of the engine (`streamFor(seed, name)`), so one subject never shifts another's sounds. */
+    readonly channel?: string;
+};
+type VoiceHandle = {
+    readonly id: number;
+    readonly plan: SoundPlan;
+    stop(): void;
+};
+/** A subject's own random stream; `ownNoise` also gives it its own noise buffer, filled from that stream (the order `createWeaponAudio` uses). */
+type AudioChannel = {
+    readonly random: () => number;
+    play(id: string, options?: PlayOptions): VoiceHandle | null;
+    plan(id: string, options?: PlayOptions): SoundPlan | null;
+};
+type AudioStats = {
+    readonly context: 'none' | AudioContextState;
+    readonly voices: number;
+    readonly peak: number;
+    readonly dropped: number;
+    readonly maxVoices: number;
+    readonly loops: number;
+};
+type AudioEngineOptions = {
+    /** Seeds the engine stream: the noise, the reverb impulse and every sound played without its own seed or channel. Default 1. */
+    readonly seed?: number;
+    /** Default `art_scene` (Q1). */
+    readonly mix?: string | MixProfile;
+    readonly profiles?: Readonly<Record<string, MixProfile>>;
+    readonly banks?: readonly SoundBank[];
+    readonly maxVoices?: number;
+    readonly groups?: Readonly<Record<string, VoiceGroup>>;
+    readonly distance?: DistanceMode;
+    /** 0 (clear) to 1 (behind a wall) for a sound at a point; without it there is no occlusion (Q8). */
+    readonly occlusion?: (point: Vec3) => number;
+    readonly createContext?: () => AudioContext | null;
+};
+type AudioEngine = {
+    readonly registry: SoundRegistry;
+    register(bank: SoundBank): void;
+    /** Pure: the plan a sound would play with, from `options.seed` or the engine seed; draws nothing from the live streams. */
+    plan(id: string, options?: PlayOptions): SoundPlan | null;
+    play(id: string, options?: PlayOptions): VoiceHandle | null;
+    playPlan(plan: SoundPlan, options?: {
+        readonly delay?: number;
+    }): VoiceHandle | null;
+    loop(id: string, options?: {
+        readonly volume?: number;
+    }): AudioLoopHandle;
+    channel(options: {
+        readonly seed?: number;
+        readonly random?: () => number;
+        readonly ownNoise?: boolean;
+    }): AudioChannel;
+    setListener(listener: Listener): void;
+    setBus(id: BusId, setting: BusSetting): void;
+    setMix(mix: string | MixProfile): void;
+    /** The master volume of the current chain and of any later one (0 to 1). */
+    setMaster(gain: number): void;
+    /** Creates the context and the mixing chain if needed and resumes it; call from a click or a key. */
+    unlock(): void;
+    stats(): AudioStats;
+    /** RMS (0 to 1) of what a bus carries now, read from an analyser the first time you ask; sounds started before that do not reach it. 0 without a context. */
+    level(bus: BusId): number;
+    dispose(): void;
+};
+/**
+ * The sound engine: plans recipes and builds them on a lazily created AudioContext through one of the team mixing chains. Without an AudioContext
+ * (Node, workers) every call except `plan` does nothing.
+ */
+declare function createAudioEngine(options?: AudioEngineOptions): AudioEngine;
+
+/** Where a plan is built: the context, the bus it plays into, the reverb send (if the mix has one), the shared noise and the start time. */
+type RealizeTarget = {
+    readonly context: AudioContext;
+    readonly output: AudioNode;
+    readonly wet?: AudioNode;
+    /** The noise buffer; made on the first call when the mix makes it on demand. */
+    readonly noise: () => AudioBuffer;
+    readonly time: number;
+};
+/** What `realize` built: every scheduled source (so the voice can be cut short) and `stop`. */
+type RealizedVoice = {
+    readonly sources: readonly AudioScheduledSourceNode[];
+    stop(): void;
+};
+
+/** Builds a plan's nodes on `target`, in the node order of the team routine its `order` names. */
+declare function realize(plan: SoundPlan, target: RealizeTarget): RealizedVoice;
+
+type MixChain = {
+    readonly master: GainNode;
+    readonly wet?: GainNode;
+    disconnect(): void;
+};
+/**
+ * The mixing chain in the team order (cena L1308–1311; jogo L62080): compressor to the output, master into it (or straight to the output), then the
+ * convolver with an impulse drawn from `random` and the wet bus into it, back into the master.
+ */
+declare function buildChain(context: AudioContext, profile: MixProfile, random: () => number): MixChain;
+
+/** `length` samples of white noise, `random × 2 − 1`, drawn in order (jogo L62086, cena L1312). */
+declare function fillNoise(random: () => number, length: number): Float32Array;
+/**
+ * A reverb impulse: per channel, noise times `(1 − i / length)^decay` (cena L1310). `length` is `sampleRate × seconds` as the art scene computes it,
+ * which is not always whole (48000 × 2.2 = 105600.00000000001): the loop runs while `i < length`, so one more number is drawn than the buffer holds,
+ * exactly like the team code. The power is `exp(decay × log(base))`, which every engine computes the same.
+ */
+declare function fillImpulse(random: () => number, options: {
+    readonly channels: number;
+    readonly length: number;
+    readonly decay: number;
+}): Float32Array[];
+/** An AudioBuffer holding the samples (one channel per array). */
+declare function bufferOf(context: AudioContext, channels: readonly Float32Array[], requestedLength: number): AudioBuffer;
+
+/** A new context from the page (`AudioContext` or the old `webkitAudioContext`), or `null` in Node and workers. */
+declare function globalContext(): AudioContext | null;
+/** Browsers start a context suspended until a click or key; call from one. */
+declare function unlockContext(context: AudioContext): void;
+
+/** An `AudioSink` (what a host lends its modules) that carries the engine behind it, so a module that wants more than `play` can use the engine. */
+type EngineSink = AudioSink & {
+    readonly engine: AudioEngine;
+};
+/** Lends an engine as the host's `audio`: sounds by key, loops, the listener, and banks registered into the same engine. */
+declare function createAudioSink(engine: AudioEngine): EngineSink;
+
+/**
+ * Two probe sounds of the bench itself (a ping and a hiss), so panning, distance and the seed can be heard on something that has no subject. They are
+ * made by the kit, not delivered by any team (`sdk` in the sources).
+ */
+declare const BENCH_BANK: SoundBank;
+type AudioTestModuleOptions = {
+    /** The engine to test (default: the one the host lends in `host.audio`, else a new one of the module's own). */
+    engine?: AudioEngine;
+    /** Banks registered in the engine besides the bench's probes (default the game's noise classes and the library). */
+    banks?: readonly SoundBank[];
+    locale?: string;
+    /** Text of a sound or loop id (`sound.glass`) in the game's words; without it the bench shows the bank and the id. */
+    translate?: (key: string, locale: string) => string | undefined;
+    seed?: number;
+    /** First sound chosen (default `bench_ping`). */
+    sound?: string;
+};
+/** What the scenarios use of the context the test room passes. */
+interface AudioScenarioLike {
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+}
+type AudioTestModule = TestableModule<AudioScenarioLike> & {
+    /** The engine in use: the host's when it lent one, the module's own otherwise. */
+    readonly engine: AudioEngine;
+    /** The resolved plan of the chosen sound as text (the S3 view: every number decided). */
+    sheet(): string;
+    /** Plays the chosen sound as the bench is set. */
+    play(): VoiceHandle | null;
+};
+/**
+ * The sound area of a test room, written against the generic contracts only: it plays any sound of an engine at a distance and bearing from the listener
+ * (or from a probe standing in the area), runs loops, throws a storm of voices at the limiter, switches the mixing chain and its parts, reads the
+ * level of each bus and prints the resolved plan. The engine is the host's (`host.audio`) when lent, else the module's own.
+ */
+declare function createAudioTestModule(options?: AudioTestModuleOptions): AudioTestModule;
+
+type AudioBenchText = {
+    readonly group: string;
+    readonly name: string;
+    readonly probe: string;
+    readonly controls: Readonly<Record<'sound' | 'distance' | 'bearing' | 'volume' | 'mix' | 'seed' | 'play' | 'voice_storm' | 'loop' | 'loop_level' | 'loop_pitch' | 'source', string>>;
+    readonly hints: Readonly<Record<'distance' | 'bearing' | 'mix' | 'seed' | 'voice_storm' | 'loop_pitch' | 'source', string>>;
+    readonly options: Readonly<Record<'none' | 'bench' | 'probe', string>>;
+    readonly layers: Readonly<Record<'reverb' | 'compressor' | 'panning' | 'muffling', string>>;
+    readonly metrics: Readonly<Record<'voices' | 'peak' | 'dropped' | 'loops' | 'context' | 'plan_length' | 'plan_level' | 'plan_pan' | 'level_weapons' | 'level_voices' | 'level_world' | 'level_ambience' | 'level_weather' | 'level_ui', string>>;
+    readonly scenarios: Readonly<Record<'panning' | 'distance' | 'determinism' | 'limiter', string>>;
+    readonly mixes: Readonly<Record<string, string>>;
+    /** Text of a sound or loop id when the game has one; the bench falls back to the id. */
+    readonly sheet: Readonly<Record<'title' | 'level' | 'distance' | 'pan' | 'length' | 'silent' | 'layer' | 'none', string>>;
+};
+declare const audioBenchTextOf: (locale: string) => AudioBenchText;
+
+export { type AudioBenchText, type AudioChannel, type AudioEngine, type AudioEngineOptions, type AudioLoopHandle, type AudioScenarioLike, type AudioStats, type AudioTestModule, type AudioTestModuleOptions, type Automation, BENCH_BANK, BUILD_ORDERS, BUS_IDS, BUS_PRIORITY, type BuildOrder, type BusId, type BusSetting, type Curve, DEFAULT_LISTENER, DEFAULT_MAX_VOICES, DEFAULT_MIX, DISTANCE_CURVES, type DeepPartial, type DistanceCurveName, type DistanceMode, type EngineSink, type Envelope, type EnvelopePoint, type Falloff, type FilterBank, type FilterSpec, type FormantVoiceSource, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, type Layer, type LayerSource, type Listener, type LoopAction, type LoopOrder, type LoopRecipe, type LoopState, MIX_PROFILES, type MixChain, type MixProfile, type Modulator, type NoiseClass, type NoiseSource, type OscSource, PAN_LIMIT, PAN_MIN_DISTANCE, type ParamRef, type PlanInput, type PlannedAutomation, type PlannedEnvelopePoint, type PlannedFilter, type PlannedLayer, type PlannedModulator, type PlannedSource, type PlayOptions, type Range, type RealizeTarget, type RealizedVoice, type SoundBank, type SoundPlan, type SoundRecipe, type SoundRegistry, type Time, VOICE_GROUPS, type VoiceDecision, type VoiceGroup, type VoiceHandle, type VoiceManager, type VoiceManagerOptions, type VoiceRefusal, type VoiceRequest, type VoiceStats, audioBenchTextOf, bufferOf, buildChain, busGain, busPriority, createAudioEngine, createAudioSink, createAudioTestModule, createLoopState, createRng, createSoundRegistry, createVoiceManager, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, listenerDistance, noiseClassRecipe, panFor, planSound, realize, resolveMix, streamFor, streamSeed, unlockContext };