@adatechnology/game-audio 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -649,6 +649,13 @@ type AudioLoopHandle = {
     stop(): void;
 };
 
+type StartQueueOptions = {
+    /** Most milliseconds of main-thread work one task spends building voices (at least one voice is always built). Default 2. */
+    readonly budgetMs?: number;
+    /** A voice still waiting after this many milliseconds is dropped instead of starting late. Default 250. */
+    readonly maxLatencyMs?: number;
+};
+
 type PlayOptions = {
     readonly position?: Vec3;
     /** Meters; overrides `position` for the distance (not for the pan). */
@@ -694,6 +701,8 @@ type AudioEngineOptions = {
     /** 0 (clear) to 1 (behind a wall) for a sound at a point; without it there is no occlusion (Q8). */
     readonly occlusion?: (point: Vec3) => number;
     readonly createContext?: () => AudioContext | null;
+    /** Build voices in timed slices between frames instead of inside `play` (a sound starts a few ms late; a burst never costs a frame). Off by default. */
+    readonly deferredStart?: StartQueueOptions;
 };
 type AudioEngine = {
     readonly registry: SoundRegistry;
@@ -719,6 +728,8 @@ type AudioEngine = {
     setMaster(gain: number): void;
     /** Creates the context and the mixing chain if needed and resumes it; call from a click or a key. */
     unlock(): void;
+    /** Creates the context, the mixing chain (reverb impulse included) and the shared noise buffer now, so the first sound does not pay for them inside a frame. Returns false without a context. */
+    warmUp(): boolean;
     stats(): AudioStats;
     /** RMS (0 to 1) of what a bus carries now, read from an analyser the first time you ask; sounds started before that do not reach it. 0 without a context. */
     level(bus: BusId): number;
@@ -843,4 +854,4 @@ type AudioBenchText = {
 };
 declare const audioBenchTextOf: (locale: string) => AudioBenchText;
 
-export { type AudioBenchText, type AudioChannel, type AudioEngine, type AudioEngineOptions, type AudioLoopHandle, type AudioScenarioLike, type AudioStats, type AudioTestModule, type AudioTestModuleOptions, type Automation, BENCH_BANK, BUILD_ORDERS, BUS_IDS, BUS_PRIORITY, type BuildOrder, type BusId, type BusSetting, type Curve, DEFAULT_LISTENER, DEFAULT_MAX_VOICES, DEFAULT_MIX, DISTANCE_CURVES, type DeepPartial, type DistanceCurveName, type DistanceMode, type EngineSink, type Envelope, type EnvelopePoint, type Falloff, type FilterBank, type FilterSpec, type FormantVoiceSource, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, type Layer, type LayerSource, type Listener, type LoopAction, type LoopOrder, type LoopRecipe, type LoopState, MIX_PROFILES, type MixChain, type MixProfile, type Modulator, type NoiseClass, type NoiseSource, type OscSource, PAN_LIMIT, PAN_MIN_DISTANCE, type ParamRef, type PlanInput, type PlannedAutomation, type PlannedEnvelopePoint, type PlannedFilter, type PlannedLayer, type PlannedModulator, type PlannedSource, type PlayOptions, type Range, type RealizeTarget, type RealizedVoice, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SoundBank, type SoundPlan, type SoundRecipe, type SoundRegistry, type Time, VOICE_GROUPS, type VoiceDecision, type VoiceGroup, type VoiceHandle, type VoiceManager, type VoiceManagerOptions, type VoiceRefusal, type VoiceRequest, type VoiceStats, audioBenchTextOf, bufferOf, buildChain, busGain, busPriority, createAudioEngine, createAudioSink, createAudioTestModule, createLoopState, createRng, createSoundRegistry, createVoiceManager, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, listenerDistance, noiseClassRecipe, panFor, planSound, realize, resolveMix, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext };
+export { type AudioBenchText, type AudioChannel, type AudioEngine, type AudioEngineOptions, type AudioLoopHandle, type AudioScenarioLike, type AudioStats, type AudioTestModule, type AudioTestModuleOptions, type Automation, BENCH_BANK, BUILD_ORDERS, BUS_IDS, BUS_PRIORITY, type BuildOrder, type BusId, type BusSetting, type Curve, DEFAULT_LISTENER, DEFAULT_MAX_VOICES, DEFAULT_MIX, DISTANCE_CURVES, type DeepPartial, type DistanceCurveName, type DistanceMode, type EngineSink, type Envelope, type EnvelopePoint, type Falloff, type FilterBank, type FilterSpec, type FormantVoiceSource, GAME_SFX_BANK, GAME_SFX_CLASSES, GAME_SFX_FALLBACK, LIBRARY_BANK, LIBRARY_LOOPS, LIBRARY_SOUNDS, LOOP_SMOOTHING, LOOP_START_ABOVE, type Layer, type LayerSource, type Listener, type LoopAction, type LoopOrder, type LoopRecipe, type LoopState, MIX_PROFILES, type MixChain, type MixProfile, type Modulator, type NoiseClass, type NoiseSource, type OscSource, PAN_LIMIT, PAN_MIN_DISTANCE, type ParamRef, type PlanInput, type PlannedAutomation, type PlannedEnvelopePoint, type PlannedFilter, type PlannedLayer, type PlannedModulator, type PlannedSource, type PlayOptions, type Range, type RealizeTarget, type RealizedVoice, type SceneLength, type SceneNoise, type SceneRecipeOptions, type SceneTone, type SceneVoice, type SoundBank, type SoundPlan, type SoundRecipe, type SoundRegistry, type StartQueueOptions, type Time, VOICE_GROUPS, type VoiceDecision, type VoiceGroup, type VoiceHandle, type VoiceManager, type VoiceManagerOptions, type VoiceRefusal, type VoiceRequest, type VoiceStats, audioBenchTextOf, bufferOf, buildChain, busGain, busPriority, createAudioEngine, createAudioSink, createAudioTestModule, createLoopState, createRng, createSoundRegistry, createVoiceManager, cutoffDivisor, drawBetween, falloffGain, fillImpulse, fillNoise, globalContext, isSilent, listenerDistance, noiseClassRecipe, panFor, planSound, realize, resolveMix, sceneMany, sceneNoise, sceneRecipe, sceneTone, sceneVoice, streamFor, streamSeed, unlockContext };

package/dist/index.global.js

@@ -1064,6 +1064,56 @@ var GameAudio = (() => {
     return store.buffer;
   }
 
+  // src/webaudio/engine-queue.ts
+  var nowMs = () => typeof performance === "undefined" ? Date.now() : performance.now();
+  function scheduleTask(task) {
+    if (typeof MessageChannel === "undefined") {
+      setTimeout(task, 0);
+      return;
+    }
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      task();
+    };
+    channel.port2.postMessage(0);
+  }
+  function createStartQueue(options = {}) {
+    const budgetMs = options.budgetMs ?? 2;
+    const maxLatencyMs = options.maxLatencyMs ?? 250;
+    let jobs = [];
+    let scheduled = false;
+    const drain = () => {
+      scheduled = false;
+      const began = nowMs();
+      while (jobs.length > 0) {
+        const job = jobs.shift();
+        if (nowMs() - job.queuedAt > maxLatencyMs) job.drop();
+        else job.run();
+        if (nowMs() - began >= budgetMs) break;
+      }
+      if (jobs.length > 0) schedule();
+    };
+    const schedule = () => {
+      if (scheduled) return;
+      scheduled = true;
+      scheduleTask(drain);
+    };
+    return {
+      push(job) {
+        jobs.push({ ...job, queuedAt: nowMs() });
+        schedule();
+      },
+      clear() {
+        for (const job of jobs) job.drop();
+        jobs = [];
+      },
+      get size() {
+        return jobs.length;
+      }
+    };
+  }
+
   // src/webaudio/realize-game.ts
   var end = (layer, start) => start + layer.duration + layer.tail;
   var firstFilter = (layer) => layer.filters?.bank[0];
@@ -1513,15 +1563,43 @@ var GameAudio = (() => {
       ...playOptions.params ? { params: playOptions.params } : {},
       ...options.occlusion && playOptions.position && recipe.falloff?.model !== "none" ? { occlusion: options.occlusion(playOptions.position) } : {}
     });
-    const start = (plan, store, voiceId, delay = 0) => {
+    const startQueue = options.deferredStart ? createStartQueue(options.deferredStart) : null;
+    const build = (plan, store, delay) => {
       const audio = context;
-      const realized = realize(plan, {
+      return realize(plan, {
         context: audio,
         output: outputFor(plan.bus),
         ...chain?.wet ? { wet: chain.wet } : {},
         noise: () => noiseBuffer(store, audio, mix.noise.seconds),
         time: audio.currentTime + delay
       });
+    };
+    const deferVoice = (plan, store, voiceId, delay) => {
+      let built = null;
+      let cancelled = false;
+      const pending = {
+        get sources() {
+          return built?.sources ?? [];
+        },
+        stop() {
+          cancelled = true;
+          built?.stop();
+        }
+      };
+      startQueue.push({
+        run() {
+          if (!cancelled && context) built = build(plan, store, delay);
+        },
+        drop() {
+          if (voiceId === void 0) return;
+          voices.release(voiceId);
+          active.delete(voiceId);
+        }
+      });
+      return pending;
+    };
+    const start = (plan, store, voiceId, delay = 0) => {
+      const realized = startQueue ? deferVoice(plan, store, voiceId, delay) : build(plan, store, delay);
       if (voiceId === void 0) return null;
       voices.setLength(voiceId, plan.length + delay);
       active.set(voiceId, realized);
@@ -1637,6 +1715,12 @@ var GameAudio = (() => {
         const audio = ready();
         if (audio) unlockContext(audio);
       },
+      warmUp() {
+        const audio = ready();
+        if (!audio) return false;
+        noiseBuffer(shared, audio, mix.noise.seconds);
+        return true;
+      },
       level(bus) {
         watched.add(bus);
         ensureBus(bus);
@@ -1660,6 +1744,7 @@ var GameAudio = (() => {
         };
       },
       dispose() {
+        startQueue?.clear();
         for (const id of active.keys()) voices.release(id);
         for (const loop of [...loops]) loop.stop();
         active.clear();