web-audio（网络音频）

Web Audio Browser Patterns

Production-tested patterns for fault-tolerant browser audio with zero-lag rapid-fire support.

Related Skills

• javascript: Async patterns, cleanup in disconnectedCallback, singleton patterns
• web-components: Integrating audio with custom elements
• ux-feedback-patterns: Audio as part of user feedback
• ux-accessibility: Respecting prefers-reduced-motion for audio

Rule 1: AudioContext is Expensive — Create Once

AudioContext creation is expensive and browsers limit the number of contexts. Create one per page, reuse forever.

// ✅ Singleton AudioContext
class AudioService {
  static #audioContext = null;

  static getContext() {
    if (!this.#audioContext) {
      this.#audioContext = new (window.AudioContext || window.webkitAudioContext)();
    }
    return this.#audioContext;
  }

  // Resume context on user interaction (required by browsers)
  static async ensureResumed() {
    const ctx = this.getContext();
    if (ctx.state === 'suspended') {
      await ctx.resume();
    }
    return ctx;
  }
}

// ❌ Never create context per sound
function badPlaySound() {
  const ctx = new AudioContext(); // Creates new context every time!
  // ...
}

Why: Browsers limit AudioContext instances. Creating contexts is slow and triggers garbage collection.

Rule 2: Preload All Sounds at Startup

Load audio files once at startup, play instantly during gameplay. Never load audio on hot paths.

// ✅ Preload into cache
class AudioService {
  static #sounds = new Map();
  static #loaded = false;

  static async preload() {
    if (this.#loaded) return;

    const soundFiles = {
      sparkle: '/audio/sfx/sparkle.mp3',
      success: '/audio/sfx/success.mp3',
      phaseComplete: '/audio/sfx/phase-complete.mp3',
      wordComplete: '/audio/sfx/word-complete.mp3',
      milestone: '/audio/sfx/milestone.mp3',
      click: '/audio/sfx/click.mp3',
      error: '/audio/sfx/error.mp3'
    };

    const loadPromises = Object.entries(soundFiles).map(async ([name, path]) => {
      try {
        const audio = new Audio(path);
        audio.preload = 'auto';
        // Wait for audio to be loaded enough to play
        await new Promise((resolve, reject) => {
          audio.addEventListener('canplaythrough', resolve, { once: true });
          audio.addEventListener('error', reject, { once: true });
          audio.load();
        });
        this.#sounds.set(name, audio);
      } catch (error) {
        console.warn(`Failed to load sound: ${name}`, error);
        // Don't throw - audio is non-critical
      }
    });

    await Promise.allSettled(loadPromises);
    this.#loaded = true;
  }

  static getSound(name) {
    return this.#sounds.get(name);
  }
}

Why: Network requests during gameplay cause lag. Preloading ensures instant playback.

Rule 3: cloneNode() for Rapid-Fire Sounds

For sounds that trigger rapidly (hover, clicks, typing), use cloneNode() to create instant playable copies without network requests.

// ✅ Clone for overlapping/rapid plays
static playHoverSound() {
  const cached = this.#sounds.get('hover');
  if (!cached) return;

  // Cancel currently playing instance
  if (this.#currentHover && !this.#currentHover.paused) {
    this.#currentHover.pause();
    this.#currentHover.currentTime = 0;
  }

  // Clone creates instant playable copy (no network request)
  this.#currentHover = cached.cloneNode();
  this.#currentHover.volume = 0.3;

  return this.#currentHover.play().catch(() => {});
}

// ✅ Generic rapid-fire pattern
static playRapidFire(name, volume = 0.5) {
  const cached = this.#sounds.get(name);
  if (!cached) return Promise.resolve();

  const clone = cached.cloneNode();
  clone.volume = volume;
  return clone.play().catch(() => {});
}

// ❌ Never create new Audio() on hot paths
function badRapidFire(path) {
  const audio = new Audio(path); // Network request every time!
  return audio.play();
}

Why: new Audio(path) triggers a network request. cloneNode() creates an instant copy from the cached audio buffer.

Rule 4: Cancel Before Play — Prevent Audio Pile-Up

For sounds that shouldn't overlap (UI feedback, voice), cancel the previous instance before starting a new one.

// ✅ Track and cancel current instance
class AudioService {
  static #currentVoice = null;

