@utsp/audio 0.4.0-nightly.20251203172602.bbfc50f

package/dist/index.d.ts

@@ -0,0 +1,620 @@
+import { ISoundLoader, IAudioProcessor } from '@utsp/types';
+
+/**
+ * SoundBank - Unified audio asset cache for UTSP applications
+ *
+ * Stores decoded AudioBuffers from any source (File, FileExternal, Procedural)
+ * in a unified format for consistent playback.
+ *
+ * Implements ISoundLoader interface from @utsp/types for unified sound loading
+ * abstraction.
+ *
+ * @example
+ * ```typescript
+ * const soundBank = new SoundBank(audioContext);
+ *
+ * // Load from different sources (all stored the same way)
+ * await soundBank.loadFromData(0, 'coin', mp3Data);
+ * await soundBank.loadFromUrl(1, 'music', 'https://cdn.example.com/music.mp3');
+ *
+ * // Access uniformly
+ * const sound = soundBank.get('coin');
+ * console.log(sound.duration); // Works the same regardless of source
+ * ```
+ */
+
+/**
+ * Source type for a loaded sound
+ */
+type SoundSource = 'file' | 'external' | 'procedural';
+/**
+ * Metadata about a loaded sound
+ */
+interface SoundMetadata {
+    /** How the sound was loaded */
+    source: SoundSource;
+    /** Original size in bytes before decoding (if applicable) */
+    originalSize?: number;
+    /** Original URL (for external sounds) */
+    originalUrl?: string;
+    /** Timestamp when the sound was loaded */
+    loadedAt: number;
+}
+/**
+ * A loaded sound ready for playback
+ * Unified representation regardless of source
+ */
+interface LoadedSound {
+    /** Unique sound identifier (0-255) */
+    soundId: number;
+    /** Human-readable name for the sound */
+    name: string;
+    /** Decoded audio buffer ready for playback */
+    buffer: AudioBuffer;
+    /** Duration in seconds */
+    duration: number;
+    /** Loading metadata (source, size, etc.) */
+    metadata: SoundMetadata;
+}
+/**
+ * Statistics about the sound bank
+ */
+interface SoundBankStats {
+    /** Total number of loaded sounds */
+    totalSounds: number;
+    /** Total duration of all sounds in seconds */
+    totalDuration: number;
+    /** Total memory usage estimate in bytes */
+    estimatedMemory: number;
+    /** Count by source type */
+    bySource: {
+        file: number;
+        external: number;
+        procedural: number;
+    };
+}
+/**
+ * Progress callback for loading sounds
+ */
+type LoadProgressCallback = (loaded: number, total: number) => void;
+/**
+ * SoundBank - Unified storage for decoded audio assets
+ *
+ * Implements ISoundLoader for unified sound loading abstraction.
+ */
+declare class SoundBank implements ISoundLoader {
+    private sounds;
+    private nameToId;
+    private audioContext;
+    private debug;
+    /**
+     * Create a new SoundBank
+     * @param audioContext - The Web Audio context for decoding
+     * @param debug - Enable debug logging
+     */
+    constructor(audioContext: AudioContext, debug?: boolean);
+    /**
+     * Load a sound from binary data (File mode - sent via UTSP)
+     *
+     * @param soundId - Unique identifier (0-255)
+     * @param name - Human-readable name
+     * @param data - Raw audio data (MP3, WAV, OGG, etc.)
+     */
+    loadFromData(soundId: number, name: string, data: Uint8Array): Promise<void>;
+    /**
+     * Load a sound from an external URL (FileExternal mode - CDN, etc.)
+     *
+     * @param soundId - Unique identifier (0-255)
+     * @param name - Human-readable name
+     * @param url - URL to fetch the audio from
+     * @param onProgress - Optional progress callback
+     */
+    loadFromUrl(soundId: number, name: string, url: string, onProgress?: LoadProgressCallback): Promise<void>;
+    /**
+     * Load a sound from a procedural generator (future use)
+     *
+     * @param soundId - Unique identifier (0-255)
+     * @param name - Human-readable name
+     * @param buffer - Pre-generated AudioBuffer
+     */
+    loadFromBuffer(soundId: number, name: string, buffer: AudioBuffer): void;
+    /**
+     * Store a decoded sound in the bank
+     */
+    private store;
+    /**
+     * Decode raw audio data to an AudioBuffer
+     */
+    private decodeAudio;
+    /**
+     * Get a loaded sound by ID or name
+     *
+     * @param idOrName - Sound ID (number) or name (string)
+     * @returns The loaded sound, or undefined if not found
+     */
+    get(idOrName: number | string): LoadedSound | undefined;
+    /**
+     * Check if a sound is loaded
+     *
+     * @param idOrName - Sound ID (number) or name (string)
+     */
+    has(idOrName: number | string): boolean;
+    /**
+     * Get all loaded sounds
+     */
+    getAll(): LoadedSound[];
+    /**
+     * Get all loaded sound names
+     */
+    getNames(): string[];
+    /**
+     * Get the number of loaded sounds
+     */
+    get size(): number;
+    /**
+     * Remove a sound from the bank
+     *
+     * @param idOrName - Sound ID (number) or name (string)
+     * @returns true if the sound was removed, false if not found
+     */
+    remove(idOrName: number | string): boolean;
+    /**
+     * Clear all sounds from the bank
+     */
+    clear(): void;
+    /**
+     * Get statistics about the sound bank
+     */
+    getStats(): SoundBankStats;
+    private log;
+}
+
+/**
+ * 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
+ * ```
+ */
+
+interface AudioManagerOptions {
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Master volume (0.0 to 1.0, default: 1.0) */
+    masterVolume?: number;
+}
+interface ToneOptions {
+    /** Oscillator type (default: 'sine') */
+    type?: OscillatorType;
+    /** Volume (0.0 to 1.0, default: 0.3) */
+    volume?: number;
+    /** Attack time in seconds (default: 0.01) */
+    attack?: number;
+    /** Release time in seconds (default: 0.1) */
+    release?: number;
+}
+/**
+ * Options for playing a loaded sound
+ */
+interface PlayOptions {
+    /** Volume multiplier (0.0 to 1.0, default: 1.0) */
+    volume?: number;
+    /** Playback rate / pitch (0.5 = octave down, 2.0 = octave up, default: 1.0) */
+    pitch?: number;
+    /** Loop the sound (default: false) */
+    loop?: boolean;
+    /** Start time offset in seconds (default: 0) */
+    offset?: number;
+    /** Fade in duration in seconds (0 = no fade, default: 0) */
+    fadeIn?: number;
+    /** Spatial position for 2D positional audio (16-bit X/Y) */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Instance ID for this playback (optional)
+     * If provided (e.g., from server), this ID will be used.
+     * If not provided (standalone mode), an ID will be auto-generated.
+     */
+    instanceId?: number;
+}
+/**
+ * Configuration for spatial audio listener
+ */
+interface SpatialConfig {
+    /** Listener X position (0-65535) */
+    listenerX: number;
+    /** Listener Y position (0-65535) */
+    listenerY: number;
+    /** Maximum audible distance (default: 16384 = 1/4 of 16-bit range) */
+    maxDistance: number;
+    /** Reference distance where volume = 1.0 (default: 1024) */
+    referenceDistance: number;
+    /** Rolloff factor (higher = faster volume falloff, default: 1.0) */
+    rolloffFactor: number;
+    /** Pan spread (0 = no stereo, 1 = full stereo pan, default: 0.8) */
+    panSpread: number;
+}
+/**
+ * Handle to a playing sound for stop/control
+ */
+interface PlayingSound {
+    /** Unique instance ID for this playback */
+    readonly instanceId: number;
+    /** Stop the sound immediately */
+    stop(): void;
+    /** Check if the sound is still playing */
+    readonly playing: boolean;
+    /** The sound being played */
+    readonly sound: LoadedSound;
+}
+/**
+ * AudioManager - Main audio management class
+ *
+ * Implements IAudioProcessor for unified audio handling in standalone and connected modes.
+ */
+declare class AudioManager implements IAudioProcessor {
+    private audioContext;
+    private masterGainNode;
+    private soundBank;
+    private options;
+    private initialized;
+    private nextInstanceId;
+    private instances;
+    private instancesBySound;
+    private activeSounds;
+    private spatialSounds;
+    private spatialConfig;
+    constructor(options?: AudioManagerOptions);
+    /**
+     * Initialize the Web AudioContext
+     * Must be called from a user interaction event (click, touch, keypress)
+     *
+     * @returns true if initialization was successful, false otherwise
+     */
+    initialize(): boolean;
+    /**
+     * Check if the AudioManager is initialized and ready to play sounds
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the underlying AudioContext
+     * Returns null if not initialized
+     */
+    getContext(): AudioContext | null;
+    /**
+     * Get the master gain node for connecting custom audio nodes
+     * Returns null if not initialized
+     */
+    getMasterGain(): GainNode | null;
+    /**
+     * Set master volume
+     * @param volume Volume level (0.0 to 1.0)
+     */
+    setMasterVolume(volume: number): void;
+    /**
+     * Get current master volume
+     */
+    getMasterVolume(): number;
+    /**
+     * Play a retro arcade-style start sound
+     * Creates a quick ascending arpeggio with a square wave for that classic 8-bit feel
+     */
+    playStartSound(): void;
+    /**
+     * 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: number, duration: number, options?: ToneOptions): void;
+    /**
+     * 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: string, duration: number, options?: ToneOptions): void;
+    /**
+     * 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: string): number | null;
+    /**
+     * Resume the AudioContext if it was suspended
+     * Useful when tab becomes visible again
+     */
+    resumeContext(): Promise<void>;
+    /**
+     * Suspend the AudioContext to save resources
+     * Useful when tab becomes hidden
+     */
+    suspendContext(): Promise<void>;
+    /**
+     * Get the current state of the AudioContext
+     */
+    getState(): AudioContextState | null;
+    /**
+     * Get the sound bank for loading and managing sounds
+     * Returns null if not initialized
+     */
+    getSoundBank(): SoundBank | null;
+    /**
+     * 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: string | number, options?: PlayOptions): PlayingSound | 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: number | string): number;
+    /**
+     * 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: number | string | 'all', duration: number): number;
+    /**
+     * Fade out a specific instance
+     * @private
+     */
+    private fadeOutInstance;
+    /**
+     * Fade out all instances of a sound by name
+     * @private
+     */
+    private fadeOutByName;
+    /**
+     * Fade out all playing sounds
+     * @private
+     */
+    private fadeOutAll;
+    /**
+     * 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: number | string | 'all'): number;
+    /**
+     * Pause a specific instance
+     * @private
+     */
+    private pauseInstance;
+    /**
+     * Pause all instances of a sound by name
+     * @private
+     */
+    private pauseByName;
+    /**
+     * Pause all playing sounds
+     * @private
+     */
+    private pauseAll;
+    /**
+     * 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: number | string | 'all'): number;
+    /**
+     * Resume a specific paused instance
+     * @private
+     */
+    private resumeInstance;
+    /**
+     * Resume all instances of a sound by name
+     * @private
+     */
+    private resumeByName;
+    /**
+     * Resume all paused sounds
+     * @private
+     */
+    private resumeAll;
+    /**
+     * Stop a specific sound instance by ID
+     * @private
+     */
+    private stopInstance;
+    /**
+     * Stop all instances of a sound by name
+     * @private
+     */
+    private stopByName;
+    /**
+     * Cleanup instance data after it ends or is stopped
+     * @private
+     */
+    private cleanupInstance;
+    /**
+     * 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: number, y: number): void;
+    /**
+     * Update all active spatial sounds based on current listener position
+     * Called automatically when listener position changes
+     * @private
+     */
+    private updateAllSpatialSounds;
+    /**
+     * Get the current listener position
+     */
+    getListenerPosition(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * 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: Partial<SpatialConfig>): void;
+    /**
+     * Get current spatial audio configuration
+     */
+    getSpatialConfig(): Readonly<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
+     */
+    private calculateSpatialAudio;
+    /**
+     * Stop all currently playing sounds
+     * @returns Number of instances stopped
+     */
+    stopAll(): number;
+    /**
+     * Get the number of currently playing sounds
+     */
+    getPlayingCount(): number;
+    /**
+     * Get all active instance IDs
+     */
+    getActiveInstances(): number[];
+    /**
+     * Check if a specific instance is still playing
+     */
+    isPlaying(instanceId: number): boolean;
+    /**
+     * Destroy the AudioManager and release resources
+     */
+    destroy(): void;
+    private log;
+}
+
+export { AudioManager, SoundBank };
+export type { AudioManagerOptions, LoadProgressCallback, LoadedSound, PlayOptions, PlayingSound, SoundBankStats, SoundMetadata, SoundSource, ToneOptions };

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @utsp/audio
+ *
+ * Web Audio API management for UTSP applications.
+ * Provides audio context initialization, sound playback, and utilities.
+ */
+// Main AudioManager
+export { AudioManager } from './AudioManager';
+// SoundBank for managing loaded sounds
+export { SoundBank } from './SoundBank';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,uCAAuC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.mjs

