Script format

videos/<name>/script.md controls the whole video. The voice is made from it, the word timings are aligned to it, and the agent builds the animation from its scene hints. reelsmith new <name> writes a template.

A complete example#

---
title: Reelsmith in 60 seconds
topic: devtools
date: 2026-09-30
wpm: 170
style: motion
tts_voice: Leda
tts_mode: performance
series: reelsmith-tutorials
episode: 1
---

## Script

### Scene 1
You write one hundred and fifty words.
You get a finished vertical video, with a voice, live subtitles, and motion graphics.

### Scene 2
That is Reelsmith.
> say: "Reelsmith" as one word
It is an open framework for making short videos with a coding agent like Claude Code.

## Voice direction
The narrator is introducing a new open source framework to developers who have never seen it. Confident, not a sales pitch.

## Scene Hints
- Scene 1 (hook): Big numeral "150" counts up, then "words" snaps in. Primitive: Counter + PhoneFrame
- Scene 2 (name reveal): Wordmark assembles letter by letter on "That is Reelsmith". Primitive: Wordmark

Frontmatter#

The block between the two --- lines. Flat key: value lines only. A trailing # comment is stripped. Numbers are read as numbers.

Anything set here beats reelsmith.config.json and the environment. A CLI flag beats the frontmatter. The full order is in Concepts.

## Script: scenes and sentences#

• Each scene is a ### Scene N heading. N starts at 1 and has no gaps.
• Inside a scene, one sentence per line. A line is the unit everything else works with: the TTS clip in sentence mode, the re-record unit for a recorded take, the alignment unit for word timings.
• Each line gets an id s<scene>.<line>: the second line of scene 3 is s3.2. Take analysis and re-records use these ids.
• Blank lines are ignored.
• Any heading other than Scene N ends the current scene.

> cue lines#

A line that starts with > is a note for a human reader, not narration:

> say: "one hundred", not "a hundred"
At 100 input tokens per output token, that prompt is most of your bill.
> [breath]
Renaming a directory with a hundred thousand files can take minutes, because every file gets copied.

• Never spoken, never aligned, never sent to a TTS voice.
• A cue attaches to the sentence below it. Put it on the line above the sentence it describes.
• A > line outside any scene (for example right after the frontmatter) is a file-level note and is ignored.

A TTS voice reads the line itself, so for a TTS video write numbers and symbols the way they should be heard: "one hundred fifty", "script dot md", "Python three eleven". Cues only help a human reader.

Sections after the script#

The parser only reads ### Scene N blocks. Other sections are for people and agents:

Never put a Scene N heading in these sections. The parser treats any Scene N heading, at any level, as spoken.

Length#

• About 150 spoken words is a 60 second short at a normal pace. Aim for 130 to 170.
• Keep each line to about 8 to 16 spoken words, so it can be said in one breath.
• Word counts mean spoken words. "5.5" is "five point five", three words.
• The first line should be 12 spoken words or fewer and say something specific.

Common mistakes#