The Howl class represents a sound group that can contain multiple audio sources and manage individual sound instances with comprehensive playback controls, event handling, and audio effects.
Create a new Howl instance with audio sources and configuration options.
/**
* Create a new Howl instance
* @param options - Configuration options for the sound group
*/
class Howl {
constructor(options: HowlOptions);
}
interface HowlOptions {
/** Array of source file URLs (required) */
src: string | string[];
/** Initial volume (0.0-1.0, default: 1.0) */
volume?: number;
/** Force HTML5 Audio usage (default: false) */
html5?: boolean;
/** Loop the audio (default: false) */
loop?: boolean;
/** Preload audio (true/false/'metadata', default: true) */
preload?: boolean | 'metadata';
/** Autoplay when loaded (default: false) */
autoplay?: boolean;
/** Start muted (default: false) */
mute?: boolean;
/** Audio sprite definitions */
sprite?: AudioSprite;
/** Playback rate (default: 1.0) */
rate?: number;
/** Size of concurrent sound pool (default: 5) */
pool?: number;
/** Array of audio formats for this sound */
format?: string | string[];
/** Custom XHR settings */
xhr?: XHROptions;
/** Event callbacks */
onend?: () => void;
onfade?: () => void;
onload?: () => void;
onloaderror?: (id: number, error: any) => void;
onplayerror?: (id: number, error: any) => void;
onpause?: () => void;
onplay?: () => void;
onstop?: () => void;
onmute?: () => void;
onvolume?: () => void;
onrate?: () => void;
onseek?: () => void;
onunlock?: () => void;
}Usage Examples:
import { Howl } from "howler";
// Basic sound creation
const sound = new Howl({
src: ['sound.webm', 'sound.mp3'],
volume: 0.5,
loop: true
});
// Sound with sprite and events
const gameAudio = new Howl({
src: ['game-audio.webm', 'game-audio.mp3'],
sprite: {
shot: [0, 500],
explosion: [1000, 2000],
pickup: [4000, 1000]
},
onload: function() {
console.log('Game audio loaded');
},
onplayerror: function(id, error) {
console.error('Playback error:', error);
}
});
// Custom XHR configuration
const protectedAudio = new Howl({
src: ['/api/audio/protected.mp3'],
xhr: {
method: 'GET',
headers: {
'Authorization': 'Bearer token123'
},
withCredentials: true
}
});Manually load audio files when preload is disabled or for explicit loading control.
/**
* Load the audio file
* @returns Howl instance for chaining
*/
load(): Howl;Control audio playback with play, pause, and stop functionality.
/**
* Begin playback of the sound or specific sprite
* @param sprite - Name of sprite to play (optional)
* @returns Unique sound ID for this playback instance
*/
play(sprite?: string): number;
/**
* Pause playback of a sound
* @param id - Sound ID to pause (optional, pauses all if not provided)
* @returns Howl instance for chaining
*/
pause(id?: number): Howl;
/**
* Stop playback and reset position
* @param id - Sound ID to stop (optional, stops all if not provided)
* @returns Howl instance for chaining
*/
stop(id?: number): Howl;Usage Examples:
// Basic playback
const id = sound.play();
// Play specific sprite
const shotId = gameAudio.play('shot');
const explosionId = gameAudio.play('explosion');
// Control specific sounds
sound.pause(id);
sound.stop(shotId);
// Control all sounds in the group
sound.pause(); // Pause all
sound.stop(); // Stop allGet or set volume for individual sounds or the entire sound group.
/**
* Get/set volume for sound(s)
* @param vol - Volume from 0.0 to 1.0 (optional)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Current volume if getting, Howl instance if setting
*/
volume(vol?: number, id?: number): Howl | number;Usage Examples:
// Set volume for all sounds in group
sound.volume(0.5);
// Set volume for specific sound
sound.volume(0.8, id);
// Get current volume
const currentVol = sound.volume(); // For entire group
const soundVol = sound.volume(undefined, id); // For specific soundMute or unmute individual sounds or the entire sound group.
/**
* Mute/unmute sound(s)
* @param muted - True to mute, false to unmute (optional for getting state)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Mute state if getting, Howl instance if setting
*/
mute(muted?: boolean, id?: number): Howl | boolean;Apply fade effects and control playback rate.
/**
* Fade volume from one level to another over time
* @param from - Starting volume (0.0-1.0)
* @param to - Ending volume (0.0-1.0)
* @param len - Duration in milliseconds
* @param id - Sound ID (optional, affects all if not provided)
* @returns Howl instance for chaining
*/
fade(from: number, to: number, len: number, id?: number): Howl;
/**
* Get/set playback rate
* @param rate - Playback rate (0.5 = half speed, 2.0 = double speed)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Current rate if getting, Howl instance if setting
*/
rate(rate?: number, id?: number): Howl | number;Usage Examples:
// Fade in over 2 seconds
sound.fade(0, 1, 2000);
// Fade out specific sound
sound.fade(1, 0, 1000, id);
// Change playback speed
sound.rate(1.5); // 1.5x speed
sound.rate(0.5, id); // Half speed for specific soundControl playback position within the audio.
/**
* Get/set seek position in seconds
* @param seek - Position in seconds (optional)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Current position if getting, Howl instance if setting
*/
seek(seek?: number, id?: number): Howl | number;Control whether audio should loop when it reaches the end.
/**
* Get/set loop state
* @param loop - True to loop, false to play once (optional)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Loop state if getting, Howl instance if setting
*/
loop(loop?: boolean, id?: number): Howl | boolean;Query playback status and audio properties.
/**
* Check if sound is currently playing
* @param id - Sound ID (optional, checks any if not provided)
* @returns True if playing, false otherwise
*/
playing(id?: number): boolean;
/**
* Get duration of the audio
* @param id - Sound ID (optional)
* @returns Duration in seconds
*/
duration(id?: number): number;
/**
* Get current load state
* @returns Current state ('unloaded', 'loading', 'loaded')
*/
state(): LoadState;Clean up audio resources and unload from memory.
/**
* Unload and destroy this Howl object
* @returns Howl instance for chaining
*/
unload(): Howl;Register event listeners for audio lifecycle events.
/**
* Listen for events on this sound
* @param event - Event name to listen for
* @param fn - Callback function
* @param id - Sound ID (optional, listens to all if not provided)
* @returns Howl instance for chaining
*/
on(event: HowlEvent, fn: Function, id?: number): Howl;
/**
* Remove event listeners
* @param event - Event name (optional, removes all if not provided)
* @param fn - Specific callback (optional, removes all for event if not provided)
* @param id - Sound ID (optional, affects all if not provided)
* @returns Howl instance for chaining
*/
off(event?: HowlEvent, fn?: Function, id?: number): Howl;
/**
* Listen for event once
* @param event - Event name to listen for
* @param fn - Callback function
* @param id - Sound ID (optional)
* @returns Howl instance for chaining
*/
once(event: HowlEvent, fn: Function, id?: number): Howl;
type HowlEvent = 'load' | 'loaderror' | 'play' | 'end' | 'pause' | 'stop' | 'mute' | 'volume' | 'rate' | 'seek' | 'fade' | 'playerror' | 'unlock';Usage Examples:
// Listen for load completion
sound.on('load', function() {
console.log('Sound loaded successfully');
});
// Listen for playback end
sound.on('end', function() {
console.log('Sound finished playing');
});
// Listen for errors
sound.on('loaderror', function(id, error) {
console.error('Failed to load audio:', error);
});
sound.on('playerror', function(id, error) {
console.error('Playback error:', error);
});
// Remove specific listener
const callback = () => console.log('played');
sound.on('play', callback);
sound.off('play', callback);
// Remove all listeners for an event
sound.off('end');
// Listen once
sound.once('load', function() {
sound.play(); // Auto-play when loaded
});Audio sprites allow you to define segments within a single audio file for efficient resource usage.
interface AudioSprite {
[key: string]: [number, number] | [number, number, boolean];
// Format: [start_time_ms, duration_ms] or [start_time_ms, duration_ms, loop]
}Usage Examples:
const sounds = new Howl({
src: ['sprite.webm', 'sprite.mp3'],
sprite: {
// [start, duration] in milliseconds
blaster: [0, 3000],
laser: [4000, 1000],
winner: [6000, 5000],
// [start, duration, loop]
engine: [12000, 2000, true]
}
});
// Play specific sprites
sounds.play('blaster');
sounds.play('laser');
sounds.play('winner');
// Loop will override sprite loop setting
const loopId = sounds.play('engine');Customize how audio files are loaded with custom HTTP headers and settings.
interface XHROptions {
/** HTTP method (default: 'GET') */
method?: string;
/** Custom HTTP headers */
headers?: { [key: string]: string };
/** Include credentials in cross-origin requests */
withCredentials?: boolean;
}Control concurrent playback instances for performance optimization.
// Configure pool size for simultaneous playback
const sound = new Howl({
src: ['effect.mp3'],
pool: 10 // Allow up to 10 simultaneous instances
});
// Useful for rapid-fire sound effects
for (let i = 0; i < 5; i++) {
sound.play(); // Each gets its own pool instance
}