@adatechnology/game-audio 0.8.0 → 0.9.1

package/dist/{locale-BJMhMT0G.d.ts → locale-YHyJwN2P.d.ts}

@@ -1,372 +1,119 @@
+import { B as BusId, q as SampleEnvironment, p as SampleCrossover, F as Falloff, c as SampleSound, t as SampleTier, h as BuildOrder, C as Curve, b as SoundRecipe, S as SoundRegistry, a as SoundBank } from './bank-Dsj1VAht.js';
 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;
+/** 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;
+
 /**
- * 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.
+ * 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.
  */
-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';
+
+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;
+    /** Seconds into the file (the take's trim). */
+    readonly offset?: number;
+    /** Seconds of the file played (the take's trim). */
+    readonly duration?: number;
 };
-/**
- * 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 = {
+type SamplePlan = {
+    readonly kind: 'sample';
     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 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;
-    /** 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`). */
+/** 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;
-    /**
-     * 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[];
-    /**
-     * Ids of this bank that play the takes of a sample sound registered by another bank (a manifest's file id), resolved when the id is looked up, so
-     * the order the banks register in does not matter. A sample of the alias's own id, when one is registered, wins.
-     */
-    readonly sampleAliases?: readonly SampleAlias[];
+    /** 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;
 };
 /**
- * One id answered by the takes of another sample sound (`file`): `engine_car_low` by `engine_loop_car_idle`. The other numbers replace the file's;
- * `offset` and `duration` trim every take (one recording holding the start, the run and the stop gives each its own id). The recipe or loop of `id`
- * stays as the fallback while the files load or where they are missing.
+ * 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.
  */
-type SampleAlias = {
-    readonly id: string;
-    readonly file: string;
-    readonly offset?: number;
-    readonly duration?: number;
-    readonly loop?: SampleSound['loop'];
-    readonly baseFrequency?: number;
-    readonly gain?: number;
-    readonly pitch?: number;
-    readonly falloff?: Falloff;
-};
-/** One take: a file and its own trim (linear gain, default 1). */
-type SampleRef = {
-    readonly url: string;
-    readonly gain?: number;
-    /** Seconds into the file the take starts at (default 0). A looping take starts there the first time round. */
-    readonly offset?: number;
-    /** Seconds of the file the take plays (default to its end); a trimmed one-shot fades out over its last 40 ms, so the cut does not click. */
-    readonly duration?: 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;
+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;
 /**
- * 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`.
+ * 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).
  */
-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;
-    };
-    /**
-     * The frequency the recording of a loop sounds at (an engine's firing frequency at the RPM it was recorded at): `set({ frequency })` then plays
-     * the takes at `frequency / baseFrequency`, gliding, as an oscillator loop follows it. Without it the loop keeps the pitch of its files.
-     */
-    readonly baseFrequency?: 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[];
-    /** The licence of the files when one is declared (a local pack's entry); the sound panel lists those that are not CC0 / CC-BY. */
-    readonly license?: 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;
+declare function planSample(sound: SampleSound, input: SamplePlanInput): SamplePlan | null;
 
 /** How an AudioParam moves, with every number resolved and every time in seconds from the layer start. */
 type PlannedAutomation = {
@@ -480,105 +227,6 @@ type PlanInput = {
  */
 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;
-    /** Seconds into the file (the take's trim). */
-    readonly offset?: number;
-    /** Seconds of the file played (the take's trim). */
-    readonly duration?: 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).
@@ -660,35 +308,6 @@ declare function resolveMix(mix: string | MixProfile, profiles?: Readonly<Record
 /** 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;
-    /** Drops only the sample sound of an id; a recipe or loop of the same id stays. */
-    removeSample(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;
-    /** The sample sound of an id: its own, or the takes of the sound a bank's `sampleAliases` points it at (once that one is registered). */
-    sample(id: string): SampleSound | undefined;
-    soundIds(): string[];
-    setIds(): string[];
-    loopIds(): string[];
-    /** Every id `sample` answers, aliases whose file is registered included. */
-    sampleIds(): string[];
-    /** Which bank each id came from. */
-    bankOf(id: string): string | undefined;
-};
-/** The sample an alias names: the file's takes and numbers, with the alias's id and its own numbers; the recipe of the alias id is the fallback. */
-declare function aliasSample(alias: SampleAlias, file: SampleSound): SampleSound;
-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);
@@ -901,7 +520,10 @@ type AudioEngine = {
     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. */
+    /**
+     * Loads the files of these sample sounds (default all registered). Creates the context; resolves when every file is decoded or failed. An id named
+     * here that has no files yet (its manifest not registered) loads as soon as a bank that resolves it registers.
+     */
     loadSamples(ids?: readonly string[]): Promise<SampleLoadReport>;
     /** `ready` when every file of the sound is decoded. */
     sampleStatus(id: string): SampleStatus;
@@ -1293,4 +915,4 @@ type AudioBenchText = {
 };
 declare const audioBenchTextOf: (locale: string) => AudioBenchText;
 
-export { type FilterSpec as $, type AudioEngine as A, type BusId as B, type BusSetting as C, type DistanceMode as D, CRITERIA as E, type Falloff as F, CRITERIA_TARGETS as G, type CriterionId as H, type CriterionResult as I, type Curve as J, DEFAULT_CROSSOVER as K, type LoopRecipe as L, type MixProfile as M, DEFAULT_LISTENER as N, DEFAULT_MAX_VOICES as O, type ParamRef as P, DEFAULT_MIX as Q, type Range as R, type SampleSound as S, DEFAULT_SAMPLE_CUTOFF_K as T, DEFAULT_SAMPLE_FALLOFF as U, DEFAULT_SAMPLE_PITCH as V, DEFAULT_TAIL_GAIN as W, type DeepPartial as X, type Envelope as Y, type EnvelopePoint as Z, type FilterBank as _, type SampleLoader as a, USER_SOUND_PREFIX as a$, type FormantVoiceSource as a0, KIT_SAMPLES_BANK as a1, LAYER_FLOOR as a2, type LayerSource as a3, type LoadUserSamplesOptions as a4, type LoopOrder as a5, type LoopSet as a6, MIX_PROFILES as a7, type MeasureOptions as a8, type Modulator as a9, type SampleEnvironment as aA, type SampleLayerRole as aB, type SampleLoadReport as aC, type SampleMemory as aD, type SampleOptions as aE, type SamplePlanInput as aF, type SampleRef as aG, type SampleStatus as aH, type SampleStore as aI, type SampleTail as aJ, type SampleTier as aK, type SdkLicense as aL, type SfxBlow as aM, type SfxCategory as aN, type SfxEntry as aO, type SfxFileEntry as aP, type SfxLayer as aQ, type SfxManifestLike as aR, type SfxManifestSound as aS, type SfxMaterial as aT, type SfxPriority as aU, type SfxState as aV, type SoundRegistry as aW, type SoundSource as aX, type StartQueueOptions as aY, type Time as aZ, USER_SAMPLES_BANK as a_, type NoiseSource as aa, OPEN_CUTOFF as ab, type OscSource as ac, PAN_LIMIT as ad, PAN_MIN_DISTANCE as ae, type PlanInput as af, type PlannedAutomation as ag, type PlannedEnvelopePoint as ah, type PlannedFilter as ai, type PlannedLayer as aj, type PlannedModulator as ak, type PlannedSampleLayer as al, type PlannedSource as am, type PlayOptions as an, SAMPLE_ENVIRONMENTS as ao, SDK_LICENSES as ap, SFX_BLOWS as aq, SFX_CATALOG as ar, SFX_CATEGORIES as as, SFX_IMPACTS as at, SFX_LAYERS as au, SFX_MATERIALS as av, SFX_TIERS as aw, type SampleAlias as ax, type SampleBankOptions as ay, type SampleCrossover as az, type SfxManifest as b, type UserSampleBankOptions as b0, type UserSampleBankResult as b1, type UserSfxFile as b2, type UserSfxManifest as b3, type UserSfxSound as b4, type UserSoundPick as b5, type UserSoundPicks as b6, type UserSoundRole as b7, VOICE_GROUPS as b8, type VoiceDecision as b9, panFor as bA, parseSfxName as bB, pickTake as bC, planSample as bD, planSound as bE, recordOutput as bF, resolveMix as bG, sampleBankFromManifest as bH, sampleCutoff as bI, sampleUrls as bJ, sfxState as bK, soundSourceOf as bL, splitTier as bM, tierFor as bN, userSampleBank as bO, type VoiceGroup as ba, type VoiceHandle as bb, type VoiceManager as bc, type VoiceManagerOptions as bd, type VoiceRefusal as be, type VoiceRequest as bf, type VoiceStartEvent as bg, type VoiceStats as bh, aliasSample as bi, audioBenchTextOf as bj, busGain as bk, busPriority as bl, createAudioEngine as bm, createAudioTestModule as bn, createSampleStore as bo, createSoundRegistry as bp, createVoiceManager as bq, crossGains as br, farMixAt as bs, fetchLoader as bt, impactSoundId as bu, inlineLoader as bv, limiterCurve as bw, listenerDistance as bx, loadUserSamples as by, measureCriteria as bz, type SoundBank as c, type SampleDefaults as d, type SoundRecipe as e, type Layer as f, type SoundSet as g, type SoundPlan as h, type SamplePlan as i, type AudioLoopHandle as j, type LoopEntry as k, type Listener as l, type ActionCheck as m, type AudioBenchText as n, type AudioChannel as o, type AudioEngineOptions as p, type AudioScenarioLike as q, type AudioStats as r, type AudioTestModule as s, type AudioTestModuleOptions as t, type Automation as u, BENCH_BANK as v, BUILD_ORDERS as w, BUS_IDS as x, BUS_PRIORITY as y, type BuildOrder as z };
+export { SDK_LICENSES as $, type AudioEngine as A, BENCH_BANK as B, CRITERIA as C, type DistanceMode as D, DEFAULT_TAIL_GAIN as E, LAYER_FLOOR as F, type LoadUserSamplesOptions as G, type LoopSet as H, MIX_PROFILES as I, type MeasureOptions as J, KIT_SAMPLES_BANK as K, type LoopEntry as L, type MixProfile as M, PAN_MIN_DISTANCE as N, OPEN_CUTOFF as O, PAN_LIMIT as P, type PlanInput as Q, type PlannedAutomation as R, type SampleLoader as S, type PlannedEnvelopePoint as T, type PlannedFilter as U, type PlannedLayer as V, type PlannedModulator as W, type PlannedSampleLayer as X, type PlannedSource as Y, type PlayOptions as Z, SAMPLE_ENVIRONMENTS as _, type SfxManifest as a, measureCriteria as a$, SFX_BLOWS as a0, SFX_CATALOG as a1, SFX_CATEGORIES as a2, SFX_IMPACTS as a3, SFX_LAYERS as a4, SFX_MATERIALS as a5, SFX_TIERS as a6, type SampleBankOptions as a7, type SampleLayerRole as a8, type SampleLoadReport as a9, type UserSoundPicks as aA, type UserSoundRole as aB, VOICE_GROUPS as aC, type VoiceDecision as aD, type VoiceGroup as aE, type VoiceHandle as aF, type VoiceManager as aG, type VoiceManagerOptions as aH, type VoiceRefusal as aI, type VoiceRequest as aJ, type VoiceStartEvent as aK, type VoiceStats as aL, audioBenchTextOf as aM, busGain as aN, busPriority as aO, createAudioEngine as aP, createAudioTestModule as aQ, createSampleStore as aR, createVoiceManager as aS, crossGains as aT, farMixAt as aU, fetchLoader as aV, impactSoundId as aW, inlineLoader as aX, limiterCurve as aY, listenerDistance as aZ, loadUserSamples as a_, type SampleMemory as aa, type SampleOptions as ab, type SamplePlanInput as ac, type SampleStatus as ad, type SampleStore as ae, type SdkLicense as af, type SfxBlow as ag, type SfxCategory as ah, type SfxEntry as ai, type SfxFileEntry as aj, type SfxLayer as ak, type SfxManifestLike as al, type SfxManifestSound as am, type SfxMaterial as an, type SfxPriority as ao, type SfxState as ap, type SoundSource as aq, type StartQueueOptions as ar, USER_SAMPLES_BANK as as, USER_SOUND_PREFIX as at, type UserSampleBankOptions as au, type UserSampleBankResult as av, type UserSfxFile as aw, type UserSfxManifest as ax, type UserSfxSound as ay, type UserSoundPick as az, type SampleDefaults as b, panFor as b0, parseSfxName as b1, pickTake as b2, planSample as b3, planSound as b4, recordOutput as b5, resolveMix as b6, sampleBankFromManifest as b7, sampleCutoff as b8, sampleUrls as b9, sfxState as ba, soundSourceOf as bb, splitTier as bc, tierFor as bd, userSampleBank as be, type SoundPlan as c, type SamplePlan as d, type AudioLoopHandle as e, type Listener as f, type ActionCheck as g, type AudioBenchText as h, type AudioChannel as i, type AudioEngineOptions as j, type AudioScenarioLike as k, type AudioStats as l, type AudioTestModule as m, type AudioTestModuleOptions as n, BUS_PRIORITY as o, type BusSetting as p, CRITERIA_TARGETS as q, type CriterionId as r, type CriterionResult as s, DEFAULT_CROSSOVER as t, DEFAULT_LISTENER as u, DEFAULT_MAX_VOICES as v, DEFAULT_MIX as w, DEFAULT_SAMPLE_CUTOFF_K as x, DEFAULT_SAMPLE_FALLOFF as y, DEFAULT_SAMPLE_PITCH as z };