Performance Notes

• Take your time to do this thoroughly

• Quality is more important than speed

• Do not skip validation steps

Add Audio

Add procedural music and sound effects to an existing game. BGM uses a Web Audio API step sequencer for looping patterns. SFX use the Web Audio API directly for true one-shot playback. No audio files or npm packages needed — everything is synthesized in the browser.

Instructions

Analyze the game at $ARGUMENTS (or the current directory if no path given).

First, load the game-audio skill to get the full Web Audio patterns and integration guide.

Step 1: Audit

• Read src/core/EventBus.js to see what game events exist (flap, score, death, etc.)

• Read all scene files to understand the game flow (gameplay, game over)

• Identify what music and SFX would fit the game's genre and mood

Step 2: Plan

Present a table of planned audio:

Event / Scene

Audio Type

Style

Description

GameScene

BGM

Chiptune

Upbeat square wave melody + bass + drums

GameOverScene

BGM

Somber

Slow descending melody

Player action

SFX

Retro

Quick pitch sweep

Score

SFX

Retro

Two-tone ding

Death

SFX

Retro

Descending crushed notes

Explain in plain English: "Background music will automatically loop during each scene. Sound effects will play when you do things like jump, score, or die. The first time you click/tap, the audio system will activate (browsers require a user interaction before playing sound)."

Step 3: Implement

• Create src/audio/AudioManager.js — AudioContext init, master gain node, BGM sequencer play/stop

• Create src/audio/AudioBridge.js — wires EventBus events to AudioManager for BGM, calls SFX functions directly

• Create src/audio/music.js with BGM patterns for each scene (Web Audio step sequencer — note arrays that loop continuously)

• Create src/audio/sfx.js with SFX for each event (Web Audio API — OscillatorNode + GainNode + BiquadFilterNode for true one-shot playback)

• Add audio events to EventBus.js if not present (AUDIO_INIT, MUSIC_GAMEPLAY, MUSIC_GAMEOVER, MUSIC_STOP, AUDIO_TOGGLE_MUTE)

• Wire initAudioBridge() in main.js

• Emit AUDIO_INIT on first user interaction (game starts immediately, no menu)

• Emit music events at scene transitions and SFX events at game actions

• Add mute toggle — AUDIO_TOGGLE_MUTE event, UI button, M key shortcut

Step 4: Verify

• Run npm run build to confirm no errors

• List all files created/modified

• Remind the user: "Click/tap once to activate audio, then you'll hear the music"

Example Usage

Full audio pass

/add-audio examples/flappy-bird

Result: Creates src/audio/AudioManager.js, music.js (gameplay + game-over BGM patterns), sfx.js (flap, score, death, button SFX) → wires via AudioBridge → mute toggle on M key. First click activates audio.

Troubleshooting

No sound plays

Cause: AudioContext not resumed after user interaction (browser autoplay policy).

Fix: Ensure AudioContext.resume() is called on first user input (click/tap/keydown). Check for AUDIO_INIT event wiring.

Audio causes lag spikes

Cause: Creating new OscillatorNodes every frame.

Fix: SFX should be one-shot (create, connect, start, stop). BGM uses a single looping sequencer. Never create nodes in update().

Next Step

Tell the user:

Your game now has music and sound effects! Next, run /game-creator:qa-game to add automated tests that verify your game boots correctly, scenes transition properly, scoring works, and visuals haven't broken.

Pipeline progress: /viral-game → /design-game → /add-audio → /qa-game → /review-game

(This is the /viral-game one-shot pipeline — not the /make-game multi-session, milestone-driven workflow.)