@adatechnology/game-audio 0.5.0 → 0.6.0

package/dist/{locale-BugSe8dA.d.ts → locale-CJfDpWnI.d.ts}

@@ -783,6 +783,8 @@ type VoiceStartEvent = {
     readonly kind: 'recipe' | 'sample';
     /** The sample sound this recipe stood in for while its files were not loaded. */
     readonly fallbackOf?: string;
+    /** The bank the played id is registered in (`kit_samples`, `user_samples`, a recipe bank...). */
+    readonly bank?: string;
     readonly requestedAt: number;
     readonly startAt: number;
     readonly outputLatency: number;
@@ -1011,6 +1013,183 @@ declare function sfxState(entry: SfxEntry, has: {
     sound(id: string): unknown;
 }): SfxState;
 
+/**
+ * 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: {
+        readonly id: string;
+        readonly category: string;
+    }) => 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;
+};
+/** What `sampleBankFromManifest` reads of a manifest: the sounds, their layers and where each file came from (any licence string). */
+type SfxManifestLike = {
+    readonly sounds: readonly {
+        readonly id: string;
+        readonly category: string;
+        readonly layers: Partial<Readonly<Record<SfxLayer, readonly {
+            readonly file: string;
+            readonly source: string;
+            readonly author: string;
+            readonly license: string;
+        }[]>>>;
+    }[];
+};
+/** A bank of sample sounds from a manifest. */
+declare function sampleBankFromManifest(manifest: SfxManifestLike, options: SampleBankOptions): SoundBank;
+
+declare const USER_SAMPLES_BANK = "user_samples";
+declare const KIT_SAMPLES_BANK = "kit_samples";
+/** Prefix of the id each pick is also registered under. */
+declare const USER_SOUND_PREFIX = "user:";
+type UserSoundRole = 'primary' | 'fallback';
+/** One sound the owner's files answer. */
+type UserSoundPick = {
+    readonly id: string;
+    readonly role: UserSoundRole;
+    /** The kit category (`armas`, `personagem`...): the bus and the folder of the converted files. */
+    readonly category: string;
+    readonly label: string;
+    /** The pack the files come from (a folder of the owner's sounds). */
+    readonly pack: string;
+    /** Paths inside the pack (matched by their end, so the pack may be nested differently). */
+    readonly files: readonly string[];
+    /** 0–10: how well the files fit the sound (rate, clipping, band). */
+    readonly score: number;
+    readonly loop?: boolean;
+};
+type UserSoundPicks = {
+    readonly version: 1;
+    readonly author: string;
+    readonly license: string;
+    readonly picks: readonly UserSoundPick[];
+};
+/** One converted file, as `sfx:user` writes it. */
+type UserSfxFile = {
+    readonly file: string;
+    readonly sampleRate: number;
+    readonly channels: number;
+    readonly peak: number;
+    readonly seconds: number;
+    readonly source: string;
+    readonly author: string;
+    readonly license: string;
+};
+type UserSfxSound = {
+    readonly id: string;
+    readonly category: string;
+    readonly role: UserSoundRole;
+    readonly label: string;
+    readonly layers: Partial<Readonly<Record<SfxLayer, readonly UserSfxFile[]>>>;
+};
+/** The manifest `sfx:user` writes in `.sfx-local/manifest.json`. */
+type UserSfxManifest = {
+    readonly version: 1;
+    readonly sounds: readonly UserSfxSound[];
+};
+/** Where a voice came from: the kit's recording, the owner's file, or the synthesized recipe. */
+type SoundSource = 'sdk' | 'user' | 'synth';
+/** The source of a started voice, from its kind and the bank its id is registered in. */
+declare function soundSourceOf(event: {
+    readonly kind: 'recipe' | 'sample';
+    readonly bank?: string;
+}): SoundSource;
+type UserSampleBankOptions = {
+    readonly baseUrl?: string;
+    /** True for an id the kit already plays from a file: a `fallback` pick is then only registered under `user:<id>`. */
+    readonly kitHas?: (id: string) => boolean;
+};
+type UserSampleBankResult = {
+    readonly bank: SoundBank;
+    /** Ids the owner's files now answer (primary picks, and fallbacks the kit lacks). */
+    readonly playing: readonly string[];
+    /** Fallback ids the kit answers, kept under `user:<id>`. */
+    readonly behindKit: readonly string[];
+};
+/** The bank of the owner's converted files. */
+declare function userSampleBank(manifest: UserSfxManifest, options?: UserSampleBankOptions): UserSampleBankResult;
+type LoadUserSamplesOptions = UserSampleBankOptions & {
+    readonly fetchManifest?: (url: string) => Promise<UserSfxManifest>;
+};
+type Registers = {
+    register(bank: SoundBank): void;
+    readonly registry?: {
+        sample(id: string): unknown;
+    };
+};
+/**
+ * Fetches `<baseUrl>manifest.json` (default `./sfx-local/`) and registers the owner's files. Call it after the kit's bank loaded, so a fallback
+ * pick stays behind the kit's recording. Resolves to `null` when the folder is not there (a machine without the owner's sounds): nothing changes.
+ */
+declare function loadUserSamples(engine: Registers, options?: LoadUserSamplesOptions): Promise<UserSampleBankResult | null>;
+
 /**
  * Two probe sounds of the bench itself (a ping and a hiss), so panning, distance and the seed can be heard on something that has no subject. They are
  * made by the kit, not delivered by any team (`sdk` in the sources).
@@ -1068,4 +1247,4 @@ type AudioBenchText = {
 };
 declare const audioBenchTextOf: (locale: string) => AudioBenchText;
 
-export { LAYER_FLOOR as $, type AudioLoopHandle as A, type BusId as B, CRITERIA as C, type CriterionId as D, type CriterionResult as E, type Falloff as F, type Curve as G, DEFAULT_CROSSOVER as H, DEFAULT_LISTENER as I, DEFAULT_MAX_VOICES as J, DEFAULT_MIX as K, type LoopRecipe as L, type MixProfile as M, DEFAULT_SAMPLE_CUTOFF_K as N, DEFAULT_SAMPLE_FALLOFF as O, type ParamRef as P, DEFAULT_SAMPLE_PITCH as Q, type Range as R, type SampleSound as S, DEFAULT_TAIL_GAIN as T, type DeepPartial as U, type DistanceMode as V, type Envelope as W, type EnvelopePoint as X, type FilterBank as Y, type FilterSpec as Z, type FormantVoiceSource as _, type SampleLoader as a, createSoundRegistry as a$, type LayerSource as a0, type Listener as a1, type LoopOrder as a2, type LoopSet as a3, MIX_PROFILES as a4, type MeasureOptions as a5, type Modulator as a6, type NoiseSource as a7, OPEN_CUTOFF as a8, type OscSource as a9, type SampleTail as aA, type SampleTier as aB, type SfxBlow as aC, type SfxCategory as aD, type SfxEntry as aE, type SfxMaterial as aF, type SfxPriority as aG, type SfxState as aH, type SoundRegistry as aI, type StartQueueOptions as aJ, type Time as aK, VOICE_GROUPS as aL, type VoiceDecision as aM, type VoiceGroup as aN, type VoiceHandle as aO, type VoiceManager as aP, type VoiceManagerOptions as aQ, type VoiceRefusal as aR, type VoiceRequest as aS, type VoiceStartEvent as aT, type VoiceStats as aU, audioBenchTextOf as aV, busGain as aW, busPriority as aX, createAudioEngine as aY, createAudioTestModule as aZ, createSampleStore as a_, PAN_LIMIT as aa, PAN_MIN_DISTANCE as ab, type PlanInput as ac, type PlannedAutomation as ad, type PlannedEnvelopePoint as ae, type PlannedFilter as af, type PlannedLayer as ag, type PlannedModulator as ah, type PlannedSampleLayer as ai, type PlannedSource as aj, type PlayOptions as ak, SAMPLE_ENVIRONMENTS as al, SFX_BLOWS as am, SFX_CATALOG as an, SFX_CATEGORIES as ao, SFX_IMPACTS as ap, SFX_MATERIALS as aq, type SampleEnvironment as ar, type SampleLayerRole as as, type SampleLoadReport as at, type SampleMemory as au, type SampleOptions as av, type SamplePlanInput as aw, type SampleRef as ax, type SampleStatus as ay, type SampleStore as az, type SampleCrossover as b, createVoiceManager as b0, crossGains as b1, farMixAt as b2, fetchLoader as b3, impactSoundId as b4, inlineLoader as b5, limiterCurve as b6, listenerDistance as b7, measureCriteria as b8, panFor as b9, pickTake as ba, planSample as bb, planSound as bc, recordOutput as bd, resolveMix as be, sampleCutoff as bf, sampleUrls as bg, sfxState as bh, tierFor as bi, type SoundBank as c, type SoundRecipe as d, type Layer as e, type SoundSet as f, type SoundPlan as g, type SamplePlan as h, type LoopEntry as i, type AudioEngine as j, type ActionCheck as k, type AudioBenchText as l, type AudioChannel as m, type AudioEngineOptions as n, type AudioScenarioLike as o, type AudioStats as p, type AudioTestModule as q, type AudioTestModuleOptions as r, type Automation as s, BENCH_BANK as t, BUILD_ORDERS as u, BUS_IDS as v, BUS_PRIORITY as w, type BuildOrder as x, type BusSetting as y, CRITERIA_TARGETS as z };
+export { type FormantVoiceSource as $, type AudioLoopHandle as A, type BusId as B, CRITERIA as C, CRITERIA_TARGETS as D, type CriterionId as E, type Falloff as F, type CriterionResult as G, type Curve as H, DEFAULT_CROSSOVER as I, DEFAULT_LISTENER as J, DEFAULT_MAX_VOICES as K, type LoopRecipe as L, type MixProfile as M, DEFAULT_MIX as N, DEFAULT_SAMPLE_CUTOFF_K as O, type ParamRef as P, DEFAULT_SAMPLE_FALLOFF as Q, type Range as R, type SampleSound as S, DEFAULT_SAMPLE_PITCH as T, DEFAULT_TAIL_GAIN as U, type DeepPartial as V, type DistanceMode as W, type Envelope as X, type EnvelopePoint as Y, type FilterBank as Z, type FilterSpec as _, type SampleLoader as a, type UserSampleBankOptions as a$, KIT_SAMPLES_BANK as a0, LAYER_FLOOR as a1, type LayerSource as a2, type Listener 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 SampleLayerRole as aA, type SampleLoadReport as aB, type SampleMemory as aC, type SampleOptions as aD, type SamplePlanInput as aE, type SampleRef as aF, type SampleStatus as aG, type SampleStore as aH, type SampleTail as aI, type SampleTier as aJ, type SdkLicense as aK, type SfxBlow as aL, type SfxCategory as aM, type SfxEntry as aN, type SfxFileEntry as aO, type SfxLayer as aP, type SfxManifestLike as aQ, type SfxManifestSound as aR, type SfxMaterial as aS, type SfxPriority as aT, type SfxState as aU, type SoundRegistry as aV, type SoundSource as aW, type StartQueueOptions as aX, type Time as aY, USER_SAMPLES_BANK as aZ, USER_SOUND_PREFIX 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 SampleBankOptions as ax, type SampleCrossover as ay, type SampleEnvironment as az, type SfxManifest as b, type UserSampleBankResult as b0, type UserSfxFile as b1, type UserSfxManifest as b2, type UserSfxSound as b3, type UserSoundPick as b4, type UserSoundPicks as b5, type UserSoundRole as b6, VOICE_GROUPS as b7, type VoiceDecision as b8, type VoiceGroup as b9, pickTake as bA, planSample as bB, planSound as bC, recordOutput as bD, resolveMix as bE, sampleBankFromManifest as bF, sampleCutoff as bG, sampleUrls as bH, sfxState as bI, soundSourceOf as bJ, splitTier as bK, tierFor as bL, userSampleBank as bM, type VoiceHandle as ba, type VoiceManager as bb, type VoiceManagerOptions as bc, type VoiceRefusal as bd, type VoiceRequest as be, type VoiceStartEvent as bf, type VoiceStats as bg, audioBenchTextOf as bh, busGain as bi, busPriority as bj, createAudioEngine as bk, createAudioTestModule as bl, createSampleStore as bm, createSoundRegistry as bn, createVoiceManager as bo, crossGains as bp, farMixAt as bq, fetchLoader as br, impactSoundId as bs, inlineLoader as bt, limiterCurve as bu, listenerDistance as bv, loadUserSamples as bw, measureCriteria as bx, panFor as by, parseSfxName 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 LoopEntry as j, type AudioEngine as k, type ActionCheck as l, type AudioBenchText as m, type AudioChannel as n, type AudioEngineOptions as o, type AudioScenarioLike as p, type AudioStats as q, type AudioTestModule as r, type AudioTestModuleOptions as s, type Automation as t, BENCH_BANK as u, BUILD_ORDERS as v, BUS_IDS as w, BUS_PRIORITY as x, type BuildOrder as y, type BusSetting as z };

package/dist/testing.d.ts

@@ -1,13 +1,13 @@
-import { aC as SfxBlow, aF as SfxMaterial, ar as SampleEnvironment, aH as SfxState, D as CriterionId, o as AudioScenarioLike, j as AudioEngine, E as CriterionResult, aT as VoiceStartEvent, aO as VoiceHandle, c as SoundBank, a as SampleLoader, aE as SfxEntry, k as ActionCheck } from './locale-BugSe8dA.js';
-export { l as AudioBenchText, q as AudioTestModule, r as AudioTestModuleOptions, t as BENCH_BANK, aV as audioBenchTextOf, aZ as createAudioTestModule } from './locale-BugSe8dA.js';
+import { aL as SfxBlow, aS as SfxMaterial, az as SampleEnvironment, aU as SfxState, E as CriterionId, aW as SoundSource, p as AudioScenarioLike, k as AudioEngine, G as CriterionResult, bf as VoiceStartEvent, ba as VoiceHandle, c as SoundBank, a as SampleLoader, aN as SfxEntry, l as ActionCheck } from './locale-CJfDpWnI.js';
+export { m as AudioBenchText, r as AudioTestModule, s as AudioTestModuleOptions, u as BENCH_BANK, bh as audioBenchTextOf, bl as createAudioTestModule } from './locale-CJfDpWnI.js';
 import { TestableModule } from '@adatechnology/game-contracts';
 
 type Strength = 'light' | 'medium' | 'heavy';
 type SoundCheckText = {
     readonly group: string;
     readonly name: string;
-    readonly controls: Readonly<Record<'category' | 'sound' | 'play' | 'material' | 'blow' | 'strike' | 'distance' | 'bearing' | 'environment' | 'strength' | 'wall' | 'burst' | 'play_a' | 'play_b' | 'ab_cycle' | 'blind' | 'reveal' | 'prefer_a' | 'prefer_b' | 'measure' | 'record' | 'approve', string>>;
-    readonly hints: Readonly<Record<'sound' | 'strike' | 'wall' | 'burst' | 'ab_cycle' | 'blind' | 'measure' | 'record' | 'approve', string>>;
+    readonly controls: Readonly<Record<'category' | 'sound' | 'play' | 'play_user' | 'material' | 'blow' | 'strike' | 'distance' | 'bearing' | 'environment' | 'strength' | 'wall' | 'burst' | 'play_a' | 'play_b' | 'ab_cycle' | 'blind' | 'reveal' | 'prefer_a' | 'prefer_b' | 'measure' | 'record' | 'approve', string>>;
+    readonly hints: Readonly<Record<'play_user' | 'sound' | 'strike' | 'wall' | 'burst' | 'ab_cycle' | 'blind' | 'measure' | 'record' | 'approve', string>>;
     readonly categories: Readonly<Record<string, string>>;
     readonly blows: Readonly<Record<SfxBlow, string>>;
     readonly materials: Readonly<Record<SfxMaterial, string>>;
@@ -15,9 +15,11 @@ type SoundCheckText = {
     readonly strengths: Readonly<Record<Strength, string>>;
     readonly states: Readonly<Record<SfxState, string>>;
     readonly criteria: Readonly<Record<CriterionId, string>>;
-    readonly metrics: Readonly<Record<'chosen' | 'matrix' | 'last' | 'ab' | 'blind' | 'verdicts' | 'state' | 'count', string>>;
+    readonly metrics: Readonly<Record<'source' | 'chosen' | 'matrix' | 'last' | 'ab' | 'blind' | 'verdicts' | 'state' | 'count', string>>;
     readonly run: Readonly<Record<'idle' | 'measuring' | 'done' | 'failed' | 'recording' | 'recorded', string>>;
     readonly words: Readonly<Record<'none' | 'hidden' | 'prefers' | 'approved', string>>;
+    /** Where the voice came from: the kit's file, the owner's file, the synthesized recipe. */
+    readonly sources: Readonly<Record<SoundSource, string>>;
     readonly probe: string;
     readonly wall: string;
     readonly scenarios: Readonly<Record<'pipeline' | 'criteria' | 'loop' | 'panel', string>>;

package/dist/testing.js

@@ -6,7 +6,7 @@ import {
   createAudioTestModule,
   createSoundCheckModule,
   soundCheckTextOf
-} from "./chunk-7TLFY7VO.js";
+} from "./chunk-KBTUANNG.js";
 export {
   BENCH_BANK,
   CALIBRATION_CATEGORY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/game-audio",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "Sound as data for games: recipes planned into resolved, seeded sound plans, a WebAudio layer that builds them, distance curves, pan, a voice limiter, loops and mixing profiles taken from the teams (the game and the art scene). Sounds from recorded files too (.ogg takes with round-robin, pitch, near/far layers, indoor/outdoor tails and strength tiers), a converter for the files the team drops in, and a measuring harness of the sound criteria. Knows nothing about any game.",
   "keywords": [
@@ -57,6 +57,7 @@
     "build": "tsup",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "sfx:convert": "node scripts/sfx-convert.mjs"
+    "sfx:convert": "node scripts/sfx-convert.mjs",
+    "sfx:user": "node scripts/sfx-user.mjs"
   }
 }