Class AudioManager

AudioManager is a framework-agnostic audio management system built on the Web Audio API. It provides centralized control for organizing, playing, and managing audio assets in games and interactive applications.

Example

const audio = new AudioManager();

// Initialize on user interaction (required by browsers)
button.onclick = async () => {
  await audio.resumeAudioContext();
};

// Add and play sounds
audio.addAudioTrack('explosion', 'sfx', '/sounds/explosion.wav');
await audio.preload(['explosion']);
audio.playAudioTrack('explosion');

// Play background music with fade
audio.addAudioTrack('music', 'music', '/sounds/track.mp3');
await audio.fadeIn('music', 2000);

Constructors

constructor

new AudioManager(): AudioManager
Creates a new AudioManager instance. The AudioContext is created lazily on first use or via initAudio.

Returns AudioManager
- Defined in audio-manager.ts:139

Properties

`Readonly`onTrackStart$

onTrackStart$: Observable<TrackStartEvent> = ...

Observable that emits when a track starts playing.

Example

audio.onTrackStart$.subscribe(event => {
  console.log(`Playing: ${event.key} on channel ${event.channelId}`);
});

`Readonly`onTrackEnd$

onTrackEnd$: Observable<TrackEndEvent> = ...

Observable that emits when a track finishes playing.

Example

audio.onTrackEnd$.subscribe(event => {
  console.log(`Finished: ${event.key}`);
});

`Readonly`onLoadComplete$

onLoadComplete$: Observable<LoadCompleteEvent> = ...

Observable that emits when a track's metadata is loaded and ready to play.

Example

audio.onLoadComplete$.subscribe(event => {
  console.log(`Loaded: ${event.key}, duration: ${event.duration}s`);
});

`Readonly`onError$

onError$: Observable<AudioErrorEvent> = ...

Observable that emits when an audio error occurs.

Example

audio.onError$.subscribe(event => {
  console.error(`Audio error: ${event.message}`, event.error);
});

Accessors

loggingEnabled

get loggingEnabled(): boolean
Gets or sets whether debug logging is enabled. When enabled, the AudioManager logs internal operations to the console.

Returns boolean
Default
```
false
```
- Defined in audio-manager.ts:127
set loggingEnabled(value: boolean): void
Parameters
- value: boolean
Returns void
- Defined in audio-manager.ts:131

Methods

initAudio

initAudio(): Promise<void>
Initializes the AudioContext and resumes it if suspended. Call this method on user interaction to ensure audio playback works in browsers.

Returns Promise<void>
A promise that resolves when the AudioContext is ready.
Example
```
document.getElementById('startButton').onclick = async () => {
  await audio.initAudio();
  console.log('Audio ready!');
};
```
- Defined in audio-manager.ts:182

resumeAudioContext

resumeAudioContext(): Promise<void>
Resumes a suspended AudioContext. Browsers require user interaction before allowing audio playback. Call this method in response to a user gesture (click, touch, keypress).

Returns Promise<void>
A promise that resolves when the AudioContext is resumed.
Example
```
playButton.onclick = async () => {
  await audio.resumeAudioContext();
  audio.playAudioTrack('click');
};
```
- Defined in audio-manager.ts:204

suspendAudioContext

suspendAudioContext(): Promise<void>
Suspends the AudioContext to save resources when audio is not needed. Useful for pausing all audio when the application loses focus or enters background.

Returns Promise<void>
A promise that resolves when the AudioContext is suspended.
Example
```
document.addEventListener('visibilitychange', async () => {
  if (document.hidden) {
    await audio.suspendAudioContext();
  } else {
    await audio.resumeAudioContext();
  }
});
```
- Defined in audio-manager.ts:230

isAudioReady

isAudioReady(): boolean
Checks if the AudioContext is initialized and running.

Returns boolean
true if the AudioContext is ready for playback, false otherwise.
Example
```
if (!audio.isAudioReady()) {
  showMessage('Click to enable audio');
}
```
- Defined in audio-manager.ts:248

setMasterVolume

setMasterVolume(volume: number): void
Sets the master volume that affects all audio output. The value is clamped to the range [0, 1].
Parameters
- volume: number
  The master volume level (0 = silent, 1 = full volume).
