@adatechnology/game-audio 0.4.0 → 0.6.0

package/dist/testing-BZQid7h0.d.ts

@@ -1,653 +0,0 @@
-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;
-    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[];
-};
-
-/** 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;
-
-/**
- * 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;
-
-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;
-    /** The set an id names (`SoundBank.sets`), if any; a recipe with the same id wins in `play`. */
-    set(id: string): SoundSet | undefined;
-    soundIds(): string[];
-    setIds(): string[];
-    loopIds(): string[];
-    /** Which bank each id came from. */
-    bankOf(id: string): string | undefined;
-};
-declare function createSoundRegistry(banks?: readonly SoundBank[]): SoundRegistry;
-
-/** 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 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;
-    /** 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;
-    /** 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;
-};
-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;
-    /** 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 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;
-
-/**
- * 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 { type PlannedSource as $, type AudioEngine as A, type BusId as B, type Curve as C, DEFAULT_LISTENER as D, type Envelope as E, type Falloff as F, type FormantVoiceSource as G, type LayerSource as H, type Listener as I, type LoopOrder as J, MIX_PROFILES as K, type LoopRecipe as L, type MixProfile as M, type Modulator as N, type NoiseSource as O, type ParamRef as P, type OscSource as Q, type Range as R, type SoundBank as S, PAN_LIMIT as T, PAN_MIN_DISTANCE as U, type PlanInput as V, type PlannedAutomation as W, type PlannedEnvelopePoint as X, type PlannedFilter as Y, type PlannedLayer as Z, type PlannedModulator as _, type SoundRecipe as a, type PlayOptions as a0, type SoundRegistry as a1, type StartQueueOptions as a2, type Time as a3, VOICE_GROUPS as a4, type VoiceDecision as a5, type VoiceGroup as a6, type VoiceHandle as a7, type VoiceManager as a8, type VoiceManagerOptions as a9, type VoiceRefusal as aa, type VoiceRequest as ab, type VoiceStats as ac, audioBenchTextOf as ad, busGain as ae, busPriority as af, createAudioEngine as ag, createAudioTestModule as ah, createSoundRegistry as ai, createVoiceManager as aj, listenerDistance as ak, panFor as al, planSound as am, resolveMix as an, type Layer as b, type SoundSet as c, type SoundPlan as d, type AudioBenchText as e, type AudioChannel as f, type AudioEngineOptions as g, type AudioLoopHandle as h, type AudioScenarioLike as i, type AudioStats as j, type AudioTestModule as k, type AudioTestModuleOptions as l, type Automation as m, BENCH_BANK as n, BUILD_ORDERS as o, BUS_IDS as p, BUS_PRIORITY as q, type BuildOrder as r, type BusSetting as s, DEFAULT_MAX_VOICES as t, DEFAULT_MIX as u, type DeepPartial as v, type DistanceMode as w, type EnvelopePoint as x, type FilterBank as y, type FilterSpec as z };