# Generate Voiceover

> Synthesize a spoken voiceover for the video from the narration script via HeyGen TTS. Use after generate-script and before customize-composition. Runs by default for every video unless the user asked for no narration.

- Skill: `heygen-com/generate-voiceover` (Agent Skill)
- Install (CLI): `npx skillmds@latest add heygen-com/generate-voiceover`
- Raw SKILL.md: https://api.skillmd.com/api/skills/heygen-com/generate-voiceover/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: heygen-com (https://skillmd.com/u/heygen-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/heygen-com/generate-voiceover

---


# Generate the voiceover

Every video gets a spoken voiceover **by default** — it's the single biggest
lift in perceived quality. You turn the narration script into audio with
HeyGen's text-to-speech, then hand the audio URL to the composition.

**Skip this step only if** the user's prompt explicitly asks for no narration —
"no voiceover", "silent", "ambient only", "music only", "text only". When you
skip, leave `voiceover_url` empty and tell the user the video is silent.

## Inputs

- The **narration script** from generate-script (a short spoken line or two,
  sized to the starter's duration — distinct from the on-screen copy).
- The chosen composition's `manifest.json`, which carries a
  `recommended_voice_id` (the default voice for that starter).

## Steps

1. **Pick a voice.** Use the starter's `recommended_voice_id` unless the user's
   prompt gives tone direction — then override from the catalog below.
2. **Synthesize** with the TTS helper:

   ```bash
   set +x
   RESULT=$(python3 /.agents/workspace/scripts/tts_client.py \
     "<narration script>" "<voice_id>")
   AUDIO_URL=$(echo "$RESULT" | jq -r '.audio_url')
   DURATION=$(echo "$RESULT" | jq -r '.duration')
   ```

   `tts_client.py` calls `POST /v3/voices/speech` and prints
   `{audio_url, duration, voice_id, word_timestamps}`. The sandbox proxy injects
   the HeyGen key — you pass no credential. (Dev test: prefix with
   `HEYGEN_API_URL=https://api.dev.heygen.com`.)
3. **Check the duration against the starter.** Compare `DURATION` to the
   starter's `duration_seconds` (from its manifest). The audio must fit:
   - `DURATION` ≤ starter duration → good, use it.
   - `DURATION` > starter duration → **do not truncate.** Trim the narration
     script (fewer words / shorter sentences) and re-synthesize until it fits,
     with ~0.3s of headroom. A tight, punchy line beats a rushed or cut-off one.
4. **Save the audio URL** for customize-composition:

   ```bash
   echo -n "$AUDIO_URL" > /.agents/workspace/output/voiceover_url.txt
   ```

   (If you skipped narration, write an empty file or skip this — customize will
   strip the audio element.)

## Voice catalog (starfish engine)

Pick by tone. Tones are a starting point — the per-starter `recommended_voice_id`
is the default; override only on explicit prompt direction.

| Voice | `voice_id` | Tone — use for |
|---|---|---|
| Luna Bright (f) | `2b0124724e144eedba61ecb590d6c266` | Bright, friendly — consumer apps, social promos |
| Smooth Dev (m) | `07d2ba65847541feb97abc9b60181555` | Smooth, confident — product trailers, narration |
| Marcus – Professional (m) | `0f50a7a5577e4cd583ba738094956899` | Warm, clear, professional — explainers, how-it-works, B2B |
| Peaceful Paige (f) | `035ec8f52ec247cdbed5f3bf9f7991ef` | Calm, soft, soothing — wellness, meditation, premium calm |
| Energetic Mikey (m) | `25a40947b46942c1a8e5bd329074bba2` | Upbeat, punchy, high-energy — launches, hype, social |

Override cues: "calm / relaxing / meditative / soothing" → Peaceful Paige ·
"energetic / exciting / hype / launch / punchy" → Energetic Mikey · "friendly /
fun / approachable" → Luna Bright · "professional / corporate / clear" →
Marcus · "smooth / cinematic / confident" → Smooth Dev.

(These are public starfish-engine voices; if a `voice_id` ever fails, list
current options with `GET /v3/voices?engine=starfish`.)

## Output of this step

- `/.agents/workspace/output/voiceover_url.txt` — the synthesized audio URL.

The renderer reads the `<audio>` `src` as a static HTML attribute, so this URL
isn't a runtime variable — customize-composition bakes it into the staged
composition's HTML (via `apply_voiceover.py`). Then move to
**customize-composition**.