Sound core — short sound effects that play on a phone
prompts/pkg/llms/sound-core.md on every deploy, so it
can't drift from what the platform actually does. Read it from your terminal any
time with npx vibes-diy skills.
Web Audio is a browser built-in: use window.AudioContext (with the window.webkitAudioContext
fallback) directly. Synthesize effects with an oscillator and a gain envelope; a sound effect needs
no audio file.
Unlock audio first, synchronously, in the gesture handler. iOS Safari plays sound only when it
directly results from a trusted pointerdown, touchend, click or keydown. Inside that handler,
before any other work: create or resume the AudioContext and start one real sound (a ~10ms
blip at gain ≈ 0.0001). An unlock that runs later — from a setTimeout, Promise.then, await,
requestAnimationFrame, a React state update's effect, or a game-loop tick — stays silent on iOS.
Once the context runs, sounds may start from anywhere, the game loop included. iOS suspends audio
after the app goes to the background or the phone locks, so the gate re-checks the context on
every gesture.
lib/sfx.js — the one module that touches audio
js// lib/sfx.js — plain module, no React, so no re-render rebuilds the context.
let audioCtx;
let master; // every effect plays through this gain; muting sets it to 0
let muted = false;
const LEVEL = 0.8;
// Call FIRST, synchronously, at the top of every pointerdown (and the Start button's handler).
export function unlockAudio() {
if (!audioCtx) {
audioCtx = new (window.AudioContext || window.webkitAudioContext)();
master = audioCtx.createGain();
master.gain.value = muted ? 0 : LEVEL;
master.connect(audioCtx.destination);
}
// Re-check every gesture: iOS suspends audio after backgrounding or a lock.
if (audioCtx.state !== "running") {
audioCtx.resume();
// One real, silent sound inside the gesture: the part a resume() alone misses on iOS.
const osc = audioCtx.createOscillator();
const gain = audioCtx.createGain();
gain.gain.value = 0.0001;
osc.connect(gain).connect(audioCtx.destination);
osc.start();
osc.stop(audioCtx.currentTime + 0.01);
}
return audioCtx;
}
export function setMuted(next) {
muted = next;
if (master) master.gain.setTargetAtTime(next ? 0 : LEVEL, audioCtx.currentTime, 0.02);
}
// One short effect: a pitch sweep with a fast fade, 80–150ms, never longer than the action.
export function blip({ from = 660, to = 990, ms = 90, type = "square", vol = 0.15 } = {}) {
if (!audioCtx || muted) return; // guard on the context alone, never on audioCtx.state
const t = audioCtx.currentTime;
const osc = audioCtx.createOscillator();
const gain = audioCtx.createGain();
osc.type = type;
osc.frequency.setValueAtTime(from, t);
osc.frequency.exponentialRampToValueAtTime(to, t + ms / 1000);
gain.gain.setValueAtTime(vol, t);
gain.gain.exponentialRampToValueAtTime(0.0001, t + ms / 1000);
osc.connect(gain).connect(master);
osc.start(t);
osc.stop(t + ms / 1000 + 0.02);
}
// The core actions, one sound each. Tune by parameter; keep the set this small.
export const sfx = {
hit: () => blip(),
score: () => blip({ from: 523, to: 1047, ms: 120, type: "triangle" }),
jump: () => blip({ from: 300, to: 600, ms: 100, type: "sine", vol: 0.2 }),
miss: () => blip({ from: 220, to: 110, ms: 140, type: "triangle", vol: 0.2 }),
lose: () => blip({ from: 300, to: 60, ms: 400, type: "sawtooth", vol: 0.12 }),
win: () => [523, 659, 784].forEach((f, i) => setTimeout(() => blip({ from: f, to: f * 1.01, ms: 110, type: "triangle" }), i * 90)),
};
Why blip checks the context and not its state. resume() is asynchronous, so in the very tap
that unlocks, audioCtx.state still reads "suspended" when that tap's effect plays. A sound started
on a suspended context plays the moment it resumes. A state !== "running" early return drops the
first tap's sound and the first hit after the app comes back from the background.
Wire it to the gesture
jsimport { unlockAudio, sfx } from "./lib/sfx.js";
function onPointerDown(e) {
unlockAudio(); // first line of the handler, every gesture
// ...then the tap, swipe or hold logic, which may call sfx.jump() right here
}
// In the game loop, after the context runs: sfx.hit() on a hit, sfx.score() on a point,
// sfx.miss() on a miss, sfx.lose() at game over, sfx.win() on a cleared round.
✗ Too late on iOS: useEffect(() => new AudioContext(), []) on mount, a context created in a state
update's effect, el.onclick = () => requestAnimationFrame(() => audioCtx.resume()), or any
setTimeout, await or .then before the first sound.
A mute toggle beside the menu
Every app with sound effects carries one mute toggle, a small icon button next to the menu button, that silences the master gain at once:
jsximport { IconButton } from "@vibes.diy/ui";
import { setMuted } from "./lib/sfx.js";
const [muted, setMutedState] = React.useState(false);
<IconButton
icon={muted ? "🔇" : "🔊"}
label={muted ? "Turn sound on" : "Mute sound"}
onClick={() => {
setMuted(!muted);
setMutedState(!muted);
}}
/>;
Restraint — sound belongs on the core actions
- Sound plays on the core actions: a hit lands, a point scores, a shot misses, the player jumps, a round is won or lost. One or two of them carry most of the feel; failure gets at most one distinct sound.
- Not on spawns or ticks: an enemy appearing, a timer counting, every frame, every hover, keystroke or list render stays silent. No ambient loop or background music unless the person asks for it.
- Never autoplay on load; the first sound follows a gesture, through
unlockAudio(). - Menus, settings and leaderboards stay quiet.