Zavis Video OS
← All skills
Skill

zavis-narration-director

Write voiceover narration for videos. Load this skill whenever writing the actual words a narrator will say, choosing a narrator profile, or reviewing if narration timing aligns with visuals. Pairs with zavis-story-writer (for the structure) and integrates with packages/pipeline/src/voiceover/profiles.ts. Updated for single-pass narration as the default.

skills/zavis-narration-director/SKILL.md

Zavis Narration Director

You write the words the viewer hears. The story-writer chose what beats happen. The hook-engineer chose how it opens. You choose the exact sentences the narrator speaks.

SINGLE-PASS BY DEFAULT (the most important rule)

Generate the entire video's narration in ONE ElevenLabs API call. NEVER generate it scene-by-scene.

Why:

  • Per-scene calls create unnatural pauses between scenes (each call has its own intro/outro silence)
  • Per-scene calls drift in tonality and energy across scenes (different "takes" of the same voice)
  • Per-scene calls cost N times more in API credits

How: the pipeline has generateContinuousVoiceover() in packages/pipeline/src/voiceover/single-pass.ts. It:

  1. Concatenates all scene narration into one prompt with deliberate punctuation
  2. Calls ElevenLabs /v1/text-to-speech/{voice_id}/with-timestamps once
  3. Receives audio + character-level alignment
  4. Cuts the audio at the exact timestamps where each scene's narration begins/ends
  5. Returns per-scene clips ready for the composition

To enable single-pass for a narrator profile, set `singlePass: true` on it. The "zavis" profile (cloned voice) has it on by default. The pre-built authority, storyteller, etc. profiles have it off — they're per-scene legacy, only kept for backward compatibility.

You should always default to using the "zavis" narrator profile, which is the cloned voice with singlePass: true and tempo: 0.85 (auto-slowdown).

The pause discipline (critical for single-pass narration)

Because the entire script is sent as one prompt, your punctuation IS the directing. ElevenLabs respects:

  • , → ~120ms pause (micro-beat)
  • . → ~280ms pause (sentence beat)
  • ! and ? → ~300ms pause + intonation lift
  • Nothing else — avoid em dashes, ellipses, semicolons in narration text

