vibes.diy/docs Make an app → Discord
creator docs · reference · generated

Sound core — short sound effects that play on a phone

This is the same document the Vibes code generator reads when it builds apps — rendered from 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.