How to Add Sound Effects to JavaScript Games

Step 1: Create the AudioContext and Unlock on User Interaction

Browsers require a user gesture (click, tap, keypress) before audio can play. Create the AudioContext early, but resume it inside your game's first interaction handler.

The AudioContext starts in a "suspended" state on most browsers. Calling ctx.resume() transitions it to "running," and from that point forward all audio plays normally. Many games handle this with a "Click to Start" screen that doubles as the audio unlock trigger. Once resumed, the context stays running for the rest of the session.

A robust approach is to add a one-time click handler to the document that resumes the context and removes itself. This way, no matter where the user first interacts, the audio system activates. You can also retry the resume on every subsequent user gesture until the context state confirms "running," which handles edge cases on iOS Safari where a single resume call occasionally fails.

Step 2: Build a Sound Loading System

Load all your sound effect files during the game's loading screen. For each file, fetch it as an ArrayBuffer, decode it into an AudioBuffer, and store it in a map keyed by a short name like "jump," "coin," or "explosion."

The loading function should accept an array of sound definitions (name and URL pairs) and return a Promise that resolves when all sounds are decoded. Use Promise.all() to parallelize the fetches. A typical indie web game has 20-50 sound effects totaling 1-5MB compressed, which loads in under a second on a decent connection.

Error handling matters here. If a sound file fails to load (404, network error, corrupted file), your game should continue without it rather than crashing. Log the error, store null for that sound's buffer, and have your play function silently skip null buffers. Players will notice missing audio, but a working game without one sound effect is better than a game that refuses to start.

Consider organizing sounds into groups that load at different times. Essential sounds (UI clicks, core gameplay) load during the initial loading screen. Level-specific sounds (environment ambience, enemy types) load during level transitions. This keeps the initial load time short while still supporting large sound libraries.

Step 3: Create a Gain Node Routing Structure

Before playing any sounds, set up the gain node hierarchy that gives you mix control. Create a master GainNode connected to the AudioContext destination, then create separate GainNodes for sound effects, music, and UI sounds, each connected to the master.

This three-tier structure maps directly to the volume sliders players expect in a settings menu: Master Volume, Music Volume, and SFX Volume. Each category gain node controls the volume of everything connected to it, and the master gain applies on top. Setting the SFX gain to 0.5 and the master to 0.8 results in sound effects playing at 40% volume (0.5 * 0.8).

Store the gain nodes in a central audio manager object alongside the AudioContext and the loaded buffers map. This audio manager becomes the single point of access for all audio operations in your game. It initializes during startup, loads sounds, and exposes a simple play(name) method that the rest of your game code calls.

Step 4: Write a Play Function with Variation Support

The core play function creates an AudioBufferSourceNode, assigns the requested buffer, connects it to the SFX gain node, and starts playback. This takes about five lines of code for the basic version.

The production version adds variation. Hearing the exact same sound hundreds of times causes listener fatigue. Two techniques combat this: multiple samples and pitch randomization. For multiple samples, store 3-5 variations of each common sound (jump_1.mp3 through jump_5.mp3) and select randomly on each play. For pitch randomization, set the source node's playbackRate.value to a random value between 0.9 and 1.1, which subtly shifts the pitch without sounding obviously modified.

Volume randomization adds further variation. Multiply the output gain by a random factor between 0.8 and 1.0 so each playback is slightly different in loudness. Combined with pitch variation, even a single source file sounds organic over hundreds of repetitions.

The play function should return a reference object that allows the caller to stop the sound early if needed. Store the source node and its associated gain node in this reference. For fire-and-forget sounds like coin pickups, the caller ignores the reference. For looping sounds like engine hum, the caller keeps it and calls stop when the engine turns off.

Step 5: Add Priority and Polyphony Limits

When 30 enemies fire simultaneously, 30 gunshot sounds trigger at once. On desktop, this is fine. On mobile, it can cause audio glitches and performance issues. A priority and polyphony system prevents this.

Assign each sound type a priority level: critical (player damage, game over), high (weapon fire, explosions), medium (enemy sounds, pickups), low (ambient detail, footsteps). Track the count of currently playing sounds. When a new sound triggers and the active count exceeds your limit (16-24 is typical for mobile, 32-64 for desktop), compare the new sound's priority against active sounds and skip it if lower-priority sounds need the slot.

Track active sounds by listening for the source node's ended event, which fires when the sound finishes playing. Decrement your active count in the handler. For sounds stopped early via stop(), the ended event still fires, so your tracking stays accurate.

Per-sound instance limits are also valuable. Even if total polyphony allows it, hearing 15 simultaneous copies of the same footstep sound is not useful. Limit individual sound types to 3-5 simultaneous instances and silently drop extras.

Step 6: Wire Sound Triggers to Game Events

The final step connects your audio system to actual gameplay. In your game's event system or directly in gameplay code, call the audio manager's play function when events occur.

Common trigger points: player jump (in the jump action handler), projectile fire (in the weapon system), item pickup (in the collision handler), enemy death (in the health system), UI button press (in the UI event handlers), level complete (in the state machine transition), damage taken (in the health system with pitch variation based on damage amount).

Timing is important. Play the sound at the moment the action occurs, not when the animation starts or finishes. A jump sound should play on the frame the character leaves the ground, not at the apex or landing. An explosion should play when the projectile hits, not when the explosion animation starts rendering. Misaligned audio timing is one of the most common mistakes in game audio and it makes the entire experience feel sluggish.

For continuous sounds like footsteps, use a timer or distance counter rather than triggering on every frame. Play a footstep sound every N pixels of movement or every M milliseconds while the character is walking. Adjust the interval based on movement speed so running footsteps are faster than walking footsteps.