@adatechnology/game-audio 0.7.0 → 0.9.0

package/README.md

@@ -103,5 +103,73 @@ engine.play('pistol_9mm', { position: [10, 0, -40], environment: 'indoor', delay
 - Each play: a take drawn among all but the last one (round-robin, never twice in a row), the rate ± `pitch` (default 4 %), the level by `falloff`, a lowpass by distance (`cutoffK`) and behind a wall (`occlusion`), the pan.
 - Sample voices of a bus go through a zero-delay limiter (ceiling −1 dBFS); `choke: { voices }` fades the oldest plays of a sound for rapid fire.
 - `onVoiceStart` reports every voice (recipe or sample, the files and takes, `requestedAt` / `startAt`): the event log the criteria measure.
-- Files: drop them in `assets/sfx-inbox/<categoria>/` with a line in its `CREDITOS.md` and run `pnpm --filter @adatechnology/game-audio sfx:convert` (ffmpeg): Ogg Vorbis mono 48 kHz, −1 dBFS peak, attack on the first ms, `manifest.json` and `CREDITOS.md`. Only CC0 and CC-BY go into the SDK.
+- **The kit's default sounds ship with it**: `assets/sfx/<categoria>/<nome>.ogg` (1050 takes, CC0 and CC-BY only), with `assets/sfx/manifest.json`
+  (sound id → path, with source, author and licence) and `assets/sfx/CREDITOS.md` (who to credit for a CC-BY sound). A game serves that folder and
+  passes it as `baseUrl`; a take whose file is missing plays its fitted copy (or the recipe of its id). The originals the converter reads stay
+  outside the kit (ZombiAdA `assets/sfx-originais/`).
+- **A game plays its own files for any id**: `pointSamples(engine, { pistol_9mm: ['armas/tiro_1.ogg', 'armas/tiro_2.ogg'] }, { baseUrl: './sfx/' })`
+  after `loadKitSamples` keeps the kit's numbers for the id (bus, level, falloff) and plays the game's takes; an id the kit lacks is added. A whole
+  folder laid out like the kit's, with its own `manifest.json`: `loadKitSamples(engine, { baseUrl: './game-sfx/', id: 'game_samples' })` after the
+  kit's. Nothing in the kit changes.
+- On this machine, `scripts/sfx-dir.mjs` says where the files are: the kit's own folder, or `KIT_SFX_DIR` / `KIT_SFX_INBOX`, or `.sfx-local.json` at
+  the repo root (ignored by git) `{ "kit": "../zombiada/assets/sfx", "inbox": "../zombiada/assets/sfx-originais" }` to try a game's set in the
+  kit's pages. The test room links them into `dist/sfx/`. Git (CI and pre-commit, `tools/local-audio/local-audio.mjs guard-git`) takes only the
+  manifest's CC0 and CC-BY files under `assets/sfx/`, no other audio.
+- New files: the original in `<inbox>/<categoria>/` with a line in its `CREDITOS.md`, then `pnpm --filter @adatechnology/game-audio sfx:convert`
+  (ffmpeg): Ogg Vorbis mono 48 kHz, −1 dBFS peak, attack on the first ms, written to the game's folder, with the manifest and credits updated here.
+  Only CC0 and CC-BY (the kit and the game are public).
 - Measuring: `measureCriteria({ sound, banks, loader })` renders C1–C9 through the real engine on an `OfflineAudioContext`; the test room's `?area=sound_check_area` (`createSoundCheckModule`) runs it on a button and records 3 s for C10. `CALIBRATION_SOUND` is a kit-made sample sound (no file) with every layer, for checking the path end to end.
+
+## Fitted copies of the recordings (`@adatechnology/game-audio/fitted`)
+
+Where the files are not on the machine (CI, the published site, a clean clone) or have not loaded yet, a recorded id plays its **fitted copy**:
+numbers measured from each take by `tools/sfx-sources/fit.mjs`, not audio. Each take becomes a recipe of white noise through fourteen bandpass bands
+(35 Hz to 17 kHz, two biquads in series each), each band with its own gain curve down to -80 dB, plus the ringing partials as sines; the
+takes of an id form a set, and a loop keeps its average band gains. Through the real engine, over the 136 one-shot sounds measured, they land a
+median 2.3 dB from the recording (mean band error over time; the pistol 1.7, a punch 1.5) where the hand-made recipes were 26 dB away.
+
+```ts
+import { registerFittedSounds } from '@adatechnology/game-audio/fitted'
+
+registerFittedSounds(engine) // after the game's own banks: the fitted set replaces the older recipe of the same id, its recorded takes stay
+```
+
+- `KIT_SAMPLE_ALIASES` are answered too (`shut_wood` plays the fitted `door_wood_shut`), and the bare id of tiered recordings plays the medium tier.
+- `FITTED_KEEPS_RECIPE` (`fire_extinguish`, `gas_leak`) keep their recipes, which read params; `{ replace: false }` keeps every older recipe.
+- Vehicles are not fitted: their loops follow the engine's RPM.
+- After new recordings: `node tools/sfx-sources/fit.mjs` (ffmpeg, the files where `scripts/sfx-dir.mjs` finds them) rewrites `src/data/fitted-sfx.json`.
+
+## Local sound pack (your own files, by config)
+
+A project can answer any SDK sound id with its own files, kept in its own folders and never in the SDK. A JSON config maps each id to its takes:
+
+```json
+{
+  "version": 1,
+  "baseUrl": "audio/",
+  "sounds": {
+    "pistol_9mm": { "files": ["weapons/pistol_01.ogg", "weapons/pistol_02.ogg"], "license": "CC0" },
+    "door_wood_close": { "files": ["doors/close.ogg"], "license": "CC-BY", "score": 7 }
+  }
+}
+```
+
+```ts
+import { applyLocalSoundPack, parseLocalSoundPack } from '@adatechnology/game-audio'
+
+const pack = applyLocalSoundPack(engine, parseLocalSoundPack(await (await fetch('audio/pack.json')).json()), { baseUrl: 'audio/' })
+await pack.done // { file: ids now playing your files, fallback: ids whose files failed }
+pack.unlicensed() // ids playing a file whose licence is not CC0 / CC-BY
+pack.dispose() // every id gets its previous sound back
+```
+
+- Urls are `baseUrl + file`: a folder served next to the page or any url (`https://cdn.example/sfx/`). `options.baseUrl` overrides the config's.
+- Nothing runs in the frame a sound plays: each id's files are fetched and decoded in idle time (`requestIdleCallback`, one id per slot), once per
+  url and shared by every voice. Until they decode the id plays what it played before (the SDK recording, else the synthesized recipe); a file that
+  fails leaves the id on the SDK sound for good, decided once at load.
+- `license` is `CC0`, `CC-BY`, `unknown` or `proprietary`. The sound panel (`createSoundCheckModule`, metric "File without licence") lists the ids
+  playing a file that is not CC0 / CC-BY: those may be tried locally but cannot ship.
+- `parseLocalSoundPack` validates at the boundary and throws `LocalSoundPackError` with every problem at once.
+- In this repo the test room reads `audio.local.json` at the root (git-ignored; see `examples/test-room/audio.local.example.json`, with `root` the
+  folder of the files): `tools/local-audio/local-audio.mjs link` symlinks it into `dist/local-audio/`, and `guard` / `guard-git` (build, site build,
+  pre-commit and CI) fail if a local file reaches a build or git.

package/assets/sfx/CREDITOS.md

@@ -1,7 +1,7 @@
 # Créditos dos sons
 
-Gerado por `scripts/sfx-convert.mjs` a partir de `assets/sfx-inbox/CREDITOS.md`. Pasta: `packages/game-audio/assets/sfx`.
-Só CC0 e CC-BY entram no SDK; quem usa um som CC-BY credita o autor abaixo.
+Gerado por `scripts/sfx-convert.mjs` a partir do `CREDITOS.md` dos originais. Pasta: `packages/game-audio/assets/sfx` (os sons padrão do kit).
+Só CC0 e CC-BY entram no SDK; quem usa um som CC-BY credita o autor abaixo. Um jogo pode apontar qualquer som para os seus arquivos (`pointSamples`).
 
 | arquivo | fonte | autor | licença |
 |---|---|---|---|

package/assets/sfx/manifest.json

@@ -12088,6 +12088,54 @@
           }
         ]
       }
