# Helikona — Sound-effect prompts for ElevenLabs

> The brief behind the brand sound set, and the audition rules. Derived from [`brand.md`](../brand.md) (voice, name, principles) and [`video-guidelines.md`](../video-guidelines.md) §5 (logo sting), §6 (motion) and §10 (sound).
>
> **The prompts themselves live in [`assets/audio/manifest.json`](../assets/audio/manifest.json)**, which is what `pnpm audio` sends to the API and what the Sound page (`pnpm preview` → `preview/audio.html`, live at <https://helikona-brand.vercel.app/audio>) renders. The tables below are the same prompts with their reasoning; when the two disagree, the manifest is what was actually generated. Generate, audition on the Sound page, keep the few that earn their place.

---

## 1. Sonic palette: a secret island, heard from the shade

The brand is a heliconia, jungle greens, temple stone and iron oxide. In sound, that is a **hidden tropical island**: a sheltered cove, dense canopy, old stone under the trees, and the sea always there but never in your face. The listener is sitting in the shade, not on the beach. Everything is heard from a little distance, slowed down, and settled.

| Brand fact | Sonic consequence |
|---|---|
| Calm and grounded; we don't sell urgency | The island is heard at dawn or dusk, never at noon. Low-to-mid register, soft transients, long natural decays. Surf is distant and slow. |
| Restraint over expression | Every sound is short, quiet, and single-gesture. Room tone and sea air are the default; a sound is the exception. |
| Editorial, not corporate | Real island materials: bamboo, driftwood, coral stone, coconut husk, wet sand, broad leaves, salt air, still water. No synth chirps, no glassy UI pings. |
| The name: heliconia, jungle, temple stone, iron oxide | Canopy and cove ambiences, an old stone terrace under the trees, red earth. Warm and unhurried, not a resort (no steel drums, no ukulele, no parrots, no cocktail-bar shimmer). |
| Evidence is the keystone | Sounds feel *settled* and *resolved*: a stone set down, a wave finishing its retreat. No rising questions, no shimmer tails. |
| The rust dot lands last, deliberately (video §5) | The brand's sonic "full stop": one soft, low tap of driftwood or a river stone, ~150ms after the mark resolves. |
| Decelerate into the ending; the last frame is still | Stings and transitions fall in pitch and energy, like a wave drawing back. End cards resolve to sea air and near-silence. |
| No impact hits on text, no whoosh on every element (video §10) | The video set is tiny: one sting, one transition, one end-card resolve, room tone. |

**Banned textures:** braams, risers, sub-drops, glitch, bright bells, glass, laser/beeps, reverse cymbals, trailer anything, notification-style "ding". And the island clichés: steel drums, ukulele, bongos, seagulls, parrots, crashing surf up close, "tropical house" synths.

---

## 2. How to prompt the API

- Endpoint: `POST https://api.elevenlabs.io/v1/sound-generation` with header `xi-api-key`. Body: `text`, optional `duration_seconds` (0.5–30; omit to let the model choose), `prompt_influence` (0–1, default 0.3), `loop` (for ambiences). Query `output_format=mp3_44100_128`. Verified against the live API on 2026-09-06: all four fields are accepted and the response is `audio/mpeg` at the requested length.
- The key lives in `.env.local` as `ELEVENLABS_API_KEY` (gitignored; copy it from the primary checkout into any worktree).
- The model responds best to **concrete sound-design language** (source material, transient, tail, register, mono/stereo, dry/roomy) rather than mood words alone. Each prompt below pairs a material with one or two mood words, and says *how far away* it is, which is what keeps the island from becoming a resort.
- Negatives ("no seagulls") are only partly honoured. Raise `prompt_influence` to ~0.5–0.7 when a generation drifts bright, busy or beachy; drop it to ~0.2 when you want variation across takes.
- `pnpm audio` generates every missing take of every manifest entry: `takes` in the manifest says how many per sound (three), under `assets/audio/takes/<id>-<n>.mp3`. `--only <id-prefix>` narrows, `--force` regenerates, `--dry-run` lists.
- Choose on the Sound page: pick one take per sound and it writes the `pnpm audio --choose <id>=<n>,…` command. Running that copies each chosen take to `assets/audio/<id>.mp3` (the file that ships) and records `chosen` on the entry. Nothing ships until it is chosen. Trim tails yourself if needed; the model over-lengthens.
- Master everything to sit under narration: peaks around −18 dBFS for stings and transitions, −30 dBFS or lower for room tone, so the final mix lands near the −14 LUFS target in video §10.

Example call:

```bash
curl -s -X POST "https://api.elevenlabs.io/v1/sound-generation?output_format=mp3_44100_128" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "A single piece of dry driftwood tapped softly once against another, low and rounded, very short, dry, one-shot",
    "duration_seconds": 0.6,
    "prompt_influence": 0.5
  }' -o rust-dot.mp3
```

---

## 3. Video set (the only sounds a Helikona video should need)

### 3.1 Logo sting — the mark builds, the dot lands
Timing from video §5: field and glyph resolve over ~400ms, the rust dot settles ~150ms later; whole sting 0.8–1.2s, then hold.

| # | Prompt | `duration_seconds` | `prompt_influence` |
|---|---|---|---|
| A | A very small, gentle wave on a calm sheltered lagoon quietly receding over wet sand, heard from far away under trees, hushed, soft and barely there, no wind, no surf, settling into stillness, then one quiet tap of driftwood on driftwood as it fades, calm, one-shot | 2.0 | 0.6 |
| B | Near silence: the faint warm room tone of a still evening under trees with no wind at all, then a single smooth river stone set down gently on flat stone, one soft low contact, no ring, no air movement, no leaves, intimate, dry, one-shot | 1.8 | 0.7 |
| C | A low bamboo flute note breathed very softly with almost no attack, fading down into sea air, then one muted wooden knock, unhurried, no reverb tail | 2.0 | 0.4 |
| D | Warm low marimba note struck softly with a felt mallet, decaying naturally in the open air under a canopy, distant surf far below, ending with one quiet tap of a pebble on coral stone | 1.8 | 0.5 |

Audition note: the sting must **fall** in energy, like a wave drawing back, not rise. Reject any take with a swell, shimmer or bright harmonic bloom on the tail. First round (2026-09-06): A and B both came back stormy; "wave" and "sea breeze" read to the model as weather. Reworded to lead with the stillness (lagoon, hushed, no wind, barely there) and raised influence to 0.6. D was kept as three variants to cycle through rather than one take. Second round: the same happened to "Small wave, distant", "Cove at dusk" and "Palms in a sea breeze": any prompt that names surf, waves or a sea breeze comes back as weather. B failed a second time even with "the faintest air", so its third wording drops moving air altogether and leads with room tone and the stone, at influence 0.7. The rule that emerged: **name the stillness, not the sea, and not the air either.** Lapping water, a faint sigh of leaves, the gentlest air; put "no wind, no surf" in explicitly and hold influence at 0.6.

### 3.2 The rust dot — the sonic full stop (also usable alone)
The last element in the logo build. Short, low, rounded, dry. Should read as "placed", not "hit".

| # | Prompt | `duration_seconds` | `prompt_influence` |
|---|---|---|---|
| A | A single piece of dry driftwood tapped softly once against another, low and rounded, very short, dry, one-shot | 0.6 | 0.6 |
| B | A small smooth sea-worn stone set down gently on a flat coral-stone step, one quiet contact, low and muted, no ring | 0.6 | 0.6 |
| C | One soft tap of a knuckle on a thick bamboo pole, hollow and low, very short, dry, one-shot | 0.5 | 0.6 |
| D | A dry coconut husk set down softly on packed wet sand, one dull low contact, muted, intimate close-mic | 0.5 | 0.5 |

### 3.3 Scene transition — "a soft, low whoosh under a crossfade" (video §10)
Sits under a 300–500ms crossfade. Must be near-inaudible in isolation.

| # | Prompt | `duration_seconds` | `prompt_influence` |
|---|---|---|---|
| A | Very soft gust of warm sea air passing slowly through palm fronds, low-passed and quiet, fading in and out smoothly, no sharp rustle, no impact | 1.0 | 0.5 |
| B | The faintest lapping of calm water on sand heard from far away, very quiet, one slow gentle ripple fading out, hushed, no wind, no surf, muffled and peaceful | 1.2 | 0.6 |
| C | Gentle breeze moving through dense jungle canopy far overhead, distant and muffled, one slow pass left to right, subtle and low | 1.2 | 0.4 |
| D | A broad banana leaf brushing slowly against another in a light breeze, soft and airy, one smooth pass, quiet, dry | 0.9 | 0.5 |

### 3.4 End-card resolve — settling into stillness
Plays as the end card lands; hold ≥2s in silence after it. Nothing here should be a stinger.

| # | Prompt | `duration_seconds` | `prompt_influence` |
|---|---|---|---|
| A | A calm sheltered cove at dusk heard from far up in the trees, the faintest lapping of still water on sand, hushed and peaceful, one soft gentle breath of warm air fading completely into silence, calm and resolved, no wind, no surf, no swell | 4.0 | 0.6 |
| B | Warm evening breeze through a rainforest canopy gradually going still, distant sea far below, until only faint salt air and room tone remain, peaceful | 4.0 | 0.4 |
| C | A single warm low nylon-string guitar note plucked gently with the thumb, ringing down into the sound of distant surf and evening air, unhurried, resolved | 3.5 | 0.4 |
| D | A low bamboo wind chime moved once by a slow breeze, two or three soft hollow wooden notes, muted, settling into quiet sea air | 3.0 | 0.5 |

### 3.5 Room tone and beds (loopable)
For scenes that work "in near-silence with room tone" (video §10). These carry the island quietly and from a distance.

| # | Prompt | `duration_seconds` | `loop` | `prompt_influence` |
|---|---|---|---|---|
| A | Hidden cove at dawn heard from inside the treeline, very distant slow surf, soft warm sea air, a few far-off forest birds, no seagulls, calm and spacious, seamless loop | 12 | true | 0.4 |
| B | Deep jungle canopy at dusk, very quiet, warm still air, a slow drip of water in the distance, occasional soft insect hum far away, no birds, seamless loop | 12 | true | 0.4 |
| C | An old stone terrace under trees on a tropical island, faint low air movement, very distant surf far below, almost silent, still, seamless loop | 12 | true | 0.5 |
| D | The gentlest warm air drifting through palm fronds on a still evening, barely moving, soft and hushed, no wind, no rustle, only a faint sigh of leaves now and then, a very distant calm sea barely audible, peaceful, seamless loop | 12 | true | 0.6 |
| E | Warm tropical rain falling softly on broad leaves and a thatched roof, heard from inside, muffled and close, no thunder, distant surf, seamless loop | 12 | true | 0.4 |
| F | A still freshwater pool in a jungle clearing, tiny occasional drips and a faint trickle, very quiet, humid air, seamless loop | 12 | true | 0.4 |

---

## 4. Product-UI set (proposal, not yet a guideline)

Video §10 bans UI clicks *in video*. The apps are a different surface: the agent rail, Learn, and the app switcher sometimes need a sound to say "done" or "your turn" when the user is not looking at the screen. If we adopt any, the set stays this small and every sound is off by default. Same palette: driftwood, stone, bamboo, leaves, sea air.

| Event | Prompt | `duration_seconds` | `loop` | `prompt_influence` |
|---|---|---|---|---|
| Working (pairs with the BrandSway heliconia) | Very quiet slow sea breeze moving gently through a single heliconia plant's broad leaves, soft and low, rhythmic like slow breathing, distant surf barely audible, seamless loop | 8 | true | 0.4 |
| Task complete | A single small wave finishing its retreat over sand, heard from a distance, then one soft tap of driftwood, settled, one-shot | 1.2 | 0.5 |
| Reply received (your turn) | A small sea-worn stone placed gently on a wooden table, one quiet low contact with a short warm resonance, unhurried | 0.8 | 0.5 |
| Message sent | A broad dry leaf released and sliding softly off a wooden surface, one short quiet movement, dry | 0.7 | 0.5 |
| Needs attention (calm, never alarming) | Two soft unhurried taps of a knuckle on a hollow bamboo pole, low-pitched, a slow beat apart, muted and dry | 1.2 | 0.6 |
| Module or chapter complete (Learn) | Warm low marimba note struck softly with a felt mallet under an open canopy, decaying naturally, then one quiet tap of a pebble on stone as it fades, resolved and calm | 2.0 | 0.5 |
| Switch app (app switcher) | Soft short exhale of warm sea air through a doorway, low and muffled, one-shot | 0.6 | 0.5 |

Rejection criteria: anything that reads as a phone notification, anything with a rising pitch, anything you would notice from across the room, anything that sounds like a holiday.

---

## 5. Audition checklist

Before a sound enters the package, confirm:

- [ ] It is a real island material (driftwood, stone, bamboo, leaf, sand, water, salt air) or an acoustic instrument played softly.
- [ ] The sea, if present, is distant and slow. Never up close, never crashing.
- [ ] Energy and pitch fall or hold; nothing rises or swells.
- [ ] Attack is soft; there is no "hit."
- [ ] It sits below narration and disappears under a bed.
- [ ] It resolves to silence or sea air rather than a tail that lingers or shimmers.
- [ ] The rust-dot tap is placed, not struck, and lands last in any logo build.
- [ ] No resort tells: no steel drums, ukulele, bongos, seagulls, parrots.
- [ ] A senior listener would not call it a sound effect; they would call it quiet.

---

*Each take under `assets/audio/takes/` is made by exactly the manifest entry that names it, so a regeneration is a re-run rather than a rediscovery. Only the chosen files at `assets/audio/<id>.mp3` ship in the package; the takes stay in the repo for the Sound page. Loops are generated at 12s rather than 20s to keep the package small; a seamless loop does not need to be long.*