Returns void
Example
```
// Set master volume to 50%
audio.setMasterVolume(0.5);

// Mute all audio
audio.setMasterVolume(0);
```
- Defined in audio-manager.ts:268

getMasterVolume

getMasterVolume(): number
Gets the current master volume level.

Returns number
The master volume level (0-1).
Example
```
const volume = audio.getMasterVolume();
volumeSlider.value = volume * 100;
```
- Defined in audio-manager.ts:286

setAudioEnabled

setAudioEnabled(group: string, enabled: boolean): void
Enables or disables audio playback for a specific group. When disabled, all sounds in the group are muted and continuous playback is paused.
Parameters
- group: string
  The audio group name (e.g., 'sfx', 'music', 'ambient').
- enabled: boolean
  Whether the group should be enabled.
Returns void
Example
```
// Mute sound effects
audio.setAudioEnabled('sfx', false);

// Re-enable sound effects
audio.setAudioEnabled('sfx', true);
```
- Defined in audio-manager.ts:307

setAudioVolume

setAudioVolume(group: string, volume: number): void
Sets the volume for a specific audio group. The value is clamped to the range [0, 1].
Parameters
- group: string
  The audio group name (e.g., 'sfx', 'music', 'ambient').
- volume: number
  The volume level (0 = silent, 1 = full volume).
Returns void
Example
```
// Set music volume to 70%
audio.setAudioVolume('music', 0.7);

// Set SFX volume from a slider
audio.setAudioVolume('sfx', sfxSlider.value / 100);
```
- Defined in audio-manager.ts:363

setGroupPoolSize

setGroupPoolSize(group: string, maxConcurrent: number): void
Sets the maximum number of concurrent sounds for a group. When the limit is reached, new sounds in the group will not play.
Parameters
- group: string
  The audio group name.
- maxConcurrent: number
  Maximum number of simultaneous sounds (minimum: 1).
Returns void
Example
```
// Allow up to 4 concurrent footstep sounds
audio.setGroupPoolSize('sfx', 4);

// Allow more sounds for ambient group
audio.setGroupPoolSize('ambient', 16);
```
- Defined in audio-manager.ts:393

getPoolStats

getPoolStats(group?: string): PoolStats | PoolStats[]
Gets statistics about the audio pool for one or all groups.
Parameters
- Optionalgroup: string
  Optional group name. If omitted, returns stats for all groups.
Returns PoolStats | PoolStats[]
Pool statistics for the specified group, or an array of stats for all groups.
Example
```
// Get stats for a specific group
const sfxStats = audio.getPoolStats('sfx');
console.log(`SFX: ${sfxStats.inUse}/${sfxStats.maxConcurrent} in use`);

// Get stats for all groups
const allStats = audio.getPoolStats();
allStats.forEach(stats => console.log(stats.group, stats.inUse));
```
- Defined in audio-manager.ts:414

isLoaded

isLoaded(key: string): boolean
Checks if all tracks for a key are fully loaded and ready to play.
Parameters
- key: string
  The audio key to check.
Returns boolean
true if all tracks for the key are loaded, false otherwise.
Example
```
if (audio.isLoaded('explosion')) {
  audio.playAudioTrack('explosion');
} else {
  await audio.preload(['explosion']);
}
```
- Defined in audio-manager.ts:463

getLoadStatus

getLoadStatus(key: string): LoadStatus
Gets detailed loading status for a specific audio key.
Parameters
- key: string
  The audio key to check.
Returns LoadStatus
An object with total tracks, loaded count, and ready status.
Example
```
const status = audio.getLoadStatus('footsteps');
console.log(`Loaded ${status.loaded}/${status.total} tracks`);
if (status.ready) {
  console.log('All footstep sounds ready!');
}
```
- Defined in audio-manager.ts:485

preload

preload(keys: string[]): Promise<void>
Preloads audio tracks into memory for low-latency playback. This is especially important for one-shot sounds (SFX) that need instant playback.
Parameters
- keys: string[]
  Array of audio keys to preload.
