/generating-audio

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