@adatechnology/game-audio 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { S as SampleSound, a as SampleLoader, B as BusId, b as SfxManifest, c as SoundBank, d as SampleDefaults, F as Falloff, L as LoopRecipe, e as SoundRecipe, P as ParamRef, R as Range, f as Layer, g as SoundSet, h as SoundPlan, i as SamplePlan, A as AudioLoopHandle, j as LoopEntry, M as MixProfile, k as AudioEngine } from './locale-CJfDpWnI.js';
-export { l as ActionCheck, m as AudioBenchText, n as AudioChannel, o as AudioEngineOptions, p as AudioScenarioLike, q as AudioStats, r as AudioTestModule, s as AudioTestModuleOptions, t as Automation, u as BENCH_BANK, v as BUILD_ORDERS, w as BUS_IDS, x as BUS_PRIORITY, y as BuildOrder, z as BusSetting, C as CRITERIA, D as CRITERIA_TARGETS, E as CriterionId, G as CriterionResult, H as Curve, I as DEFAULT_CROSSOVER, J as DEFAULT_LISTENER, K as DEFAULT_MAX_VOICES, N as DEFAULT_MIX, O as DEFAULT_SAMPLE_CUTOFF_K, Q as DEFAULT_SAMPLE_FALLOFF, T as DEFAULT_SAMPLE_PITCH, U as DEFAULT_TAIL_GAIN, V as DeepPartial, W as DistanceMode, X as Envelope, Y as EnvelopePoint, Z as FilterBank, _ as FilterSpec, $ as FormantVoiceSource, a0 as KIT_SAMPLES_BANK, a1 as LAYER_FLOOR, a2 as LayerSource, a3 as Listener, a4 as LoadUserSamplesOptions, a5 as LoopOrder, a6 as LoopSet, a7 as MIX_PROFILES, a8 as MeasureOptions, a9 as Modulator, aa as NoiseSource, ab as OPEN_CUTOFF, ac as OscSource, ad as PAN_LIMIT, ae as PAN_MIN_DISTANCE, af as PlanInput, ag as PlannedAutomation, ah as PlannedEnvelopePoint, ai as PlannedFilter, aj as PlannedLayer, ak as PlannedModulator, al as PlannedSampleLayer, am as PlannedSource, an as PlayOptions, ao as SAMPLE_ENVIRONMENTS, ap as SDK_LICENSES, aq as SFX_BLOWS, ar as SFX_CATALOG, as as SFX_CATEGORIES, at as SFX_IMPACTS, au as SFX_LAYERS, av as SFX_MATERIALS, aw as SFX_TIERS, ax as SampleBankOptions, ay as SampleCrossover, az as SampleEnvironment, aA as SampleLayerRole, aB as SampleLoadReport, aC as SampleMemory, aD as SampleOptions, aE as SamplePlanInput, aF as SampleRef, aG as SampleStatus, aH as SampleStore, aI as SampleTail, aJ as SampleTier, aK as SdkLicense, aL as SfxBlow, aM as SfxCategory, aN as SfxEntry, aO as SfxFileEntry, aP as SfxLayer, aQ as SfxManifestLike, aR as SfxManifestSound, aS as SfxMaterial, aT as SfxPriority, aU as SfxState, aV as SoundRegistry, aW as SoundSource, aX as StartQueueOptions, aY as Time, aZ as USER_SAMPLES_BANK, a_ as USER_SOUND_PREFIX, a$ as UserSampleBankOptions, b0 as UserSampleBankResult, b1 as UserSfxFile, b2 as UserSfxManifest, b3 as UserSfxSound, b4 as UserSoundPick, b5 as UserSoundPicks, b6 as UserSoundRole, b7 as VOICE_GROUPS, b8 as VoiceDecision, b9 as VoiceGroup, ba as VoiceHandle, bb as VoiceManager, bc as VoiceManagerOptions, bd as VoiceRefusal, be as VoiceRequest, bf as VoiceStartEvent, bg as VoiceStats, bh as audioBenchTextOf, bi as busGain, bj as busPriority, bk as createAudioEngine, bl as createAudioTestModule, bm as createSampleStore, bn as createSoundRegistry, bo as createVoiceManager, bp as crossGains, bq as farMixAt, br as fetchLoader, bs as impactSoundId, bt as inlineLoader, bu as limiterCurve, bv as listenerDistance, bw as loadUserSamples, bx as measureCriteria, by as panFor, bz as parseSfxName, bA as pickTake, bB as planSample, bC as planSound, bD as recordOutput, bE as resolveMix, bF as sampleBankFromManifest, bG as sampleCutoff, bH as sampleUrls, bI as sfxState, bJ as soundSourceOf, bK as splitTier, bL as tierFor, bM as userSampleBank } from './locale-CJfDpWnI.js';
+import { c as SampleSound, B as BusId, a as SoundBank, F as Falloff, L as LoopRecipe, b as SoundRecipe, P as ParamRef, R as Range, d as Layer, e as SoundSet } from './bank-Dsj1VAht.js';
+export { A as Automation, f as BUILD_ORDERS, g as BUS_IDS, h as BuildOrder, C as Curve, D as DeepPartial, E as Envelope, i as EnvelopePoint, j as FilterBank, k as FilterSpec, l as FormantVoiceSource, m as LayerSource, n as LoopOrder, M as Modulator, N as NoiseSource, O as OscSource, o as SampleAlias, p as SampleCrossover, q as SampleEnvironment, r as SampleRef, s as SampleTail, t as SampleTier, S as SoundRegistry, T as Time, u as aliasSample, v as createSoundRegistry } from './bank-Dsj1VAht.js';
+import { S as SampleLoader, a as SfxManifest, b as SampleDefaults, A as AudioEngine, c as SoundPlan, d as SamplePlan, e as AudioLoopHandle, L as LoopEntry, f as Listener, D as DistanceMode, M as MixProfile } from './locale-YHyJwN2P.js';
+export { g as ActionCheck, h as AudioBenchText, i as AudioChannel, j as AudioEngineOptions, k as AudioScenarioLike, l as AudioStats, m as AudioTestModule, n as AudioTestModuleOptions, B as BENCH_BANK, o as BUS_PRIORITY, p as BusSetting, C as CRITERIA, q as CRITERIA_TARGETS, r as CriterionId, s as CriterionResult, t as DEFAULT_CROSSOVER, u as DEFAULT_LISTENER, v as DEFAULT_MAX_VOICES, w as DEFAULT_MIX, x as DEFAULT_SAMPLE_CUTOFF_K, y as DEFAULT_SAMPLE_FALLOFF, z as DEFAULT_SAMPLE_PITCH, E as DEFAULT_TAIL_GAIN, K as KIT_SAMPLES_BANK, F as LAYER_FLOOR, G as LoadUserSamplesOptions, H as LoopSet, I as MIX_PROFILES, J as MeasureOptions, O as OPEN_CUTOFF, P as PAN_LIMIT, N as PAN_MIN_DISTANCE, Q as PlanInput, R as PlannedAutomation, T as PlannedEnvelopePoint, U as PlannedFilter, V as PlannedLayer, W as PlannedModulator, X as PlannedSampleLayer, Y as PlannedSource, Z as PlayOptions, _ as SAMPLE_ENVIRONMENTS, $ as SDK_LICENSES, a0 as SFX_BLOWS, a1 as SFX_CATALOG, a2 as SFX_CATEGORIES, a3 as SFX_IMPACTS, a4 as SFX_LAYERS, a5 as SFX_MATERIALS, a6 as SFX_TIERS, a7 as SampleBankOptions, a8 as SampleLayerRole, a9 as SampleLoadReport, aa as SampleMemory, ab as SampleOptions, ac as SamplePlanInput, ad as SampleStatus, ae as SampleStore, af as SdkLicense, ag as SfxBlow, ah as SfxCategory, ai as SfxEntry, aj as SfxFileEntry, ak as SfxLayer, al as SfxManifestLike, am as SfxManifestSound, an as SfxMaterial, ao as SfxPriority, ap as SfxState, aq as SoundSource, ar as StartQueueOptions, as as USER_SAMPLES_BANK, at as USER_SOUND_PREFIX, au as UserSampleBankOptions, av as UserSampleBankResult, aw as UserSfxFile, ax as UserSfxManifest, ay as UserSfxSound, az as UserSoundPick, aA as UserSoundPicks, aB as UserSoundRole, aC as VOICE_GROUPS, aD as VoiceDecision, aE as VoiceGroup, aF as VoiceHandle, aG as VoiceManager, aH as VoiceManagerOptions, aI as VoiceRefusal, aJ as VoiceRequest, aK as VoiceStartEvent, aL as VoiceStats, aM as audioBenchTextOf, aN as busGain, aO as busPriority, aP as createAudioEngine, aQ as createAudioTestModule, aR as createSampleStore, aS as createVoiceManager, aT as crossGains, aU as farMixAt, aV as fetchLoader, aW as impactSoundId, aX as inlineLoader, aY as limiterCurve, aZ as listenerDistance, a_ as loadUserSamples, a$ as measureCriteria, b0 as panFor, b1 as parseSfxName, b2 as pickTake, b3 as planSample, b4 as planSound, b5 as recordOutput, b6 as resolveMix, b7 as sampleBankFromManifest, b8 as sampleCutoff, b9 as sampleUrls, ba as sfxState, bb as soundSourceOf, bc as splitTier, bd as tierFor, be as userSampleBank } from './locale-YHyJwN2P.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. */
@@ -90,6 +92,107 @@ type Registers = {
  * `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>;
+/** A game's own files, by sound id: one url or several takes (relative to `baseUrl`). */
+type SampleFiles = Readonly<Record<string, string | readonly string[]>>;
+type PointSamplesOptions = {
+    /** Put before every url (the game's folder, `./sfx/` say). */
+    readonly baseUrl?: string;
+    /** The bank id (default `game_samples`). */
+    readonly id?: string;
+    /** Bus of an id the kit has no sound for (default `world`). */
+    readonly bus?: BusId;
+};
+type PointsSamples = {
+    register(bank: SoundBank): void;
+    readonly registry: {
+        sample(id: string): SampleSound | undefined;
+    };
+};
+/**
+ * Points sound ids at a game's own files: each id keeps the kit's numbers (bus, level, pitch spread, falloff, choke) and plays the game's takes in
+ * place of the kit's (its far takes, tiers and room tails included, since they are the kit's files); an id the kit has no sound for is added on
+ * `bus`. Call it after the kit's bank (`loadKitSamples`): a later bank wins, so the rest of the kit's sounds stay. For a whole folder laid out like
+ * the kit's (`<categoria>/<nome>.ogg` and a `manifest.json`), `loadKitSamples(engine, { baseUrl: '<folder>/', id: 'game_samples' })` does the same.
+ */
+declare function pointSamples(engine: PointsSamples, files: SampleFiles, options?: PointSamplesOptions): SoundBank;
+
+declare const LOCAL_PACK_LICENSES: readonly ["CC0", "CC-BY", "unknown", "proprietary"];
+type LocalPackLicense = (typeof LOCAL_PACK_LICENSES)[number];
+/** Which sound an id plays when the SDK also has a recording for it: the pack's files (default) or the SDK's, the pack staying as the alternative. */
+declare const LOCAL_PACK_PREFERENCES: readonly ["pack", "sdk"];
+type LocalPackPreference = (typeof LOCAL_PACK_PREFERENCES)[number];
+type LocalSoundEntry = {
+    /** Paths or urls of the takes, relative to the pack's base. */
+    readonly files: readonly string[];
+    readonly license: LocalPackLicense;
+    /** Default `pack`; `sdk` keeps the SDK recording when there is one (the pack's files are then not even fetched). */
+    readonly prefer?: LocalPackPreference;
+    /** Bus of the sound (default the bus of its catalogue category). */
+    readonly bus?: BusId;
+    readonly gain?: number;
+    /** 0–10: how well the files fit the id (a reviewer's note, shown by tools). */
+    readonly score?: number;
+    readonly note?: string;
+};
+type LocalSoundPack = {
+    readonly version: 1;
+    /** Prefix of every file (a folder served next to the page, or a url); the consumer can override it. */
+    readonly baseUrl?: string;
+    /** SDK sound id → its files. */
+    readonly sounds: Readonly<Record<string, LocalSoundEntry>>;
+};
+declare class LocalSoundPackError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/** Checks a parsed JSON config; every problem is reported at once. */
+declare function parseLocalSoundPack(value: unknown): LocalSoundPack;
+/** Whether the SDK may ship a file of this licence (public domain or attribution). */
+declare const isShippableLicense: (license: string | undefined) => boolean;
+type LocalPackSampleOptions = {
+    /** Overrides the pack's `baseUrl`. */
+    readonly baseUrl?: string;
+};
+/** The pack as sample sounds, one per id, with the synthesized sound of the catalogue as the fallback. */
+declare function localPackSamples(pack: LocalSoundPack, options?: LocalPackSampleOptions): SampleSound[];
+
+/**
+ * Puts a local sound pack on an engine without touching the frame a sound is played in. Each id's files are fetched and decoded in idle time
+ * (one id per idle slot), once per url (the engine's sample store shares buffers between ids and voices). Until they decode, the id plays what it
+ * played before (the SDK's recording, else its synthesized recipe); once they do, the id is swapped to the files. The choice is made once, when the
+ * files load: a file that fails leaves the id on the SDK's sound for good, so `play` never fetches or decodes anything.
+ */
+
+declare const LOCAL_PACK_BANK_ID = "local_sound_pack";
+/** `pending` while loading, `file` once the pack's files play, `fallback` when they failed and the SDK's sound stays, `sdk` when the entry prefers the SDK recording and there is one. */
+type LocalPackStatus = 'pending' | 'file' | 'fallback' | 'sdk';
+type LocalPackReport = {
+    readonly file: readonly string[];
+    /** Ids that kept the SDK recording by preference (their files were not fetched). */
+    readonly sdk: readonly string[];
+    readonly fallback: readonly {
+        readonly id: string;
+        readonly error: string;
+    }[];
+};
+/** Runs a task when the page is idle; returns a cancel function. */
+type IdleScheduler = (task: () => void) => () => void;
+/** `requestIdleCallback` where there is one, else the next macrotask. */
+declare const defaultIdleScheduler: IdleScheduler;
+type ApplyLocalSoundPackOptions = LocalPackSampleOptions & {
+    readonly schedule?: IdleScheduler;
+};
+type LocalPackHandle = {
+    /** Resolves when every id has loaded or fallen back. */
+    readonly done: Promise<LocalPackReport>;
+    status(id: string): LocalPackStatus | undefined;
+    /** The ids playing a pack file whose licence is not CC0 / CC-BY. */
+    unlicensed(): readonly string[];
+    /** Stops loading and gives every swapped id back the sound it had before. */
+    dispose(): void;
+};
+type Engine = Pick<AudioEngine, 'registry' | 'register' | 'loadSamples'>;
+declare function applyLocalSoundPack(engine: Engine, pack: LocalSoundPack, options?: ApplyLocalSoundPackOptions): LocalPackHandle;
 
 /** The distance curves of the team routines, by name. Each recipe carries its own; these are the values to copy. */
 declare const DISTANCE_CURVES: {
@@ -256,6 +359,31 @@ declare const LIBRARY_BANK: SoundBank;
 declare const CABIN_SOUNDS: readonly SoundRecipe[];
 declare const CABIN_BANK: SoundBank;
 
+type Note = readonly [beat: number, midi: number, beats: number];
+type TrackSpec = {
+    id: string;
+    bpm: number;
+    bars: number;
+    wave: 'sine' | 'triangle' | 'square' | 'sawtooth';
+    bass: readonly Note[];
+    chords: readonly Note[];
+    melody: readonly Note[];
+};
+/** A song of the radio: the ids of its bars in order and the seconds of one bar. */
+type RadioSong = {
+    readonly id: string;
+    readonly barSeconds: number;
+    readonly bars: readonly string[];
+};
+/** One song cut in bars: every note a layer at its beat inside its bar. */
+declare function radioTrack(spec: TrackSpec): {
+    song: RadioSong;
+    recipes: SoundRecipe[];
+};
+/** The songs a cabin steps through. */
+declare const RADIO_TRACKS: readonly RadioSong[];
+declare const RADIO_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). */
@@ -324,6 +452,8 @@ type RealizedVoice = {
     stop(): void;
 };
 
+/** Seconds a trimmed take fades out over at its cut. */
+declare const TRIM_FADE = 0.04;
 type SampleTarget = {
     readonly context: BaseAudioContext;
     readonly output: AudioNode;
@@ -366,7 +496,12 @@ type SampleLoopHost = {
     unregister(loop: LoopEntry): void;
     /** Whether a bus is muted now. */
     muted(bus: BusId): boolean;
+    /** Where the listener is, for a loop placed by `set({ position })`. */
+    listener?(): Listener;
+    distance?: DistanceMode;
 };
+/** The rate a loop with `baseFrequency` plays at for a frequency. */
+declare const loopRate: (sound: SampleSound, frequency: number) => number;
 
 /** 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;
@@ -409,4 +544,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, AudioLoopHandle, BODY_FALLOFF, BODY_FOLEY_BANK, BODY_FOLEY_SET_IDS, BODY_FOLEY_TAKES, BusId, CABIN_BANK, CABIN_SOUNDS, 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, SampleDefaults, SampleLoader, type SampleLoopHost, SamplePlan, SampleSound, type SampleTarget, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SetPicker, SfxManifest, 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, peakIndex, peakOf, realize, realizeSample, retunePlan, ringSeconds, rmsDb, sampleLength, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext, withAliases };
+export { type ApplyLocalSoundPackOptions, AudioEngine, AudioLoopHandle, BODY_FALLOFF, BODY_FOLEY_BANK, BODY_FOLEY_SET_IDS, BODY_FOLEY_TAKES, BusId, CABIN_BANK, CABIN_SOUNDS, CALIBRATION_ID, CALIBRATION_LOOP_ID, CALIBRATION_LOOP_SOUND, CALIBRATION_SOUND, CROSSFADE_STEPS, DEFAULT_LOOP_CROSSFADE, DISTANCE_CURVES, type DistanceCurveName, DistanceMode, type EngineSink, FOLEY_BANK, FOLEY_FALLOFF, FOOTSTEP_FALLOFF, Falloff, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, ITEM_FOLEY, type IdleScheduler, KIT_CATEGORY_BUS, KIT_SAMPLE_ALIASES, type KitSampleBankOptions, LEAF_FOLEY, LEAF_FOLEY_SETS, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOCAL_PACK_BANK_ID, LOCAL_PACK_LICENSES, LOCAL_PACK_PREFERENCES, LOOP_SMOOTHING, LOOP_START_ABOVE, Layer, type LeafFoley, Listener, type LoadKitSamplesOptions, type LocalPackHandle, type LocalPackLicense, type LocalPackPreference, type LocalPackReport, type LocalPackSampleOptions, type LocalPackStatus, type LocalSoundEntry, type LocalSoundPack, LocalSoundPackError, type LoopAction, LoopRecipe, type LoopState, type MixChain, MixProfile, type NoiseClass, PICKUP_CLASSES, ParamRef, type PickupClass, type PointSamplesOptions, RADIO_BANK, RADIO_TRACKS, type RadioSong, Range, type RealizeTarget, type RealizedSampleVoice, type RealizedVoice, SampleDefaults, type SampleFiles, SampleLoader, type SampleLoopHost, SamplePlan, SampleSound, type SampleTarget, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SetPicker, SfxManifest, SoundBank, SoundPlan, SoundRecipe, SoundSet, TRIM_FADE, applyLocalSoundPack, balanceOf, bufferOf, buildChain, calibrationLoader, centroidHz, countHits, createAudioSink, createLoopState, createRng, createSetPicker, cutoffDivisor, dbOf, defaultIdleScheduler, drawBetween, encodeWav, endDropDb, equalPowerIn, falloffGain, fillImpulse, fillNoise, globalContext, isCalibrationUrl, isShippableLicense, isSilent, kitSampleBank, kitSampleDefaults, loadKitSamples, localPackSamples, loopCrossfade, loopRate, noiseClassRecipe, onsetIndex, parseLocalSoundPack, peakIndex, peakOf, pointSamples, radioTrack, realize, realizeSample, retunePlan, ringSeconds, rmsDb, sampleLength, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext, withAliases };