agentleFS
salomonMurielsalomonMuriel/media-production-skills/skills/voice-direction/SKILL.md

voice-direction

Skill1 starsChanged 41 days agoMITView on GitHub

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 for voiceover.

  • Reads credentials

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always set the language, and cast a voice native to the target language and accent.

    line 32
  2. Distinctive:

    Write a spoken layer separate from captions: numbers, URLs and brands as they should be said.

    line 36
  3. Distinctive:

    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).

    line 40
  4. Very specific:

    Gate: every take with voice_qa.py (noise floor, duration, loudness, quiet at source, clipping, optional STT).

    line 55

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

TopicFile
Models, settings, tags, pronunciation, context framing, the feeling matrix, accents and registerreferences/direction.md
Static and noise gates, verification without ears, casting tests, children's voicesreferences/quality.md
Other providers, account limits, costreferences/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.

With a voice already locked in a project voice file, skip casting (step 2). A take that passes voice_qa.py is used as it is; pairwise judging (step 6) is for hero lines only, such as a film's opening line or a brand tagline.

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).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.