Script Syntax Guide

Use this guide while editing your LongStories script. The script reviewer uses the same checklist to grade your script, so a script that follows these rules will pass review.

The editor highlights each element as you type — that's your fastest feedback loop:

• Sky blue — spoken text (narration and dialogue)
• Violet — speaker labels (not spoken)
• Green — valid visual beats (not spoken)
• Gray — break tags (not spoken)

The rule of thumb: anything highlighted blue will be read aloud. If a visual beat shows blue instead of green, it's malformed — fix it or the narrator will read it out.

Character dialogue

Use character dialogue when a specific character should speak.

Professor Time: Welcome to the lecture!
Girl Maria: Thanks, I'm excited to learn.
Male Roman Citizen: The gates are open.
Female General: Hold the line.

Format:

Character Name: Dialogue goes here.

A speaker label must be 1 to 4 words with no sentence punctuation (. ! ? ;). Capitalization doesn't matter — john: works fine. The label itself is never spoken; only the text after the colon is read.

These labels won't work — the whole line gets treated as narration and read aloud:

Guide?: Are you listening?
The brave hero of the northern kingdom: We must go.

Not every colon means dialogue, and that's by design: if the text before a colon is a full sentence or longer than 4 words, LongStories treats the line as narration. So you can safely write things like "The lesson is simple: never give up." in narration.

Narration

Any line without a speaker label is narration, read aloud by the narrator.

The sun rises over the mountains.
Birds begin their morning songs.
The village slowly wakes as golden light fills the valley.

Important: there are no comments in scripts. Anything that isn't a valid visual beat or break tag will be spoken. Don't put private notes, camera instructions, or scene directions in the script unless you want to hear them in the video — for silent visual direction, use a visual beat.

Visual beats

Use a visual beat for a silent visual moment: pauses, scene transitions, cinematic shots, and actions that should be seen instead of described.

[visual beat: a bird flying over the valley | 4s]
[visual beat: camera pans slowly over the field | 3.5s]
[visual beat: Professor Time opens an ancient book under warm candlelight | 5s]

Format:

[visual beat: what the viewer should see | duration]

The rules:

• The duration is required. A beat without one ([visual beat: a bird flying]) is invalid and will be read aloud.
• Keep durations between 2 and 10 seconds. Shorter than 2s is rejected (the line gets spoken); longer than 10s is cut down to 10.
• Decimals are fine: 3.5s.

Make the description a complete visual instruction — it's what the scene is generated from:

Too vague:  [visual beat: battle | 4s]
Better:     [visual beat: Roman soldiers clash with shields raised at the stone gate | 4s]

Too vague:  [visual beat: she looks around | 4s]
Better:     [visual beat: Girl Maria looks around the ancient Roman marketplace in amazement | 4s]

Speech breaks

Use a break tag for a short pause inside spoken narration or dialogue.

Let me think<break time="1.0s" />about that.
This is important<break time="2.0s" />remember it.
Professor Time: Look closely<break time="1.0s" />the answer is hidden in the map.

Format:

<break time="1.0s" />

Two rules:

• Keep breaks inline, inside a spoken sentence — never on their own line.
• Keep them short — 2 seconds at most. For anything longer, use a visual beat instead.

Quick checklist

Before generating, check:

• Dialogue uses Character Name: Dialogue, with labels of 1–4 words and no punctuation.
• Every visual beat has a duration: [visual beat: description | 4s], between 2 and 10 seconds.
• Every visual beat is highlighted green in the editor — blue means it will be read aloud.
• Break tags are inline and 2 seconds or less: <break time="1.0s" />.
• Nothing you meant as a private note or camera direction is sitting in plain narration.

Updated on: 11/08/2026