+    },
+    {
+      "id": "mag_drop_concreto",
+      "category": "armas",
+      "layers": {
+        "close": [
+          {
+            "file": "impactos/metal_fall_close_08.ogg",
+            "sampleRate": 48000,
+            "channels": 1,
+            "peak": -1.05,
+            "seconds": 0.418,
+            "source": "https://opengameart.org/content/cc0-audio-uploader-rubberduck",
+            "author": "rubberduck",
+            "license": "CC0"
+          },
+          {
+            "file": "impactos/metal_fall_close_09.ogg",
+            "sampleRate": 48000,
+            "channels": 1,
+            "peak": -1.18,
+            "seconds": 0.427,
+            "source": "https://opengameart.org/content/cc0-audio-uploader-rubberduck",
+            "author": "rubberduck",
+            "license": "CC0"
+          },
+          {
+            "file": "impactos/metal_fall_close_10.ogg",
+            "sampleRate": 48000,
+            "channels": 1,
+            "peak": -1.1,
+            "seconds": 0.403,
+            "source": "https://opengameart.org/content/cc0-audio-uploader-rubberduck",
+            "author": "rubberduck",
+            "license": "CC0"
+          },
+          {
+            "file": "itens-portas/item_drop_metal_05.ogg",
+            "sampleRate": 48000,
+            "channels": 1,
+            "peak": -1.19,
+            "seconds": 0.669,
+            "source": "https://developers.meta.com/vr/downloads/package/oculus-audio-pack-1/",
+            "author": "Oculus VR, LLC (\"Oculus Audio Pack 01\", via github.com/facebookincubator/Meta-open-sound)",
+            "license": "CC-BY"
+          }
+        ]
+      }
     }
   ]
 }

