cacophony 0.18.3 → 0.19.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
-- **Audio Streaming**: Support for streaming audio directly from URLs
+- **Network-Backed Playback**: Play audio directly from URLs using media-element-backed sounds
 - **Flexible Caching**: Implement efficient audio caching strategies for improved performance
 
 ## Installation
@@ -92,13 +92,13 @@ sound.stop();  // Stops all three playbacks
 
 ## Sound Types
 
-Cacophony supports three sound types, each optimized for different use cases:
+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 | Limited | Background music, large audio files, podcasts |
-| **Streaming** | Low | Medium | Limited | No | Internet radio, live streams, very large files |
+| 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
@@ -107,8 +107,8 @@ const sfx = await cacophony.createSound('explosion.mp3', SoundType.Buffer);
 // HTML - streams from network, good for large files
 const music = await cacophony.createSound('bgm.mp3', SoundType.HTML);
 
-// Streaming - for live streams
-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');
 ```
 
 ## Playback Control
@@ -441,22 +441,28 @@ const footsteps = await cacophony.createGroupFromUrls([
 
 footsteps.playRandom();  // Picks one at random
 
-// Play sounds in sequence
-const dialog = await cacophony.createGroupFromUrls(['line1.mp3', 'line2.mp3', 'line3.mp3']);
-dialog.playOrdered(true);  // Plays: 1, 2, 3, 1, 2, 3...
-
-// 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.setVolume(0.5);
-
-// 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
 
@@ -483,16 +489,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);
-```
-
-## 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.
 
@@ -857,9 +869,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();  // Disconnects nodes, removes playbacks, clears listeners
+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/basePlayback.d.ts

@@ -1,14 +1,14 @@
 import { FadeType } from './cacophony';
 import { IPlaybackContainer } from './container';
 import { AudioNode } from './context';
-import { FilterManager } from './filters';
 import { TypedEventEmitter } from './eventEmitter';
 import { PlaybackEvents } from './events';