  static playVoiceFeedback(text) {
    // Cancel any currently playing voice
    if (this.#currentVoice && !this.#currentVoice.paused) {
      this.#currentVoice.pause();
      this.#currentVoice.currentTime = 0;
    }

    this.#currentVoice = this.#sounds.get('voice')?.cloneNode();
    if (!this.#currentVoice) return;

    this.#currentVoice.volume = 0.5;
    return this.#currentVoice.play().catch(() => {});
  }
}

// ✅ For overlapping sounds (celebrations), don't cancel - let them layer
static playCelebrationSound() {
  const cached = this.#sounds.get('celebration');
  if (!cached) return;

  // Clone without canceling previous - sounds can overlap
  const clone = cached.cloneNode();
  clone.volume = 0.7;
  return clone.play().catch(() => {});
}

Why: Without cancellation, rapid triggers create audio pile-up where dozens of sounds play simultaneously.

Rule 5: Silent.catch() on Every.play()

Browser autoplay policies block audio until user interaction. Always catch and ignore these errors silently.

// ✅ Silent catch - ALWAYS
audio.play().catch(() => {});

// ✅ With optional logging for development
audio.play().catch(e => {
  if (e.name !== 'NotAllowedError') {
    console.warn('Audio playback failed:', e);
  }
});

// ❌ Never leave .play() uncaught
audio.play(); // Throws on autoplay block!

// ❌ Don't let autoplay errors bubble up
async function badPlaySound() {
  await audio.play(); // Throws to caller on autoplay block
}

Why: Browsers block autoplay until user interaction. Uncaught promise rejections crash the application or flood the console.

Rule 6: Window Globals for Hot-Reload Survival

For background music or persistent audio state, store singletons on window to survive module hot-reload during development.

// ✅ Singleton survives hot-reload
if (typeof window.__AudioServiceClass === 'undefined') {
  window.__AudioServiceClass = class AudioService {
    #enabled = true;
    #volume = 0.5;
    #sounds = new Map();

    constructor() {
      // Restore state from previous instance
      this.#enabled = window.__audioEnabled ?? true;
      this.#volume = window.__audioVolume ?? 0.5;
    }

    setEnabled(enabled) {
      this.#enabled = enabled;
      window.__audioEnabled = enabled; // Persist across hot-reload
    }

    setVolume(volume) {
      this.#volume = volume;
      window.__audioVolume = volume;
    }
  };
}

if (!window.__audioServiceInstance) {
  window.__audioServiceInstance = new window.__AudioServiceClass();
}

export default window.__audioServiceInstance;

Why: During development, module hot-reload destroys and recreates module scope. Window globals persist, preventing audio restart.

Rule 7: Volume Hierarchy by Sound Type

Different sound types serve different purposes and need different volume levels to feel balanced.

// ✅ Volume constants
const VOLUMES = {
  MICRO: 0.25,      // sparkle, click, hover
  FEEDBACK: 0.4,    // success, error
  CELEBRATION: 0.6, // phase complete
  MAJOR: 0.75,      // word complete, milestone
  MUSIC: 0.2        // background
};

static playSparkle() {
  return this.playRapidFire('sparkle', VOLUMES.MICRO);
}

static playSuccess() {
  return this.play('success', VOLUMES.FEEDBACK);
}

static playMilestone() {
  return this.play('milestone', VOLUMES.MAJOR);
}

Why: Balanced audio creates professional feel. Loud frequent sounds cause fatigue; quiet celebrations feel anticlimactic.

Rule 8: Respect prefers-reduced-motion for Audio

Users who prefer reduced motion often want reduced audio stimulation too. Check the preference and adjust.

// ✅ Check preference and adjust
class AudioService {
  static #enabled = true;

  static {
    // Disable by default if user prefers reduced motion
    const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
    this.#enabled = !mediaQuery.matches;

    // Listen for changes
    mediaQuery.addEventListener('change', (e) => {
      this.#enabled = !e.matches;
    });
  }

