@adatechnology/game-audio 0.3.6 → 0.5.0

package/dist/locale-BugSe8dA.d.ts

@@ -0,0 +1,1071 @@
+import { Vec3, DeferredQueue, TestableModule } from '@adatechnology/game-contracts';
+
+/**
+ * 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;
+    /**
+     * Distance falloff of the loop, applied each time `set` gives a `position` (an engine, a fire, a skid heard from where it is). Left out, the loop is
+     * heard at the listener, as the team loops are. `cutoffK` also lowers the first filter's cutoff with the distance, as it does for one-shots.
+     */
+    readonly falloff?: Falloff;
+    /** Stereo pan from the listener, from the `position` of each `set` (a panner after the gain). Off by default. */
+    readonly pan?: boolean;
+    readonly sources: readonly string[];
+};
+/**
+ * One id that plays one of several recipes (the takes of a footstep, of a punch): `play(id)` draws a variant, never the one it played last time (unless
+ * `repeat`), and plays it at a rate drawn from `rate` (1.04 is 4% higher and 4% shorter; see `retunePlan`), so ten footsteps never sound like one.
+ */
+type SoundSet = {
+    readonly id: string;
+    /** Recipe ids, at least one. */
+    readonly variants: readonly string[];
+    /** `[min, max]` of the playback rate (pitch and speed together). Default `[1, 1]`. */
+    readonly rate?: readonly [min: number, max: number];
+    /** Allow the same variant twice in a row (default false). */
+    readonly repeat?: boolean;
+};
+type SoundBank = {
+    readonly id: string;
+    readonly sounds?: readonly SoundRecipe[];
+    readonly loops?: readonly LoopRecipe[];
+    readonly sets?: readonly SoundSet[];
+    /** Sounds played from recorded files (see `sample.ts`). A sample and a recipe may share an id: the sample plays once its files are loaded. */
+    readonly samples?: readonly SampleSound[];
+};
+/** One take: a file and its own trim (linear gain, default 1). */
+type SampleRef = {
+    readonly url: string;
+    readonly gain?: number;
+};
+/** Where a sound happens: a closed room rings short and dense, the open field long and thin. */
+type SampleEnvironment = 'indoor' | 'outdoor';
+/** Where the near take hands over to the far one: all near up to `from` metres, all far from `to`, an equal-power crossfade between. */
+type SampleCrossover = {
+    readonly from: number;
+    readonly to: number;
+};
+type SampleTail = {
+    readonly indoor?: readonly SampleRef[];
+    readonly outdoor?: readonly SampleRef[];
+    /** Level of the tail against the dry take (default 0.6). */
+    readonly gain?: number;
+    /** Seconds after the start (default 0: the tail file carries its own pre-delay). */
+    readonly at?: number;
+};
+/**
+ * A set of takes for a strength of the action (criterion C7: a light blow, a heavy one, a car at 10 or 60 km/h): from `from` (0..1) up, these takes
+ * replace `close` and `far`. The tier played is the last one whose `from` is at or below `PlayOptions.intensity`.
+ */
+type SampleTier = {
+    readonly name: string;
+    readonly from: number;
+    readonly close: readonly SampleRef[];
+    readonly far?: readonly SampleRef[];
+};
+type SampleSound = {
+    readonly id: string;
+    readonly bus: BusId;
+    /** The takes heard near; at least one (the criteria ask four for a sound heard all the time). */
+    readonly close: readonly SampleRef[];
+    /** The takes heard far; without them the near take plays at every distance (muffled by the lowpass). */
+    readonly far?: readonly SampleRef[];
+    /** Takes by strength (light, medium, heavy), in rising `from`; without `intensity` the near takes above play. */
+    readonly tiers?: readonly SampleTier[];
+    /** Default `{ from: 30, to: 80 }`. */
+    readonly crossover?: SampleCrossover;
+    readonly tail?: SampleTail;
+    /** ± fraction of the playback rate drawn per play (default 0.04: ±4 %, inside the 3–5 % of the criteria). 0 plays every take at its pitch. */
+    readonly pitch?: number;
+    /** Level of the sound (default 1). */
+    readonly gain?: number;
+    /** Default `{ model: 'inverse_square', k: 0.002, minGain: 0.002 }`: a recorded take already sounds near or far, so the curve is gentler than a recipe's. */
+    readonly falloff?: Falloff;
+    /** The lowpass cutoff is `20000 / (1 + d × cutoffK)` Hz (default 0.01: 10 kHz at 100 m). 0 turns the distance lowpass off. */
+    readonly cutoffK?: number;
+    /** Stereo pan from the listener (default true). */
+    readonly pan?: boolean;
+    readonly group?: string;
+    readonly priority?: number;
+    /**
+     * At most `voices` plays of this sound ring at once: a new one fades the oldest out in `fade` seconds (default 0.03) at its own start. Rapid fire
+     * then stays shot by shot instead of a wall of overlapping takes (criterion C9). Without it every play rings to its end.
+     */
+    readonly choke?: {
+        readonly voices: number;
+        readonly fade?: number;
+    };
+    /**
+     * A continuous sound (fire, rain, an engine idling) that `engine.loop(id)` plays: the near takes chained without a seam, each crossed into the next
+     * in `crossfade` seconds (default 0.25, equal power), never the same take twice in a row. While the files load, the recipe loop of `fallback`
+     * (or of the same id) plays. `play(id)` still plays one take as a one-shot.
+     */
+    readonly loop?: boolean | {
+        readonly crossfade?: number;
+    };
+    /** A recipe id the engine plays while the files are not loaded yet (or failed): the synthesized sound stays as the fallback. */
+    readonly fallback?: string;
+    /** Where each file came from: `"freesound:123456 autor CC0"`, or `"sdk"` for files the kit made. */
+    readonly sources: readonly string[];
+};
+
+/** 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;
+
+/**
+ * Sounds made of recorded files (`.ogg`), as data. A `SampleSound` lists the takes of each layer: `close` (the sound as heard near, the only one
+ * required), `far` (the same event heard from far away: a muffled bang with its echo) and the tail of the place it happens in (`indoor` / `outdoor`).
+ * `planSample` decides, from a seeded stream, which take plays (round-robin: never the same take twice in a row), the pitch (± a fraction), how the
+ * near and far layers cross over with the distance, the level, the pan and the distance lowpass. It is pure, so it runs in Node and in tests; the
+ * WebAudio layer (`realizeSample`) plays the plan from decoded buffers.
+ */
+
+declare const SAMPLE_ENVIRONMENTS: readonly ["indoor", "outdoor"];
+/** The role of a layer in a plan. */
+type SampleLayerRole = 'close' | 'far' | 'tail';
+declare const DEFAULT_SAMPLE_FALLOFF: Falloff;
+declare const DEFAULT_CROSSOVER: SampleCrossover;
+declare const DEFAULT_SAMPLE_PITCH = 0.04;
+declare const DEFAULT_TAIL_GAIN = 0.6;
+declare const DEFAULT_SAMPLE_CUTOFF_K = 0.01;
+/** The open lowpass: at or above it the realizer leaves the filter out. */
+declare const OPEN_CUTOFF = 20000;
+/** A layer quieter than this is left out of the plan. */
+declare const LAYER_FLOOR = 0.001;
+/** One file to play: which take, at what level (already times the sound level), rate and start. */
+type PlannedSampleLayer = {
+    readonly role: SampleLayerRole;
+    readonly url: string;
+    /** Index of the take in its list. */
+    readonly take: number;
+    readonly gain: number;
+    readonly rate: number;
+    readonly at: number;
+};
+type SamplePlan = {
+    readonly kind: 'sample';
+    readonly id: string;
+    readonly bus: BusId;
+    readonly level: number;
+    readonly distance: number;
+    readonly pan?: number;
+    /** Lowpass cutoff in Hz (`OPEN_CUTOFF` = no filter). */
+    readonly cutoff: number;
+    /** Playback rate of every layer (the pitch drawn for this play). */
+    readonly rate: number;
+    readonly environment: SampleEnvironment;
+    /** The tier played (`undefined` without tiers or intensity). */
+    readonly tier?: string;
+    /** 0 = all near, 1 = all far. */
+    readonly farMix: number;
+    readonly layers: readonly PlannedSampleLayer[];
+    readonly priority: number;
+    readonly group?: string;
+};
+/** The last take each sound layer played (`<id>/<role>` → index), so the next play never repeats it. Keep one per engine or channel. */
+type SampleMemory = Map<string, number>;
+type SamplePlanInput = {
+    readonly random: () => number;
+    readonly listener?: Listener;
+    readonly distanceMode?: DistanceMode;
+    readonly position?: Vec3;
+    /** Metres; overrides `position` for the distance (not for the pan). */
+    readonly distance?: number;
+    readonly volume?: number;
+    /** Default `outdoor`. */
+    readonly environment?: SampleEnvironment;
+    /** 0 (clear) to 1 (behind a wall): lowers the level and closes the lowpass. */
+    readonly occlusion?: number;
+    /** Round-robin memory; without it each plan is drawn on its own (and may repeat). */
+    readonly memory?: SampleMemory;
+    /** Limiter priority when the sound has none. */
+    readonly priority?: number;
+    /** 0 (light) to 1 (heavy): picks the tier (see `SampleTier`). */
+    readonly intensity?: number;
+};
+/**
+ * Round-robin without repeat: a take drawn among all but the last one played. With one take it is always 0; without `last` any take may come.
+ * One random number per call.
+ */
+declare function pickTake(count: number, last: number | undefined, random: () => number): number;
+/** 0 at or below `from`, 1 at or beyond `to`, linear between. */
+declare function farMixAt(crossover: SampleCrossover, distance: number): number;
+/** Equal-power gains of the near and far layers for a far mix (so the crossover has no dip in loudness). */
+declare function crossGains(farMix: number): {
+    readonly close: number;
+    readonly far: number;
+};
+/** The distance lowpass, closed further behind a wall (an occluded sound loses its highs first). */
+declare function sampleCutoff(cutoffK: number, distance: number, occlusion?: number): number;
+/** Every file a sound may play (to load before its first play). */
+declare function sampleUrls(sound: SampleSound): string[];
+/** The tier for an intensity: the last whose `from` is at or below it. */
+declare function tierFor(sound: SampleSound, intensity: number | undefined): SampleTier | undefined;
+/**
+ * The plan of one play, or `null` when the sound is too far to be heard. Random numbers, in order: the pitch, the near take, the far take, the
+ * tail take (each drawn only when that layer has more than zero takes and is heard).
+ */
+declare function planSample(sound: SampleSound, input: SamplePlanInput): SamplePlan | null;
+
+/**
+ * Decoded sample buffers by url. Files load once (concurrent asks share the same promise), decode on the engine's context and stay until `clear`.
+ * The bytes come from a `SampleLoader`: `fetch` by default, or anything else (a single-file page passes the files inlined as base64).
+ */
+/** Gets the bytes of a file. */
+type SampleLoader = (url: string) => Promise<ArrayBuffer>;
+type SampleStatus = 'none' | 'loading' | 'ready' | 'failed';
+type SampleLoadReport = {
+    readonly loaded: readonly string[];
+    readonly failed: readonly {
+        readonly url: string;
+        readonly error: string;
+    }[];
+};
+type SampleStore = {
+    status(url: string): SampleStatus;
+    /** The decoded buffer, once ready. */
+    buffer(url: string): AudioBuffer | undefined;
+    /** Whether every url is ready. */
+    ready(urls: readonly string[]): boolean;
+    load(urls: readonly string[], context: BaseAudioContext): Promise<SampleLoadReport>;
+    /** Seconds of the decoded file, or `undefined` while not ready. */
+    seconds(url: string): number | undefined;
+    clear(): void;
+};
+/** `fetch` relative to `baseUrl` (default the page). */
+declare function fetchLoader(baseUrl?: string): SampleLoader;
+/** Bytes of files given inline as base64 (or `data:` urls), by url. */
+declare function inlineLoader(files: Readonly<Record<string, string>>): SampleLoader;
+declare function createSampleStore(loader?: SampleLoader): SampleStore;
+
+type BusSetting = {
+    readonly gain?: number;
+    readonly muted?: boolean;
+};
+/**
+ * A mixing chain. `master` → (compressor) → (limiter) → 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;
+    };
+    /**
+     * A last stage after the compressor that keeps every peak under `ceiling` dBFS: below `knee` dBFS the sound passes untouched, above it the peak
+     * bends smoothly toward the ceiling (a soft clipper, no lookahead and no delay), so a blast with its debris and a fire catching all at once never
+     * clips the output. `range` is the loudest input it shapes, as a factor of full scale (default 4, +12 dB); louder is held at the ceiling.
+     */
+    readonly limiter?: {
+        readonly ceiling: number;
+        readonly knee: number;
+        readonly range?: 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) with a limiter at the end (`kit`); `mix: 'art_scene'` is the page as it was, `mix: 'game'` the game's. */
+declare const DEFAULT_MIX = "kit";
+/** 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> | DeepPartial<SampleSound>): void;
+    remove(id: string): void;
+    sound(id: string): SoundRecipe | undefined;
+    loop(id: string): LoopRecipe | undefined;
+    /** The set an id names (`SoundBank.sets`), if any; a recipe with the same id wins in `play`. */
+    set(id: string): SoundSet | undefined;
+    sample(id: string): SampleSound | undefined;
+    soundIds(): string[];
+    setIds(): string[];
+    loopIds(): string[];
+    sampleIds(): string[];
+    /** Which bank each id came from. */
+    bankOf(id: string): string | undefined;
+};
+declare function createSoundRegistry(banks?: readonly SoundBank[]): SoundRegistry;
+
+/**
+ * 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;
+
+/**
+ * What one `set` changes. `volume` and `frequency` glide as in the team loops. `position` places the loop: with a recipe `falloff` the level falls
+ * with the distance from the listener (and the cutoff with `cutoffK`), with `pan` it goes to the listener's side. `cutoff` glides the first filter
+ * (an engine opening up under load, a skid getting brighter).
+ */
+type LoopSet = {
+    readonly volume?: number;
+    readonly frequency?: number;
+    readonly position?: Vec3;
+    readonly cutoff?: number;
+};
+/** A continuous sound: `set` glides the volume and, for an oscillator, the frequency; `stop` tears the nodes down. */
+type AudioLoopHandle = {
+    set(state: LoopSet): void;
+    stop(): void;
+};
+type LoopEntry = {
+    rewire(): void;
+    stop(): void;
+    readonly created: boolean;
+};
+
+type StartQueueOptions = {
+    /** Most milliseconds of main-thread work one task spends building voices (at least one voice is always built). Default 2. */
+    readonly budgetMs?: number;
+    /** A voice still waiting after this many milliseconds is dropped instead of starting late. Default 250. */
+    readonly maxLatencyMs?: number;
+};
+
+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;
+    /** Built now instead of waiting in the engine's deferred start queue: for a sound that has to land on the frame the player sees it (a blow's
+     * contact, a heel strike, a landing). The queue builds a voice on the next frame budget and drops it after its latency, which at a low frame
+     * rate is late or silent. Default false. */
+    readonly urgent?: boolean;
+    /** A named stream of the engine (`streamFor(seed, name)`), so one subject never shifts another's sounds. */
+    readonly channel?: string;
+    /** The tail a sample sound plays (default the engine's, see `setEnvironment`). */
+    readonly environment?: SampleEnvironment;
+    /** 0 (light) to 1 (heavy): the tier of takes a sample sound plays (criterion C7). */
+    readonly intensity?: number;
+    /** 0 (clear) to 1 (behind a wall) for this play, over the engine's `occlusion` (a test bench puts a wall in between). Sample sounds only. */
+    readonly occlusion?: number;
+};
+/** A playing voice: a recipe (`kind: 'recipe'`, the plan of the synthesized sound) or files (`kind: 'sample'`). */
+type VoiceHandle = {
+    readonly id: number;
+    readonly kind: 'recipe';
+    readonly plan: SoundPlan;
+    stop(): void;
+} | {
+    readonly id: number;
+    readonly kind: 'sample';
+    readonly plan: SamplePlan;
+    stop(): void;
+};
+/**
+ * A voice that started, for measuring (criterion C1: the event against the start of the sound). Times are the context clock, in seconds:
+ * `requestedAt` when `play` was called, `startAt` when the first sample of the sound leaves the engine; `outputLatency` is what the device adds
+ * after that (`baseLatency + outputLatency` of the context, 0 when unknown).
+ */
+type VoiceStartEvent = {
+    readonly id: string;
+    readonly kind: 'recipe' | 'sample';
+    /** The sample sound this recipe stood in for while its files were not loaded. */
+    readonly fallbackOf?: string;
+    readonly requestedAt: number;
+    readonly startAt: number;
+    readonly outputLatency: number;
+    readonly level: number;
+    readonly distance: number;
+    readonly pan?: number;
+    /** The files a sample voice plays, by layer. */
+    readonly layers?: readonly {
+        readonly role: string;
+        readonly url: string;
+        readonly take: number;
+        readonly rate: number;
+    }[];
+    /** The tier of takes a sample voice played (criterion C7). */
+    readonly tier?: string;
+};
+type SampleOptions = {
+    /** Gets the bytes of a file (default `fetch`, relative to `baseUrl`). */
+    readonly loader?: SampleLoader;
+    readonly baseUrl?: string;
+    /** Load a sound's files the first time it is played (default true); the fallback plays meanwhile. */
+    readonly autoLoad?: boolean;
+    /**
+     * The peak limiter every sample voice of a bus goes through before the bus (criteria C6 and C9: no sound and no burst goes over −1 dBFS): linear
+     * up to `knee` (default 0.5, −6 dBFS), then bent smoothly to `ceiling` (default 0.891, −1 dBFS), with no delay. `false` leaves it out.
+     */
+    readonly limiter?: false | {
+        readonly knee?: number;
+        readonly ceiling?: number;
+    };
+};
+/** 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;
+    /** Build voices in timed slices between frames instead of inside `play` (a sound starts a few ms late; a burst never costs a frame). Off by default. */
+    readonly deferredStart?: StartQueueOptions;
+    /** Where sample sounds get their files. */
+    readonly samples?: SampleOptions;
+    /** The tail sample sounds play when `play` names none (default `outdoor`). */
+    readonly environment?: SampleEnvironment;
+    /** Called when a voice is built (recipe or sample): the measuring hook of the criteria. */
+    readonly onVoiceStart?: (event: VoiceStartEvent) => void;
+};
+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;
+    /** Pure: the plan a sample sound would play with (no round-robin memory), from `options.seed` or the engine seed. */
+    planSample(id: string, options?: PlayOptions): SamplePlan | null;
+    /** Loads the files of these sample sounds (default all registered). Creates the context; resolves when every file is decoded or failed. */
+    loadSamples(ids?: readonly string[]): Promise<SampleLoadReport>;
+    /** `ready` when every file of the sound is decoded. */
+    sampleStatus(id: string): SampleStatus;
+    /** The tail sample sounds play from now on. */
+    setEnvironment(environment: SampleEnvironment): void;
+    /** The node everything is mixed into before the speakers (to record or meter the whole output), or `null` before the context exists. */
+    output(): AudioNode | null;
+    /** Another place files come from: urls `accepts` takes go to `loader`, the rest to the engine's own (a bench lends its calibration takes). */
+    addSampleSource(accepts: (url: string) => boolean, loader: SampleLoader): void;
+    /** Follows every voice built from now on (as `onVoiceStart` does); returns the unsubscribe function. */
+    watchVoices(listener: (event: VoiceStartEvent) => void): () => void;
+    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;
+    /** Creates the context, the mixing chain (reverb impulse included) and the shared noise buffer now, so the first sound does not pay for them inside a frame. Returns false without a context. */
+    warmUp(): boolean;
+    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;
+    /**
+     * The voice start queue as a `DeferredQueue` for a shared frame budget (`budget.register` attaches it and the queue stops scheduling its own tasks), or `null`
+     * without `deferredStart`. Asking for it changes nothing.
+     */
+    deferredQueue?(): DeferredQueue | null;
+    dispose(): void;
+};
+/** The limiter's transfer curve over ±`range`: linear up to `knee`, then a tanh bend that never passes `ceiling`. */
+declare function limiterCurve(knee: number, ceiling: number, range: number, points?: number): Float32Array<ArrayBuffer>;
+/**
+ * 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;
+
+/**
+ * The measuring harness of the sound criteria (C1–C10 of the sound checklist). Each criterion plays the sound through a real engine on an
+ * `OfflineAudioContext` (the same mix, limiter and realizer the game uses, rendered faster than real time), and measures the rendered output: when it
+ * starts against the event, how loud and bright it is at each distance, which side, how many takes, how it ends. Runs in a browser (or anything with
+ * an `OfflineAudioContext`); C10 is the owner's ear, so it is left open with a recording to listen to (`recordOutput`).
+ */
+
+declare const CRITERIA: readonly ["C1", "C2", "C3", "C4", "C5", "C6", "C7", "C8", "C9", "C10"];
+type CriterionId = (typeof CRITERIA)[number];
+/** The targets of the checklist, as numbers the harness compares with. */
+declare const CRITERIA_TARGETS: {
+    /** C1: event to the first sample, and onset to the peak (one 60 fps frame). */
+    readonly syncMs: 20;
+    readonly peakAfterOnsetMs: number;
+    /** C3: distances measured, metres. */
+    readonly distances: readonly number[];
+    /** C5: plays, distinct takes and the pitch range (fraction). */
+    readonly plays: 10;
+    readonly minTakes: 4;
+    readonly pitch: readonly [0.03, 0.05];
+    /** C6: the highest peak, dBFS. */
+    readonly peakDb: -1;
+    /** C8: the end of each file against its peak, dB. */
+    readonly endDropDb: -40;
+    /** C9: a burst of rapid fire. */
+    readonly burst: 20;
+    readonly burstSpacing: 0.06;
+};
+type CriterionResult = {
+    readonly id: CriterionId;
+    /** `null`: not decided by the harness (C10, the owner's ear). */
+    readonly pass: boolean | null;
+    /** What was measured, short (the bench prints it). */
+    readonly value: string;
+    readonly target: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+};
+/** One action of the game and the sound it must play (C2). */
+type ActionCheck = {
+    readonly action: string;
+    readonly play: string;
+    readonly expect: string;
+    readonly options?: PlayOptions;
+};
+type MeasureOptions = {
+    /** The sample sound measured. */
+    readonly sound: string;
+    readonly banks: readonly SoundBank[];
+    readonly loader: SampleLoader;
+    /** The mixing chain the game uses (default the engine's default). */
+    readonly mix?: string | MixProfile;
+    readonly sampleRate?: number;
+    /** `new OfflineAudioContext(...)` by default. */
+    readonly createOfflineContext?: (channels: number, length: number, sampleRate: number) => OfflineAudioContext;
+    /** The live context's `baseLatency` (s), added to the rendered delay for C1. */
+    readonly baseLatency?: number;
+    /** The device's `outputLatency` (s), reported with C1 but not counted (it is the speakers', not the game's). */
+    readonly outputLatency?: number;
+    /** C2: the actions to check (default the sound for itself). */
+    readonly actions?: readonly ActionCheck[];
+    /** C6: sound ids loudest first, the order the buses must keep (tiro > explosão > impacto > passo). */
+    readonly loudnessOrder?: readonly string[];
+};
+/** Runs the criteria (all by default) and returns one result each, in order. C10 is always open: it is the owner's ear on a recording. */
+declare function measureCriteria(options: MeasureOptions, only?: readonly CriterionId[]): Promise<CriterionResult[]>;
+/**
+ * Records what the engine outputs while `act` plays, `seconds` long (the C10 recording): a `MediaRecorder` on a stream tapped from the master. Returns
+ * `null` where there is no recorder or no context.
+ */
+declare function recordOutput(engine: AudioEngine, seconds: number, act: () => void): Promise<Blob | null>;
+
+/**
+ * The sounds a game needs, by category, as the sound checklist lists them (generic, real-world names: a 9 mm pistol, a wooden door): the id a file
+ * takes, its priority and the synthesized sound it replaces today (`current`, the A of an A/B). A sound is "file" once a bank registers a sample under
+ * its id; "synth" while only `current` exists; "missing" when neither does. Data only: a game adds, renames or drops entries without touching the engine.
+ */
+declare const SFX_CATEGORIES: readonly ["armas", "impactos", "explosoes-fogo", "personagem", "veiculos", "itens-portas", "ambiente"];
+type SfxCategory = (typeof SFX_CATEGORIES)[number];
+type SfxPriority = 1 | 2 | 3;
+type SfxEntry = {
+    readonly id: string;
+    readonly category: SfxCategory;
+    readonly priority: SfxPriority;
+    /** The synthesized sound playing in its place today (a recipe id of some bank), if any. */
+    readonly current?: string;
+};
+declare const SFX_CATALOG: readonly SfxEntry[];
+/** The materials of the impact matrix, with the group whose synthesized sound plays for them today. */
+declare const SFX_MATERIALS: readonly [readonly ["steel", "metal"], readonly ["aluminium", "metal"], readonly ["wood", "wood"], readonly ["plywood", "wood"], readonly ["mdf", "wood"], readonly ["glass", "glass"], readonly ["tempered_glass", "glass"], readonly ["ceramic", "glass"], readonly ["concrete", "masonry"], readonly ["brick", "masonry"], readonly ["plaster", "masonry"], readonly ["plastic", "soft"], readonly ["fabric", "soft"], readonly ["paper", "soft"], readonly ["foliage", "soft"], readonly ["soil", "soft"], readonly ["flesh", "soft"]];
+type SfxMaterial = (typeof SFX_MATERIALS)[number][0];
+declare const SFX_BLOWS: readonly ["bullet", "blunt", "blade", "break", "drag"];
+type SfxBlow = (typeof SFX_BLOWS)[number];
+/** The id a file of the matrix takes: `impact_<material>_<blow>` (`impact_concrete_bullet`). */
+declare const impactSoundId: (material: SfxMaterial, blow: SfxBlow) => string;
+/** The impact matrix as entries (the `impactos` category of the catalogue). */
+declare const SFX_IMPACTS: readonly SfxEntry[];
+/** Where an entry stands in an engine: a file registered (`file`), only the synthesized sound (`synth`), or nothing (`missing`). */
+type SfxState = 'file' | 'synth' | 'missing';
+declare function sfxState(entry: SfxEntry, has: {
+    sample(id: string): unknown;
+    sound(id: string): unknown;
+}): SfxState;
+
+/**
+ * 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;
+    /**
+     * Draws the thing the probe stands for, where the sound comes from with the `probe` source (for example a portable radio of `game-items-three`). The module
+     * draws nothing of its own: without it the area has no probe and the sounds come from the bench settings.
+     */
+    probe?: (THREE: unknown) => unknown;
+};
+/** 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 { LAYER_FLOOR as $, type AudioLoopHandle as A, type BusId as B, CRITERIA as C, type CriterionId as D, type CriterionResult as E, type Falloff as F, type Curve as G, DEFAULT_CROSSOVER as H, DEFAULT_LISTENER as I, DEFAULT_MAX_VOICES as J, DEFAULT_MIX as K, type LoopRecipe as L, type MixProfile as M, DEFAULT_SAMPLE_CUTOFF_K as N, DEFAULT_SAMPLE_FALLOFF as O, type ParamRef as P, DEFAULT_SAMPLE_PITCH as Q, type Range as R, type SampleSound as S, DEFAULT_TAIL_GAIN as T, type DeepPartial as U, type DistanceMode as V, type Envelope as W, type EnvelopePoint as X, type FilterBank as Y, type FilterSpec as Z, type FormantVoiceSource as _, type SampleLoader as a, createSoundRegistry as a$, type LayerSource as a0, type Listener as a1, type LoopOrder as a2, type LoopSet as a3, MIX_PROFILES as a4, type MeasureOptions as a5, type Modulator as a6, type NoiseSource as a7, OPEN_CUTOFF as a8, type OscSource as a9, type SampleTail as aA, type SampleTier as aB, type SfxBlow as aC, type SfxCategory as aD, type SfxEntry as aE, type SfxMaterial as aF, type SfxPriority as aG, type SfxState as aH, type SoundRegistry as aI, type StartQueueOptions as aJ, type Time as aK, VOICE_GROUPS as aL, type VoiceDecision as aM, type VoiceGroup as aN, type VoiceHandle as aO, type VoiceManager as aP, type VoiceManagerOptions as aQ, type VoiceRefusal as aR, type VoiceRequest as aS, type VoiceStartEvent as aT, type VoiceStats as aU, audioBenchTextOf as aV, busGain as aW, busPriority as aX, createAudioEngine as aY, createAudioTestModule as aZ, createSampleStore as a_, PAN_LIMIT as aa, PAN_MIN_DISTANCE as ab, type PlanInput as ac, type PlannedAutomation as ad, type PlannedEnvelopePoint as ae, type PlannedFilter as af, type PlannedLayer as ag, type PlannedModulator as ah, type PlannedSampleLayer as ai, type PlannedSource as aj, type PlayOptions as ak, SAMPLE_ENVIRONMENTS as al, SFX_BLOWS as am, SFX_CATALOG as an, SFX_CATEGORIES as ao, SFX_IMPACTS as ap, SFX_MATERIALS as aq, type SampleEnvironment as ar, type SampleLayerRole as as, type SampleLoadReport as at, type SampleMemory as au, type SampleOptions as av, type SamplePlanInput as aw, type SampleRef as ax, type SampleStatus as ay, type SampleStore as az, type SampleCrossover as b, createVoiceManager as b0, crossGains as b1, farMixAt as b2, fetchLoader as b3, impactSoundId as b4, inlineLoader as b5, limiterCurve as b6, listenerDistance as b7, measureCriteria as b8, panFor as b9, pickTake as ba, planSample as bb, planSound as bc, recordOutput as bd, resolveMix as be, sampleCutoff as bf, sampleUrls as bg, sfxState as bh, tierFor as bi, type SoundBank as c, type SoundRecipe as d, type Layer as e, type SoundSet as f, type SoundPlan as g, type SamplePlan as h, type LoopEntry as i, type AudioEngine as j, type ActionCheck as k, type AudioBenchText as l, type AudioChannel as m, type AudioEngineOptions as n, type AudioScenarioLike as o, type AudioStats as p, type AudioTestModule as q, type AudioTestModuleOptions as r, type Automation as s, BENCH_BANK as t, BUILD_ORDERS as u, BUS_IDS as v, BUS_PRIORITY as w, type BuildOrder as x, type BusSetting as y, CRITERIA_TARGETS as z };