Returns Promise<void>
A promise that resolves when all tracks are loaded.
Throws
If any track fails to load.
Example
```
// Preload during a loading screen
async function loadGame() {
  showLoadingScreen();
  await audio.preload(['explosion', 'gunshot', 'footstep', 'jump']);
  hideLoadingScreen();
}

// Track loading progress
audio.preload(['music1', 'music2']).then(() => {
  console.log('All music loaded');
});
```
- Defined in audio-manager.ts:517

addAudioTrack

addAudioTrack(key: string, group: string, path: string): void

Registers an audio track with the manager. Multiple tracks can be registered under the same key for random variation.

Parameters

key: string
Unique identifier for the sound (e.g., 'explosion', 'footstep').
group: string
Audio group for volume/mute control (e.g., 'sfx', 'music').
path: string
URL or path to the audio file.

Returns void

Example

// Add a single sound effect
audio.addAudioTrack('explosion', 'sfx', '/sounds/explosion.wav');

// Add multiple variations for the same key (random selection on play)
audio.addAudioTrack('footstep', 'sfx', '/sounds/footstep1.wav');
audio.addAudioTrack('footstep', 'sfx', '/sounds/footstep2.wav');
audio.addAudioTrack('footstep', 'sfx', '/sounds/footstep3.wav');

// Add background music
audio.addAudioTrack('battle', 'music', '/music/battle-theme.mp3');

playAudioTrack

playAudioTrack(key: string): void
Plays a one-shot sound effect. If multiple tracks are registered under the key, one is selected randomly. The sound plays to completion and cannot be stopped or paused.
Parameters
- key: string
  The audio key to play.
Returns void
Example
```
// Play a sound effect
audio.playAudioTrack('explosion');

// Play footstep (random variation if multiple tracks registered)
audio.playAudioTrack('footstep');

// Rapid fire - respects pool limits
for (let i = 0; i < 10; i++) {
  audio.playAudioTrack('gunshot');
}
```
- Defined in audio-manager.ts:637

playContinuous

playContinuous(key: string, channelId?: string): void
Starts continuous playback on a channel. When a track ends, the next track is automatically played (looping through all tracks). Ideal for background music, ambient sounds, or any audio that should loop.
Parameters
- key: string
  The audio key to play.
- channelId: string = DEFAULT_CHANNEL
  Optional channel identifier (default: 'default'). Use different channels for simultaneous playback (e.g., music + ambient).
Returns void
Example
```
// Play background music on default channel
audio.playContinuous('battle-music');

// Play ambient sounds on a separate channel
audio.playContinuous('forest-ambient', 'ambient');

// Both play simultaneously and can be controlled independently
audio.pauseContinuous('ambient');  // Pause only ambient
audio.stopContinuous();            // Stop only default channel
```
- Defined in audio-manager.ts:796

stopContinuous

stopContinuous(channelId?: string): void
Stops continuous playback on a channel and resets to the beginning.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to stop (default: 'default').
Returns void
Example
```
// Stop the default channel
audio.stopContinuous();

// Stop a specific channel
audio.stopContinuous('ambient');
```
- Defined in audio-manager.ts:950

pauseContinuous

pauseContinuous(channelId?: string): void
Pauses continuous playback on a channel. The playback position is preserved and can be resumed with resumeContinuous.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to pause (default: 'default').
Returns void
Example
```
// Pause when game is paused
audio.pauseContinuous();

// Pause ambient channel only
audio.pauseContinuous('ambient');
```
- Defined in audio-manager.ts:991

resumeContinuous

resumeContinuous(channelId?: string): void
Resumes paused continuous playback on a channel.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to resume (default: 'default').
Returns void
Example
```
// Resume when game is unpaused
audio.resumeContinuous();

// Resume ambient channel only
audio.resumeContinuous('ambient');
```
- Defined in audio-manager.ts:1026

fadeIn

fadeIn(key: string, duration: number, channelId?: string): Promise<void>
Starts playback with a gradual volume fade-in effect. Uses the Web Audio API's native gain automation for smooth transitions.
Parameters
- key: string
  The audio key to play.
- duration: number
  Fade duration in milliseconds.
