Sound Effects
Announce at start: "I'm using the humane:sound-effects skill to make a small, coherent sound palette for this interface."
Sound is feedback, not wallpaper. Generate a short cue only when it acknowledges
a change that the interface needs to make felt: a panel catching after a drag,
a confirmed action, a changed mode, or a boundary reached. It is never added
merely because something moves.
Before generating
- Name the moment and the change it confirms. If the interface already makes it obvious, do not add a sound.
- Read the project's token set or
DESIGN.md when it exists. It supplies the material vocabulary; do not invent a second brand in audio.
- Ask whether sound is opt-in, and identify motion-reduction and system sound settings. Effects must never autoplay, convey the only meaning, or prevent a task from being completed silently.
Generate a palette, not isolated noises
Start with three to five roles. Keep each effect short and quieter than a notification.
| Moment |
Duration |
Prompt shape |
| Press / select |
0.50 s |
dry tactile click, no voice, no melody |
| Panel drag |
0.50–0.60 s |
restrained low-friction mechanical glide, soft analogue texture |
| Snap / settle |
0.50 s |
soft magnetic catch, rounded transient, short decay |
| Boundary |
0.50 s |
muted non-alarming low pulse |
| Completion |
0.50–0.80 s |
small upward confirmation tone, restrained and non-game-like |
For Humane, begin with precise, editorial, retro-futurist, tactile, quiet and exclude voice, melody, fanfare, harsh alarms, and bright game UI. Generate alternatives, then choose the family by listening side by side.
Provider adapters
ElevenLabs is the first adapter, not the architecture. The generator takes a
--provider name and loads scripts/providers/<name>.py; every adapter shares
the same prompt, duration, loop, output, and receipt contract. Read
references/provider-adapters.md before adding one. This is where another
hosted provider or local sound model can be integrated later without changing
the skill's UI rules, prompt palette, generated files, or review handoff.
The ElevenLabs adapter calls POST /v1/sound-generation with
ELEVENLABS_API_KEY. The key belongs in the project's approved secret manager
or local environment, never in humane.json, a prompt, source code, or a
committed .env file. Read setup/references/secrets.md when setting up or
changing secret access.
python3 scripts/generate_sound.py --provider elevenlabs --name panel-snap --text "A soft magnetic mechanical catch; tactile analogue electronics, warm low mid tone, precise and quiet, no voice, no melody, no alarm" --duration 0.5 --out <resolved-sound-directory>/panel-snap.mp3
Resolve <resolved-sound-directory> with artifact_path(palette, "sound-effects"), which produces .design/sound-<palette>/ under the project;
never construct that path from the current working directory. ElevenLabs accepts
explicit durations from 0.5 seconds, so the generation table does not promise a
shorter value than the adapter can request. Use --duration only when
interaction timing needs it. --loop is for ambience only, never a click, drag,
or completion cue. The script writes audio plus a JSON receipt containing its
prompt and parameters, never a key.
Wire and check
- Preload only selected, compressed effects; never fetch a key or generate in the browser.
- Trigger after a visual state change begins. A sound that predicts a change that later fails is misleading.
- Use one sound per completed gesture and rate-limit rapid hover, drag, and click events.
- Offer a visible mute control when sound recurs, preserving that choice for the current device.
- Hand the live interaction to
humane:walkthrough. Check whether the cue clarifies what happened; do not judge it in isolation.
Boundaries
- Never generate speech here; use a speech tool for narration.
- Never claim an effect improves accessibility without testing it with people who use sound differently or not at all.
- Never spend credits or call the API until the user approves the selected prompts and variation count.
1---2name: sound-effects3description: Generate a small, coherent sound palette for interface moments through interchangeable provider adapters, beginning with ElevenLabs Sound Effects, then hand it to a walkthrough to check that the cues clarify rather than distract. Use when a product needs interaction sounds, feedback cues, micro-sound design, or a retro-futuristic audio layer. Triggers on sound effects, UI sounds, interaction audio, micro sounds, click sound, swipe sound, drag sound, ElevenLabs sound effects, audio feedback, retro-futuristic sound.4---56# Sound Effects78**Announce at start:** "I'm using the humane:sound-effects skill to make a small, coherent sound palette for this interface."910Sound is feedback, not wallpaper. Generate a short cue only when it acknowledges11a change that the interface needs to make felt: a panel catching after a drag,12a confirmed action, a changed mode, or a boundary reached. It is never added13merely because something moves.1415## Before generating16171. Name the moment and the change it confirms. If the interface already makes it obvious, do not add a sound.182. Read the project's token set or `DESIGN.md` when it exists. It supplies the material vocabulary; do not invent a second brand in audio.193. Ask whether sound is opt-in, and identify motion-reduction and system sound settings. Effects must never autoplay, convey the only meaning, or prevent a task from being completed silently.2021## Generate a palette, not isolated noises2223Start with three to five roles. Keep each effect short and quieter than a notification.2425| Moment | Duration | Prompt shape |26| --- | --- | --- |27| Press / select | 0.50 s | dry tactile click, no voice, no melody |28| Panel drag | 0.50–0.60 s | restrained low-friction mechanical glide, soft analogue texture |29| Snap / settle | 0.50 s | soft magnetic catch, rounded transient, short decay |30| Boundary | 0.50 s | muted non-alarming low pulse |31| Completion | 0.50–0.80 s | small upward confirmation tone, restrained and non-game-like |3233For Humane, begin with **precise, editorial, retro-futurist, tactile, quiet** and exclude voice, melody, fanfare, harsh alarms, and bright game UI. Generate alternatives, then choose the family by listening side by side.3435## Provider adapters3637ElevenLabs is the first adapter, not the architecture. The generator takes a38`--provider` name and loads `scripts/providers/<name>.py`; every adapter shares39the same prompt, duration, loop, output, and receipt contract. Read40`references/provider-adapters.md` before adding one. This is where another41hosted provider or local sound model can be integrated later without changing42the skill's UI rules, prompt palette, generated files, or review handoff.4344The ElevenLabs adapter calls `POST /v1/sound-generation` with45`ELEVENLABS_API_KEY`. The key belongs in the project's approved secret manager46or local environment, never in `humane.json`, a prompt, source code, or a47committed `.env` file. Read `setup/references/secrets.md` when setting up or48changing secret access.4950```bash51python3 scripts/generate_sound.py --provider elevenlabs --name panel-snap --text "A soft magnetic mechanical catch; tactile analogue electronics, warm low mid tone, precise and quiet, no voice, no melody, no alarm" --duration 0.5 --out <resolved-sound-directory>/panel-snap.mp352```5354Resolve `<resolved-sound-directory>` with `artifact_path(palette,55"sound-effects")`, which produces `.design/sound-<palette>/` under the project;56never construct that path from the current working directory. ElevenLabs accepts57explicit durations from 0.5 seconds, so the generation table does not promise a58shorter value than the adapter can request. Use `--duration` only when59interaction timing needs it. `--loop` is for ambience only, never a click, drag,60or completion cue. The script writes audio plus a JSON receipt containing its61prompt and parameters, never a key.6263## Wire and check6465- Preload only selected, compressed effects; never fetch a key or generate in the browser.66- Trigger after a visual state change begins. A sound that predicts a change that later fails is misleading.67- Use one sound per completed gesture and rate-limit rapid hover, drag, and click events.68- Offer a visible mute control when sound recurs, preserving that choice for the current device.69- Hand the live interaction to `humane:walkthrough`. Check whether the cue clarifies what happened; do not judge it in isolation.7071## Boundaries7273- Never generate speech here; use a speech tool for narration.74- Never claim an effect improves accessibility without testing it with people who use sound differently or not at all.75- Never spend credits or call the API until the user approves the selected prompts and variation count.
glebis