Narrate
Turn a script into speech, and write a word timing file beside it. kokoro runs on this machine and is
the default. elevenlabs is a separate, optional backend that sends the text to a third party; use it
only when the user asks for it by name.
Inputs
- Script. A path to a UTF-8 text file, or text the user gave. For given text, write it to
script.txt in the output folder first, so the run is repeatable. Write the script the way it
should be spoken: spell out abbreviations you want expanded and keep one idea per sentence.
- Backend (
--backend). Default kokoro. elevenlabs only when the user names it; it follows
its own section below.
- Output folder (
--out). Default: the script file's folder. The run writes two files there and
replaces earlier ones with the same names.
- Voice (
--voice, kokoro). Default af_heart. Names starting af_/am_ speak American English,
bf_/bm_ British English. ${CLAUDE_PLUGIN_ROOT}/scripts/kokoro-assets.json lists every
voice the plugin pins.
- Speed (
--speed, kokoro). Default 1.0, from 0.5 to 2.0.
Run (kokoro)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py" run --data-dir "${CLAUDE_PLUGIN_DATA}" -- \
"${CLAUDE_PLUGIN_ROOT}/scripts/narrate.py" --data-dir "${CLAUDE_PLUGIN_DATA}" \
--model-dir '${user_config.model_dir}' \
--script <script file> --out <output folder> [--voice <name>] [--speed <x>]
Where python3 is not on PATH, run the same command with python; the SessionStart hook accepts either.
Keep the --model-dir argument exactly as shown, in single quotes: it carries the plugin's
model_dir option, and the script handles an unset one (reference/plugin-options.md).
narrate.py owns the behavior: how words are split, how timings are measured, and the
words.json fields. Read its docstring when you need the details.
- Exit 0: it prints the audio path with its length and word count, then the
words.json path.
Report both paths and the length.
- Exit 2: a prerequisite is missing. The message names it: espeak-ng, the model files, or the
Python packages. Report the message as written and stop. Do not install anything.
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/check.py" --data-dir "${CLAUDE_PLUGIN_DATA}" --model-dir '${user_config.model_dir}'
lists every gap with its remedy, and installs nothing. Where python3 is not on PATH, run it with
python. Keep --model-dir exactly as shown, in single quotes; the script handles an unset
model_dir option.
- Exit 1: report the error. An unknown voice or a speed out of range is the caller's to fix.
The elevenlabs backend
Third-party egress: the script text goes to api.elevenlabs.io, and ElevenLabs bills it per
character. Pick this backend only when the user names ElevenLabs. Never pick it because kokoro is
slow or its output was disliked, and never switch to it after a kokoro failure.
The key is the ELEVENLABS_API_KEY environment variable. When it is unset and vault-exec is on
PATH, the script runs itself again under vault-exec, which supplies the key to that one process
from the user's vault. Never ask the user to paste the key into the chat, never put it on a command
line, never wrap the command in vault-exec yourself, and never print, echo or log the key.
Two runs, with the user's answer between them:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/elevenlabs.py" --data-dir "${CLAUDE_PLUGIN_DATA}" \
--model '${user_config.elevenlabs_model}' --script <script file> --out <output folder> \
[--voice <voice id>] [--setting <name>=<value> ...] [--no-cache]
Keep --model exactly as shown, in single quotes: it carries the plugin's elevenlabs_model
option, and the script uses its default model, eleven_v4, when that option is unset (reference/plugin-options.md). When the
user names a model for this run, replace that argument with --model <model id>.
eleven_multilingual_v2 gives a steadier, less expressive delivery.
- Without
--proceed, the script prints one statement and sends nothing (exit 3): the
character count, the host, the model and voice, the plan's remaining character quota, and the
pricing page. Show that statement to the user as printed and ask whether to proceed. Stop until
they answer.
- After a yes, run the same command with
--proceed added. A no, or no answer, ends the task.
Do not add --proceed on your own, and do not reuse an earlier yes for a changed script, model,
voice or setting: run step 1 again.
A request identical to an earlier one (text, voice, model, settings) is served from the cache in
the plugin data directory: the script says so, sends nothing, needs no key and no --proceed, and
exits 0. --no-cache forces a new call, which goes through both steps above.
The models, their limits, and whether each is confirmed on the timed endpoint are the script's
MODELS table. --setting takes the voice settings the script names in its --help. Where to read the
live ElevenLabs specifics (models, script-writing guidance, voice cloning, pricing) is
reference/elevenlabs.md.
- Exit 0: report the audio path with its length, and the
words.json path, and say when the
audio came from the cache.
- Exit 3: the statement was shown and nothing was sent. Ask, as above.
- Exit 4: the organization's egress floor forbids this backend (
SPEECH_EGRESS_FLOOR is
set in the environment, usually from managed settings). Report the reason as written, use kokoro
if the user agrees, and do not try to unset the variable.
- Exit 2: no key:
ELEVENLABS_API_KEY is unset and vault-exec is absent or could not supply
the secret. Report the message as written; it names the remedy.
- Exit 1: report the error, such as a rejected key, a script over the model's limit, or an
empty audio reply.
Outputs
narration.wav: 24 kHz mono, 16-bit PCM.
words.json: audio, sample_rate, duration, backend, voice, speed (kokoro) or model,
voice_settings, request_id, character_cost and cached (elevenlabs), and words, a list
with one {word, start, end} per whitespace-separated token of the script, in script order. A
kokoro token with only punctuation, such as a dash, spans its pause. ElevenLabs reports a time for every character, and a word spans its first to its last character.
Next
/harness-ops:prerequisites
When the run stopped with exit 2, it lists the declared tools this machine lacks.
Gotchas
- Never read, print or pass
ELEVENLABS_API_KEY yourself. elevenlabs.py reads it from the
environment, and no command, message or file you write carries its value.
- espeak-ng is GPL-3.0. The user installs it. Never install it, download it, or suggest a
package that bundles it.
- The first run of a session loads a 325 MB model. On a desktop CPU the model makes audio faster
than real time (about 0.4 s of compute for each second of audio, measured on a 32-thread x86
CPU).
- Each word is phonemized on its own, so a function word can carry more stress than it would in
running speech. Rewrite the sentence if one sounds wrong.
1---2name: narrate3description: "Text-to-speech: turn a narration script into narration.wav plus words.json with per-word start and end times, so video, captions or a page can sync to the voice. The default kokoro backend runs locally. The optional elevenlabs backend sends the script text to the third-party ElevenLabs API, only after showing the character count against remaining quota and getting the user's go-ahead. Use when: 'narrate this script', 'text to speech', 'read this aloud', 'make a voiceover', 'generate narration audio', 'TTS with word timings', 'I need audio for this explainer', 'narrate with elevenlabs'. Not for transcribing existing audio."4argument-hint: "<script or text> [--backend kokoro|elevenlabs] [--out <dir>] [--voice <v>] [--speed <n>]"5user-invocable: true6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/narrate9 workflow-stage: implement10 summary: Script in, narration.wav and words.json out (kokoro local; elevenlabs optional, third-party)11---1213# Narrate1415Turn a script into speech, and write a word timing file beside it. kokoro runs on this machine and is16the default. elevenlabs is a separate, optional backend that sends the text to a third party; use it17only when the user asks for it by name.1819## Inputs2021- **Script.** A path to a UTF-8 text file, or text the user gave. For given text, write it to22 `script.txt` in the output folder first, so the run is repeatable. Write the script the way it23 should be spoken: spell out abbreviations you want expanded and keep one idea per sentence.24- **Backend** (`--backend`). Default `kokoro`. `elevenlabs` only when the user names it; it follows25 its own section below.26- **Output folder** (`--out`). Default: the script file's folder. The run writes two files there and27 replaces earlier ones with the same names.28- **Voice** (`--voice`, kokoro). Default `af_heart`. Names starting `af_`/`am_` speak American English,29 `bf_`/`bm_` British English. `${CLAUDE_PLUGIN_ROOT}/scripts/kokoro-assets.json` lists every30 voice the plugin pins.31- **Speed** (`--speed`, kokoro). Default `1.0`, from `0.5` to `2.0`.3233## Run (kokoro)3435```bash36python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pydeps.py" run --data-dir "${CLAUDE_PLUGIN_DATA}" -- \37 "${CLAUDE_PLUGIN_ROOT}/scripts/narrate.py" --data-dir "${CLAUDE_PLUGIN_DATA}" \38 --model-dir '${user_config.model_dir}' \39 --script <script file> --out <output folder> [--voice <name>] [--speed <x>]40```4142Where `python3` is not on PATH, run the same command with `python`; the SessionStart hook accepts either.43Keep the `--model-dir` argument exactly as shown, in single quotes: it carries the plugin's44`model_dir` option, and the script handles an unset one ([reference/plugin-options.md](../../reference/plugin-options.md)).4546`narrate.py` owns the behavior: how words are split, how timings are measured, and the47`words.json` fields. Read its docstring when you need the details.4849- **Exit 0:** it prints the audio path with its length and word count, then the `words.json` path.50 Report both paths and the length.51- **Exit 2:** a prerequisite is missing. The message names it: espeak-ng, the model files, or the52 Python packages. Report the message as written and stop. Do not install anything.53 `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/check.py" --data-dir "${CLAUDE_PLUGIN_DATA}" --model-dir '${user_config.model_dir}'`54 lists every gap with its remedy, and installs nothing. Where `python3` is not on PATH, run it with55 `python`. Keep `--model-dir` exactly as shown, in single quotes; the script handles an unset56 `model_dir` option.57- **Exit 1:** report the error. An unknown voice or a speed out of range is the caller's to fix.5859## The elevenlabs backend6061Third-party egress: the script text goes to `api.elevenlabs.io`, and ElevenLabs bills it per62character. Pick this backend only when the user names ElevenLabs. Never pick it because kokoro is63slow or its output was disliked, and never switch to it after a kokoro failure.6465The key is the `ELEVENLABS_API_KEY` environment variable. When it is unset and `vault-exec` is on66PATH, the script runs itself again under `vault-exec`, which supplies the key to that one process67from the user's vault. Never ask the user to paste the key into the chat, never put it on a command68line, never wrap the command in `vault-exec` yourself, and never print, echo or log the key.6970Two runs, with the user's answer between them:7172```bash73python3 "${CLAUDE_PLUGIN_ROOT}/scripts/elevenlabs.py" --data-dir "${CLAUDE_PLUGIN_DATA}" \74 --model '${user_config.elevenlabs_model}' --script <script file> --out <output folder> \75 [--voice <voice id>] [--setting <name>=<value> ...] [--no-cache]76```7778Keep `--model` exactly as shown, in single quotes: it carries the plugin's `elevenlabs_model`79option, and the script uses its default model, `eleven_v4`, when that option is unset ([reference/plugin-options.md](../../reference/plugin-options.md)). When the80user names a model for this run, replace that argument with `--model <model id>`.81`eleven_multilingual_v2` gives a steadier, less expressive delivery.82831. **Without `--proceed`**, the script prints one statement and sends nothing (exit 3): the84 character count, the host, the model and voice, the plan's remaining character quota, and the85 pricing page. Show that statement to the user as printed and ask whether to proceed. Stop until86 they answer.872. **After a yes**, run the same command with `--proceed` added. A no, or no answer, ends the task.88 Do not add `--proceed` on your own, and do not reuse an earlier yes for a changed script, model,89 voice or setting: run step 1 again.9091A request identical to an earlier one (text, voice, model, settings) is served from the cache in92the plugin data directory: the script says so, sends nothing, needs no key and no `--proceed`, and93exits 0. `--no-cache` forces a new call, which goes through both steps above.9495The models, their limits, and whether each is confirmed on the timed endpoint are the script's96`MODELS` table. `--setting` takes the voice settings the script names in its `--help`. Where to read the97live ElevenLabs specifics (models, script-writing guidance, voice cloning, pricing) is98[reference/elevenlabs.md](../../reference/elevenlabs.md).99100- **Exit 0:** report the audio path with its length, and the `words.json` path, and say when the101 audio came from the cache.102- **Exit 3:** the statement was shown and nothing was sent. Ask, as above.103- **Exit 4:** the organization's egress floor forbids this backend (`SPEECH_EGRESS_FLOOR` is104 set in the environment, usually from managed settings). Report the reason as written, use kokoro105 if the user agrees, and do not try to unset the variable.106- **Exit 2:** no key: `ELEVENLABS_API_KEY` is unset and `vault-exec` is absent or could not supply107 the secret. Report the message as written; it names the remedy.108- **Exit 1:** report the error, such as a rejected key, a script over the model's limit, or an109 empty audio reply.110111## Outputs112113- `narration.wav`: 24 kHz mono, 16-bit PCM.114- `words.json`: `audio`, `sample_rate`, `duration`, `backend`, `voice`, `speed` (kokoro) or `model`,115 `voice_settings`, `request_id`, `character_cost` and `cached` (elevenlabs), and `words`, a list116 with one `{word, start, end}` per whitespace-separated token of the script, in script order. A117 kokoro token with only punctuation, such as a dash, spans its pause. ElevenLabs reports a time for every character, and a word spans its first to its last character.118119## Next120121/harness-ops:prerequisites122123When the run stopped with exit 2, it lists the declared tools this machine lacks.124125## Gotchas126127- Never read, print or pass `ELEVENLABS_API_KEY` yourself. `elevenlabs.py` reads it from the128 environment, and no command, message or file you write carries its value.129- espeak-ng is GPL-3.0. The user installs it. Never install it, download it, or suggest a130 package that bundles it.131- The first run of a session loads a 325 MB model. On a desktop CPU the model makes audio faster132 than real time (about 0.4 s of compute for each second of audio, measured on a 32-thread x86133 CPU).134- Each word is phonemized on its own, so a function word can carry more stress than it would in135 running speech. Rewrite the sentence if one sounds wrong.