Web Audio API Basics for Games

Step 1: Create and Resume an AudioContext

The AudioContext is the central object that manages all audio operations. Create one when your game initializes. All browsers now enforce an autoplay policy that requires a user gesture (click, tap, or key press) before audio can play. This means your AudioContext starts in a "suspended" state and must be resumed after the player interacts with the page.

The standard pattern is to create the AudioContext at load time, then call context.resume() inside a click or keydown event handler. Many games handle this by showing a "Click to Start" screen. Once the context is resumed, it stays active for the rest of the session. You only need one AudioContext per game. Creating multiple contexts wastes resources and can cause audio glitches. Store the context as a global or singleton that your audio manager and all game systems reference.

The AudioContext also provides the high-resolution clock (context.currentTime) that drives all scheduling. This clock runs in seconds at audio sample rate precision and is independent of JavaScript's event loop. When you need to schedule audio events at exact times (starting a music transition at a bar boundary, triggering a sound effect synchronized with an animation frame), you use this clock, not setTimeout or requestAnimationFrame.

Step 2: Load and Decode Audio Files

Audio files need to be fetched over the network and decoded into a format the Web Audio API can play directly. The process has two stages: fetch the file as an ArrayBuffer using the Fetch API, then decode it into an AudioBuffer using context.decodeAudioData(). The AudioBuffer is a decoded, in-memory representation of the audio that can be played back instantly with no decoding delay.

Decoding is asynchronous and takes time, especially for longer files. Decode your audio during a loading screen or scene transition, not at the moment you need to play it. A good pattern is to have an asset loader that accepts a list of audio file URLs, fetches and decodes them all in parallel using Promise.all(), and stores the resulting AudioBuffers in a map keyed by sound name. Your game code then requests sounds by name from this map, knowing they are already decoded and ready for instant playback.

For memory management, keep AudioBuffers for sounds you are currently using and release references to sounds you are done with. A large game with hundreds of sound effects does not need them all decoded simultaneously. Load and decode the sounds for the current scene, and free the buffers from the previous scene when the player transitions. The browser's garbage collector will reclaim the memory once all references are released.

Step 3: Build the Audio Node Graph

The Web Audio API uses a node-based routing system. Audio flows from source nodes, through processing nodes, to the destination (speakers). The simplest possible graph is a source node connected directly to the destination. A practical game audio graph adds gain nodes for volume control, panner nodes for spatial positioning, and effect nodes for environmental processing.

A typical game audio setup has three main buses: a music bus, an SFX bus, and a dialogue bus. Each bus is a GainNode connected to the master output (another GainNode connected to context.destination). When you play music, you route it through the music bus. Sound effects route through the SFX bus. Dialogue routes through the dialogue bus. Each bus has independent volume control, letting the player adjust music, effects, and voice levels separately in the settings menu.

Create your bus structure when the AudioContext initializes and keep it for the game's lifetime. Individual sounds connect to their appropriate bus when they play and disconnect when they finish. The bus nodes are permanent; the source nodes are temporary. This separation keeps your graph clean and your code organized.

Step 4: Implement Sound Playback

To play a sound, create an AudioBufferSourceNode, set its buffer to the decoded AudioBuffer, connect it to the appropriate bus, and call start(). Each AudioBufferSourceNode can only be played once. After it finishes (or after you call stop()), it cannot be restarted. You create a new source node every time you play a sound. This is by design and is lightweight, source nodes are cheap to create.

For looping music, set the source node's loop property to true before starting playback. The loopStart and loopEnd properties (in seconds) let you define a precise loop region within the buffer. This is useful when your track has an intro that should play once before the looping section begins. Set loopStart to where the loop body begins and loopEnd to where it should jump back to loopStart.

For one-shot sound effects, create the source, connect it, call start(), and let it finish. The onended event fires when playback completes, which you can use to clean up references or trigger game logic. For sounds that need to stop early (an ambient loop that should end when the player leaves an area), call stop() on the source node. Stopped nodes cannot be restarted, so stopping a looping ambient sound means you will create a new source when the player re-enters the area.

Precise timing uses the start() method's optional when parameter, which accepts a time value from context.currentTime. Calling source.start(context.currentTime + 0.5) schedules the sound to start exactly 0.5 seconds from now. This is far more accurate than setTimeout and is essential for rhythmic or synchronized audio.

Step 5: Add Spatial Positioning

The PannerNode positions a sound source in 3D space. You set its positionX, positionY, and positionZ values to match the sound source's position in your game world. The AudioListener (accessed via context.listener) represents the player's ears and has its own position and orientation. The browser calculates the appropriate panning, volume attenuation, and filtering based on the relative positions of the source and listener.

Update the listener position every frame to match the camera or player character position. Update sound source positions whenever the emitting object moves. For a 2D game, you can ignore the Z axis and just use X for left-right panning. For 3D web games built with Babylon.js or Three.js, map the engine's coordinate system to the Web Audio coordinate system (they may use different axis conventions).

The PannerNode's distanceModel property controls how volume decreases with distance. "Linear" drops volume proportionally. "Inverse" drops quickly at close range and slowly at distance (more natural for most game sounds). "Exponential" drops off very quickly. Set the refDistance (distance at which volume starts decreasing), maxDistance (distance at which the sound is inaudible), and rolloffFactor to tune how your game's soundscape responds to player movement.

Step 6: Apply Real-Time Effects

Processing nodes transform audio as it flows through the graph. The BiquadFilterNode provides low-pass, high-pass, band-pass, and other standard filter types. A common game use is applying a low-pass filter to muffle sounds when the player is underwater or behind a wall, then removing the filter when they surface or enter line-of-sight. Automating the filter's frequency parameter over time creates smooth transitions.

The ConvolverNode applies convolution reverb using an impulse response buffer. Load a short recording of a room's acoustic response (many are available freely online), decode it as an AudioBuffer, and set it as the convolver's buffer. Route sounds through the convolver to simulate that room's acoustics. Different impulse responses for caves, hallways, outdoors, and chambers let you change the acoustic environment as the player moves through your game world.

The DynamicsCompressorNode prevents clipping when multiple loud sounds play simultaneously, which is common during combat or explosions. Place it on your master output bus to catch peaks that would otherwise distort. The default parameters work reasonably well for games, but adjusting the threshold and ratio can fine-tune how aggressively it compresses.