+import { FilterManager } from './filters';
 declare const BasePlayback_base: (abstract new (...args: any[]) => {
     panner?: import('./context').PannerNode | import('./context').StereoPannerNode | undefined;
     _panType: import('./cacophony').PanType;
     readonly panType: import('./cacophony').PanType;
-    setPanType(panType: import('./cacophony').PanType, audioContext: import('standardized-audio-context').IAudioContext): void;
+    setPanType(panType: import('./cacophony').PanType, audioContext: import('./context').BaseContext): void;
     setPannerNode(pannerNode: import('./context').PannerNode): void;
     get stereoPan(): number | null;
     set stereoPan(value: number);
@@ -16,13 +16,13 @@ declare const BasePlayback_base: (abstract new (...args: any[]) => {
     set threeDOptions(options: Partial<PannerOptions>);
     position: import('./cacophony').Position;
     cleanup(): void;
-    _filters: BiquadFilterNode[];
-    addFilter(filter: BiquadFilterNode): void;
-    removeFilter(filter: BiquadFilterNode): void;
+    _filters: import('./context').BiquadFilterNode[];
+    addFilter(filter: import('./context').BiquadFilterNode): void;
+    removeFilter(filter: import('./context').BiquadFilterNode): void;
     applyFilters(connection: any): any;
-    readonly filters: BiquadFilterNode[];
-    addFilters(filters: BiquadFilterNode[]): void;
-    removeFilters(filters: BiquadFilterNode[]): void;
+    readonly filters: import('./context').BiquadFilterNode[];
+    addFilters(filters: import('./context').BiquadFilterNode[]): void;
+    removeFilters(filters: import('./context').BiquadFilterNode[]): void;
 }) & (abstract new (...args: any[]) => {
     gainNode?: import('./context').GainNode | undefined;
     _fadeTimeout?: NodeJS.Timeout | undefined;
@@ -35,13 +35,13 @@ declare const BasePlayback_base: (abstract new (...args: any[]) => {
     cancelFade(): void;
     fadeIn(duration: number, type?: FadeType | undefined): Promise<void>;
     fadeOut(duration: number, type?: FadeType | undefined): Promise<void>;
-    _filters: BiquadFilterNode[];
-    addFilter(filter: BiquadFilterNode): void;
-    removeFilter(filter: BiquadFilterNode): void;
+    _filters: import('./context').BiquadFilterNode[];
+    addFilter(filter: import('./context').BiquadFilterNode): void;
+    removeFilter(filter: import('./context').BiquadFilterNode): void;
     applyFilters(connection: any): any;
-    readonly filters: BiquadFilterNode[];
-    addFilters(filters: BiquadFilterNode[]): void;
-    removeFilters(filters: BiquadFilterNode[]): void;
+    readonly filters: import('./context').BiquadFilterNode[];
+    addFilters(filters: import('./context').BiquadFilterNode[]): void;
+    removeFilters(filters: import('./context').BiquadFilterNode[]): void;
 }) & typeof FilterManager;
 export declare abstract class BasePlayback extends BasePlayback_base {
     source?: AudioNode;
@@ -61,7 +61,7 @@ export declare abstract class BasePlayback extends BasePlayback_base {
      * Register event listener.
      * @returns Cleanup function
      */
-    on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): void;
+    on<K extends keyof PlaybackEvents>(event: K, listener: (data: PlaybackEvents[K]) => void): () => void;
     /**
      * Remove event listener.
      */

package/dist/cache.d.ts

@@ -1,6 +1,6 @@
-import { AudioContext } from './context';
+import { BaseContext } from './context';
 export interface ICache {
-    getAudioBuffer(context: AudioContext, url: string, signal?: AbortSignal, callbacks?: {
+    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: {
         onLoadingStart?: (event: any) => void;
         onLoadingProgress?: (event: any) => void;
         onLoadingComplete?: (event: any) => void;
@@ -85,7 +85,7 @@ export declare class AudioCache implements ICache {
      * @returns Promise that resolves to decoded AudioBuffer
      * @throws Error if audio cannot be fetched or decoded
      */
-    getAudioBuffer(context: AudioContext, url: string, signal?: AbortSignal, callbacks?: {
+    getAudioBuffer(context: BaseContext, url: string, signal?: AbortSignal, callbacks?: {
         onLoadingStart?: (event: any) => void;
         onLoadingProgress?: (event: any) => void;
         onLoadingComplete?: (event: any) => void;

package/dist/cacophony.d.ts

@@ -1,6 +1,5 @@
-import { AudioContext, IAudioListener, IPannerNode, IPannerOptions } from 'standardized-audio-context';
 import { ICache } from './cache';
-import { AudioBuffer, GainNode } from './context';
+import { AudioBuffer, AudioListener, BaseContext, BiquadFilterNode, GainNode, PannerNode } from './context';
 import { CacophonyEvents } from './events';
 import { Group } from './group';
 import { MicrophoneStream } from './microphone';
@@ -12,7 +11,6 @@ export declare enum SoundType {
     Buffer = "Buffer",
     Oscillator = "oscillator"
 }
-type PannerNode = IPannerNode<AudioContext>;
 /**
  * Represents a 3D position in space.
  * @typedef {Array<number>} Position - An array of three numbers representing the x, y, and z coordinates.
@@ -73,20 +71,76 @@ export interface BaseSound {
     fadeOut?(duration: number, type?: FadeType): Promise<void>;
     stopWithFade?(duration: number, type?: FadeType): Promise<void>;
 }
+/**
+ * Options for creating an offline audio context.
+ */
+export interface OfflineOptions {
+    numberOfChannels: number;
+    length: number;
+    sampleRate: number;
+    context?: BaseContext & {
+        startRendering(): Promise<AudioBuffer>;
+    };
+}
+export interface RuntimeOptions {
+    createAudioWorkletNode?: (context: BaseContext, name: string) => any;
+}
+/**
+ * Resources belonging to a Sound that must be released when the Sound is
+ * garbage collected without an explicit cleanup() call. The record is a plain
+ * data bag with no back-references to the Sound or its Playbacks — a
+ * FinalizationRegistry strongly retains its held value, so holding the Sound
+ * itself would prevent the target from ever becoming collectable.
+ */
+export interface SoundCleanupHoldings {
+    sources: Array<{
+        disconnect(): void;
+    }>;
+    gainNodes: GainNode[];
+    mediaElements: HTMLMediaElement[];
+}
 export declare class Cacophony {
-    context: AudioContext;
+    context: BaseContext;
     globalGainNode: GainNode;
-    listener: IAudioListener;
+    listener: AudioListener;
     private prevVolume;
     private finalizationRegistry;
     private eventEmitter;
     private cache;
-    constructor(context?: AudioContext, cache?: ICache);
+    private createAudioWorkletNode;
+    constructor(context?: BaseContext, cache?: ICache, runtimeOptions?: RuntimeOptions);
+    /** @internal */
+    registerSoundForCleanup(sound: object, holdings: SoundCleanupHoldings, unregisterToken: object): void;
+    /** @internal */
+    unregisterSoundCleanup(unregisterToken: object): void;
+    /**
+     * Creates a Cacophony instance backed by an OfflineAudioContext.
+     * Use this for rendering, bouncing, precomputing processed output,
+     * or non-realtime scenarios.
+     *
+     * @param options - Offline context configuration (channels, length, sampleRate)
+     * @param cache - Optional cache implementation
+     * @returns A Cacophony instance backed by OfflineAudioContext
+     */
+    static createOffline(options: OfflineOptions, cache?: ICache): Cacophony;
+    /**
+     * Returns true if this instance is backed by an offline audio context
+     * (i.e., the context has a startRendering method).
+     */
+    get isOffline(): boolean;
+    /**
+     * Renders the offline audio graph to a buffer.
+     * Only available when the context has a startRendering method.
+     *
+     * @returns Promise that resolves to the rendered AudioBuffer
+     * @throws Error if the context does not support offline rendering
+     */
+    startRendering(): Promise<AudioBuffer>;
     /**
      * Register event listener.
      * @returns Cleanup function
      */
-    on<K extends keyof CacophonyEvents>(event: K, listener: (data: CacophonyEvents[K]) => void): void;
+    on<K extends keyof CacophonyEvents>(event: K, listener: (data: CacophonyEvents[K]) => void): () => void;
     /**
      * Remove event listener.
      */
@@ -94,7 +148,9 @@ export declare class Cacophony {
     emit<K extends keyof CacophonyEvents>(event: K, data: CacophonyEvents[K]): void;
     emitAsync<K extends keyof CacophonyEvents>(event: K, data: CacophonyEvents[K]): Promise<void>;
     loadWorklets(signal?: AbortSignal): Promise<void>;
-    createWorkletNode(name: string, url: string, signal?: AbortSignal): Promise<import('standardized-audio-context').IAudioWorkletNode<import('standardized-audio-context').IAudioContext>>;
+    createWorkletNode(name: string, url: string, signal?: AbortSignal): Promise<any>;
+    private createAbortError;
+    private createMediaSound;
     clearMemoryCache(): void;
     createOscillator(options: OscillatorOptions, panType?: PanType): Synth;
     /**
@@ -127,10 +183,10 @@ export declare class Cacophony {
      * @returns Promise that resolves to a Sound instance for streaming
      */
     createStream(url: string, signal?: AbortSignal): Promise<Sound>;
-    createBiquadFilter: ({ type, frequency, gain, Q, }: BiquadFilterOptions) => BiquadFilterNode;
+    createBiquadFilter: ({ type, frequency, gain, Q }: BiquadFilterOptions) => BiquadFilterNode;
     /**
      * Creates a PannerNode with the specified options.
-     * @param {IPannerOptions} options - An object containing the options to use when creating the PannerNode.
+     * @param {PannerOptions} options - An object containing the options to use when creating the PannerNode.
      * @returns {PannerNode} A new PannerNode instance with the specified options.
      * @example
      * const panner = audio.createPanner({
@@ -142,7 +198,7 @@ export declare class Cacophony {
      * orientationZ: 0,
      * });
      */
-    createPanner({ coneInnerAngle, coneOuterAngle, coneOuterGain, distanceModel, maxDistance, channelCount, channelCountMode, channelInterpretation, panningModel, refDistance, rolloffFactor, positionX, positionY, positionZ, orientationX, orientationY, orientationZ, }: Partial<IPannerOptions>): PannerNode;
+    createPanner({ coneInnerAngle, coneOuterAngle, coneOuterGain, distanceModel, maxDistance, channelCount, channelCountMode, channelInterpretation, panningModel, refDistance, rolloffFactor, positionX, positionY, positionZ, orientationX, orientationY, orientationZ, }: Partial<PannerOptions>): PannerNode;
     /**
      * Suspends the audio context.
      */
@@ -170,4 +226,3 @@ export declare class Cacophony {
     get listenerPosition(): Position;
     set listenerPosition(position: Position);
 }
-export {};

package/dist/container.d.ts

@@ -1,5 +1,6 @@
 import { BasePlayback } from 'basePlayback';
 import { FadeType, Position } from './cacophony';
+import { BiquadFilterNode } from './context';
 import { FilterManager } from './filters';
 type Constructor<T = FilterManager> = abstract new (...args: any[]) => T;
 export interface IPlaybackContainer {

package/dist/context.d.ts

@@ -1,13 +1,130 @@
-import { AudioContext, IAudioBuffer, IAudioBufferSourceNode, IAudioNode, IBiquadFilterNode, IGainNode, IMediaElementAudioSourceNode, IMediaStreamAudioSourceNode, IOscillatorNode, IPannerNode, IStereoPannerNode } from 'standardized-audio-context';
-export type AudioNode = IAudioNode<AudioContext>;
-export type BiquadFilterNode = IBiquadFilterNode<AudioContext>;
-export type MediaElementSourceNode = IMediaElementAudioSourceNode<AudioContext>;
-export type AudioBuffer = IAudioBuffer;
-export type AudioBufferSourceNode = IAudioBufferSourceNode<AudioContext>;
-export type OscillatorNode = IOscillatorNode<AudioContext>;
+/**
+ * Cacophony's own audio type interfaces.
+ *
+ * These are minimal structural interfaces covering only what Cacophony
+ * actually uses. Both the native Web Audio API and standardized-audio-context
+ * satisfy these structurally, so users can pass either.
+ */
+export interface AudioParam {
+    value: number;
+    setValueAtTime(value: number, startTime: number): AudioParam;
+    linearRampToValueAtTime(value: number, endTime: number): AudioParam;
+    exponentialRampToValueAtTime(value: number, endTime: number): AudioParam;
+    cancelScheduledValues(cancelTime: number): AudioParam;
+}
+export interface AudioNode extends EventTarget {
+    connect(destination: AudioNode, output?: number, input?: number): AudioNode;
+    connect(destination: AudioParam, output?: number): void;
+    disconnect(): void;
+    disconnect(output: number): void;
+    disconnect(destination: AudioNode): void;
+    disconnect(destination: AudioParam): void;
+    channelCount: number;
+    channelCountMode: ChannelCountMode;
+    channelInterpretation: ChannelInterpretation;
+    readonly context: {
+        readonly currentTime: number;
+    };
+    readonly numberOfInputs: number;
+    readonly numberOfOutputs: number;
+}
+export interface GainNode extends AudioNode {
+    readonly gain: AudioParam;
+}
+export interface BiquadFilterNode extends AudioNode {
+    type: BiquadFilterType;
+    readonly frequency: AudioParam;
+    readonly detune: AudioParam;
+    readonly Q: AudioParam;
+    readonly gain: AudioParam;
+    getFrequencyResponse(frequencyHz: Float32Array, magResponse: Float32Array, phaseResponse: Float32Array): void;
+}
+export interface PannerNode extends AudioNode {
+    coneInnerAngle: number;
+    coneOuterAngle: number;
+    coneOuterGain: number;
+    distanceModel: DistanceModelType;
+    maxDistance: number;
+    panningModel: PanningModelType;
+    refDistance: number;
+    rolloffFactor: number;
+    readonly positionX: AudioParam;
+    readonly positionY: AudioParam;
+    readonly positionZ: AudioParam;
+    readonly orientationX: AudioParam;
+    readonly orientationY: AudioParam;
+    readonly orientationZ: AudioParam;
+}
+export interface StereoPannerNode extends AudioNode {
+    readonly pan: AudioParam;
+}
+export interface AudioBufferSourceNode extends AudioNode {
+    buffer: AudioBuffer | null;
+    loop: boolean;
+    loopStart: number;
+    loopEnd: number;
+    readonly playbackRate: AudioParam;
+    onended: ((ev: Event) => any) | null;
+    start(when?: number, offset?: number, duration?: number): void;
+    stop(when?: number): void;
+}
+export interface OscillatorNode extends AudioNode {
+    type: OscillatorType;
+    readonly frequency: AudioParam;
+    readonly detune: AudioParam;
+    onended: ((ev: Event) => any) | null;
+    start(when?: number): void;
+    stop(when?: number): void;
+}
+export interface MediaElementSourceNode extends AudioNode {
+    readonly mediaElement: HTMLMediaElement;
+}
+export interface MediaStreamAudioSourceNode extends AudioNode {
+    readonly mediaStream: MediaStream;
+}
+export interface AudioBuffer {
+    readonly duration: number;
+    readonly length: number;
+    readonly sampleRate: number;
+    readonly numberOfChannels: number;
+    getChannelData(channel: number): Float32Array;
+    copyFromChannel(destination: Float32Array, channelNumber: number, bufferOffset?: number): void;
+    copyToChannel(source: Float32Array, channelNumber: number, bufferOffset?: number): void;
+}
+export interface AudioListener {
+    readonly positionX: AudioParam;
+    readonly positionY: AudioParam;
+    readonly positionZ: AudioParam;
+    readonly forwardX: AudioParam;
+    readonly forwardY: AudioParam;
+    readonly forwardZ: AudioParam;
+    readonly upX: AudioParam;
+    readonly upY: AudioParam;
+    readonly upZ: AudioParam;
+}
+export interface AudioWorklet {
+    addModule(moduleURL: string, options?: WorkletOptions): Promise<void>;
+}
+export interface BaseContext {
+    readonly currentTime: number;
+    readonly sampleRate: number;
+    readonly destination: AudioNode;
+    readonly listener: AudioListener;
+    readonly audioWorklet?: AudioWorklet;
+    createGain(): GainNode;
+    createBufferSource(): AudioBufferSourceNode;
+    createBiquadFilter(): BiquadFilterNode;
+    createPanner(): PannerNode;
+    createStereoPanner(): StereoPannerNode;
+    createOscillator(): OscillatorNode;
+    decodeAudioData(audioData: ArrayBuffer): Promise<AudioBuffer>;
+    decodeAudioData(audioData: ArrayBuffer, successCallback: (buffer: AudioBuffer) => void, errorCallback?: (error: DOMException) => void): Promise<AudioBuffer>;
+    createMediaElementSource?(mediaElement: HTMLMediaElement): MediaElementSourceNode;
+    createMediaStreamSource?(stream: MediaStream): MediaStreamAudioSourceNode;
+    suspend?(suspendTime?: number): Promise<void>;
+    resume?(): Promise<void>;
+    close?(): Promise<void>;
+    startRendering?(): Promise<AudioBuffer>;
+    readonly length?: number;
+}
 export type SourceNode = AudioBufferSourceNode | MediaElementSourceNode | OscillatorNode;
-export type MediaStreamAudioSourceNode = IMediaStreamAudioSourceNode<AudioContext>;
-export type GainNode = IGainNode<AudioContext>;
-export type PannerNode = IPannerNode<AudioContext>;
-export type StereoPannerNode = IStereoPannerNode<AudioContext>;
-export { AudioContext };

package/dist/events.d.ts

@@ -1,7 +1,7 @@
 import { BasePlayback } from './basePlayback';
-import { SynthPlayback } from './synthPlayback';
 import { Sound } from './sound';
 import { Synth } from './synth';
+import { SynthPlayback } from './synthPlayback';
 /**
  * Base events for all audio objects.
  */
@@ -12,21 +12,21 @@ export interface FadeStartEvent {
 }
 export interface BaseAudioEvents {
     play: BasePlayback;
-    stop: void;
-    pause: void;
-    resume: void;
-    ended: void;
+    stop: undefined;
+    pause: undefined;
+    resume: undefined;
+    ended: undefined;
     volumeChange: number;
     error: PlaybackErrorEvent;
     fadeStart: FadeStartEvent;
-    fadeEnd: void;
-    fadeCancel: void;
+    fadeEnd: undefined;
+    fadeCancel: undefined;
 }
 /**
  * Sound-specific events.
  */
 export interface SoundEvents extends BaseAudioEvents {
-    loopEnd: void;
+    loopEnd: undefined;
     rateChange: number;
     soundError: SoundErrorEvent;
 }
@@ -39,7 +39,7 @@ export interface PlaybackEvents extends BaseAudioEvents {
 /**
  * Synthesizer-specific events.
  */
-export interface SynthEvents extends Omit<BaseAudioEvents, 'play'> {
+export interface SynthEvents extends Omit<BaseAudioEvents, "play"> {
     play: SynthPlayback;
     frequencyChange: number;
     typeChange: OscillatorType;
@@ -57,10 +57,10 @@ export interface GlobalPlaybackEvent {
  */
 export interface CacophonyEvents {
     volumeChange: number;
-    mute: void;
-    unmute: void;
-    suspend: void;
-    resume: void;
+    mute: undefined;
+    unmute: undefined;
+    suspend: undefined;
+    resume: undefined;
     loadingStart: LoadingStartEvent;
     loadingProgress: LoadingProgressEvent;
     loadingComplete: LoadingCompleteEvent;
@@ -105,7 +105,7 @@ export interface LoadingCompleteEvent {
 export interface LoadingErrorEvent {
     url: string;
     error: Error;
-    errorType: 'network' | 'decode' | 'abort' | 'unknown';
+    errorType: "network" | "decode" | "abort" | "unknown";
     timestamp: number;
 }
 /**
@@ -113,7 +113,7 @@ export interface LoadingErrorEvent {
  */
 export interface PlaybackErrorEvent {
     error: Error;
-    errorType: 'context' | 'source' | 'decode' | 'unknown';
+    errorType: "context" | "source" | "decode" | "unknown";
     timestamp: number;
     recoverable: boolean;
 }
@@ -123,7 +123,7 @@ export interface PlaybackErrorEvent {
 export interface SoundErrorEvent {
     url?: string;
     error: Error;
-    errorType: 'load' | 'playback' | 'context' | 'unknown';
+    errorType: "load" | "playback" | "context" | "unknown";
     timestamp: number;
     recoverable: boolean;
 }
@@ -132,7 +132,7 @@ export interface SoundErrorEvent {
  */
 export interface CacheHitEvent {
     url: string;
-    cacheType: 'memory' | 'browser' | 'conditional';
+    cacheType: "memory" | "browser" | "conditional";
     timestamp: number;
 }
 /**
@@ -140,7 +140,7 @@ export interface CacheHitEvent {
  */
 export interface CacheMissEvent {
     url: string;
-    reason: 'not-found' | 'expired' | 'invalid';
+    reason: "not-found" | "expired" | "invalid";
     timestamp: number;
 }
 /**
@@ -149,7 +149,7 @@ export interface CacheMissEvent {
 export interface CacheErrorEvent {
     url: string;
     error: Error;
-    operation: 'get' | 'set' | 'delete' | 'validate';
+    operation: "get" | "set" | "delete" | "validate";
     timestamp: number;
 }
 /**

package/dist/filters.d.ts

@@ -1,3 +1,4 @@
+import { BiquadFilterNode } from './context';
 export type FilterCloneOverrides = {
     filters?: BiquadFilterNode[];
 };

package/dist/group.d.ts

@@ -1,4 +1,5 @@
 import { BaseSound, FadeType, LoopCount } from './cacophony';
+import { BiquadFilterNode } from './context';
 import { Playback } from './playback';
 import { Sound } from './sound';
 export declare class Group implements BaseSound {
@@ -9,8 +10,7 @@ export declare class Group implements BaseSound {
     constructor(sounds?: Sound[]);
     /**
      * Prepares a random sound from the group for playback.
-     * @returns The playback object representing the prepared sound.
-     * @throws Error if the group is empty and there are no sounds to prepare.
+     * @returns The playback object representing the prepared sound, or undefined if the group is empty.
      */
     preplayRandom(): Playback | undefined;
     /**