OverlayMotion
PROFounder Support

Sound cues

Read this when an overlay should make a sound, or when a request asks to change, swap or silence one. For the bed under the whole edit, see music.md.

sound at the spec root sets defaults; each overlay may override with its own sound block. Cues resolve to built-in names, arbitrary audio paths, or false to silence one cue. Cues default on. The curated core palette, which is what to reach for first: click, pop, whoosh, ding, typewriter (CORE_SFX in src/sound/config.ts).

Two scopes, and picking the wrong one is the usual mistake

  • A template's own cue is a prop, and every template that makes a sound has one. It is never a boolean: false is silence, a premade name swaps the cue ("sfx": "ding"), and any path or URL plays your own file ("sfx": "/sfx/library/my-stamp.wav"). Omit it and the template's default cue plays. true is rejected on purpose, because a boolean can only mean "whatever the template picked", which is the one choice that belongs to the caller.

    Naming is uniform: one sound is sfx, and a template with several names each one (tickSfx and endSfx on countdown, typingSfx on tweet-card and chat-bubbles, exitSfx on speaker-card, checkSfx and stepSfx on the step lists). Each template's page and its props schema list the ones it has.

  • sound.sounds remaps BY CUE NAME, for everything in scope: { "pop": "ding" } on an overlay changes every pop that overlay fires, including the one exit: "vanish" plays. Reach for it when you are restyling a whole edit, and for the template's own sound reach for the prop.

{ "template": "sticker", "props": { "src": "logo.png", "sfx": "ding" } }
{ "template": "sticker", "props": { "src": "logo.png", "sfx": false } }
{ "template": "countdown", "props": { "from": 3, "tickSfx": "click", "endSfx": false } }
{ "template": "sticker", "sound": { "sounds": { "pop": "/sfx/custom.wav" } },
  "props": { "src": "logo.png" } }

Library cues

Some defaults are library cues: a name whose sound is a bundled CC0 file rather than a pack entry (quote-word and word-settle, the word-reveal clicks; chat-typing, the typing-dots blip; list-step, the non-check list marker). They behave like any other cue: swap them with a prop, or remap them by name in sound.sounds. LIBRARY_CUES is in src/sound/config.ts, provenance in sfx-library.md.

Avoid decorative sound under important speech.