Sound Loading and Playback

/**
 * 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;
}

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
  }
});

/**
 * Load the audio file
 * @returns Howl instance for chaining
 */
load(): Howl;

/**
 * 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;

// 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 all

/**
 * 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;

// 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 sound

/**
 * 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;

/**
 * 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;

// 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 sound

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * Unload and destroy this Howl object
 * @returns Howl instance for chaining
 */
unload(): Howl;

/**
 * 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';

// 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
});

interface AudioSprite {
  [key: string]: [number, number] | [number, number, boolean];
  // Format: [start_time_ms, duration_ms] or [start_time_ms, duration_ms, loop]
}

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');

interface XHROptions {
  /** HTTP method (default: 'GET') */
  method?: string;
  /** Custom HTTP headers */
  headers?: { [key: string]: string };
  /** Include credentials in cross-origin requests */
  withCredentials?: boolean;
}

// 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
}