Script Syntax Guide

Use this guide while editing your LongStories script. The same rules are used by the script reviewer to check whether your script is formatted correctly.

Colors in the editor match each script type: character dialogue, narration, visual beats, and speech breaks.

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.

Keep speaker labels short, usually 1 to 4 words. Speaker labels are not spoken aloud; only the dialogue after the colon is read.

Good labels:

Professor Time:
Girl Maria:
john:
john the great:
Male Roman Citizen:
Female General:

Avoid sentence punctuation in labels:

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

Not every colon means dialogue. If the text before the colon is a full sentence or a long phrase, LongStories may treat it as narration instead of a character label.

Narration

Use narration for anything the narrator should read aloud.

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

Lines without a character label are narration.

Important: Anything that is not a valid visual beat or cue line may be read aloud. Do not place private notes, camera instructions, or scene directions in narration unless you want them spoken.

Visual Beats

Use visual beats when you want a silent visual moment.

[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]

Visual beats are useful for pauses, scene transitions, cinematic moments, and actions that should be seen instead of spoken.

Use durations between 2 and 10 seconds.

Good examples:

[visual beat: Girl Maria looks up as the classroom transforms into ancient Rome | 4s]
[visual beat: Roman soldiers march through the stone gate | 5s]

Avoid unclear or incomplete beats:

[visual beat: she looks around | 1s]
[visual beat: camera]
[visual beat: battle]

Better:

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

Speech Breaks

Use speech breaks when you want a short pause inside spoken narration or dialogue.

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

Format:

<break time="1s"/>

Speech breaks should stay inside spoken text. Do not put them on their own line.

Use speech breaks for short pauses only. For longer visual pauses, use a visual beat instead.

Quick Checklist

Before generating, check:

• Character dialogue uses Character Name: Dialogue.
• Speaker labels are short, usually 1 to 4 words.
• Narration lines are meant to be spoken aloud.
• Visual beats use [visual beat: description | 4s].
• Visual beats are between 2 and 10 seconds.
• Speech breaks are inline, like <break time="1s"/>.
• No private notes or visual directions are accidentally written as spoken narration.

Updated on: 06/05/2026