generating-audio — Claude Code skill for speech generation

---
name: generating-audio
description: ALWAYS read this skill before generating spoken audio or calling audio_generate — a voiceover, narration, an ad read, a character line, or any script read aloud. Turns a script into speech — picks the model and voice, prepares the text for reading, and splits a long script into clips. Use whenever the user asks for text-to-speech, a voiceover, narration, or to have something read or spoken aloud.
license: Apache-2.0
metadata:
  version: "0.1.0"
  category: creative
  summary: "Converts scripts into audio. Lets you preview voice candidates from top models before generating. It then formats your script's numbers, dates, and URLs so the chosen AI model pronounces them accurately."
---

# Audio Generation

Turn a script into spoken audio via the `audio_generate` tool. Two decisions drive quality: **which
voice** reads it, and **how the script is written for the ear**.

**Scope.** Speech — a voice reading written words, delivered as its own audio file. Nothing here makes
non-speech sound, alters audio that already exists, or combines two tracks into one.

Lip-synced dialogue spoken by a character *inside* a video clip belongs to `generating-videos`.

## Workflow

### Step 1: Settle the script

Generate only from the exact words that will be spoken.

- **Supplied** → use them verbatim.
- **Enough to write them** — the product, audience, platform, and length are known → draft the script
  and show it before generating.
- **Not enough** → ask. Never invent a tagline, product claim, or brand name to fill the gap.

**Write to a duration.** Speech runs about two to three words a second, so a fifteen-second read is
thirty to forty-five words. Set the word count before writing, and trim words rather than speeding up
the delivery.

### Step 2: Pick the model

**`eleven-v3` is the default** — the most expressive read, and right for anything heard as a
performance. Reach for another only on a clear signal:

| Reach for another model when the script… | Model |
| --- | --- |
| Is a long, even read — an explainer, documentary narration, an audiobook chapter — where the voice must not drift | `eleven-multilingual-v2` |
| Is high-volume, a throwaway draft, or cost-sensitive, and expressiveness doesn't matter | `eleven-flash-v2.5` |

When the user names a model, use it. Per-request character limits differ sharply between models, and
an over-limit script is rejected rather than truncated — `list_audio_models` carries each ceiling.

### Step 3: Pick the voice

Call `list_voices`, filtered by what the brief demands — `gender`, `accent`, `age`, `use_case`,
`language`, or free-text `search`. Each row carries a `preview_url`. 
**There is no default voice**: every request needs a `voice_id` chosen here, passed as `voice`. 
Display names are not accepted.

- A stated **gender, accent, or age is a hard filter** — apply it, don't trade it away on tone.
  Read the attribute back from the row's own fields; **never infer it from the voice's name**. 
- **Let the user hear the options.** Unless they named a voice, offer two or three candidates with
  their `preview_url`s and let them pick.
- **Choose on tone**: what is the listener doing (half-watching a social clip wants attack and
  momentum; following an explainer wants a voice that stays out of the way), and whose voice is it
  meant to be (a brand narrator should stay neutral enough to reuse; a character should match the
  age and register of the writing).
- **Non-English script** → check the row's `language`, and that the model of Step 2 covers it.
- A `voice_id` the user pastes themselves is taken as given.
- Reuse the chosen `voice_id` for every clip in the job.
- **Nothing matched** → a normal result, not a dead end. Drop the narrowest facet — `use_case`
  first, then `age` — and search again. Only when gender and accent alone come back empty is the
  account genuinely short of voices; then relay the tool's hint verbatim, since the cause and the fix
  differ by provider and by whose key is in use.

### Step 4: Prepare the text

`text` is read out word for word, so write it the way it should sound.

- **Strip anything unspoken** — stage directions, speaker labels, bracketed cues, markdown.
- **Spell out** numbers, dates, currency, acronyms, and URLs as a person would say them.
- **Punctuate for pacing** — commas and full stops become pauses, and are the main lever on rhythm.

Direct the delivery with `stability` and `style` (`references/directing-the-read.md`), never with instructions
written into the text.

### Step 5: Generate

Speech comes **only** from `audio_generate`. If it errors, or no voice fits, say so and stop — never
substitute another text-to-speech tool the host happens to expose. A different engine means a
different voice, no access to the account's voices, and output outside the media directory.

Call `audio_generate` with a `requests` list — one object per clip, up to ten per call.

- Per object: `text` and `voice` (both required — the `voice_id` from Step 3); `model` only when
  Step 2 chose a non-default; `speed`, `stability`, `style`, `similarity_boost`, `format` as needed.
- **Split only where the audio will actually be cut** — per scene, or per section placed separately.
  Objects generate independently, so a continuous read split across two of them seams audibly.
- **Hold one `voice` and `model` across every object**, for the same reason. In a dialogue, one voice
  per character, consistent across that character's lines.
- **Repeat a line to get alternate takes** — different voices when the choice is unclear, or the same
  voice twice at low `stability`. Worth it on one short line, not a whole script.

### Step 6: Return

Share the audio file path(s). When the script was split, label each with the section it covers.

## Edge cases

- **Something other than speech is asked for** (music, sound effects, ambience, re-voicing, dubbing,
  cloning a voice from a sample) → say so plainly rather than substituting something else. In
  particular, do not generate a clip through `generating-videos` to get music or effects out of its
  native audio: that bakes the sound into the picture, so it can never serve as a track the user
  mixes. An already-cloned voice still works by its `voice_id`, and another language works by
  translating the script and generating it fresh.
- **Tracks need mixing or timing** ("the voiceover under the music", "a swoosh on the logo") → deliver
  clean speech and let the user assemble it in their editor.
- **Part of the brief is speech and part isn't** → state the limits in one message up front, then
  deliver the speech. Never generate first and disclose the gaps after.
- **Script over the model's character limit** → split it at a natural break, or switch to a
  higher-ceiling model.
- **`error: "no_voices_available"`** → relay the hint; it distinguishes an empty account from a key
  lacking permission to read voices, and the fixes differ.
- **Part of a batch fails** → keep the takes that worked and resend only the failed lines.
- **The read itself came out wrong** (flat, erratic, mispronounced, stress on the wrong word) →
  `references/directing-the-read.md` diagnoses it symptom by symptom.
- **Safety rejection** → remove the sensitive wording and retry once.
- **Generic failure** → retry once as-is, then report the error.
- **`error: "no_provider_configured"`** → relay the tool's `hint` (the user must set their key).

## Reference

- `references/directing-the-read.md` — tuning the delivery with `stability`, `style`,
  `similarity_boost` and `speed`, and diagnosing a read that isn't working.