CRITICAL RULE: no ellipses (`…`) in narration text. The v4 video failed because the pipeline concatenated scenes with … separators, which caused the cloned voice to insert long unnatural pauses, throat clears, and filler sounds. v5 fixed this by using a plain period + space as the scene separator (the single-pass pipeline does this automatically now — you do not need to add any separator yourself, just end each scene's narration with terminal punctuation).

CRITICAL RULE: full sentences, not period splits. v4 also failed because scenes were written like:

First came. G P T one. Then G P T two. Then three. Each one closer to language itself.

That over-splitting caused the cloned voice to pause unnaturally between every fragment, producing a stuttery, broken read. v5 fixed this by writing full, flowing sentences:

A small lab in San Francisco called OpenAI started scaling it up. GPT one. GPT two. GPT three.

The first two sentences carry the ideas; the terminal fragments are INTENTIONAL ("GPT one. GPT two. GPT three.") because they rhyme and build rhythm. Use period-split fragments for deliberate rhythmic effect, not as a default way to pace.

Rule of thumb: your narration should read naturally when you say it out loud. If it feels clipped or staccato when YOU read it, the narrator will sound the same.

The non-negotiable rule

Narration is parallel narrative, not slide-reading.

If the on-screen text says "ChatGPT launched in November 2022," the narrator must NOT say "ChatGPT launched in November 2022." That's wasted bandwidth. The narrator should add what the visual cannot show — context, consequence, contrast, emotion.

The viewer is using two channels (eyes + ears). Two channels with the same content = one channel of value. Two channels with complementary content = three channels of value (because the brain integrates them).

Sentence-level rules

  1. Short sentences. Most under 9 words. If a sentence is over 14 words, break it.
  2. One idea per sentence. Don't compound.
  3. Front-load the surprise. Put the unexpected word first or last, never middle.
  4. Periods over commas. A period gives the listener a beat. A comma keeps them running.
  5. Avoid filler clauses. "It is interesting to note that" → cut. "What's important here is" → cut. Just say the thing.
  6. No three-syllable words when a one-syllable word works. "Utilize" → "use." "Implement" → "do." "Initiate" → "start." "Subsequently" → "then." "Approximately" → "about."
  7. Read it aloud. If you stumble, the narrator will too. Rewrite.

Pacing rules

ElevenLabs narrators (in this project) speak at roughly:

  • 140 words/minute for "authority" and "executive" profiles (slower, gravitas)
  • 160 words/minute for "analyst" (precise, neutral)
  • 180 words/minute for "presenter" (energetic)
  • 150 words/minute for "storyteller" (conversational)

For a 90-second video with the "authority" narrator:

  • Maximum total narration ≈ 140 × 1.5 = 210 words
  • Realistic with breathing pauses ≈ 150-180 words
  • Aim for 160 words and you have natural breathing room

If your script narration is over 200 words for 90 seconds, it WILL sound rushed. Cut.

Pause discipline

Use periods for beats, commas for micro-beats. Do NOT use ellipses or "..." (see v4 failure note above). If you need a longer pause, structure it as a standalone short sentence — the terminal period IS the pause engine.

Example of pause discipline:

"And then on November thirtieth, twenty twenty-two, the whole world met ChatGPT."

One flowing sentence. The commas give natural breath; the period at the end gives a landing beat. The single-pass pipeline joins this with the next scene automatically.

Don't do this (v4 mistake):

"On November thirtieth. Twenty twenty-two. The world met ChatGPT."
The cloned voice stutters at every period and the phrasing loses momentum.

When period-splits ARE allowed: for list rhythm or deliberate staccato crescendos.

"GPT one. GPT two. GPT three."
Here the fragments are the content — three beats, not a sentence being hacked up.

ElevenLabs voice settings (the "zavis" profile)

For v5 the cloned voice uses:

  • stability: 0.78 — high, for consistent scripted energy (NOT the 0.55 of v4 which drifted)
  • similarity_boost: 0.9 — high, to lock the voice identity
  • style: 0.15 — low, to minimize filler pauses and breath sounds
  • use_speaker_boost: true
  • tempo: 0.85 — post-processed via ffmpeg atempo for cinematic pacing

If the narration still sounds stuttery, the fix is usually in the text (period-split fragments) not the settings.

Emphasis discipline

ElevenLabs doesn't reliably honor SSML emphasis tags. Instead, get emphasis from word choice and sentence structure:

  • Front-loaded surprise: "Eight pages. That changed everything."
  • One-word sentences: "Five days. A million people. Two months. A hundred million."
  • Repetition: "More users. More uses. More stakes."
  • Specificity: never "millions," always "a hundred million"

The forbidden words list (in narration)

Cut these on sight:

  • "Let's dive in"
  • "Today we'll talk about"
  • "In this video"
  • "At the end of the day"
  • "It's important to remember"
  • "The thing is"
  • "Basically"
  • "As you can see"
  • "Here's the thing"
  • "Without further ado"
  • Anything that addresses the viewer as "you guys"
  • Anything that says "AI" instead of being more specific (use "language models," "machine learning," "image generation," etc. when accuracy matters — but use "AI" when the cultural shorthand IS the point)

Narrator profile selection

See packages/pipeline/src/voiceover/profiles.ts for the full list. The default for ALL Zavis content is `zavis` — the cloned voice from the Instagram reel reference. It is single-pass-enabled and pitch-preserved auto-slowed via tempo: 0.85.

| Profile | When to use | Single-pass | |---|---|---| | `zavis` (cloned, default) | All Zavis branded content — evolution stories, brand films, founder stories, Instagram, YouTube | ✓ | | authority (Adam) | Legacy — only if you specifically need Bloomberg-anchor gravitas | ✗ | | storyteller (Bella) | Legacy — only if you need a warm female narrator | ✗ | | analyst (Arnold) | Legacy — data-heavy comparisons | ✗ | | presenter (Antoni) | Legacy — high-energy ad reads | ✗ | | executive (Rachel) | Legacy — investor/executive content | ✗ |

If you're not sure, use zavis. Always.

Timing alignment with visuals

The narrator must NEVER:

  • Start speaking before the visual is on screen
  • Finish speaking after the visual has changed
  • Say a key word more than 200ms after the visual reveals it
  • Say a key word more than 200ms before the visual shows it

If your script has a moment "the camera reveals the iPhone" and the narrator says "and then came the iPhone" 1 second later, the viewer is bored for 1 second. That's a critical issue.

How to write narration for a script

  1. Read the visual beat sheet first (from the story-writer). Mark which beats are dialogue-driven vs visual-only.
  2. Allocate words: with 160 wpm budget, plan how many words go to each beat. Hook gets ~5-10. Body beats get ~25-35 each. Landing gets ~5-10.
  3. Write the body first, hook second, landing third. (Body grounds the voice; hook should match the body's energy; landing should rhyme with the hook's promise.)
  4. Time-check every sentence: read it aloud at the narrator's pace. Cut anything that doesn't fit.
  5. Test the pause map: where does the narrator breathe? Mark with periods.
  6. Audit against the forbidden words list.
  7. Audit against the parallel-narrative rule: nothing the narrator says should be visible on screen at the same moment.

The first sentence rule

The first sentence the narrator speaks (after any source-audio hook) sets the entire emotional tone of the video. It must:

  • Be under 8 words
  • Contain a concrete noun
  • Open a curiosity loop
  • Sound like something a person would actually say to a friend, not an AI assistant

Examples that work:

  • "Long before ChatGPT, there was a quiet idea."
  • "The robots are not coming. They're here."
  • "Eight pages changed everything."

Examples that fail:

  • "Today we'll explore the fascinating history of artificial intelligence."
  • "AI has come a long way in recent years."
  • "Have you ever wondered how we got here?"