@@ -0,0 +1 @@
+var $=Object.defineProperty;var I=(m,t,e)=>t in m?$(m,t,{enumerable:!0,configurable:!0,writable:!0,value:e}):m[t]=e;var A=(m,t)=>$(m,"name",{value:t,configurable:!0});var c=(m,t,e)=>(I(m,typeof t!="symbol"?t+"":t,e),e);var S=class S{constructor(t,e=!1){c(this,"sounds",new Map);c(this,"nameToId",new Map);c(this,"audioContext");c(this,"debug");this.audioContext=t,this.debug=e,this.log("SoundBank created")}async loadFromData(t,e,n){this.log(`Loading sound from data: ${e} (${n.length} bytes)`);try{let o=await this.decodeAudio(n);this.store(t,e,o,{source:"file",originalSize:n.length,loadedAt:Date.now()}),this.log(`\u2713 Loaded: ${e} (${o.duration.toFixed(2)}s)`)}catch(o){throw console.error(`[SoundBank] Failed to decode sound "${e}":`,o),o}}async loadFromUrl(t,e,n,o){this.log(`Loading sound from URL: ${e} \u2192 ${n}`);try{let i=await fetch(n);if(!i.ok)throw new Error(`HTTP ${i.status}: ${i.statusText}`);let r=i.headers.get("content-length"),d=r?parseInt(r,10):0,a;if(d>0&&o&&i.body){let u=i.body.getReader(),l=[],f=0;for(;;){let{done:p,value:h}=await u.read();if(p)break;l.push(h),f+=h.length,o(f,d)}let y=new Uint8Array(f),x=0;for(let p of l)y.set(p,x),x+=p.length;a=y.buffer}else a=await i.arrayBuffer();let s=await this.decodeAudio(new Uint8Array(a));this.store(t,e,s,{source:"external",originalSize:a.byteLength,originalUrl:n,loadedAt:Date.now()}),this.log(`\u2713 Loaded from URL: ${e} (${s.duration.toFixed(2)}s)`)}catch(i){throw console.error(`[SoundBank] Failed to load sound "${e}" from ${n}:`,i),i}}loadFromBuffer(t,e,n){this.log(`Loading sound from buffer: ${e}`),this.store(t,e,n,{source:"procedural",loadedAt:Date.now()}),this.log(`\u2713 Loaded from buffer: ${e} (${n.duration.toFixed(2)}s)`)}store(t,e,n,o){if(this.sounds.has(t)){let r=this.sounds.get(t);this.log(`Replacing sound ID ${t} (was: ${r.name}, now: ${e})`),this.nameToId.delete(r.name)}if(this.nameToId.has(e)){let r=this.nameToId.get(e);r!==t&&this.log(`Warning: Sound name "${e}" already exists with ID ${r}`)}let i={soundId:t,name:e,buffer:n,duration:n.duration,metadata:o};this.sounds.set(t,i),this.nameToId.set(e,t)}async decodeAudio(t){let e=new ArrayBuffer(t.byteLength);return new Uint8Array(e).set(t),this.audioContext.decodeAudioData(e)}get(t){if(typeof t=="number")return this.sounds.get(t);let e=this.nameToId.get(t);return e!==void 0?this.sounds.get(e):void 0}has(t){return this.get(t)!==void 0}getAll(){return Array.from(this.sounds.values())}getNames(){return Array.from(this.nameToId.keys())}get size(){return this.sounds.size}remove(t){let e=this.get(t);return e?(this.sounds.delete(e.soundId),this.nameToId.delete(e.name),this.log(`Removed sound: ${e.name}`),!0):!1}clear(){let t=this.sounds.size;this.sounds.clear(),this.nameToId.clear(),this.log(`Cleared ${t} sounds`)}getStats(){let t=this.getAll(),e=0;for(let n of t){let{buffer:o}=n;e+=o.length*o.numberOfChannels*4}return{totalSounds:t.length,totalDuration:t.reduce((n,o)=>n+o.duration,0),estimatedMemory:e,bySource:{file:t.filter(n=>n.metadata.source==="file").length,external:t.filter(n=>n.metadata.source==="external").length,procedural:t.filter(n=>n.metadata.source==="procedural").length}}}log(t){this.debug&&console.warn(`[SoundBank] ${t}`)}};A(S,"SoundBank");var b=S;var v=class v{constructor(t={}){c(this,"audioContext",null);c(this,"masterGainNode",null);c(this,"soundBank",null);c(this,"options");c(this,"initialized",!1);c(this,"nextInstanceId",1);c(this,"instances",new Map);c(this,"instancesBySound",new Map);c(this,"activeSounds",new Set);c(this,"spatialSounds",new Map);c(this,"spatialConfig",{listenerX:32768,listenerY:32768,maxDistance:16384,referenceDistance:1024,rolloffFactor:1,panSpread:.8});this.options={debug:t.debug??!1,masterVolume:t.masterVolume??1},this.log("AudioManager created")}initialize(){if(this.initialized&&this.audioContext)return this.log("AudioContext already initialized"),!0;try{let t=window.AudioContext||window.webkitAudioContext;return t?(this.audioContext=new t,this.log(`AudioContext initialized (state: ${this.audioContext.state}, sampleRate: ${this.audioContext.sampleRate}Hz)`),this.masterGainNode=this.audioContext.createGain(),this.masterGainNode.gain.value=this.options.masterVolume,this.masterGainNode.connect(this.audioContext.destination),this.audioContext.state==="suspended"&&this.audioContext.resume().then(()=>{this.log("AudioContext resumed")}),this.soundBank=new b(this.audioContext,this.options.debug),this.initialized=!0,!0):(console.warn("[AudioManager] Web Audio API not supported"),!1)}catch(t){return console.error("[AudioManager] Failed to initialize AudioContext:",t),!1}}isInitialized(){return this.initialized&&this.audioContext!==null}getContext(){return this.audioContext}getMasterGain(){return this.masterGainNode}setMasterVolume(t){this.options.masterVolume=Math.max(0,Math.min(1,t)),this.masterGainNode&&(this.masterGainNode.gain.value=this.options.masterVolume),this.log(`Master volume set to ${this.options.masterVolume}`)}getMasterVolume(){return this.options.masterVolume}playStartSound(){if(!this.audioContext||!this.masterGainNode){this.log("Cannot play sound: AudioContext not initialized");return}try{let t=this.audioContext,e=t.currentTime,n=[262,330,392,523],o=.06,i=.07;n.forEach((r,d)=>{let a=e+d*i,s=t.createOscillator();s.type="square",s.frequency.setValueAtTime(r,a);let u=t.createGain();u.gain.setValueAtTime(0,a),u.gain.linearRampToValueAtTime(.15,a+.005),u.gain.setValueAtTime(.15,a+o-.01),u.gain.linearRampToValueAtTime(0,a+o),s.connect(u),u.connect(this.masterGainNode),s.start(a),s.stop(a+o)}),this.log("Start sound played (retro arpeggio)")}catch(t){console.error("[AudioManager] Failed to play start sound:",t)}}playTone(t,e,n={}){if(!this.audioContext||!this.masterGainNode){this.log("Cannot play tone: AudioContext not initialized");return}let{type:o="sine",volume:i=.3,attack:r=.01,release:d=.1}=n;try{let a=this.audioContext,s=a.currentTime,u=a.createOscillator();u.type=o,u.frequency.setValueAtTime(t,s);let l=a.createGain();l.gain.setValueAtTime(0,s),l.gain.linearRampToValueAtTime(i,s+r),l.gain.setValueAtTime(i,s+e-d),l.gain.linearRampToValueAtTime(0,s+e),u.connect(l),l.connect(this.masterGainNode),u.start(s),u.stop(s+e),this.log(`Tone played: ${t}Hz for ${e}s`)}catch(a){console.error("[AudioManager] Failed to play tone:",a)}}playNote(t,e,n={}){let o=this.noteToFrequency(t);if(o===null){console.warn(`[AudioManager] Invalid note: ${t}`);return}this.playTone(o,e,n)}noteToFrequency(t){let e=/^([A-Ga-g])([#b]?)(\d)$/,n=t.match(e);if(!n)return null;let[,o,i,r]=n,d=parseInt(r,10),s={C:0,D:2,E:4,F:5,G:7,A:9,B:11}[o.toUpperCase()];if(s===void 0)return null;i==="#"?s+=1:i==="b"&&(s-=1);let u=s+(d+1)*12;return 440*Math.pow(2,(u-49)/12)}async resumeContext(){this.audioContext&&this.audioContext.state==="suspended"&&(await this.audioContext.resume(),this.log("AudioContext resumed"))}async suspendContext(){this.audioContext&&this.audioContext.state==="running"&&(await this.audioContext.suspend(),this.log("AudioContext suspended"))}getState(){return this.audioContext?.state??null}getSoundBank(){return this.soundBank}play(t,e={}){if(!this.audioContext||!this.masterGainNode||!this.soundBank)return this.log("Cannot play: not initialized"),null;let n=this.soundBank.get(t);if(!n)return console.warn(`[AudioManager] Sound not found: ${t}`),null;try{let o=this.audioContext,i=e.instanceId??this.nextInstanceId++;e.instanceId!==void 0&&e.instanceId>=this.nextInstanceId&&(this.nextInstanceId=e.instanceId+1);let r=o.createBufferSource();r.buffer=n.buffer,r.loop=e.loop??!1,r.playbackRate.value=e.pitch??1;let d=o.createGain(),a=e.volume??1,s=e.fadeIn??0,u={source:r,gainNode:d,soundName:n.name,stopped:!1,baseVolume:a,targetVolume:a,fadingOut:!1,paused:!1,pausedAt:0,startedAt:o.currentTime,loop:e.loop??!1,playbackRate:e.pitch??1,buffer:n.buffer},l=a,f=a;if(e.position){let{pan:p,distanceVolume:h}=this.calculateSpatialAudio(e.position.x,e.position.y),g=o.createStereoPanner();g.pan.value=p,l=s>0?0:a*h,f=a*h,d.gain.setValueAtTime(l,o.currentTime),s>0&&(d.gain.linearRampToValueAtTime(f,o.currentTime+s),this.log(`Fade in: ${n.name} [#${i}] over ${s}s`)),r.connect(d),d.connect(g),g.connect(this.masterGainNode),u.pannerNode=g,u.position={x:e.position.x,y:e.position.y},u.targetVolume=f,this.spatialSounds.set(r,{gainNode:d,pannerNode:g,position:{x:e.position.x,y:e.position.y},baseVolume:a}),this.log(`Playing spatial: ${n.name} [#${i}] at (${e.position.x}, ${e.position.y}) pan=${p.toFixed(2)} vol=${h.toFixed(2)}`)}else l=s>0?0:a,f=a,d.gain.setValueAtTime(l,o.currentTime),s>0&&(d.gain.linearRampToValueAtTime(f,o.currentTime+s),this.log(`Fade in: ${n.name} [#${i}] over ${s}s`)),r.connect(d),d.connect(this.masterGainNode);this.instances.set(i,u),this.instancesBySound.has(n.name)||this.instancesBySound.set(n.name,new Set),this.instancesBySound.get(n.name).add(i),this.activeSounds.add(r),r.onended=()=>{u.paused||this.cleanupInstance(i)},r.start(0,e.offset??0),e.position||this.log(`Playing: ${n.name} [#${i}]`);let y=this.stop.bind(this),x=this.instances;return{instanceId:i,stop:()=>{y(i)},get playing(){let p=x.get(i);return p!==void 0&&!p.stopped},sound:n}}catch(o){return console.error(`[AudioManager] Failed to play sound "${t}":`,o),null}}stop(t){return t==="all"?this.stopAll():typeof t=="number"?this.stopInstance(t)?1:0:this.stopByName(t)}fadeOut(t,e){if(!this.audioContext)return 0;let n=Math.max(.01,e);return t==="all"?this.fadeOutAll(n):typeof t=="number"?this.fadeOutInstance(t,n)?1:0:this.fadeOutByName(t,n)}fadeOutInstance(t,e){let n=this.instances.get(t);if(!n||n.stopped||n.fadingOut||!this.audioContext)return!1;let o=this.audioContext;n.fadingOut=!0;let i=n.gainNode.gain.value;return n.gainNode.gain.cancelScheduledValues(o.currentTime),n.gainNode.gain.setValueAtTime(i,o.currentTime),n.gainNode.gain.linearRampToValueAtTime(0,o.currentTime+e),setTimeout(()=>{this.stopInstance(t)},e*1e3),this.log(`Fading out instance #${t} (${n.soundName}) over ${e}s`),!0}fadeOutByName(t,e){let n=this.instancesBySound.get(t);if(!n||n.size===0)return 0;let o=0;for(let i of Array.from(n))this.fadeOutInstance(i,e)&&o++;return this.log(`Fading out ${o} instances of "${t}" over ${e}s`),o}fadeOutAll(t){let e=0;for(let n of Array.from(this.instances.keys()))this.fadeOutInstance(n,t)&&e++;return this.log(`Fading out all sounds (${e} instances) over ${t}s`),e}pause(t){return t==="all"?this.pauseAll():typeof t=="number"?this.pauseInstance(t)?1:0:this.pauseByName(t)}pauseInstance(t){let e=this.instances.get(t);if(!e||e.stopped||e.paused||e.fadingOut||!this.audioContext)return!1;let o=(this.audioContext.currentTime-e.startedAt)*e.playbackRate;if(e.loop)e.pausedAt=o%e.buffer.duration;else if(e.pausedAt=o,e.pausedAt>=e.buffer.duration)return!1;try{e.source.stop()}catch{}return e.paused=!0,this.log(`Paused instance #${t} (${e.soundName}) at ${e.pausedAt.toFixed(2)}s`),!0}pauseByName(t){let e=this.instancesBySound.get(t);if(!e||e.size===0)return 0;let n=0;for(let o of Array.from(e))this.pauseInstance(o)&&n++;return this.log(`Paused ${n} instances of "${t}"`),n}pauseAll(){let t=0;for(let e of Array.from(this.instances.keys()))this.pauseInstance(e)&&t++;return this.log(`Paused all sounds (${t} instances)`),t}resume(t){return t==="all"?this.resumeAll():typeof t=="number"?this.resumeInstance(t)?1:0:this.resumeByName(t)}resumeInstance(t){let e=this.instances.get(t);if(!e||e.stopped||!e.paused||!this.audioContext||!this.masterGainNode)return!1;let n=this.audioContext,o=n.createBufferSource();return o.buffer=e.buffer,o.loop=e.loop,o.playbackRate.value=e.playbackRate,o.connect(e.gainNode),e.source=o,e.paused=!1,e.startedAt=n.currentTime-e.pausedAt/e.playbackRate,o.onended=()=>{e.paused||this.cleanupInstance(t)},o.start(0,e.pausedAt),this.log(`Resumed instance #${t} (${e.soundName}) from ${e.pausedAt.toFixed(2)}s`),!0}resumeByName(t){let e=this.instancesBySound.get(t);if(!e||e.size===0)return 0;let n=0;for(let o of Array.from(e))this.resumeInstance(o)&&n++;return this.log(`Resumed ${n} instances of "${t}"`),n}resumeAll(){let t=0;for(let e of Array.from(this.instances.keys()))this.resumeInstance(e)&&t++;return this.log(`Resumed all sounds (${t} instances)`),t}stopInstance(t){let e=this.instances.get(t);if(!e||e.stopped)return!1;try{e.source.stop(),e.stopped=!0,this.log(`Stopped instance #${t} (${e.soundName})`)}catch{}return this.cleanupInstance(t),!0}stopByName(t){let e=this.instancesBySound.get(t);if(!e||e.size===0)return 0;let n=0;for(let o of Array.from(e))this.stopInstance(o)&&n++;return this.log(`Stopped ${n} instances of "${t}"`),n}cleanupInstance(t){let e=this.instances.get(t);if(!e)return;this.instances.delete(t);let n=this.instancesBySound.get(e.soundName);n&&(n.delete(t),n.size===0&&this.instancesBySound.delete(e.soundName)),this.activeSounds.delete(e.source),this.spatialSounds.delete(e.source)}setListenerPosition(t,e){t===this.spatialConfig.listenerX&&e===this.spatialConfig.listenerY||(this.spatialConfig.listenerX=t,this.spatialConfig.listenerY=e,this.spatialSounds.size>0&&this.updateAllSpatialSounds())}updateAllSpatialSounds(){for(let[t,e]of this.spatialSounds){if(!this.activeSounds.has(t)){this.spatialSounds.delete(t);continue}let{pan:n,distanceVolume:o}=this.calculateSpatialAudio(e.position.x,e.position.y);e.pannerNode.pan.value=n,e.gainNode.gain.value=e.baseVolume*o}}getListenerPosition(){return{x:this.spatialConfig.listenerX,y:this.spatialConfig.listenerY}}configureSpatial(t){t.listenerX!==void 0&&(this.spatialConfig.listenerX=Math.max(0,Math.min(65535,t.listenerX))),t.listenerY!==void 0&&(this.spatialConfig.listenerY=Math.max(0,Math.min(65535,t.listenerY))),t.maxDistance!==void 0&&(this.spatialConfig.maxDistance=Math.max(1,t.maxDistance)),t.referenceDistance!==void 0&&(this.spatialConfig.referenceDistance=Math.max(1,t.referenceDistance)),t.rolloffFactor!==void 0&&(this.spatialConfig.rolloffFactor=Math.max(0,t.rolloffFactor)),t.panSpread!==void 0&&(this.spatialConfig.panSpread=Math.max(0,Math.min(1,t.panSpread)))}getSpatialConfig(){return{...this.spatialConfig}}calculateSpatialAudio(t,e){let{listenerX:n,listenerY:o,maxDistance:i,referenceDistance:r,panSpread:d}=this.spatialConfig,a=t-n,s=e-o,u=Math.sqrt(a*a+s*s),l;u<=r?l=1:u>=i?l=0:l=1-(u-r)/(i-r);let f=0;return i>0&&d>0&&(f=a/i*d,f=Math.max(-1,Math.min(1,f))),this.log(`Spatial: listener(${n.toFixed(1)}, ${o.toFixed(1)}) sound(${t.toFixed(1)}, ${e.toFixed(1)}) dist=${u.toFixed(1)} vol=${l.toFixed(2)} pan=${f.toFixed(2)}`),{pan:f,distanceVolume:l}}stopAll(){let t=this.instances.size;for(let[,e]of this.instances)if(!e.stopped)try{e.source.stop(),e.stopped=!0}catch{}return this.instances.clear(),this.instancesBySound.clear(),this.activeSounds.clear(),this.spatialSounds.clear(),this.log(`Stopped all sounds (${t} instances)`),t}getPlayingCount(){return this.instances.size}getActiveInstances(){return Array.from(this.instances.keys())}isPlaying(t){let e=this.instances.get(t);return e!==void 0&&!e.stopped}destroy(){this.stopAll(),this.soundBank&&(this.soundBank.clear(),this.soundBank=null),this.audioContext&&(this.audioContext.close(),this.audioContext=null),this.masterGainNode=null,this.initialized=!1,this.log("AudioManager destroyed")}log(t){this.options.debug&&console.warn(`[AudioManager] ${t}`)}};A(v,"AudioManager");var C=v;export{C as AudioManager,b as SoundBank};