Voice Direction

---
name: voice-direction
description: "Casting, directing, recording and checking AI voices (ElevenLabs first; OpenAI, Gemini, Cartesia, Hume, Fish as alternatives) for any product: video voiceover, ads, explainers, app audio such as word or flashcard pronunciations, onboarding prompts, podcasts and characters. Matches voice, model, settings, tags and script writing to the feeling wanted (warm, trustworthy, hype, calm, premium, playful and more), keeps a specific language and regional accent, screens voices and takes for static, verifies takes without ears (noise floor, loudness, speech-to-text with repeats), runs blind casting tests, and builds loudness-matched files with word timings. Use it whenever the user wants to generate, choose, direct, fix or evaluate a synthetic voice, mentions ElevenLabs, TTS, voiceover, narration, accents or a voice that sounds breathy, robotic, noisy or foreign, even if they don't say \"voice direction\". The video-director skill calls it at its voice gate."
---

# Voice direction

Cast first, then direct, then verify with measurements, because you can't hear. Product voice docs (for example a repo's
`AUDIO.md`) override this skill's defaults.

## Step 0: read every file before the first action

This skill is loaded whole, never in part. Read this `SKILL.md` to the end, then every file in the table below, each to
its last line: no `offset`/`limit`, no `head`, `grep` or skimming, no "only the sections this task needs". If a read comes
back truncated, keep reading until the file ends. The task decides what you apply, never what you read; the table says
where each topic lives, not which files to skip. This holds when the skill is called on its own, from `video-director`, or
by a sub-agent. If the context is summarised mid-task, read the set again before the next action that depends on it.

| Topic | File |
|---|---|
| Models, settings, tags, pronunciation, context framing, the feeling matrix, accents and register | `references/direction.md` |
| Static and noise gates, verification without ears, casting tests, children's voices | `references/quality.md` |
| Other providers, account limits, cost | `references/providers.md` |

## Ten rules

1. **Cast first, then direct.** The voice's own recordings limit what a tag or setting can do.
2. On `eleven_v4` only **stability** and **similarity** exist; `style`, `speed` and SSML are ignored (a shipped film's speed
   setting was silently ignored). Pace comes from the script, `[slowly]`/`[rushed]` tags, then `atempo` within 0.95 to 1.08.
3. Direct with inline audio tags: English, square brackets, before the words they shape, on the shifts only. Describe the
   voice, not a sound (`[low, gravelly voice]`), because v4 also knows sound effects.
4. Always set the language, and cast a voice **native to the target language and accent**. A non-native voice on v4 drifts
   to a generic accent; short words that are also English words get an American accent when sent bare.
5. Unspoken context in `previous_text`/`next_text` says who speaks, to whom and how, in the target language. It fixed
   breathy and suggestive reads and English accents. Watch for syllables leaking from it into the take.
6. Write a spoken layer separate from captions: numbers, URLs and brands as they should be said.
7. One file per line, 2 takes per line (3 for the hero line and the CTA), `/with-timestamps`, seed and provenance logged.
8. **Screen every voice and every take for static**: noise floor ≤ −62 dB per take, ≤ −65 dB on two probes per voice
   (static measured −50 to −60, clean −66 to −76). Quiet-at-source takes (−24 to −32 LUFS) are breathy: re-record.
9. Never trust one absolute score from an audio-model judge (30 film takes all scored 8 to 10 and all were called the right
   accent). Use speech-to-text with repeats, measurements, pairwise and blind comparisons with a decoy, then human ears on
   hero lines.
10. At most 2 requests in flight (a ~27-request burst got an account flagged). Archive the audio: the same request may not
    give the same audio next month.

## Workflow

1. **Script** in two layers (display and spoken), one idea per line. The scriptwriting skill writes it; check the feeling
   matrix in `direction.md` so sentence shape matches the delivery wanted.
2. **Cast**: filter the library by language, accent and use case; noise-screen two probes per candidate; blind-test 3 to 4
   finalists on 3 to 4 representative lines with a known reference voice and a wrong-accent decoy. Lock the result in a
   project voice file (`assets/voice.example.json`).