- channelId: string = DEFAULT_CHANNEL
  The channel to use (default: 'default').
Returns Promise<void>
A promise that resolves when the fade-in completes.
Example
```
// Fade in background music over 2 seconds
await audio.fadeIn('battle-music', 2000);

// Fade in on a specific channel
await audio.fadeIn('ambient', 3000, 'ambient');
```
- Defined in audio-manager.ts:1073

fadeOut

fadeOut(duration: number, channelId?: string): Promise<void>
Gradually fades out and stops the current playback on a channel. Uses the Web Audio API's native gain automation for smooth transitions.
Parameters
- duration: number
  Fade duration in milliseconds.
- channelId: string = DEFAULT_CHANNEL
  The channel to fade out (default: 'default').
Returns Promise<void>
A promise that resolves when the fade-out completes and playback stops.
Example
```
// Fade out current music over 1.5 seconds
await audio.fadeOut(1500);

// Fade out ambient sounds
await audio.fadeOut(2000, 'ambient');
```
- Defined in audio-manager.ts:1259

crossFade

crossFade(key: string, duration: number, channelId?: string): Promise<void>
Cross-fades from the current track to a new track on the same channel. The old track fades out while the new track fades in simultaneously.
Parameters
- key: string
  The audio key of the new track to play.
- duration: number
  Cross-fade duration in milliseconds.
- channelId: string = DEFAULT_CHANNEL
  The channel to cross-fade on (default: 'default').
Returns Promise<void>
A promise that resolves when the cross-fade completes.
Example
```
// Cross-fade to a new music track
await audio.crossFade('boss-music', 2000);

// Seamless transition between ambient tracks
await audio.crossFade('cave-ambient', 3000, 'ambient');
```
- Defined in audio-manager.ts:1332

getActiveChannels

getActiveChannels(): { [channelId: string]: ChannelInfo }
Gets information about all active continuous playback channels.

Returns { [channelId: string]: ChannelInfo }
An object mapping channel IDs to their playback info.
Example
```
const channels = audio.getActiveChannels();
Object.entries(channels).forEach(([id, info]) => {
  console.log(`Channel ${id}: ${info.key} (playing: ${info.isPlaying})`);
});
```
- Defined in audio-manager.ts:1561

getChannelInfo

getChannelInfo(channelId?: string): ChannelInfo | null
Gets information about a specific playback channel.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to query (default: 'default').
Returns ChannelInfo | null
Channel info if active, or null if no playback on channel.
Example
```
const info = audio.getChannelInfo('music');
if (info?.isPlaying) {
  console.log(`Now playing: ${info.key}`);
}
```
- Defined in audio-manager.ts:1587

stopAllContinuous

stopAllContinuous(): void
Stops all continuous playback on all channels.

Returns void
Example
```
// Stop all music/ambient when leaving a scene
audio.stopAllContinuous();
```
- Defined in audio-manager.ts:1608

pauseAllContinuous

pauseAllContinuous(): void
Pauses all continuous playback on all channels.

Returns void
Example
```
// Pause everything when game is paused
audio.pauseAllContinuous();
```
- Defined in audio-manager.ts:1623

resumeAllContinuous

resumeAllContinuous(): void
Resumes all paused continuous playback on all channels.

Returns void
Example
```
// Resume everything when game is unpaused
audio.resumeAllContinuous();
```
- Defined in audio-manager.ts:1640

setPlaybackRate

setPlaybackRate(rate: number, channelId?: string): void
Sets the playback speed/rate for a channel. The value is clamped to the range [0.25, 4.0].
Parameters
- rate: number
  Playback rate (1.0 = normal, 0.5 = half speed, 2.0 = double speed).
- channelId: string = DEFAULT_CHANNEL
  The channel to modify (default: 'default').
Returns void
Example
```
// Slow motion music effect
audio.setPlaybackRate(0.5);

// Fast forward
audio.setPlaybackRate(2.0);

// Reset to normal
audio.setPlaybackRate(1.0);
```
- Defined in audio-manager.ts:1668

getPlaybackRate