package/dist/bank-Dsj1VAht.d.ts

@@ -0,0 +1,391 @@
+/**
+ * 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[];
+    /**
+     * 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[];
+};
+/**
+ * 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.
+ */
+type SampleAlias = {
+    readonly id: string;
+    readonly file: string;
+    /**
+     * Keep only the takes whose url contains this (`_01.`): a trim measured on one recording must not land on another take of the same file id,
+     * which may be longer and hold something else at that time.
+     */
+    readonly only?: 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;
+};
+/**
+ * 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;
+    };
+    /**
+     * 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;
+};
+
+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 (those `only` keeps) and numbers, with the alias's id and its own numbers; the recipe of the alias id is
+ * the fallback. `undefined` when `only` keeps no take.
+ */
+declare function aliasSample(alias: SampleAlias, file: SampleSound): SampleSound | undefined;
+declare function createSoundRegistry(banks?: readonly SoundBank[]): SoundRegistry;
+
+export { type Automation as A, type BusId as B, type Curve as C, type DeepPartial as D, type Envelope as E, type Falloff as F, type LoopRecipe as L, type Modulator as M, type NoiseSource as N, type OscSource as O, type ParamRef as P, type Range as R, type SoundRegistry as S, type Time as T, type SoundBank as a, type SoundRecipe as b, type SampleSound as c, type Layer as d, type SoundSet as e, BUILD_ORDERS as f, BUS_IDS as g, type BuildOrder as h, type EnvelopePoint as i, type FilterBank as j, type FilterSpec as k, type FormantVoiceSource as l, type LayerSource as m, type LoopOrder as n, type SampleAlias as o, type SampleCrossover as p, type SampleEnvironment as q, type SampleRef as r, type SampleTail as s, type SampleTier as t, aliasSample as u, createSoundRegistry as v };