audio-system

Audio System

When to Use

Use this skill when:

• Playing sound effects
• Managing background music
• Implementing spatial 3D audio
• Creating audio feedback for actions
• Building audio mixing system
• Handling audio asset loading

Core Principles

1. Web Audio API: Use modern audio capabilities
2. Spatial Audio: 3D positioned sounds
3. Audio Pooling: Reuse audio sources
4. Volume Control: Master, music, and SFX volumes
5. Performance-Aware: Limit concurrent sounds
6. Mobile-Friendly: Handle autoplay restrictions

Audio System Implementation

1. Audio Manager

// audio/AudioManager.ts
export interface AudioConfig {
  masterVolume?: number;
  musicVolume?: number;
  sfxVolume?: number;
  maxConcurrentSounds?: number;
}

export class AudioManager {
  private context: AudioContext;
  private masterGain: GainNode;
  private musicGain: GainNode;
  private sfxGain: GainNode;
  private sounds = new Map<string, AudioBuffer>();
  private activeSounds: AudioBufferSourceNode[] = [];
  private maxConcurrentSounds: number;
  private listener: AudioListener | null = null;

  constructor(config: AudioConfig = {}) {
    this.context = new AudioContext();

    // Create gain nodes
    this.masterGain = this.context.createGain();
    this.musicGain = this.context.createGain();
    this.sfxGain = this.context.createGain();

    // Connect gain hierarchy
    this.musicGain.connect(this.masterGain);
    this.sfxGain.connect(this.masterGain);
    this.masterGain.connect(this.context.destination);

    // Set volumes
    this.masterGain.gain.value = config.masterVolume ?? 1;
    this.musicGain.gain.value = config.musicVolume ?? 0.7;
    this.sfxGain.gain.value = config.sfxVolume ?? 1;

    this.maxConcurrentSounds = config.maxConcurrentSounds ?? 32;
  }

  async loadSound(name: string, url: string): Promise<void> {
    try {
      const response = await fetch(url);
      const arrayBuffer = await response.arrayBuffer();
      const audioBuffer = await this.context.decodeAudioData(arrayBuffer);
      this.sounds.set(name, audioBuffer);
    } catch (error) {
      console.error(`Failed to load sound: ${name}`, error);
    }
  }

  async loadSounds(sounds: Record<string, string>): Promise<void> {
    const promises = Object.entries(sounds).map(([name, url]) =>
      this.loadSound(name, url)
    );
    await Promise.all(promises);
  }

  playSound(
    name: string,
    options: {
      volume?: number;
      loop?: boolean;
      playbackRate?: number;
      destination?: GainNode;
    } = {}
  ): AudioBufferSourceNode | null {
    const buffer = this.sounds.get(name);
    if (!buffer) {
      console.warn(`Sound not found: ${name}`);
      return null;
    }

    // Limit concurrent sounds
    if (this.activeSounds.length >= this.maxConcurrentSounds) {
      this.stopOldestSound();
    }

    // Resume audio context (required after user interaction)
    if (this.context.state === 'suspended') {
      this.context.resume();
    }

    // Create source
    const source = this.context.createBufferSource();
    source.buffer = buffer;
    source.loop = options.loop ?? false;
    source.playbackRate.value = options.playbackRate ?? 1;

    // Create gain node for individual sound volume
    const gainNode = this.context.createGain();
    gainNode.gain.value = options.volume ?? 1;

    // Connect to destination (music or sfx)
    source.connect(gainNode);
    gainNode.connect(options.destination ?? this.sfxGain);

    // Track active sound
    this.activeSounds.push(source);

    source.onended = () => {
      const index = this.activeSounds.indexOf(source);
      if (index !== -1) {
        this.activeSounds.splice(index, 1);
      }
    };

    source.start(0);

    return source;
  }

  playSoundAt(
    name: string,
    position: Vector3,
    options: {
      volume?: number;
      loop?: boolean;
      refDistance?: number;
      maxDistance?: number;
      rolloffFactor?: number;
    } = {}
  ): AudioBufferSourceNode | null {
    const buffer = this.sounds.get(name);
    if (!buffer) {
      console.warn(`Sound not found: ${name}`);
      return null;
    }

    if (this.activeSounds.length >= this.maxConcurrentSounds) {
      this.stopOldestSound();
    }

    if (this.context.state === 'suspended') {
      this.context.resume();
    }

    // Create source
    const source = this.context.createBufferSource();
    source.buffer = buffer;
    source.loop = options.loop ?? false;

    // Create panner for 3D positioning
    const panner = this.context.createPanner();
    panner.panningModel = 'HRTF';
    panner.distanceModel = 'inverse';
    panner.refDistance = options.refDistance ?? 1;
    panner.maxDistance = options.maxDistance ?? 10000;
    panner.rolloffFactor = options.rolloffFactor ?? 1;
    panner.coneInnerAngle = 360;
    panner.coneOuterAngle = 0;
    panner.coneOuterGain = 0;

    // Set position
    panner.positionX.value = position.x;
    panner.positionY.value = position.y;
    panner.positionZ.value = position.z;

    // Create gain node
    const gainNode = this.context.createGain();
    gainNode.gain.value = options.volume ?? 1;

    // Connect: source -> panner -> gain -> destination
    source.connect(panner);
    panner.connect(gainNode);
    gainNode.connect(this.sfxGain);

    this.activeSounds.push(source);

    source.onended = () => {
      const index = this.activeSounds.indexOf(source);
      if (index !== -1) {
        this.activeSounds.splice(index, 1);
      }
    };

    source.start(0);

    return source;
  }

  stopSound(source: AudioBufferSourceNode): void {
    try {
      source.stop();
    } catch (error) {
      // Already stopped
    }
  }

  stopAllSounds(): void {
    for (const source of this.activeSounds) {
      this.stopSound(source);
    }
    this.activeSounds = [];
  }

  private stopOldestSound(): void {
    if (this.activeSounds.length > 0) {
      const oldest = this.activeSounds.shift()!;
      this.stopSound(oldest);
    }
  }

  setMasterVolume(volume: number): void {
    this.masterGain.gain.value = Math.max(0, Math.min(1, volume));
  }

  setMusicVolume(volume: number): void {
    this.musicGain.gain.value = Math.max(0, Math.min(1, volume));
  }

  setSFXVolume(volume: number): void {
    this.sfxGain.gain.value = Math.max(0, Math.min(1, volume));
  }

  getMasterVolume(): number {
    return this.masterGain.gain.value;
  }

  getMusicVolume(): number {
    return this.musicGain.gain.value;
  }

  getSFXVolume(): number {
    return this.sfxGain.gain.value;
  }

  setListener(position: Vector3, forward: Vector3, up: Vector3): void {
    if (!this.context.listener) return;

    this.context.listener.positionX.value = position.x;
    this.context.listener.positionY.value = position.y;
    this.context.listener.positionZ.value = position.z;

    this.context.listener.forwardX.value = forward.x;
    this.context.listener.forwardY.value = forward.y;
    this.context.listener.forwardZ.value = forward.z;

    this.context.listener.upX.value = up.x;
    this.context.listener.upY.value = up.y;
    this.context.listener.upZ.value = up.z;
  }

  dispose(): void {
    this.stopAllSounds();
    this.context.close();
  }
}