lite-audio-manager

A robust audio manager built on Howler.js with iOS/mobile unlock, category-based stopping, pitch variation, fade-safe teardown, and mute persistence.

Unlike using Howler directly, this manager handles the platform edge cases that break audio in real apps — suspended AudioContext on mobile, background tab suspension in Chrome, ghost plays when the context isn't running, and the entire fade/stop race condition surface.

Features

• iOS/mobile audio unlock — silent buffer pulse + ctx.resume() on first user interaction
• Background tab resume — re-activates AudioContext on visibilitychange
• Category-based stopping — stop all sounds in a category (e.g. 'sfx', 'music') with one call
• Fade-safe stopping — fade guard prevents double-stop race conditions
• Queued sound handling — force-kills sounds that are queued but not yet playing
• Multi-instance tracking — concurrent plays of the same sound are all tracked and stoppable
• Pitch variation — random or explicit pitch for natural-sounding repeated SFX
• Mute persistence — saves to localStorage, restores on next session
• EventTarget events — emits 'mutechange' for framework-agnostic UI binding
• Clean teardown — AbortController-based listener cleanup, destroy() is idempotent

Installation

npm install lite-audio-manager

Quick Start

import { audioManager } from 'lite-audio-manager';

audioManager.init({
    bgm:   { src: ['/audio/music.mp3'], loop: true, volume: 0.5, category: 'music', html5: true },
    hit:   { src: ['/audio/hit.wav'], category: 'sfx' },
    coin:  { src: ['/audio/coin.wav'], category: 'sfx', pitchVar: 0.15 },
    win:   { src: ['/audio/fanfare.mp3'], category: 'outcome' },
    lose:  { src: ['/audio/sad.mp3'], category: 'outcome' },
});

// Play a sound
audioManager.play('hit', { volume: 0.8 });

// Play with random pitch variation (±10%)
audioManager.play('coin', { pitchVar: 0.1 });

// Start background music
audioManager.play('bgm', { loop: true, volume: 0.3 });

// Stop all SFX with a 200ms fade
audioManager.stopCategory('sfx', { fade: 200 });

// Play a win sound, stopping any current outcome audio first
audioManager.playExclusive('win');

API

audioManager.init(config)

Initialize with a sound configuration map. Call once at app startup.

audioManager.init({
    soundName: {
        src: ['/path/to/file.mp3'],  // Required: Howl source(s)
        category: 'sfx',             // Optional: for stopCategory()
        loop: false,                 // Optional: Howl option
        volume: 1,                   // Optional: Howl option
        html5: false,                // Optional: true for long tracks
        // ...any other Howl options
    }
});

Playback

Method	Description
.play(name, options?)	Play a sound. Returns Howl id or null if skipped.
.playExclusive(name, options?)	Stop 'outcome' category, then play.
.playUnique(name, threshold?)	Play only if not played within threshold ms.

Play options:

Option	Type	Default	Description
volume	number	1	Volume (0–1)
loop	boolean	false	Loop the sound
pitchVar	number	0	Random pitch variation (e.g. 0.1 = ±10%)
pitch	number | null	null	Explicit pitch override (ignores pitchVar)

Stopping

Method	Description
.stop(name, options?)	Stop a sound with optional fade.
.stopCategory(category, options?)	Stop all sounds in a category.
.stopCategories(categories, options?)	Stop multiple categories at once.

Stop options:

Option	Type	Default	Description
fade	number	120	Fade-out duration in ms (0 = instant)

Global State

// Toggle mute
audioManager.setMuted(!audioManager.isMuted);

// Listen for mute changes (framework-agnostic)
audioManager.addEventListener('mutechange', (e) => {
    console.log('Muted:', e.detail.isMuted);
});

Property	Type	Description
.isMuted	boolean	Current mute state
.isUnlocked	boolean	Whether AudioContext has been unlocked

Lifecycle

Method	Description
.destroy()	Unload all sounds, remove listeners. Idempotent.

Edge Cases Handled

Scenario	Behavior
iOS/Android first interaction	Silent buffer + ctx.resume() unlocks AudioContext
Chrome background tab	visibilitychange listener resumes suspended context
Play while context suspended	Silently returns null (no queued ghost plays)
stop() during fade	#fadingIds guard prevents double-stop crash
stop() on queued sound	Force-kills instantly (no fade on silence)
Two play('hit') calls	Both ids tracked, both stoppable independently
Looped sound cleanup	No orphaned 'end' listener (only added for non-looped)
Safari private mode	localStorage.setItem wrapped in try/catch
SSR / Service Worker	localStorage read wrapped in try/catch
Double destroy()	Idempotent — second call is a no-op

TypeScript

Full type definitions included with typed event listener overrides:

import { audioManager, type SoundConfig, type PlayOptions } from 'lite-audio-manager';

const config: Record<string, SoundConfig> = {
    hit: { src: ['/hit.wav'], category: 'sfx' },
};

audioManager.init(config);
audioManager.play('hit', { volume: 0.5, pitchVar: 0.1 });

audioManager.addEventListener('mutechange', (e) => {
    console.log(e.detail.isMuted); // fully typed
});

License

MIT