getPlaybackRate(channelId?: string): number | null
Gets the current playback rate for a channel.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to query (default: 'default').
Returns number | null
The playback rate, or null if no playback on channel.
- Defined in audio-manager.ts:1695

seek

seek(time: number, channelId?: string): void
Seeks to a specific time position in the current track.
Parameters
- time: number
  Time position in seconds.
- channelId: string = DEFAULT_CHANNEL
  The channel to seek (default: 'default').
Returns void
Example
```
// Skip to 1 minute into the track
audio.seek(60);

// Restart from beginning
audio.seek(0);
```
- Defined in audio-manager.ts:1717

getCurrentTime

getCurrentTime(channelId?: string): number | null
Gets the current playback time in seconds.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to query (default: 'default').
Returns number | null
Current time in seconds, or null if no playback on channel.
Example
```
const time = audio.getCurrentTime();
if (time !== null) {
  progressBar.value = time;
}
```
- Defined in audio-manager.ts:1757

getDuration

getDuration(channelId?: string): number | null
Gets the total duration of the current track in seconds.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to query (default: 'default').
Returns number | null
Duration in seconds, or null if unavailable.
Example
```
const duration = audio.getDuration();
if (duration !== null) {
  console.log(`Track length: ${duration}s`);
}
```
- Defined in audio-manager.ts:1778

getPlaybackInfo

getPlaybackInfo(channelId?: string): PlaybackInfo | null
Gets comprehensive playback information for a channel.
Parameters
- channelId: string = DEFAULT_CHANNEL
  The channel to query (default: 'default').
Returns PlaybackInfo | null
Playback info including time, duration, rate, and volume.
Example
```
const info = audio.getPlaybackInfo();
if (info) {
  console.log(`Playing: ${info.key}`);
  console.log(`Progress: ${info.currentTime}/${info.duration}s`);
  console.log(`Rate: ${info.playbackRate}x, Volume: ${info.volume}`);
}
```
- Defined in audio-manager.ts:1802

stopAudioGroup

stopAudioGroup(group: string): void
Stops all active one-shot sounds in a specific group. This immediately stops and cleans up all playing sounds that belong to the specified group.
Parameters
- group: string
  The group key to stop all sounds for (e.g., 'sfx', 'ui', 'ambient')
Returns void
Example
```
// Stop all UI sounds when closing a menu
audio.stopAudioGroup('ui');

// Stop all SFX when pausing the game
audio.stopAudioGroup('sfx');
```
- Defined in audio-manager.ts:2003

destroy

destroy(): void
Destroys the AudioManager and releases all resources. Stops all playback, disconnects all audio nodes, and closes the AudioContext. After calling destroy(), the AudioManager instance should not be used.

Returns void
Example
```
// Clean up when leaving a game or unmounting a component
audio.destroy();

// React useEffect cleanup
useEffect(() => {
  const audio = new AudioManager();
  return () => audio.destroy();
}, []);
```
- Defined in audio-manager.ts:2038

Class AudioManager

Example

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Returns AudioManager

Properties

ReadonlyonTrackStart$

Example

ReadonlyonTrackEnd$

Example

ReadonlyonLoadComplete$

Example

ReadonlyonError$

Example

Accessors

loggingEnabled

Returns boolean

Default

Parameters

Returns void

Methods

initAudio

Returns Promise<void>

Example

resumeAudioContext

Returns Promise<void>

Example

suspendAudioContext

Returns Promise<void>

Example

isAudioReady

Returns boolean

Example

setMasterVolume

Parameters

Returns void

Example

getMasterVolume

Returns number

Example

setAudioEnabled

Parameters

Returns void

Example

setAudioVolume

Parameters

Returns void

Example

setGroupPoolSize

Parameters

Returns void

Example

getPoolStats

Parameters

Returns PoolStats | PoolStats[]

Example

isLoaded

Parameters

Returns boolean

Example

getLoadStatus

Parameters

Returns LoadStatus

Example

preload

Parameters

Returns Promise<void>

Throws

Example

addAudioTrack

Parameters

Returns void

Example

playAudioTrack

Parameters

`Readonly`onTrackStart$

`Readonly`onTrackEnd$

`Readonly`onLoadComplete$

`Readonly`onError$