gagandeepgill/puzzle-game / .claude/skills/game-audio
game-audio
VerifiedSound 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 OfflineAudioContext plan for the native port. Use when adding or changing a sound, when a cue fires at the wrong moment or not at all, or when tuning how a drop sounds.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.9 KB |
SKILL.md
View on GitHub---
name: game-audio
description: "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 OfflineAudioContext plan for the native port. Use when adding or changing a sound, when a cue fires at the wrong moment or not at all, or when tuning how a drop sounds."
---
# Sound
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
```ts
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:
```ts
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |