cacophony 0.21.0 → 0.24.0

package/README.md

@@ -13,7 +13,7 @@ Cacophony is a powerful and intuitive audio library designed for modern web appl
 - **Synthesizer Integration**: Create and manipulate synthesized sounds with customizable oscillator options
 - **Efficient Group Management**: Organize and control multiple sounds or synthesizers as groups for streamlined audio management
 - **Live Microphone Input**: Capture and process real-time audio input from the user's microphone
-- **Network-Backed Playback**: Play audio directly from URLs using media-element-backed sounds
+- **Network-Backed Playback**: Play audio directly from URLs using media-element-backed sounds
 - **Flexible Caching**: Implement efficient audio caching strategies for improved performance
 
 ## Installation
@@ -55,6 +55,43 @@ async function audioDemo() {
 audioDemo();
 ```
 
+## Mobile Autoplay Handling
+
+Modern browsers — especially iOS Safari and Chrome on Android — refuse to
+produce sound from an `AudioContext` that was constructed before any user
+interaction. The context is created in `suspended` state and must be both
+resumed AND have a node started from inside a real user-gesture call stack
+before audio can play. Calling `context.resume()` alone is not enough on iOS.
+
+Cacophony handles this transparently by default. When you construct a
+`Cacophony` instance and the context is suspended, it installs one-time
+`touchend` / `click` / `keydown` listeners on `document.body`. The first
+user gesture resumes the context, plays a 1-sample silent primer buffer (the
+iOS unlock primer), removes the listeners, and emits the `unlock` event.
+
+```typescript
+const cacophony = new Cacophony();
+
+if (cacophony.locked) {
+  // Mobile: waiting for the first user interaction.
+  // Show a "tap to enable audio" affordance if you want one.
+}
+
+cacophony.on('unlock', () => {
+  // Audio is now usable.
+});
+```
+
+If you prefer to manage unlock yourself, opt out:
+
+```typescript
+const cacophony = new Cacophony(undefined, undefined, { autoUnlock: false });
+// You are responsible for calling cacophony.resume() inside a user gesture.
+```
+
+The auto-unlock has no effect on offline contexts or in non-browser
+environments (`typeof document === 'undefined'`).
+
 ## Core Concepts
 
 ### Sound vs Playback Architecture
@@ -92,25 +129,59 @@ sound.stop();  // Stops all three playbacks
 
 ## Sound Types
 
-Cacophony supports three sound types:
+Cacophony supports three sound types:
 
-| Type | Memory | Latency | Seeking | Multiple Instances | Best For |
-|------|--------|---------|---------|-------------------|----------|
-| **Buffer** (default) | High | None | Full | Yes | Sound effects, UI sounds, short music clips |
-| **HTML** | Medium | Low | Full | Yes | Background music, large audio files, podcasts |
-| **Streaming** | Medium | Low | Full | Yes | Network-backed playback created via `createStream()` |
+| Type | Memory | Latency | Seeking | Multiple Instances | Best For |
+|------|--------|---------|---------|-------------------|----------|
+| **Buffer** (default) | High | None | Full | Yes | Sound effects, UI sounds, short music clips |
+| **HTML** | Medium | Low | Full | Yes | Background music, large audio files, podcasts |
+| **Streaming** | Medium | Low | Full | Yes | Network-backed playback created via `createStream()` |
 
 ```typescript
 // Buffer - entire file loaded into memory
-const sfx = await cacophony.createSound('explosion.mp3', SoundType.Buffer);
+const sfx = await cacophony.createSound('explosion.mp3', 'buffer');
 
 // HTML - streams from network, good for large files
-const music = await cacophony.createSound('bgm.mp3', SoundType.HTML);
+const music = await cacophony.createSound('bgm.mp3', 'html');
 
-// Streaming - convenience helper for network-backed playback
-const radio = await cacophony.createStream('https://example.com/stream.m3u8');
+// Streaming - convenience helper for network-backed playback
+const radio = await cacophony.createStream('https://example.com/stream.m3u8');
 ```
 
+### Format Fallback (Howler-style)
+
+Pass an array of URLs and Cacophony picks the first one the browser can play.
+It queries `HTMLAudioElement.canPlayType` per extension and fetches only the
+chosen source (cache and loading events fire only for that URL). If the
+selected source's `canPlayType` was `'maybe'` and decoding actually fails,
+the next playable candidate is tried.
+
+```typescript
+// First playable source wins. Cacophony fetches only that one.
+const boom = await cacophony.createSound([
+  'sfx/boom.webm',  // small/modern, preferred when supported
+  'sfx/boom.mp3',   // universal fallback
+  'sfx/boom.wav',   // last-resort uncompressed
+]);
+boom.play();
+```
+
+Recognised extensions: `.webm`, `.mp3`, `.ogg`, `.wav`, `.flac`, `.m4a`,
+`.aac`, `.opus`. If no candidate is reported playable, or every playable
+candidate fails to decode, the promise rejects with an error naming the
+URLs that were tried and the reason each failed (codec unsupported or
+decode failure).
+
+Only decode failures advance to the next candidate. Fetch/network/cache
+failures of the selected source propagate immediately so the caller sees
+the real cause instead of a silent format swap. Decode failures are
+detected by the Web Audio spec marker -- `DOMException` with name
+`EncodingError`.
+
+v1 limitation: format fallback is only available for the default `'buffer'`
+sound type. Passing an array together with `'html'` or `'streaming'`
+rejects with a "not yet supported" error.
+
 ## Playback Control
 
 ### Seeking
@@ -269,26 +340,98 @@ playback.connect(distortion)
 
 ### Parallel Effects (Send/Return)
 
-Create parallel effect sends like a mixing console:
+For mixing-console-style routing — named buses, shared effects, and
+per-edge send gain — use the first-class [Buses and Sends](#buses-and-sends)
+API documented below. The Bus class supersedes the older user-built
+`playback.connect()` send/return pattern.
+
+## Buses and Sends
+
+A `Bus` is a named summing node with its own filter chain and per-edge
+gain on outgoing connections. Sounds and synths route to buses via
+`routeTo`; buses can carry rich effects (not just BiquadFilter) by
+adding a `CacophonyEffect` to their filter chain. The built-in
+`cacophony.createReverb()` returns a DattorroReverb effect ready to drop
+into a bus.
 
 ```typescript
-const sound = await cacophony.createSound('vocals.mp3');
-const [playback] = sound.play();
+// 1. Create a named bus
+const reverbBus = cacophony.createBus('reverb');
 
-// Create send effects
-const reverb = cacophony.context.createConvolver();
-const reverbReturn = cacophony.context.createGain();
-reverbReturn.gain.value = 0.3;  // 30% wet
+// 2. Add a DattorroReverb effect to the bus
+const reverb = cacophony.createReverb({ wet: 0.6, dry: 0.4, decay: 0.7 });
+await reverbBus.addFilter(reverb);
 
-// Dry signal to destination
-playback.connect(cacophony.context.destination);
+// 3. Lower the bus's level a bit before it hits master
+reverbBus.gain = 0.5;
 
-// Parallel wet signal: playback → reverb → reverbReturn → destination
-playback.connect(reverb)
-        .connect(reverbReturn)
-        .connect(cacophony.context.destination);
+// 4. Route one sound's primary output to the bus
+const vocals = await cacophony.createSound('vocals.mp3');
+vocals.routeTo(reverbBus);
+vocals.play();
+
+// 5. Send another sound to the bus at 30% (primary route still goes to master)
+const drums = await cacophony.createSound('drums.mp3');
+drums.routeTo(reverbBus, 0.3);
+drums.play();
 ```
 
+### Looking up buses by name
+
+```typescript
+const fx = cacophony.createBus('fx');
+cacophony.getBus('fx');       // → same Bus instance
+cacophony.listBuses();        // → ['master', 'fx']
+sound.routeTo('fx');          // string lookup via the registry
+```
+
+### The master bus
+
+`cacophony.master` is the built-in master bus. Its `input` is literally
+the same node as `cacophony.globalGainNode`, so the existing
+`cacophony.volume` and `cacophony.mute` APIs continue to work
+transparently. Routing a sound to `cacophony.master` (or never calling
+`routeTo`) sends it through the master path.
+
+### Bus-to-bus routing with per-edge gain
+
+```typescript
+const groupBus = cacophony.createBus('group');
+const sendBus = cacophony.createBus('aux');
+groupBus.connect(sendBus, 0.2);   // 20% send: groupBus.output → sendGain(0.2) → sendBus.input
+groupBus.disconnect(sendBus);     // tears down the sendGain too
+```
+
+### Adding custom effects to a bus
+
+Bus filter chains accept Cacophony-built BiquadFilters and any
+`CacophonyEffect`. Raw third-party AudioNodes are rejected unless you
+wrap them explicitly with `cacophony.shareEffect(node)` — this surfaces
+the shared-state intent (the same node will run on every bus that adds it).
+
+```typescript
+const eq = cacophony.createBiquadFilter({ type: 'highshelf', frequency: 4000, gain: 3 });
+await bus.addFilter(eq);
+
+const sharedWorklet = new AudioWorkletNode(cacophony.context, 'my-fx');
+await bus.addFilter(cacophony.shareEffect(sharedWorklet));
+```
+
+### Cleaning up
+
+```typescript
+reverbBus.destroy();   // disconnects everything, deregisters the name
+```
+
+Sounds still routed to a destroyed bus fall back to master on their
+next playback with a `console.warn`.
+
+### Legacy: user-built send/return
+
+Before buses existed, send/return was a manual `playback.connect()`
+chain (see the [Custom Audio Routing](#custom-audio-routing) section
+for the low-level pattern). New code should use a Bus and `routeTo`.
+
 ### Dynamic Routing
 
 Change routing in real-time:
@@ -441,28 +584,28 @@ const footsteps = await cacophony.createGroupFromUrls([
 
 footsteps.playRandom();  // Picks one at random
 
-// Advance through sounds in sequence, one call at a time
-const dialog = await cacophony.createGroupFromUrls(['line1.mp3', 'line2.mp3', 'line3.mp3']);
-dialog.playOrdered(true);   // Plays line1, then advances internal order
-dialog.playOrdered(true);   // Plays line2
-dialog.playOrdered(true);   // Plays line3
-dialog.playOrdered(true);   // Plays line1 again because looping is enabled
-
-// SynthGroup for synthesizers
-const synthGroup = new SynthGroup();
-const synth1 = cacophony.createOscillator({ frequency: 440, type: 'sine' });
-const synth2 = cacophony.createOscillator({ frequency: 660, type: 'square' });
-synthGroup.addSynth(synth1);
-synthGroup.addSynth(synth2);
-synthGroup.play();
-synthGroup.volume = 0.5;
-synthGroup.type = 'triangle';
-synthGroup.pause();
-synthGroup.resume();
-
-// Remove a synth from the group
-synthGroup.removeSynth(synth1);
-```
+// Advance through sounds in sequence, one call at a time
+const dialog = await cacophony.createGroupFromUrls(['line1.mp3', 'line2.mp3', 'line3.mp3']);
+dialog.playOrdered(true);   // Plays line1, then advances internal order
+dialog.playOrdered(true);   // Plays line2
+dialog.playOrdered(true);   // Plays line3
+dialog.playOrdered(true);   // Plays line1 again because looping is enabled
+
+// SynthGroup for synthesizers
+const synthGroup = new SynthGroup();
+const synth1 = cacophony.createOscillator({ frequency: 440, type: 'sine' });
+const synth2 = cacophony.createOscillator({ frequency: 660, type: 'square' });
+synthGroup.addSynth(synth1);
+synthGroup.addSynth(synth2);
+synthGroup.play();
+synthGroup.volume = 0.5;
+synthGroup.type = 'triangle';
+synthGroup.pause();
+synthGroup.resume();
+
+// Remove a synth from the group
+synthGroup.removeSynth(synth1);
+```
 
 ## Synthesizer Functionality
 
@@ -489,22 +632,22 @@ bass.addFilter(cacophony.createBiquadFilter({ type: 'lowpass', frequency: 1000 }
 bass.play();
 lead.play();
 
-// Modulate frequency over time
-let time = 0;
-setInterval(() => {
-  const frequency = 440 + Math.sin(time) * 100;
-  sineOsc.frequency = frequency;
-  time += 0.1;
-}, 50);
-
-// Pause and resume the active synth playback without losing its settings
-sineOsc.pause();
-sineOsc.resume();
-```
-
-`synth.pause()` keeps the existing synth playback object so `synth.resume()` can restart it with the current frequency, detune, type, volume, pan, and filter settings. `synth.play()` still creates a fresh playback instance, just like `Sound.play()`.
-
-## 3D Audio Positioning
+// Modulate frequency over time
+let time = 0;
+setInterval(() => {
+  const frequency = 440 + Math.sin(time) * 100;
+  sineOsc.frequency = frequency;
+  time += 0.1;
+}, 50);
+
+// Pause and resume the active synth playback without losing its settings
+sineOsc.pause();
+sineOsc.resume();
+```
+
+`synth.pause()` keeps the existing synth playback object so `synth.resume()` can restart it with the current frequency, detune, type, volume, pan, and filter settings. `synth.play()` still creates a fresh playback instance, just like `Sound.play()`.
+
+## 3D Audio Positioning
 
 Create immersive soundscapes with precise spatial audio control using HRTF (Head-Related Transfer Function) or stereo panning.
 
@@ -512,9 +655,9 @@ Create immersive soundscapes with precise spatial audio control using HRTF (Head
 const cacophony = new Cacophony();
 
 // Create sounds with HRTF panning
-const ambience = await cacophony.createSound('forest_ambience.mp3', SoundType.Buffer, 'HRTF');
-const birdSound = await cacophony.createSound('bird_chirp.mp3', SoundType.Buffer, 'HRTF');
-const footsteps = await cacophony.createSound('footsteps.mp3', SoundType.Buffer, 'HRTF');
+const ambience = await cacophony.createSound('forest_ambience.mp3', 'buffer', 'HRTF');
+const birdSound = await cacophony.createSound('bird_chirp.mp3', 'buffer', 'HRTF');
+const footsteps = await cacophony.createSound('footsteps.mp3', 'buffer', 'HRTF');
 
 // Position sounds in 3D space
 // Coordinate system: X (left- to right+), Y (down- to up+), Z (front+ to back-)
@@ -550,7 +693,7 @@ setInterval(() => {
 }, 50);
 
 // Stereo panning (simple left-right)
-const stereoSound = await cacophony.createSound('audio.mp3', SoundType.Buffer, 'stereo');
+const stereoSound = await cacophony.createSound('audio.mp3', 'buffer', 'stereo');
 stereoSound.stereoPan = 0.5;  // -1 (left) to 1 (right)
 stereoSound.play();
 ```
@@ -838,7 +981,7 @@ const controller = new AbortController();
 
 const soundPromise = cacophony.createSound(
   'large-file.mp3',
-  SoundType.Buffer,
+  'buffer',
   'HRTF',
   controller.signal
 );
@@ -858,7 +1001,7 @@ try {
 // Works with groups too
 const group = await cacophony.createGroupFromUrls(
   ['a.mp3', 'b.mp3', 'c.mp3'],
-  SoundType.Buffer,
+  'buffer',
   'HRTF',
   controller.signal
 );
@@ -869,9 +1012,9 @@ const group = await cacophony.createGroupFromUrls(
 Call `cleanup()` when done with sounds to free resources:
 
 ```typescript
-const sound = await cacophony.createSound('temp.mp3');
-sound.play();
-sound.cleanup();  // Tears down playbacks, including pausing and resetting active HTML/streaming media
+const sound = await cacophony.createSound('temp.mp3');
+sound.play();
+sound.cleanup();  // Tears down playbacks, including pausing and resetting active HTML/streaming media
 
 // Clear memory cache
 cacophony.clearMemoryCache();

package/dist/autoplayUnlock.d.ts

@@ -0,0 +1,28 @@
+import { BaseContext } from './context';
+/**
+ * Options for `installAutoplayUnlock`.
+ */
+export interface AutoplayUnlockOptions {
+    /**
+     * The audio context that should be resumed and primed.
+     */
+    context: BaseContext;
+    /**
+     * Called after the context has been resumed and the primer buffer has been
+     * started. Used by `Cacophony` to emit the public `unlock` event.
+     * Errors thrown by the callback are caught and logged so a faulty listener
+     * cannot break the unlock flow.
+     */
+    onUnlock: () => void;
+}
+/**
+ * Install one-time unlock listeners. Returns a cleanup function that removes
+ * the listeners if they have not already fired (e.g. when a `Cacophony`
+ * instance is torn down before the user interacts).
+ *
+ * If the environment is non-browser (`document` is undefined) or the context
+ * is not in `suspended` state, this is a no-op and returns a no-op cleanup.
+ *
+ * @internal
+ */
+export declare function installAutoplayUnlock(opts: AutoplayUnlockOptions): () => void;

package/dist/bus.d.ts

@@ -0,0 +1,117 @@
+import { AudioNode, BaseContext, BiquadFilterNode, GainNode } from './context';
+import { CacophonyEffect } from './effects';
+/**
+ * Connection target for {@link Bus.connect} / {@link Bus.disconnect}. Either
+ * another Bus (we connect into its `input`) or a raw AudioNode (we connect
+ * directly to it — escape hatch for advanced wiring).
+ */
+export type BusConnectionTarget = Bus | AudioNode;
+/**
+ * A named summing node with a filter chain and per-edge send gain. See
+ * module-level docstring for topology.
+ */
+export declare class Bus {
+    /** Stable name for registry lookup, or null for anonymous buses. */
+    readonly name: string | null;
+    /**
+     * Entry node — connect upstream sources here (sound playbacks, other bus
+     * outputs).
+     */
+    readonly input: GainNode;
+    /**
+     * Exit node — connected to downstream targets (other bus inputs, master,
+     * raw nodes) via {@link connect}.
+     */
+    readonly output: GainNode;
+    private readonly _context;
+    private readonly _filterNodes;
+    private readonly _filterChainEdges;
+    private readonly _sendGains;
+    private readonly _directConnections;
+    /**
+     * Hook invoked by the owning Cacophony instance to remove this bus from
+     * the named-bus registry on destroy. Anonymous buses leave this undefined.
+     */
+    private readonly _onDestroy?;
+    private _destroyed;
+    /**
+     * @param context Web Audio context the bus's nodes live on.
+     * @param name Name to register under, or null for an anonymous bus.
+     * @param input Optional pre-existing GainNode to use as the input. Used by
+     *   the `master` bus to alias `cacophony.globalGainNode`. If omitted, a
+     *   fresh GainNode is allocated.
+     * @param onDestroy Optional registry-cleanup hook fired by destroy().
+     */
+    constructor(context: BaseContext, name?: string | null, input?: GainNode, onDestroy?: () => void);
+    /** True after {@link destroy} has been called. */
+    get destroyed(): boolean;
+    /** Output node gain — controls the overall level the bus sends downstream. */
+    get gain(): number;
+    set gain(v: number);
+    /** Live filter chain (read-only view). */
+    get filters(): readonly AudioNode[];
+    /**
+     * Add a filter node to the bus's chain. Accepts:
+     *
+     * - A Cacophony-built BiquadFilterNode (created via
+     *   `cacophony.createBiquadFilter`) → added directly to the chain.
+     * - A {@link CacophonyEffect} → `build(context)` is awaited; the resulting
+     *   node is added to the chain.
+     * - A raw third-party AudioNode → REJECTED. Wrap it with
+     *   `cacophony.shareEffect(node)` (or a proper CacophonyEffect class) to
+     *   make the shared-state intent explicit.
+     *
+     * @throws if the bus has been destroyed, or if the argument is a raw
+     *   AudioNode that is not a Cacophony-built biquad.
+     */
+    addFilter(arg: BiquadFilterNode | CacophonyEffect | AudioNode): Promise<void>;
+    /**
+     * Remove a filter node from the bus's chain. The node must have been added
+     * via {@link addFilter}; the same object identity is used to match.
+     *
+     * @throws if the bus has been destroyed or if the node was never added.
+     */
+    removeFilter(node: AudioNode): void;
+    /**
+     * Connect this bus's output to another bus or to a raw AudioNode.
+     *
+     * If `gain` is omitted or equal to 1, connect directly (output →
+     * targetInput). If `gain` is provided, allocate an internal GainNode for
+     * per-edge attenuation: output → sendGain → targetInput. The sendGain is
+     * tracked so {@link disconnect} can tear it down cleanly.
+     *
+     * Re-connecting a target that is already wired is a no-op for the direct
+     * case; for a gained connection, the existing sendGain's `gain.value` is
+     * updated in place (no new edge is allocated).
+     *
+     * @throws if the bus has been destroyed.
+     */
+    connect(target: BusConnectionTarget, gain?: number): void;
+    /**
+     * Disconnect this bus's output from a target previously connected with
+     * {@link connect}. Tears down the allocated sendGain (if any). No-op if
+     * the target was never connected.
+     *
+     * @throws if the bus has been destroyed.
+     */
+    disconnect(target: BusConnectionTarget): void;
+    /**
+     * Tear down the bus — disconnects input, output, every send-gain, every
+     * filter, then deregisters from the owner Cacophony's named-bus map.
+     * Subsequent `addFilter`/`removeFilter`/`connect`/`disconnect` calls throw.
+     *
+     * Sounds routed to a destroyed bus fall back to master on their next
+     * playback (the routeTo machinery checks `destroyed` at preplay).
+     */
+    destroy(): void;
+    /**
+     * Rebuild the chain `input → [filter1 → ... → filterN] → output`. Called
+     * after any add/remove of a filter. Disconnects only the internal chain
+     * edges this bus created, then reapplies the chain. The output node's edges
+     * to downstream targets are not touched.
+     */
+    private _refreshFilters;
+    private _connectFilterChainEdge;
+    private _disconnectFilterChainEdges;
+    private _throwIfDestroyed;
+}

package/dist/cache.d.ts

@@ -1,14 +1,13 @@
 import { BaseContext } from './context';
+import { AudioEventCallbacks } from './events';
+/**
+ * Subset of {@link AudioEventCallbacks} relevant to {@link AudioCache} public API.
+ * Lets callers opt in to any combination of loading/cache events without
+ * having to import the full union.
+ */
+export type CacheCallbacks = Pick<AudioEventCallbacks, "onLoadingStart" | "onLoadingProgress" | "onLoadingComplete" | "onLoadingError" | "onCacheHit" | "onCacheMiss" | "onCacheError">;
 export interface ICache {
-    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: {
-        onLoadingStart?: (event: any) => void;
-        onLoadingProgress?: (event: any) => void;
-        onLoadingComplete?: (event: any) => void;
-        onLoadingError?: (event: any) => void;
-        onCacheHit?: (event: any) => void;
-        onCacheMiss?: (event: any) => void;
-        onCacheError?: (event: any) => void;
-    }): Promise<AudioBuffer>;
+    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: CacheCallbacks): Promise<AudioBuffer>;
     clearMemoryCache(): void;
 }
 /**
@@ -41,10 +40,9 @@ export declare class AudioCache implements ICache {
     static setCacheExpirationTime(time: number): void;
     private static openCache;
     /**
-     * Calls all registered callbacks for a specific event type on a URL
-     * @param url - The URL to get callbacks for
-     * @param callbackName - Name of the callback method to invoke
-     * @param eventData - Data to pass to the callbacks
+     * Calls all registered callbacks for a specific event type on a URL.
+     * Generic over the callback name so the payload type is checked against
+     * the canonical {@link CacheCallbacks} shape rather than `any`.
      */
     private static callAllCallbacks;
     private static getOrCreatePendingRequest;
@@ -52,10 +50,19 @@ export declare class AudioCache implements ICache {
     private static getBufferFromCache;
     private static fetchAndCacheBuffer;
     /**
-     * Creates a ReadableStream wrapper that tracks download progress
-     * Uses the callback aggregation system to emit progress to all registered listeners
+     * Atomically write a response body and its metadata into the cache.
+     * On failure, deletes both partial entries (best-effort via `allSettled`)
+     * and rethrows the original error.
+     */
+    private static writeBufferAndMetadata;
+    /**
+     * Creates a ReadableStream wrapper that tracks download progress.
+     * Uses the callback aggregation system to emit progress to all registered listeners.
+     * Honours `signal` between reads and releases the underlying reader on
+     * any exit path (done, error, abort).
      * @param response - The fetch Response object with ReadableStream body
      * @param url - URL being downloaded (for progress event data and callback lookup)
+     * @param signal - Optional AbortSignal observed at chunk boundaries
      * @returns Object containing the progress-tracking stream and total size
      */
     private static createProgressTrackingStream;
@@ -85,14 +92,6 @@ export declare class AudioCache implements ICache {
      * @returns Promise that resolves to decoded AudioBuffer
      * @throws Error if audio cannot be fetched or decoded
      */
-    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: {
-        onLoadingStart?: (event: any) => void;
-        onLoadingProgress?: (event: any) => void;
-        onLoadingComplete?: (event: any) => void;
-        onLoadingError?: (event: any) => void;
-        onCacheHit?: (event: any) => void;
-        onCacheMiss?: (event: any) => void;
-        onCacheError?: (event: any) => void;
-    }): Promise<AudioBuffer>;
+    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: CacheCallbacks): Promise<AudioBuffer>;
     clearMemoryCache(): void;
 }