@adatechnology/game-audio 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as Falloff, L as LoopRecipe, S as SoundBank, B as BusId, a as SoundRecipe, P as ParamRef, R as Range, b as Layer, c as SoundSet, d as SoundPlan, M as MixProfile, A as AudioEngine } from './testing-BZQid7h0.js';
-export { e as AudioBenchText, f as AudioChannel, g as AudioEngineOptions, h as AudioLoopHandle, i as AudioScenarioLike, j as AudioStats, k as AudioTestModule, l as AudioTestModuleOptions, m as Automation, n as BENCH_BANK, o as BUILD_ORDERS, p as BUS_IDS, q as BUS_PRIORITY, r as BuildOrder, s as BusSetting, C as Curve, D as DEFAULT_LISTENER, t as DEFAULT_MAX_VOICES, u as DEFAULT_MIX, v as DeepPartial, w as DistanceMode, E as Envelope, x as EnvelopePoint, y as FilterBank, z as FilterSpec, G as FormantVoiceSource, H as LayerSource, I as Listener, J as LoopOrder, K as MIX_PROFILES, N as Modulator, O as NoiseSource, Q as OscSource, T as PAN_LIMIT, U as PAN_MIN_DISTANCE, V as PlanInput, W as PlannedAutomation, X as PlannedEnvelopePoint, Y as PlannedFilter, Z as PlannedLayer, _ as PlannedModulator, $ as PlannedSource, a0 as PlayOptions, a1 as SoundRegistry, a2 as StartQueueOptions, a3 as Time, a4 as VOICE_GROUPS, a5 as VoiceDecision, a6 as VoiceGroup, a7 as VoiceHandle, a8 as VoiceManager, a9 as VoiceManagerOptions, aa as VoiceRefusal, ab as VoiceRequest, ac as VoiceStats, ad as audioBenchTextOf, ae as busGain, af as busPriority, ag as createAudioEngine, ah as createAudioTestModule, ai as createSoundRegistry, aj as createVoiceManager, ak as listenerDistance, al as panFor, am as planSound, an as resolveMix } from './testing-BZQid7h0.js';
+import { S as SampleSound, a as SampleLoader, B as BusId, b as SampleCrossover, F as Falloff, c as SoundBank, L as LoopRecipe, d as SoundRecipe, P as ParamRef, R as Range, e as Layer, f as SoundSet, g as SoundPlan, h as SamplePlan, A as AudioLoopHandle, i as LoopEntry, M as MixProfile, j as AudioEngine } from './locale-BugSe8dA.js';
+export { k as ActionCheck, l as AudioBenchText, m as AudioChannel, n as AudioEngineOptions, o as AudioScenarioLike, p as AudioStats, q as AudioTestModule, r as AudioTestModuleOptions, s as Automation, t as BENCH_BANK, u as BUILD_ORDERS, v as BUS_IDS, w as BUS_PRIORITY, x as BuildOrder, y as BusSetting, C as CRITERIA, z as CRITERIA_TARGETS, D as CriterionId, E as CriterionResult, G as Curve, H as DEFAULT_CROSSOVER, I as DEFAULT_LISTENER, J as DEFAULT_MAX_VOICES, K as DEFAULT_MIX, N as DEFAULT_SAMPLE_CUTOFF_K, O as DEFAULT_SAMPLE_FALLOFF, Q as DEFAULT_SAMPLE_PITCH, T as DEFAULT_TAIL_GAIN, U as DeepPartial, V as DistanceMode, W as Envelope, X as EnvelopePoint, Y as FilterBank, Z as FilterSpec, _ as FormantVoiceSource, $ as LAYER_FLOOR, a0 as LayerSource, a1 as Listener, a2 as LoopOrder, a3 as LoopSet, a4 as MIX_PROFILES, a5 as MeasureOptions, a6 as Modulator, a7 as NoiseSource, a8 as OPEN_CUTOFF, a9 as OscSource, aa as PAN_LIMIT, ab as PAN_MIN_DISTANCE, ac as PlanInput, ad as PlannedAutomation, ae as PlannedEnvelopePoint, af as PlannedFilter, ag as PlannedLayer, ah as PlannedModulator, ai as PlannedSampleLayer, aj as PlannedSource, ak as PlayOptions, al as SAMPLE_ENVIRONMENTS, am as SFX_BLOWS, an as SFX_CATALOG, ao as SFX_CATEGORIES, ap as SFX_IMPACTS, aq as SFX_MATERIALS, ar as SampleEnvironment, as as SampleLayerRole, at as SampleLoadReport, au as SampleMemory, av as SampleOptions, aw as SamplePlanInput, ax as SampleRef, ay as SampleStatus, az as SampleStore, aA as SampleTail, aB as SampleTier, aC as SfxBlow, aD as SfxCategory, aE as SfxEntry, aF as SfxMaterial, aG as SfxPriority, aH as SfxState, aI as SoundRegistry, aJ as StartQueueOptions, aK as Time, aL as VOICE_GROUPS, aM as VoiceDecision, aN as VoiceGroup, aO as VoiceHandle, aP as VoiceManager, aQ as VoiceManagerOptions, aR as VoiceRefusal, aS as VoiceRequest, aT as VoiceStartEvent, aU as VoiceStats, aV as audioBenchTextOf, aW as busGain, aX as busPriority, aY as createAudioEngine, aZ as createAudioTestModule, a_ as createSampleStore, a$ as createSoundRegistry, b0 as createVoiceManager, b1 as crossGains, b2 as farMixAt, b3 as fetchLoader, b4 as impactSoundId, b5 as inlineLoader, b6 as limiterCurve, b7 as listenerDistance, b8 as measureCriteria, b9 as panFor, ba as pickTake, bb as planSample, bc as planSound, bd as recordOutput, be as resolveMix, bf as sampleCutoff, bg as sampleUrls, bh as sfxState, bi as tierFor } from './locale-BugSe8dA.js';
 import { AudioSink } from '@adatechnology/game-contracts';
 
 /** Deterministic mulberry32 generator; floats in [0, 1). The same generator the golden tool seeds `Math.random` with, so a team routine and its recipe draw the same numbers. */