3. **Direct**: tags on the shifts, context on, language on, stability from the matrix. Lint and dry-run.
4. **Record** with `vo_record.py`; use `--until-pass` to retake down a ladder of text forms until a take passes the gates.
5. **Gate** every take with `voice_qa.py` (noise floor, duration, loudness, quiet at source, clipping, optional STT).
6. **Judge** survivors: specific defects first, then pairwise (three runs, order swapped, majority). The user's ears on hero
   lines.
7. **Build** with `vo_build.py`: picked take, tempo, splits snapped to measured silence (alignment edges ran up to 0.14 s late
   and clipped a word in a shipped master), high-pass and trims, loudness matching to −16 LUFS, word timings as JSON and an
   optional TypeScript module.
8. In a film, the voice is the clock: never squeeze a line by speeding it more than ~8%; rewrite the line.

## Scripts

**Paths:** scripts live in this skill's `scripts/` folder, under the base directory shown when the skill loads (`~/.claude/skills/voice-direction/` for a standard install; a plugin install puts it elsewhere). The other skills of this suite sit next to it as sibling folders. Paths written as `~/.claude/skills/...` below assume the standard install.

uv scripts; keys from `ELEVENLABS_API_KEY` (or `--env-file`); every script has `--help` and a `--dry-run` where it spends money.
Path: `~/.claude/skills/voice-direction/scripts/`.

```
vo_record.py script.json --voice <voice_id|voice.json> --language es [--takes 2] [--hero l03 l11 --hero-takes 3]
    [--prefix sofia-] [--only l03] [--context-before ".." --context-after ".." | --context-file ctx.json]
    [--until-pass [--qa-stt scribe]] [--seed N] [--dictionary ID[:VER]] [--normalization auto|on|off] [--stitch]
    [--output-format pcm_44100] [--strict|--no-lint] [--dry-run] [--env-file .env]
voice_qa.py out/vo/takes/*.mp3 [--script script.json] [--language es] [--stt scribe|whisper] [--allow allow.json]
    [--report out/vo/qa.json] [--report-only] [--group-by auto|prefix|folder|none]
voice_qa.py --screen-voices IDS_OR_FILE [--library "language=es&accent=colombian"] --language es
    [--probes "ma." "mariposa."] [--context-before ".."] [--blind] [--out out/vo/screen] [--dry-run]
vo_build.py picks.json --takes out/vo/takes --out public/audio/vo [--ts src/data/vo.generated.ts] [--language es]
    [--target-lufs -16] [--true-peak -1.5] [--highpass 80] [--no-trim] [--no-loudness] [--force]
```

- `script.json`: `[{"id": "l01", "text": "[warmly] …", "previous": null, "next": null, "forms": ["sol.", "«sol»."]}]`;
  `previous`/`next` default to the neighbouring lines with tags stripped.
- `picks.json`: `{"lines": [{"line": "l01", "take": "sofia-l01b", "tempo": 1.04}, {"line": "l06", "take": "sofia-l06b",
  "last_word": 9}, {"line": "l06m", "take": "sofia-l06b", "first_word": 9}, {"line": "l10", "take": "…", "spoken_fixes":
  {"lee": "lea"}}, {"line": "l13", "take": "…", "caption_joins": [{"parts": ["acme", "punto", "com."], "text": "acme.com."}]}]}`.
  Word indices are 0-based and exclude tags.
- `vo_record.py` drops v4-ignored settings with a warning, warns when tags would be spoken (v2, Flash), lints digits, URLs
  and acronyms in the spoken layer, and writes a `<take>.meta.json` (model, settings, seed, request id, character cost).
- `voice_qa.py --stt whisper` installs faster-whisper on demand through uv; Scribe (`scribe_v2`) is more accurate. A
  speech-to-text miss only fails when it repeats in 2 of 3 runs; 1 to 2 syllable texts are report-only.
- `--screen-voices --blind` writes a lettered listening page (`blind/`) and a separate `key.json`; serve only `blind/`.
- Pairwise and blind judgements with an audio model: `~/.claude/skills/video-director/scripts/media_judge.py vo-take |
  pairwise` (OpenRouter).