Audio Overview

The audio system in Web Engine is built on the Web Audio API, providing professional-grade 3D spatial audio, advanced channel routing, and zero-GC voice pooling for optimal performance.

Audio Features#

Audio Architecture#

Web Engine's audio system consists of several key components working together:

SoundManager#

The SoundManager handles one-shot sound effects with a fixed 64-voice pool. It provides:

• Zero-GC voice pooling for predictable performance
• Priority-based voice stealing when pool is full
• 3D spatial audio with HRTF panning
• Automatic spatial culling beyond max distance
• Fade in/out support for smooth transitions

AudioSystem#

The AudioSystem manages AudioSource components for persistent, looping sounds. It integrates with Three.js Audio for positional audio and handles:

• AudioSource entity lifecycle and playback
• Spatial positioning synchronized with entity transforms
• Audio LOD (Level of Detail) based on distance
• Channel routing and mixer integration
• Automatic cleanup of finished sounds

AudioMixer#

The AudioMixer provides centralized volume and mute control across all audio sources:

• Four channels: Master, SFX, Music, Voice
• Per-channel volume and mute controls
• Rate-limited updates to prevent excessive API calls
• Synchronized state across SoundManager and AudioSystem

Audio Context Management#

Web Engine creates a single global AudioContext that's shared across the entire audio system. The context is automatically resumed on user interaction to comply with browser autoplay policies.

// The audio context is initialized automatically
// when you play your first sound
 
import { SoundManager } from '@web-engine-dev/core';
 
const soundManager = SoundManager.getInstance();
soundManager.init(); // Creates and configures AudioContext
 
// Access the context if needed
const ctx = soundManager.getContext();
console.log('Sample rate:', ctx.sampleRate);
console.log('State:', ctx.state); // 'running', 'suspended', or 'closed'

Supported Audio Formats#

Web Engine supports all audio formats that the Web Audio API can decode:

• MP3 — Best compatibility, good compression. Recommended for music.
• OGG/Vorbis — Free format, excellent compression. Great for sound effects.
• WAV — Uncompressed, highest quality. Large file size.
• AAC/M4A — Good quality and compression. Widely supported.
• WebM — Modern format with excellent compression.

Quick Start#

To add audio to your game:

1. Import an audio file into your project's Assets panel.
2. Add an AudioSource component to an entity.
3. Assign the audio asset to the Asset ID field.
4. Configure volume, pitch, and loop settings.
5. Check Playing to start playback.
6. For 3D audio, enable Spatial and adjust distance settings.

Voice Pooling System#

For maximum performance, one-shot sounds use a pre-allocated pool of 64 voices. When the pool is full, the system uses priority-based voice stealing:

1. Higher priority sounds (0-255) are less likely to be stolen
2. Among equal priority, quieter sounds are stolen first
3. Spatial culling automatically stops sounds beyond max distance
4. Fade out on stop prevents audio pops and clicks

// Play a high-priority sound effect
const handle = soundManager.play(explosionAssetId, {
  volume: 0.8,
  spatial: true,
  priority: 200, // High priority - won't be stolen easily
  fadeIn: 0.05,  // 50ms fade in
  fadeOut: 0.2,  // 200ms fade out on stop
});
 
// Stop with fade out
soundManager.stop(handle); // Uses configured fadeOut duration
soundManager.stop(handle, true); // Immediate stop, no fade

Performance Optimization#

The audio system is designed for zero-GC performance in the hot path:

• Voice Pool — Pre-allocated 64 voices, no runtime allocation
• Spatial Culling — Automatically stops sounds beyond 1.5× max distance
• Audio LOD — Reduces quality/volume for distant sounds
• Rate Limiting — Prevents excessive WebAudio API calls
• Dirty Flags — Only updates when values change
• Typed Arrays — Pre-allocated buffers for zero-GC calculations