@@ -10,6 +10,160 @@ declare function streamFor(seed: number, name: string | number): () => number;
 /** `min + random × (max − min)`: the form every team routine uses (`95 + Math.random() * 40`). */
 declare function drawBetween(random: () => number, min: number, max: number): number;
 
+declare const CALIBRATION_ID = "calibration_shot";
+/** 16-bit PCM mono WAV bytes of the samples (clamped to ±1). */
+declare function encodeWav(samples: Float32Array, sampleRate?: number): ArrayBuffer;
+/** The calibration sound (weapons bus, every layer, fallback to the game's pistol noise class). */
+declare const CALIBRATION_SOUND: SampleSound;
+declare const CALIBRATION_LOOP_ID = "calibration_loop";
+/** A steady hiss in three 0.6 s takes, crossed in 0.15 s: the loop the harness checks for seams (no dip, no gap where two takes meet). */
+declare const CALIBRATION_LOOP_SOUND: SampleSound;
+/** Whether a url is one of the calibration takes. */
+declare const isCalibrationUrl: (url: string) => boolean;
+/** Bytes of the calibration takes (made on demand, the same for the same name). Falls through to `next` for any other url. */
+declare function calibrationLoader(next?: SampleLoader): SampleLoader;
+
+/**
+ * Measurements of rendered sound (pure, on plain sample arrays), for the criteria C1–C9: when it starts, how loud and how bright it is, which side
+ * it is on, how long it rings and how many separate hits a burst has.
+ */
+type Channels = readonly Float32Array[];
+/** Linear amplitude to dBFS (−Infinity for 0). */
+declare const dbOf: (amplitude: number) => number;
+/** The loudest sample of every channel between two sample indexes (linear). */
+declare function peakOf(channels: Channels, start?: number, end?: number): number;
+/** Index of the loudest sample (any channel) between two indexes. */
+declare function peakIndex(channels: Channels, start?: number, end?: number): number;
+/** First sample index at or after `start` whose amplitude (any channel) reaches `threshold`, or −1. */
+declare function onsetIndex(channels: Channels, start?: number, threshold?: number): number;
+/** RMS of all channels between two indexes, dBFS. */
+declare function rmsDb(channels: Channels, start: number, end: number): number;
+/** Spectral centroid (Hz) of `size` samples from `start` (channels summed, Hann window, plain DFT): the brightness of the sound. */
+declare function centroidHz(channels: Channels, sampleRate: number, start: number, size?: number): number;
+/** Energy balance from −1 (all left) to 1 (all right) between two indexes. */
+declare function balanceOf(left: Float32Array, right: Float32Array, start: number, end: number): number;
+/** Seconds from `start` to the last 10 ms window louder than `floorDb` (how long the sound rings, tail included). */
+declare function ringSeconds(channels: Channels, sampleRate: number, start: number, floorDb?: number): number;
+/**
+ * Separate hits in a burst: attacks of the 2 ms envelope, where it jumps to twice the mean of the 20 ms before it and reaches `threshold`, at least
+ * 30 ms apart (so a rapid fire over a long tail still counts every shot).
+ */
+declare function countHits(channels: Channels, sampleRate: number, threshold: number): number;
+/** Peak of the last `seconds` of a file against its own peak, dB (≤ −40: it fades out, it does not end on a cut). */
+declare function endDropDb(channels: Channels, sampleRate: number, seconds?: number): number;
+
+/**
+ * The manifest the converter (`scripts/sfx-convert.mjs`) writes next to the converted files: every sound id with its takes per layer, the file
+ * facts the criteria check (rate, channels, peak, length) and where each file came from. `sampleBankFromManifest` turns it into a `SoundBank`
+ * of `SampleSound`s, with the bus and the numbers of each sound given by the caller.
+ */
+
+/** Licences the SDK accepts (the files are redistributed on npm): public domain or attribution only. */
+declare const SDK_LICENSES: readonly ["CC0", "CC-BY"];
+type SdkLicense = (typeof SDK_LICENSES)[number];
+type SfxFileEntry = {
+    /** Path from the manifest's folder: `armas/pistol_9mm_close_01.ogg`. */
+    readonly file: string;
+    readonly sampleRate: number;
+    readonly channels: number;
+    /** dBFS. */
+    readonly peak: number;
+    readonly seconds: number;
+    readonly source: string;
+    readonly author: string;
+    readonly license: SdkLicense;
+};
+/** The layers a file name can end in: `<id>_<layer>_<nn>` (`pistol_9mm_close_01`); a name without one is a `close` take. */
+declare const SFX_LAYERS: readonly ["close", "far", "tail_in", "tail_out"];
+type SfxLayer = (typeof SFX_LAYERS)[number];
+type SfxManifestSound = {
+    readonly id: string;
+    readonly category: string;
+    readonly layers: Partial<Readonly<Record<SfxLayer, readonly SfxFileEntry[]>>>;
+};
+type SfxManifest = {
+    readonly version: 1;
+    readonly format: {
+        readonly codec: 'vorbis';
+        readonly sampleRate: number;
+        readonly channels: number;
+        readonly peakDb: number;
+    };
+    readonly sounds: readonly SfxManifestSound[];
+};
+/** The numbers of one sound that the files do not say (bus, curve, pitch...). */
+type SampleDefaults = {
+    readonly bus: BusId;
+    readonly gain?: number;
+    readonly pitch?: number;
+    readonly crossover?: SampleCrossover;
+    readonly tailGain?: number;
+    readonly falloff?: Falloff;
+    readonly cutoffK?: number;
+    readonly group?: string;
+    readonly priority?: number;
+    readonly fallback?: string;
+};
+type SampleBankOptions = {
+    readonly id: string;
+    /** Prefix of every url (where the manifest's folder is served: `/sfx/`). Default ''. */
+    readonly baseUrl?: string;
+    /** Numbers per sound id, or one function; a sound with neither is left out (it has no bus). */
+    readonly sounds?: Readonly<Record<string, SampleDefaults>>;
+    readonly defaults?: (sound: SfxManifestSound) => SampleDefaults | undefined;
+};
+/** The strength suffixes of a sound id (`kick_hit_heavy`): takes of the tiers of `kick_hit`, from these intensities. */
+declare const SFX_TIERS: Readonly<Record<string, number>>;
+/** Splits a file name (no extension) into its sound id, layer and take number. */
+declare function parseSfxName(name: string): {
+    readonly id: string;
+    readonly layer: SfxLayer;
+    readonly take: number;
+};
+/** The base id and tier of a sound id: `kick_hit_heavy` → `kick_hit`, `heavy`. */
+declare function splitTier(id: string): {
+    readonly base: string;
+    readonly tier?: string;
+};
+/** A bank of sample sounds from a manifest. */
+declare function sampleBankFromManifest(manifest: SfxManifest, options: SampleBankOptions): SoundBank;
+
+/** The bus of a manifest category (the folder the file sits in). */
+declare const KIT_CATEGORY_BUS: Readonly<Record<string, BusId>>;
+/**
+ * Recipe id → file id. The recipe keeps playing until the takes of the file id load. Hand-worked leaves (doors, drawers) of `game-destruction-three`
+ * and the hand sounds of items.
+ */
+declare const KIT_SAMPLE_ALIASES: Readonly<Record<string, string>>;
+/** The numbers of a sound the files do not say: the bus of its folder, a little pitch spread. */
+declare function kitSampleDefaults(sound: SfxManifestSound): SampleDefaults | undefined;
+type KitSampleBankOptions = {
+    /** Where the `assets/sfx/` folder is served (`./sfx/`). */
+    readonly baseUrl?: string;
+    /** Recipe id → file id (default `KIT_SAMPLE_ALIASES`); `{}` adds none. */
+    readonly aliases?: Readonly<Record<string, string>>;
+    readonly id?: string;
+};
+/** The manifest with each alias as one more sound, holding the takes of its file id. */
+declare function withAliases(manifest: SfxManifest, aliases: Readonly<Record<string, string>>): SfxManifest;
+/** The bank of the kit's files. */
+declare function kitSampleBank(manifest: SfxManifest, options?: KitSampleBankOptions): SoundBank;
+type LoadKitSamplesOptions = KitSampleBankOptions & {
+    /** Gets the manifest (default `fetch` of `<baseUrl>manifest.json`). */
+    readonly fetchManifest?: (url: string) => Promise<SfxManifest>;
+    /** Ids to load right away instead of on their first play (the sounds of the first seconds, so they are not the recipe). */
+    readonly preload?: readonly string[];
+};
+type Registers = {
+    register(bank: SoundBank): void;
+    loadSamples?(ids?: readonly string[]): Promise<unknown>;
+};
+/**
+ * Fetches the manifest and registers the bank on the engine. Resolves to the bank, or `null` when the manifest cannot be had (a page opened from
+ * `file://`, the folder not served): the recipes keep playing, so that is not an error.
+ */
+declare function loadKitSamples(engine: Registers, options?: LoadKitSamplesOptions): Promise<SoundBank | null>;
+
 /** The distance curves of the team routines, by name. Each recipe carries its own; these are the values to copy. */
 declare const DISTANCE_CURVES: {
     /** The game's `sfx`: `vol / (1 + d² × 0.004)`, cutoff `/ (1 + d × 0.01)`, silent below 0.01 (jogo L62091–62092, L62101). */
@@ -172,6 +326,28 @@ declare const LIBRARY_SOUNDS: readonly SoundRecipe[];
 declare const LIBRARY_LOOPS: readonly LoopRecipe[];
 declare const LIBRARY_BANK: SoundBank;
 
+/** Small sounds of the hand: `vol / (1 + d² × 0.02)`, lowpass cutoffs `/ (1 + d × 0.04)`, silent below 0.004 (a latch at 10 m is a third, at 50 m gone). */
+declare const FOLEY_FALLOFF: Falloff;
+/** The doors and lids of furniture and vehicles, by what the leaf is (the room picks one from the item, else from the leaf's material). */
+declare const LEAF_FOLEY: readonly SoundRecipe[];
+/** What the hand does with an item: picking it up by what it is made of, throwing it, and the uses (opening, drinking, eating, first aid). */
+declare const ITEM_FOLEY: readonly SoundRecipe[];
+/** The foley bank: register it in the engine (`engine.register(FOLEY_BANK)`). */
+declare const FOLEY_BANK: SoundBank;
+/** What a picked-up item sounds like, by its heaviest material class. */
+declare const PICKUP_CLASSES: readonly ["metal", "plastic", "glass", "paper", "fabric", "wood", "food"];
+type PickupClass = (typeof PICKUP_CLASSES)[number];
+/** The sound set of a leaf worked by hand: the ids it plays at the latch, while it turns, and as it meets the frame (gently, and slammed). */
+type LeafFoley = {
+    readonly open: string;
+    readonly turn?: string;
+    readonly close: string;
+    readonly slam?: string;
+    readonly locked: string;
+};
+/** The leaf sound sets the kit ships, by name; an item names one (`TestableItem.sounds.leaves`), else the room picks `wood_door` or `metal_door` by the leaf's material. */
+declare const LEAF_FOLEY_SETS: Readonly<Record<string, LeafFoley>>;
+
 /** Takes per id. */
 declare const BODY_FOLEY_TAKES = 4;
 /** Footsteps fade fast with distance and lose their top: a step 10 m away is a quarter of the level, 30 m a few percent, and duller. */
@@ -218,6 +394,50 @@ type RealizedVoice = {
     stop(): void;
 };
 
+type SampleTarget = {
+    readonly context: BaseAudioContext;
+    readonly output: AudioNode;
+    readonly buffer: (url: string) => AudioBuffer | undefined;
+    readonly time: number;
+};
+/** A sample voice can also be faded out (the choke of its sound). */
+type RealizedSampleVoice = RealizedVoice & {
+    fade(at: number, seconds: number): void;
+};
+/**
+ * Builds a sample plan: each layer is a buffer source at the planned rate with its own gain, the layers meet in one voice gain (the choke fades it),
+ * one lowpass (left out when open) and one stereo panner (when the plan has a pan), then the bus. A layer whose buffer is not loaded is skipped.
+ */
+declare function realizeSample(plan: SamplePlan, target: SampleTarget): RealizedSampleVoice;
+/** Seconds a sample plan lasts with its buffers (the longest layer, at its rate). */
+declare function sampleLength(plan: SamplePlan, seconds: (url: string) => number | undefined): number;
+
+/** The crossfade between two takes of a loop, in seconds, when `loop: true` gives none. */
+declare const DEFAULT_LOOP_CROSSFADE = 0.25;
+/** The crossfade of a looping sample sound, or `undefined` when it does not loop. */
+declare function loopCrossfade(sound: SampleSound): number | undefined;
+/** Steps of the equal-power ramps (straight lines between points of the sine and cosine quarter). */
+declare const CROSSFADE_STEPS = 8;
+/** The gain of an equal-power crossfade at `t` (0..1) for the take coming in; the take going out has the gain at `1 − t`. */
+declare const equalPowerIn: (t: number) => number;
+/** What a sample loop needs from its engine. */
+type SampleLoopHost = {
+    ready(): AudioContext | null;
+    /** The node sample voices of a bus go to (the limiter of the bus). */
+    output(bus: BusId): AudioNode;
+    buffer(url: string): AudioBuffer | undefined;
+    isReady(sound: SampleSound): boolean;
+    /** Loads the files of the sound (resolves when they are decoded or failed). */
+    load(sound: SampleSound): Promise<unknown>;
+    /** The recipe loop that plays while the files are not ready. */
+    fallback(volume: number): AudioLoopHandle;
+    random(): number;
+    register(loop: LoopEntry): void;
+    unregister(loop: LoopEntry): void;
+    /** Whether a bus is muted now. */
+    muted(bus: BusId): boolean;
+};
+
 /** Builds a plan's nodes on `target`, in the node order of the team routine its `order` names. */
 declare function realize(plan: SoundPlan, target: RealizeTarget): RealizedVoice;
 
@@ -259,4 +479,4 @@ type EngineSink = AudioSink & {
 /** Lends an engine as the host's `audio`: sounds by key, loops, the listener, and banks registered into the same engine. */
 declare function createAudioSink(engine: AudioEngine): EngineSink;
 
-export { AudioEngine, BODY_FALLOFF, BODY_FOLEY_BANK, BODY_FOLEY_SET_IDS, BODY_FOLEY_TAKES, BusId, DISTANCE_CURVES, type DistanceCurveName, type EngineSink, FOOTSTEP_FALLOFF, Falloff, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, Layer, type LoopAction, LoopRecipe, type LoopState, type MixChain, MixProfile, type NoiseClass, ParamRef, Range, type RealizeTarget, type RealizedVoice, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SetPicker, SoundBank, SoundPlan, SoundRecipe, SoundSet, bufferOf, buildChain, createAudioSink, createLoopState, createRng, createSetPicker, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, noiseClassRecipe, realize, retunePlan, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext };
+export { AudioEngine, AudioLoopHandle, BODY_FALLOFF, BODY_FOLEY_BANK, BODY_FOLEY_SET_IDS, BODY_FOLEY_TAKES, BusId, CALIBRATION_ID, CALIBRATION_LOOP_ID, CALIBRATION_LOOP_SOUND, CALIBRATION_SOUND, CROSSFADE_STEPS, DEFAULT_LOOP_CROSSFADE, DISTANCE_CURVES, type DistanceCurveName, type EngineSink, FOLEY_BANK, FOLEY_FALLOFF, FOOTSTEP_FALLOFF, Falloff, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, ITEM_FOLEY, KIT_CATEGORY_BUS, KIT_SAMPLE_ALIASES, type KitSampleBankOptions, LEAF_FOLEY, LEAF_FOLEY_SETS, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, Layer, type LeafFoley, type LoadKitSamplesOptions, type LoopAction, LoopRecipe, type LoopState, type MixChain, MixProfile, type NoiseClass, PICKUP_CLASSES, ParamRef, type PickupClass, Range, type RealizeTarget, type RealizedSampleVoice, type RealizedVoice, SDK_LICENSES, SFX_LAYERS, SFX_TIERS, type SampleBankOptions, SampleCrossover, type SampleDefaults, SampleLoader, type SampleLoopHost, SamplePlan, SampleSound, type SampleTarget, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SdkLicense, type SetPicker, type SfxFileEntry, type SfxLayer, type SfxManifest, type SfxManifestSound, SoundBank, SoundPlan, SoundRecipe, SoundSet, balanceOf, bufferOf, buildChain, calibrationLoader, centroidHz, countHits, createAudioSink, createLoopState, createRng, createSetPicker, cutoffDivisor, dbOf, drawBetween, encodeWav, endDropDb, equalPowerIn, falloffGain, fillImpulse, fillNoise, globalContext, isCalibrationUrl, isSilent, kitSampleBank, kitSampleDefaults, loadKitSamples, loopCrossfade, noiseClassRecipe, onsetIndex, parseSfxName, peakIndex, peakOf, realize, realizeSample, retunePlan, ringSeconds, rmsDb, sampleBankFromManifest, sampleLength, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, splitTier, streamFor, streamSeed, unlockContext, withAliases };