@utsp/audio 0.4.0-nightly.20251203172602.bbfc50f

package/dist/AudioManager.js

@@ -0,0 +1,1058 @@
+/**
+ * AudioManager - Web Audio API management for UTSP applications
+ *
+ * Provides a centralized audio context and utilities for playing sounds.
+ * Handles browser autoplay restrictions by requiring user interaction to initialize.
+ *
+ * Implements IAudioProcessor interface from @utsp/types for unified audio handling
+ * across standalone and connected modes.
+ *
+ * @example
+ * ```typescript
+ * // Create audio manager
+ * const audio = new AudioManager({ debug: true });
+ *
+ * // Initialize on user interaction (required by browsers)
+ * button.addEventListener('click', () => {
+ *   audio.initialize();
+ *   audio.playStartSound(); // Confirmation sound
+ * });
+ *
+ * // Play loaded sounds (from File or FileExternal)
+ * audio.play('coin');
+ * audio.play('explosion', { volume: 0.5, pitch: 1.2 });
+ *
+ * // Play custom tones
+ * audio.playTone(440, 0.5); // A4 note for 0.5 seconds
+ * ```
+ */
+import { SoundBank } from './SoundBank';
+/**
+ * AudioManager - Main audio management class
+ *
+ * Implements IAudioProcessor for unified audio handling in standalone and connected modes.
+ */
+export class AudioManager {
+    audioContext = null;
+    masterGainNode = null;
+    soundBank = null;
+    options;
+    initialized = false;
+    // Instance tracking system
+    nextInstanceId = 1;
+    instances = new Map();
+    instancesBySound = new Map();
+    // Legacy: for backward compatibility
+    activeSounds = new Set();
+    // Spatial sounds that need real-time updates when listener moves
+    spatialSounds = new Map();
+    // Spatial audio configuration
+    spatialConfig = {
+        listenerX: 32768, // Center of 16-bit range
+        listenerY: 32768,
+        maxDistance: 16384, // 1/4 of 16-bit range
+        referenceDistance: 1024,
+        rolloffFactor: 1.0,
+        panSpread: 0.8,
+    };
+    constructor(options = {}) {
+        this.options = {
+            debug: options.debug ?? false,
+            masterVolume: options.masterVolume ?? 1.0,
+        };
+        this.log('AudioManager created');
+    }
+    /**
+     * Initialize the Web AudioContext
+     * Must be called from a user interaction event (click, touch, keypress)
+     *
+     * @returns true if initialization was successful, false otherwise
+     */
+    initialize() {
+        if (this.initialized && this.audioContext) {
+            this.log('AudioContext already initialized');
+            return true;
+        }
+        try {
+            // Create AudioContext (with fallback for older browsers)
+            const AudioContextClass = window.AudioContext || window.webkitAudioContext;
+            if (!AudioContextClass) {
+                console.warn('[AudioManager] Web Audio API not supported');
+                return false;
+            }
+            this.audioContext = new AudioContextClass();
+            this.log(`AudioContext initialized (state: ${this.audioContext.state}, sampleRate: ${this.audioContext.sampleRate}Hz)`);
+            // Create master gain node for volume control
+            this.masterGainNode = this.audioContext.createGain();
+            this.masterGainNode.gain.value = this.options.masterVolume;
+            this.masterGainNode.connect(this.audioContext.destination);
+            // Resume if suspended (some browsers start in suspended state)
+            if (this.audioContext.state === 'suspended') {
+                this.audioContext.resume().then(() => {
+                    this.log('AudioContext resumed');
+                });
+            }
+            // Create SoundBank for storing loaded sounds
+            this.soundBank = new SoundBank(this.audioContext, this.options.debug);
+            this.initialized = true;
+            return true;
+        }
+        catch (error) {
+            console.error('[AudioManager] Failed to initialize AudioContext:', error);
+            return false;
+        }
+    }
+    /**
+     * Check if the AudioManager is initialized and ready to play sounds
+     */
+    isInitialized() {
+        return this.initialized && this.audioContext !== null;
+    }
+    /**
+     * Get the underlying AudioContext
+     * Returns null if not initialized
+     */
+    getContext() {
+        return this.audioContext;
+    }
+    /**
+     * Get the master gain node for connecting custom audio nodes
+     * Returns null if not initialized
+     */
+    getMasterGain() {
+        return this.masterGainNode;
+    }
+    /**
+     * Set master volume
+     * @param volume Volume level (0.0 to 1.0)
+     */
+    setMasterVolume(volume) {
+        this.options.masterVolume = Math.max(0, Math.min(1, volume));
+        if (this.masterGainNode) {
+            this.masterGainNode.gain.value = this.options.masterVolume;
+        }
+        this.log(`Master volume set to ${this.options.masterVolume}`);
+    }
+    /**
+     * Get current master volume
+     */
+    getMasterVolume() {
+        return this.options.masterVolume;
+    }
+    /**
+     * Play a retro arcade-style start sound
+     * Creates a quick ascending arpeggio with a square wave for that classic 8-bit feel
+     */
+    playStartSound() {
+        if (!this.audioContext || !this.masterGainNode) {
+            this.log('Cannot play sound: AudioContext not initialized');
+            return;
+        }
+        try {
+            const ctx = this.audioContext;
+            const now = ctx.currentTime;
+            // Ascending arpeggio notes (C major chord going up)
+            const notes = [262, 330, 392, 523]; // C4, E4, G4, C5
+            const noteDuration = 0.06;
+            const noteGap = 0.07;
+            notes.forEach((freq, index) => {
+                const startTime = now + index * noteGap;
+                // Create oscillator with square wave for retro sound
+                const oscillator = ctx.createOscillator();
+                oscillator.type = 'square';
+                oscillator.frequency.setValueAtTime(freq, startTime);
+                // Create gain node for each note
+                const gainNode = ctx.createGain();
+                gainNode.gain.setValueAtTime(0, startTime);
+                gainNode.gain.linearRampToValueAtTime(0.15, startTime + 0.005); // Quick attack
+                gainNode.gain.setValueAtTime(0.15, startTime + noteDuration - 0.01);
+                gainNode.gain.linearRampToValueAtTime(0, startTime + noteDuration);
+                // Connect nodes
+                oscillator.connect(gainNode);
+                gainNode.connect(this.masterGainNode);
+                // Play
+                oscillator.start(startTime);
+                oscillator.stop(startTime + noteDuration);
+            });
+            this.log('Start sound played (retro arpeggio)');
+        }
+        catch (error) {
+            console.error('[AudioManager] Failed to play start sound:', error);
+        }
+    }
+    /**
+     * Play a tone at a specific frequency
+     *
+     * @param frequency Frequency in Hz (e.g., 440 for A4)
+     * @param duration Duration in seconds
+     * @param options Tone options (type, volume, attack, release)
+     */
+    playTone(frequency, duration, options = {}) {
+        if (!this.audioContext || !this.masterGainNode) {
+            this.log('Cannot play tone: AudioContext not initialized');
+            return;
+        }
+        const { type = 'sine', volume = 0.3, attack = 0.01, release = 0.1 } = options;
+        try {
+            const ctx = this.audioContext;
+            const now = ctx.currentTime;
+            // Create oscillator
+            const oscillator = ctx.createOscillator();
+            oscillator.type = type;
+            oscillator.frequency.setValueAtTime(frequency, now);
+            // Create gain node for envelope
+            const gainNode = ctx.createGain();
+            gainNode.gain.setValueAtTime(0, now);
+            gainNode.gain.linearRampToValueAtTime(volume, now + attack);
+            gainNode.gain.setValueAtTime(volume, now + duration - release);
+            gainNode.gain.linearRampToValueAtTime(0, now + duration);
+            // Connect nodes
+            oscillator.connect(gainNode);
+            gainNode.connect(this.masterGainNode);
+            // Play
+            oscillator.start(now);
+            oscillator.stop(now + duration);
+            this.log(`Tone played: ${frequency}Hz for ${duration}s`);
+        }
+        catch (error) {
+            console.error('[AudioManager] Failed to play tone:', error);
+        }
+    }
+    /**
+     * Play a note by name (e.g., 'C4', 'A#5', 'Bb3')
+     *
+     * @param note Note name with octave (e.g., 'A4', 'C#5', 'Bb3')
+     * @param duration Duration in seconds
+     * @param options Tone options
+     */
+    playNote(note, duration, options = {}) {
+        const frequency = this.noteToFrequency(note);
+        if (frequency === null) {
+            console.warn(`[AudioManager] Invalid note: ${note}`);
+            return;
+        }
+        this.playTone(frequency, duration, options);
+    }
+    /**
+     * Convert a note name to frequency
+     *
+     * @param note Note name (e.g., 'A4', 'C#5', 'Bb3')
+     * @returns Frequency in Hz, or null if invalid
+     */
+    noteToFrequency(note) {
+        const notePattern = /^([A-Ga-g])([#b]?)(\d)$/;
+        const match = note.match(notePattern);
+        if (!match)
+            return null;
+        const [, noteLetter, accidental, octaveStr] = match;
+        const octave = parseInt(octaveStr, 10);
+        // Note to semitone offset from C
+        const noteOffsets = {
+            C: 0,
+            D: 2,
+            E: 4,
+            F: 5,
+            G: 7,
+            A: 9,
+            B: 11,
+        };
+        let semitone = noteOffsets[noteLetter.toUpperCase()];
+        if (semitone === undefined)
+            return null;
+        if (accidental === '#')
+            semitone += 1;
+        else if (accidental === 'b')
+            semitone -= 1;
+        // Calculate frequency (A4 = 440Hz)
+        // A4 is the 49th key on piano (0-indexed: 48)
+        // Formula: f = 440 * 2^((n-49)/12) where n is key number (1-indexed)
+        const keyNumber = semitone + (octave + 1) * 12;
+        const frequency = 440 * Math.pow(2, (keyNumber - 49) / 12);
+        return frequency;
+    }
+    /**
+     * Resume the AudioContext if it was suspended
+     * Useful when tab becomes visible again
+     */
+    async resumeContext() {
+        if (this.audioContext && this.audioContext.state === 'suspended') {
+            await this.audioContext.resume();
+            this.log('AudioContext resumed');
+        }
+    }
+    /**
+     * Suspend the AudioContext to save resources
+     * Useful when tab becomes hidden
+     */
+    async suspendContext() {
+        if (this.audioContext && this.audioContext.state === 'running') {
+            await this.audioContext.suspend();
+            this.log('AudioContext suspended');
+        }
+    }
+    /**
+     * Get the current state of the AudioContext
+     */
+    getState() {
+        return this.audioContext?.state ?? null;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SOUND BANK & PLAYBACK
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Get the sound bank for loading and managing sounds
+     * Returns null if not initialized
+     */
+    getSoundBank() {
+        return this.soundBank;
+    }
+    /**
+     * Play a loaded sound by name or ID
+     *
+     * @param nameOrId - Sound name (string) or ID (number)
+     * @param options - Playback options (volume, pitch, loop, position)
+     * @returns Handle to control the playing sound, or null if sound not found
+     *
+     * @example
+     * ```typescript
+     * // Simple playback (global, centered)
+     * const instance = audio.play('coin');
+     * console.log(instance.instanceId); // e.g., 1
+     *
+     * // With options
+     * audio.play('explosion', { volume: 0.5, pitch: 0.8 });
+     *
+     * // Positional audio (2D spatial)
+     * audio.play('footstep', { position: { x: 10000, y: 32768 } });
+     *
+     * // Looping music - can stop later by instanceId
+     * const music = audio.play('background', { loop: true });
+     * // Later: audio.stop(music.instanceId);
+     * ```
+     */
+    play(nameOrId, options = {}) {
+        if (!this.audioContext || !this.masterGainNode || !this.soundBank) {
+            this.log('Cannot play: not initialized');
+            return null;
+        }
+        const sound = this.soundBank.get(nameOrId);
+        if (!sound) {
+            console.warn(`[AudioManager] Sound not found: ${nameOrId}`);
+            return null;
+        }
+        try {
+            const ctx = this.audioContext;
+            // Use provided instanceId (from server) or generate one (standalone)
+            const instanceId = options.instanceId ?? this.nextInstanceId++;
+            // Ensure nextInstanceId stays ahead of any provided IDs to avoid conflicts
+            if (options.instanceId !== undefined && options.instanceId >= this.nextInstanceId) {
+                this.nextInstanceId = options.instanceId + 1;
+            }
+            // Create buffer source
+            const source = ctx.createBufferSource();
+            source.buffer = sound.buffer;
+            source.loop = options.loop ?? false;
+            source.playbackRate.value = options.pitch ?? 1.0;
+            // Create gain node for volume control
+            const gainNode = ctx.createGain();
+            const baseVolume = options.volume ?? 1.0;
+            const fadeInDuration = options.fadeIn ?? 0;
+            // Instance data
+            const instance = {
+                source,
+                gainNode,
+                soundName: sound.name,
+                stopped: false,
+                baseVolume,
+                targetVolume: baseVolume,
+                fadingOut: false,
+                paused: false,
+                pausedAt: 0,
+                startedAt: ctx.currentTime,
+                loop: options.loop ?? false,
+                playbackRate: options.pitch ?? 1.0,
+                buffer: sound.buffer,
+            };
+            // Calculate initial and target volumes
+            let initialVolume = baseVolume;
+            let targetVolume = baseVolume;
+            // Handle spatial audio if position is provided
+            if (options.position) {
+                const { pan, distanceVolume } = this.calculateSpatialAudio(options.position.x, options.position.y);
+                // Create stereo panner for left/right positioning
+                const pannerNode = ctx.createStereoPanner();
+                pannerNode.pan.value = pan;
+                // Calculate volumes with distance attenuation
+                initialVolume = fadeInDuration > 0 ? 0 : baseVolume * distanceVolume;
+                targetVolume = baseVolume * distanceVolume;
+                // Set initial volume
+                gainNode.gain.setValueAtTime(initialVolume, ctx.currentTime);
+                // Apply fade in if specified
+                if (fadeInDuration > 0) {
+                    gainNode.gain.linearRampToValueAtTime(targetVolume, ctx.currentTime + fadeInDuration);
+                    this.log(`Fade in: ${sound.name} [#${instanceId}] over ${fadeInDuration}s`);
+                }
+                // Connect: source -> gain -> panner -> master
+                source.connect(gainNode);
+                gainNode.connect(pannerNode);
+                pannerNode.connect(this.masterGainNode);
+                // Add spatial data to instance
+                instance.pannerNode = pannerNode;
+                instance.position = { x: options.position.x, y: options.position.y };
+                instance.targetVolume = targetVolume;
+                // Register for real-time spatial updates
+                this.spatialSounds.set(source, {
+                    gainNode,
+                    pannerNode,
+                    position: { x: options.position.x, y: options.position.y },
+                    baseVolume,
+                });
+                this.log(`Playing spatial: ${sound.name} [#${instanceId}] at (${options.position.x}, ${options.position.y}) pan=${pan.toFixed(2)} vol=${distanceVolume.toFixed(2)}`);
+            }
+            else {
+                // Non-spatial: source -> gain -> master
+                initialVolume = fadeInDuration > 0 ? 0 : baseVolume;
+                targetVolume = baseVolume;
+                // Set initial volume
+                gainNode.gain.setValueAtTime(initialVolume, ctx.currentTime);
+                // Apply fade in if specified
+                if (fadeInDuration > 0) {
+                    gainNode.gain.linearRampToValueAtTime(targetVolume, ctx.currentTime + fadeInDuration);
+                    this.log(`Fade in: ${sound.name} [#${instanceId}] over ${fadeInDuration}s`);
+                }
+                source.connect(gainNode);
+                gainNode.connect(this.masterGainNode);
+            }
+            // Register instance
+            this.instances.set(instanceId, instance);
+            // Track by sound name for stopping all instances of a sound
+            if (!this.instancesBySound.has(sound.name)) {
+                this.instancesBySound.set(sound.name, new Set());
+            }
+            this.instancesBySound.get(sound.name).add(instanceId);
+            // Track active sounds (legacy)
+            this.activeSounds.add(source);
+            // Cleanup on end (but not if paused - we'll recreate on resume)
+            source.onended = () => {
+                if (!instance.paused) {
+                    this.cleanupInstance(instanceId);
+                }
+            };
+            // Start playback
+            source.start(0, options.offset ?? 0);
+            if (!options.position) {
+                this.log(`Playing: ${sound.name} [#${instanceId}]`);
+            }
+            // Return handle - capture references for closure
+            const stopFn = this.stop.bind(this);
+            const instancesRef = this.instances;
+            return {
+                instanceId,
+                stop: () => {
+                    stopFn(instanceId);
+                },
+                get playing() {
+                    const inst = instancesRef.get(instanceId);
+                    return inst !== undefined && !inst.stopped;
+                },
+                sound,
+            };
+        }
+        catch (error) {
+            console.error(`[AudioManager] Failed to play sound "${nameOrId}":`, error);
+            return null;
+        }
+    }
+    /**
+     * Stop a sound by instance ID, sound name, or all sounds
+     *
+     * @param target - Instance ID (number), sound name (string), or 'all'
+     * @returns Number of instances stopped
+     *
+     * @example
+     * ```typescript
+     * // Stop specific instance
+     * const music = audio.play('background', { loop: true });
+     * audio.stop(music.instanceId);
+     *
+     * // Stop all instances of a sound
+     * audio.stop('explosion');
+     *
+     * // Stop everything
+     * audio.stop('all');
+     * ```
+     */
+    stop(target) {
+        if (target === 'all') {
+            return this.stopAll();
+        }
+        if (typeof target === 'number') {
+            // Stop specific instance by ID
+            return this.stopInstance(target) ? 1 : 0;
+        }
+        // Stop all instances of a sound by name
+        return this.stopByName(target);
+    }
+    /**
+     * Fade out and stop a sound
+     *
+     * @param target - Instance ID (number), sound name (string), or 'all'
+     * @param duration - Fade duration in seconds
+     * @returns Number of instances being faded
+     *
+     * @example
+     * ```typescript
+     * // Fade out specific instance over 2 seconds
+     * const music = audio.play('background', { loop: true });
+     * audio.fadeOut(music.instanceId, 2);
+     *
+     * // Fade out all instances of a sound
+     * audio.fadeOut('ambience', 1.5);
+     *
+     * // Fade out everything
+     * audio.fadeOut('all', 1);
+     * ```
+     */
+    fadeOut(target, duration) {
+        if (!this.audioContext) {
+            return 0;
+        }
+        // Ensure minimum duration
+        const fadeDuration = Math.max(0.01, duration);
+        if (target === 'all') {
+            return this.fadeOutAll(fadeDuration);
+        }
+        if (typeof target === 'number') {
+            return this.fadeOutInstance(target, fadeDuration) ? 1 : 0;
+        }
+        return this.fadeOutByName(target, fadeDuration);
+    }
+    /**
+     * Fade out a specific instance
+     * @private
+     */
+    fadeOutInstance(instanceId, duration) {
+        const instance = this.instances.get(instanceId);
+        if (!instance || instance.stopped || instance.fadingOut) {
+            return false;
+        }
+        if (!this.audioContext) {
+            return false;
+        }
+        const ctx = this.audioContext;
+        instance.fadingOut = true;
+        // Cancel any ongoing ramps and set current value
+        const currentValue = instance.gainNode.gain.value;
+        instance.gainNode.gain.cancelScheduledValues(ctx.currentTime);
+        instance.gainNode.gain.setValueAtTime(currentValue, ctx.currentTime);
+        // Ramp to 0
+        instance.gainNode.gain.linearRampToValueAtTime(0, ctx.currentTime + duration);
+        // Schedule stop after fade completes
+        setTimeout(() => {
+            this.stopInstance(instanceId);
+        }, duration * 1000);
+        this.log(`Fading out instance #${instanceId} (${instance.soundName}) over ${duration}s`);
+        return true;
+    }
+    /**
+     * Fade out all instances of a sound by name
+     * @private
+     */
+    fadeOutByName(soundName, duration) {
+        const instanceIds = this.instancesBySound.get(soundName);
+        if (!instanceIds || instanceIds.size === 0) {
+            return 0;
+        }
+        let count = 0;
+        for (const instanceId of Array.from(instanceIds)) {
+            if (this.fadeOutInstance(instanceId, duration)) {
+                count++;
+            }
+        }
+        this.log(`Fading out ${count} instances of "${soundName}" over ${duration}s`);
+        return count;
+    }
+    /**
+     * Fade out all playing sounds
+     * @private
+     */
+    fadeOutAll(duration) {
+        let count = 0;
+        for (const instanceId of Array.from(this.instances.keys())) {
+            if (this.fadeOutInstance(instanceId, duration)) {
+                count++;
+            }
+        }
+        this.log(`Fading out all sounds (${count} instances) over ${duration}s`);
+        return count;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // PAUSE / RESUME
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Pause a sound by instance ID, sound name, or all sounds
+     *
+     * @param target - Instance ID (number), sound name (string), or 'all'
+     * @returns Number of instances paused
+     *
+     * @example
+     * ```typescript
+     * // Pause specific instance
+     * const music = audio.play('background', { loop: true });
+     * audio.pause(music.instanceId);
+     *
+     * // Pause all instances of a sound
+     * audio.pause('ambience');
+     *
+     * // Pause everything
+     * audio.pause('all');
+     * ```
+     */
+    pause(target) {
+        if (target === 'all') {
+            return this.pauseAll();
+        }
+        if (typeof target === 'number') {
+            return this.pauseInstance(target) ? 1 : 0;
+        }
+        return this.pauseByName(target);
+    }
+    /**
+     * Pause a specific instance
+     * @private
+     */
+    pauseInstance(instanceId) {
+        const instance = this.instances.get(instanceId);
+        if (!instance || instance.stopped || instance.paused || instance.fadingOut) {
+            return false;
+        }
+        if (!this.audioContext) {
+            return false;
+        }
+        const ctx = this.audioContext;
+        // Calculate current playback position
+        const elapsed = (ctx.currentTime - instance.startedAt) * instance.playbackRate;
+        if (instance.loop) {
+            // For looping sounds, wrap around the buffer duration
+            instance.pausedAt = elapsed % instance.buffer.duration;
+        }
+        else {
+            instance.pausedAt = elapsed;
+            // If sound has finished naturally, don't pause
+            if (instance.pausedAt >= instance.buffer.duration) {
+                return false;
+            }
+        }
+        // Stop the source (Web Audio API doesn't support pause, must recreate)
+        try {
+            instance.source.stop();
+        }
+        catch {
+            // Already stopped
+        }
+        instance.paused = true;
+        this.log(`Paused instance #${instanceId} (${instance.soundName}) at ${instance.pausedAt.toFixed(2)}s`);
+        return true;
+    }
+    /**
+     * Pause all instances of a sound by name
+     * @private
+     */
+    pauseByName(soundName) {
+        const instanceIds = this.instancesBySound.get(soundName);
+        if (!instanceIds || instanceIds.size === 0) {
+            return 0;
+        }
+        let count = 0;
+        for (const instanceId of Array.from(instanceIds)) {
+            if (this.pauseInstance(instanceId)) {
+                count++;
+            }
+        }
+        this.log(`Paused ${count} instances of "${soundName}"`);
+        return count;
+    }
+    /**
+     * Pause all playing sounds
+     * @private
+     */
+    pauseAll() {
+        let count = 0;
+        for (const instanceId of Array.from(this.instances.keys())) {
+            if (this.pauseInstance(instanceId)) {
+                count++;
+            }
+        }
+        this.log(`Paused all sounds (${count} instances)`);
+        return count;
+    }
+    /**
+     * Resume a paused sound by instance ID, sound name, or all sounds
+     *
+     * @param target - Instance ID (number), sound name (string), or 'all'
+     * @returns Number of instances resumed
+     *
+     * @example
+     * ```typescript
+     * // Resume specific instance
+     * audio.resume(musicInstanceId);
+     *
+     * // Resume all instances of a sound
+     * audio.resume('ambience');
+     *
+     * // Resume everything
+     * audio.resume('all');
+     * ```
+     */
+    resume(target) {
+        if (target === 'all') {
+            return this.resumeAll();
+        }
+        if (typeof target === 'number') {
+            return this.resumeInstance(target) ? 1 : 0;
+        }
+        return this.resumeByName(target);
+    }
+    /**
+     * Resume a specific paused instance
+     * @private
+     */
+    resumeInstance(instanceId) {
+        const instance = this.instances.get(instanceId);
+        if (!instance || instance.stopped || !instance.paused) {
+            return false;
+        }
+        if (!this.audioContext || !this.masterGainNode) {
+            return false;
+        }
+        const ctx = this.audioContext;
+        // Create a new source node (AudioBufferSourceNode can only be started once)
+        const newSource = ctx.createBufferSource();
+        newSource.buffer = instance.buffer;
+        newSource.loop = instance.loop;
+        newSource.playbackRate.value = instance.playbackRate;
+        // Connect through existing gain node
+        newSource.connect(instance.gainNode);
+        // Update instance with new source
+        instance.source = newSource;
+        instance.paused = false;
+        instance.startedAt = ctx.currentTime - instance.pausedAt / instance.playbackRate;
+        // Cleanup on end (but not if paused again - we'll recreate on resume)
+        newSource.onended = () => {
+            if (!instance.paused) {
+                this.cleanupInstance(instanceId);
+            }
+        };
+        // Start from where we paused
+        newSource.start(0, instance.pausedAt);
+        this.log(`Resumed instance #${instanceId} (${instance.soundName}) from ${instance.pausedAt.toFixed(2)}s`);
+        return true;
+    }
+    /**
+     * Resume all instances of a sound by name
+     * @private
+     */
+    resumeByName(soundName) {
+        const instanceIds = this.instancesBySound.get(soundName);
+        if (!instanceIds || instanceIds.size === 0) {
+            return 0;
+        }
+        let count = 0;
+        for (const instanceId of Array.from(instanceIds)) {
+            if (this.resumeInstance(instanceId)) {
+                count++;
+            }
+        }
+        this.log(`Resumed ${count} instances of "${soundName}"`);
+        return count;
+    }
+    /**
+     * Resume all paused sounds
+     * @private
+     */
+    resumeAll() {
+        let count = 0;
+        for (const instanceId of Array.from(this.instances.keys())) {
+            if (this.resumeInstance(instanceId)) {
+                count++;
+            }
+        }
+        this.log(`Resumed all sounds (${count} instances)`);
+        return count;
+    }
+    /**
+     * Stop a specific sound instance by ID
+     * @private
+     */
+    stopInstance(instanceId) {
+        const instance = this.instances.get(instanceId);
+        if (!instance || instance.stopped) {
+            return false;
+        }
+        try {
+            instance.source.stop();
+            instance.stopped = true;
+            this.log(`Stopped instance #${instanceId} (${instance.soundName})`);
+        }
+        catch {
+            // Already stopped
+        }
+        this.cleanupInstance(instanceId);
+        return true;
+    }
+    /**
+     * Stop all instances of a sound by name
+     * @private
+     */
+    stopByName(soundName) {
+        const instanceIds = this.instancesBySound.get(soundName);
+        if (!instanceIds || instanceIds.size === 0) {
+            return 0;
+        }
+        let count = 0;
+        // Copy to array to avoid mutation during iteration
+        for (const instanceId of Array.from(instanceIds)) {
+            if (this.stopInstance(instanceId)) {
+                count++;
+            }
+        }
+        this.log(`Stopped ${count} instances of "${soundName}"`);
+        return count;
+    }
+    /**
+     * Cleanup instance data after it ends or is stopped
+     * @private
+     */
+    cleanupInstance(instanceId) {
+        const instance = this.instances.get(instanceId);
+        if (!instance)
+            return;
+        // Remove from instances map
+        this.instances.delete(instanceId);
+        // Remove from sound name tracking
+        const byName = this.instancesBySound.get(instance.soundName);
+        if (byName) {
+            byName.delete(instanceId);
+            if (byName.size === 0) {
+                this.instancesBySound.delete(instance.soundName);
+            }
+        }
+        // Legacy cleanup
+        this.activeSounds.delete(instance.source);
+        this.spatialSounds.delete(instance.source);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // SPATIAL AUDIO
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Set the listener position for spatial audio
+     * Updates all currently playing spatial sounds in real-time
+     *
+     * @param x - X position
+     * @param y - Y position
+     *
+     * @example
+     * ```typescript
+     * // Update listener position every frame (typically the player's position)
+     * audio.setListenerPosition(playerX, playerY);
+     * ```
+     */
+    setListenerPosition(x, y) {
+        // Skip if position hasn't changed
+        if (x === this.spatialConfig.listenerX && y === this.spatialConfig.listenerY) {
+            return;
+        }
+        this.spatialConfig.listenerX = x;
+        this.spatialConfig.listenerY = y;
+        // Update all active spatial sounds (only if we have any)
+        if (this.spatialSounds.size > 0) {
+            this.updateAllSpatialSounds();
+        }
+    }
+    /**
+     * Update all active spatial sounds based on current listener position
+     * Called automatically when listener position changes
+     * @private
+     */
+    updateAllSpatialSounds() {
+        for (const [source, spatialData] of this.spatialSounds) {
+            // Skip if sound has ended
+            if (!this.activeSounds.has(source)) {
+                this.spatialSounds.delete(source);
+                continue;
+            }
+            const { pan, distanceVolume } = this.calculateSpatialAudio(spatialData.position.x, spatialData.position.y);
+            // Update panner and gain in real-time
+            spatialData.pannerNode.pan.value = pan;
+            spatialData.gainNode.gain.value = spatialData.baseVolume * distanceVolume;
+        }
+    }
+    /**
+     * Get the current listener position
+     */
+    getListenerPosition() {
+        return {
+            x: this.spatialConfig.listenerX,
+            y: this.spatialConfig.listenerY,
+        };
+    }
+    /**
+     * Configure spatial audio parameters
+     *
+     * @param config - Partial spatial configuration
+     *
+     * @example
+     * ```typescript
+     * // Configure for a smaller game world
+     * audio.configureSpatial({
+     *   maxDistance: 8192,      // Sounds fade out at 8192 units
+     *   referenceDistance: 512, // Full volume within 512 units
+     *   rolloffFactor: 1.5,     // Faster falloff
+     *   panSpread: 1.0,         // Full stereo pan
+     * });
+     * ```
+     */
+    configureSpatial(config) {
+        if (config.listenerX !== undefined) {
+            this.spatialConfig.listenerX = Math.max(0, Math.min(65535, config.listenerX));
+        }
+        if (config.listenerY !== undefined) {
+            this.spatialConfig.listenerY = Math.max(0, Math.min(65535, config.listenerY));
+        }
+        if (config.maxDistance !== undefined) {
+            this.spatialConfig.maxDistance = Math.max(1, config.maxDistance);
+        }
+        if (config.referenceDistance !== undefined) {
+            this.spatialConfig.referenceDistance = Math.max(1, config.referenceDistance);
+        }
+        if (config.rolloffFactor !== undefined) {
+            this.spatialConfig.rolloffFactor = Math.max(0, config.rolloffFactor);
+        }
+        if (config.panSpread !== undefined) {
+            this.spatialConfig.panSpread = Math.max(0, Math.min(1, config.panSpread));
+        }
+    }
+    /**
+     * Get current spatial audio configuration
+     */
+    getSpatialConfig() {
+        return { ...this.spatialConfig };
+    }
+    /**
+     * Calculate stereo pan and volume based on sound position relative to listener
+     *
+     * Uses a linear attenuation model:
+     * - Volume = 1.0 when distance <= referenceDistance
+     * - Volume decreases linearly from 1.0 to 0.0 between referenceDistance and maxDistance
+     * - Volume = 0.0 when distance >= maxDistance
+     *
+     * @param soundX - Sound X position
+     * @param soundY - Sound Y position
+     * @returns Object with pan (-1 to 1) and distanceVolume (0 to 1)
+     * @private
+     */
+    calculateSpatialAudio(soundX, soundY) {
+        const { listenerX, listenerY, maxDistance, referenceDistance, panSpread } = this.spatialConfig;
+        // Calculate distance
+        const dx = soundX - listenerX;
+        const dy = soundY - listenerY;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+        // Calculate volume based on distance (linear attenuation model)
+        let distanceVolume;
+        if (distance <= referenceDistance) {
+            // Full volume within reference distance
+            distanceVolume = 1.0;
+        }
+        else if (distance >= maxDistance) {
+            // Silent beyond max distance
+            distanceVolume = 0.0;
+        }
+        else {
+            // Linear falloff between reference and max distance
+            distanceVolume = 1.0 - (distance - referenceDistance) / (maxDistance - referenceDistance);
+        }
+        // Calculate stereo pan based on X offset
+        // Pan ranges from -1 (left) to 1 (right)
+        let pan = 0;
+        if (maxDistance > 0 && panSpread > 0) {
+            // Normalize X difference to -1..1 range based on max distance
+            pan = (dx / maxDistance) * panSpread;
+            // Clamp to valid range
+            pan = Math.max(-1, Math.min(1, pan));
+        }
+        this.log(`Spatial: listener(${listenerX.toFixed(1)}, ${listenerY.toFixed(1)}) ` +
+            `sound(${soundX.toFixed(1)}, ${soundY.toFixed(1)}) ` +
+            `dist=${distance.toFixed(1)} vol=${distanceVolume.toFixed(2)} pan=${pan.toFixed(2)}`);
+        return { pan, distanceVolume };
+    }
+    /**
+     * Stop all currently playing sounds
+     * @returns Number of instances stopped
+     */
+    stopAll() {
+        const count = this.instances.size;
+        // Stop all tracked instances
+        for (const [, instance] of this.instances) {
+            if (!instance.stopped) {
+                try {
+                    instance.source.stop();
+                    instance.stopped = true;
+                }
+                catch {
+                    // Already stopped
+                }
+            }
+        }
+        // Clear all tracking
+        this.instances.clear();
+        this.instancesBySound.clear();
+        this.activeSounds.clear();
+        this.spatialSounds.clear();
+        this.log(`Stopped all sounds (${count} instances)`);
+        return count;
+    }
+    /**
+     * Get the number of currently playing sounds
+     */
+    getPlayingCount() {
+        return this.instances.size;
+    }
+    /**
+     * Get all active instance IDs
+     */
+    getActiveInstances() {
+        return Array.from(this.instances.keys());
+    }
+    /**
+     * Check if a specific instance is still playing
+     */
+    isPlaying(instanceId) {
+        const instance = this.instances.get(instanceId);
+        return instance !== undefined && !instance.stopped;
+    }
+    /**
+     * Destroy the AudioManager and release resources
+     */
+    destroy() {
+        // Stop all sounds
+        this.stopAll();
+        // Clear sound bank
+        if (this.soundBank) {
+            this.soundBank.clear();
+            this.soundBank = null;
+        }
+        if (this.audioContext) {
+            this.audioContext.close();
+            this.audioContext = null;
+        }
+        this.masterGainNode = null;
+        this.initialized = false;
+        this.log('AudioManager destroyed');
+    }
+    log(message) {
+        if (this.options.debug) {
+            console.warn(`[AudioManager] ${message}`);
+        }
+    }
+}
+//# sourceMappingURL=AudioManager.js.map