game-audio
Sound in the arcade: the synthesised blip vocabulary and what each cue means, why the AudioContext is built lazily, the mute preference, the per-frame cap that stops a cascade becoming noise, and the
SKILL.md.claude/skills/game-audio/SKILL.md
GitHubSound
Synthesised, never sampled. The arcade installs and runs offline, and a handful
of oscillators cost nothing to ship where audio files would dominate the
bundle. Everything lives in src/ui/audio.ts, about 90 lines.
The primitive
blip(freq, dur = 0.06, type: OscillatorType = 'square', gain = 0.05)
One oscillator into one gain node, with an exponential ramp to 0.0001
rather than a hard stop. That ramp is not decoration: stopping an oscillator at
full amplitude clicks, and the click is louder than the note. Never replace it
with setValueAtTime(0, …).
Every call is wrapped in try/catch. A device that refuses to make sound must not stop the game.
The vocabulary
sfx in audio.ts. Each cue has one job; adding a sound means asking what it
tells the player that nothing else does.
| Cue | Sound | Means |
|---|---|---|
trigger(n) |
rising square, 300 + min(n,22)*45 Hz |
a part fired. Pitch climbs with the count, so a long cascade audibly builds |
split |
880 Hz triangle | a Prism cloned the marble |
spring |
660 Hz sine | a Spring bounced it back up |
skid |
180 Hz sawtooth | an Anvil knocked it sideways |
seized |
120 Hz sawtooth, long | the marble was confiscated |
bank(value) |
784 Hz, or 1046 above 80 | the payout. The only cue that changes with the number |
place / blueprint |
short square / triangle | UI confirmation, not simulation |
roundWon |
bass note plus a 523/659/784 arpeggio | a quota was crossed |
runLost |
110 Hz sawtooth, long | the run ended |
roundWon is deliberately expensive and deliberately rare. Peggle gates its
whole musical climax to the last orange peg; spending that per part is exactly
what stops it meaning anything. Fire it on a quota crossing and nowhere else.
The context is lazy, and that is load-bearing
context() constructs the AudioContext on the first blip, not at module
load. Browsers refuse to start one outside a user gesture, so constructing it
eagerly leaves a permanently suspended context and silence for the entire
session. It also calls resume() when suspended, which is safe because the
first blip always follows a tap. That is the iOS unlock, and it is already
done. Do not add a second one.
context() returns null when muted, so mute costs nothing rather than
playing into a zeroed gain node.
Mute
isMuted() / setMuted(), persisted at payload.muted.v1, read once at
module load inside a try/catch because blocked site data must not throw. The
toggle is in the settings sheet with an aria-pressed and a soundOn /
soundOff icon, so the state is in the accessible name and not only the glyph.
Density is capped, at one place
usePayloadRun.ts fires the simulation cues as it walks the event log. One
line does the rationing:
if (fired <= 2) sfx.trigger(triggers);
Eight marbles landing on parts in the same frame is a burst of noise, not information. Two per frame is the cap. If a new cue can fire many times in one frame, it needs the same treatment.
What skipping does to sound, measured
Animation and no-animation are the same loop; only the sleeps differ. paint()
returns immediately under prefers-reduced-motion or after Skip, but the
sfx calls are not gated by it, so the same sounds still fire, compressed.
Measured on the live build: a two-sound drop spanned 668ms played normally and 143ms when skipped. A loaded column computed in Node produces five sounding events, not twenty, and the per-frame cap holds. So it is a burst rather than a wall on the boards that could be constructed.
What is unmeasured is a late-round board with three marbles and a full multiplier stack. If someone reports that skipping is loud, that is the case to build first. Tracked rather than guessed at.
Note that reduced motion is a request to lower sensory load. Sound is not motion and is not covered by that media query, so muting on it would be wrong. Compressing the same cues into a fifth of the time is still worth watching.
The native port
docs/PLATFORM.md records the plan and the constraint: React Native cannot
synthesise audio, and expo-audio plays files only. The route is to pre-render
each cue offline with OfflineAudioContext and ship about eight assets. That
is the only reason the vocabulary above is worth keeping small.
Where it is not
public/payload.html has its own copy of blip from before the port. That
file is the reference the parity tests diff against, not the game. Changing
sound there changes nothing a player hears.