  static play(name, volume = 0.5) {
    if (!this.#enabled) return Promise.resolve();

    const sound = this.#sounds.get(name);
    if (!sound) return Promise.resolve();

    const clone = sound.cloneNode();
    clone.volume = volume;
    return clone.play().catch(() => {});
  }

  static setEnabled(enabled) {
    this.#enabled = enabled;
  }

  static get enabled() {
    return this.#enabled;
  }
}

Why: Accessibility includes audio. Users with vestibular disorders or sensory sensitivities benefit from reduced audio.

Rule 9: Web Audio API for Effects (Reverb, Ducking)

Use Web Audio API for advanced effects like reverb, ducking, and filtering. Create nodes once, reuse forever.

Sidechain Ducking (Lower Music When SFX Play)

// ✅ Duck background music when sound effects play
class AudioService {
  static #musicGain = null;
  static #audioContext = null;

  static initMusicWithDucking(musicElement) {
    this.#audioContext = this.getContext();

    // Create source from music element
    const source = this.#audioContext.createMediaElementSource(musicElement);

    // Create gain node for ducking
    this.#musicGain = this.#audioContext.createGain();
    this.#musicGain.gain.value = 1.0;

    // Connect: source → gain → destination
    source.connect(this.#musicGain);
    this.#musicGain.connect(this.#audioContext.destination);
  }

  static duckMusicFor(durationMs = 1500) {
    if (!this.#musicGain || !this.#audioContext) return;

    const now = this.#audioContext.currentTime;

    // Quick duck down
    this.#musicGain.gain.setValueAtTime(this.#musicGain.gain.value, now);
    this.#musicGain.gain.linearRampToValueAtTime(0.1, now + 0.1);

    // Slow release back up
    setTimeout(() => {
      const releaseTime = this.#audioContext.currentTime;
      this.#musicGain.gain.linearRampToValueAtTime(1.0, releaseTime + 0.5);
    }, durationMs);
  }

  // Call duck when playing important sounds
  static playMilestone() {
    this.duckMusicFor(2000);
    return this.play('milestone', VOLUMES.MAJOR);
  }
}

Hall Reverb Effect

// ✅ Apply reverb effect
static applyHallReverb(duration = 2.0) {
  const ctx = this.getContext();

  // Create convolver for reverb (create once, reuse)
  if (!this.#convolver) {
    this.#convolver = ctx.createConvolver();
    this.#wetGain = ctx.createGain();
    this.#dryGain = ctx.createGain();

    // Generate impulse response
    const sampleRate = ctx.sampleRate;
    const length = sampleRate * duration;
    const impulse = ctx.createBuffer(2, length, sampleRate);

    for (let ch = 0; ch < 2; ch++) {
      const data = impulse.getChannelData(ch);
      for (let i = 0; i < length; i++) {
        // Exponential decay with noise
        data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / length, 2);
      }
    }
    this.#convolver.buffer = impulse;

    // Initial dry/wet mix
    this.#dryGain.gain.value = 1.0;
    this.#wetGain.gain.value = 0.0;
  }

  return { convolver: this.#convolver, wetGain: this.#wetGain, dryGain: this.#dryGain };
}

Why: Web Audio API enables professional audio effects without external libraries. Create nodes once to avoid performance issues.

Rule 10: Text-to-Speech Integration

Use Web Speech API for reading text aloud, with user preference persistence.

// ✅ TTS with preference check
class TTSService {
  static #enabled = false;

  static {
    this.#enabled = localStorage.getItem('ttsEnabled') === 'true';
  }

  static speak(text, options = {}) {
    if (!this.#enabled) return;
    if (!('speechSynthesis' in window)) return;

    const utterance = new SpeechSynthesisUtterance(text);
    utterance.rate = options.rate ?? 0.9;   // Slightly slower for kids
    utterance.pitch = options.pitch ?? 1.0;
    utterance.volume = options.volume ?? 0.8;

    // Cancel any current speech
    speechSynthesis.cancel();
    speechSynthesis.speak(utterance);
  }

  static stop() {
    speechSynthesis.cancel();
  }

  static setEnabled(enabled) {
    this.#enabled = enabled;
    localStorage.setItem('ttsEnabled', String(enabled));
  }

  static get enabled() {
    return this.#enabled;
  }

  static get supported() {
    return 'speechSynthesis' in window;
  }
}

Why: TTS helps emergent readers and improves accessibility. User preference should persist across sessions.

Web Audio Node Routing Reference

Simple Playback:
  Source ──────────────────────────────► Destination

With Volume Control:
  Source ──► GainNode ─────────────────► Destination

Wet/Dry Effects (Reverb):
  Source ─┬─► DryGain ─────────────────┬► Destination
          └─► Effect ──► WetGain ──────┘

Sidechain Ducking:
  Music ──► MusicGain ─────────────────► Destination
  SFX ────► SFXGain ───────────────────► Destination
            (MusicGain.gain reduced when SFX plays)

Common Web Audio Nodes

Complete AudioService Implementation

/**
 * AudioService - Centralized audio management
 *
 * Skills applied:
 * - web-audio: All 10 rules
 * - javascript: Singleton, cleanup, error handling
 * - ux-accessibility: prefers-reduced-motion
 */
class AudioService {
  static #sounds = new Map();
  static #enabled = true;
  static #volume = 0.5;
  static #currentByCategory = new Map();
  static #audioContext = null;
  static #loaded = false;

  // Volume hierarchy
  static VOLUMES = {
    MICRO: 0.25,
    FEEDBACK: 0.4,
    CELEBRATION: 0.6,
    MAJOR: 0.75,
    MUSIC: 0.2
  };

  static {
    // Respect reduced motion preference
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
    this.#enabled = !mq.matches;
    mq.addEventListener('change', (e) => { this.#enabled = !e.matches; });
  }

  static async preload() {
    if (this.#loaded) return;

    const files = {
      sparkle: '/audio/sfx/sparkle.mp3',
      success: '/audio/sfx/success.mp3',
      phaseComplete: '/audio/sfx/phase-complete.mp3',
      wordComplete: '/audio/sfx/word-complete.mp3',
      milestone: '/audio/sfx/milestone.mp3',
      click: '/audio/sfx/click.mp3',
      error: '/audio/sfx/error.mp3'
    };

    await Promise.allSettled(
      Object.entries(files).map(async ([name, path]) => {
        try {
          const audio = new Audio(path);
          audio.preload = 'auto';
          this.#sounds.set(name, audio);
        } catch (e) {
          console.warn(`Audio load failed: ${name}`, e);
        }
      })
    );

    this.#loaded = true;
  }

  static play(name, volume = 0.5, category = null) {
    if (!this.#enabled) return Promise.resolve();

    const cached = this.#sounds.get(name);
    if (!cached) return Promise.resolve();

    // Cancel previous in same category
    if (category) {
      const prev = this.#currentByCategory.get(category);
      if (prev && !prev.paused) {
        prev.pause();
        prev.currentTime = 0;
      }
    }

    const clone = cached.cloneNode();
    clone.volume = Math.min(1, volume * this.#volume);

    if (category) {
      this.#currentByCategory.set(category, clone);
    }

    return clone.play().catch(() => {});
  }

  // Convenience methods
  static playSparkle() { return this.play('sparkle', this.VOLUMES.MICRO); }
  static playSuccess() { return this.play('success', this.VOLUMES.FEEDBACK, 'feedback'); }
  static playError() { return this.play('error', this.VOLUMES.FEEDBACK, 'feedback'); }
  static playPhaseComplete() { return this.play('phaseComplete', this.VOLUMES.CELEBRATION); }
  static playWordComplete() { return this.play('wordComplete', this.VOLUMES.MAJOR); }
  static playMilestone() { return this.play('milestone', this.VOLUMES.MAJOR); }
  static playClick() { return this.play('click', this.VOLUMES.MICRO, 'ui'); }

  static setEnabled(enabled) { this.#enabled = enabled; }
  static setVolume(v) { this.#volume = Math.max(0, Math.min(1, v)); }
  static get enabled() { return this.#enabled; }
  static get volume() { return this.#volume; }
}

export { AudioService };
export const audioService = AudioService;

Checklist

• AudioContext created once per page
• All sounds preloaded at startup
• cloneNode() used for rapid-fire sounds
• Previous sound canceled before playing (where appropriate)
• Silent .catch(() => {}) on every .play()
• Window globals for hot-reload survival (if needed)
• Volume hierarchy applied by sound type
• prefers-reduced-motion respected
• Web Audio nodes created once, reused
• TTS preference persisted to localStorage