v0.9 (Public Draft)

Author: Nicola Marra de Scisciolo
Status: Public Draft
Version: 0.9
Date: April 2026
License: CC BY-ND 4.0

About CueScript

CueScript is a plain-text technical cue notation syntax for embedding standardized technical cues within readable scripts. It allows production coordinators, directors, and technical teams to annotate scripts with cue information while keeping them fully readable in any text editor or Fountain-compatible application. Structured cue interpretation is handled at the parser level.

CueScript follows the plain-text annotation philosophy established by Markdown and adopted by Fountain — structured meaning embedded in readable text using only standard characters.

CueScript is a universal format that works across any production context requiring technical notation: theatre, film, television, live events, broadcast, podcasts, and more. The same syntax serves different domains through specialized applications built on the open format.

File Format

CueScript documents are plain UTF-8 text files. They can be created and edited in any text editor. In Fountain-compatible applications, cues render as readable action lines — no modification required.

File Extensions

CueScript documents use one of two extensions:

.fountain — Standard Fountain extension. Use when working within the Fountain ecosystem or sharing with screenwriters, directors, and actors. Opens in any Fountain-compatible application.
.cuescript — CueScript-specific extension. Use when creating production-focused documents or working primarily in CueScript-aware tools. Signals that the file contains technical cue notation.

Both extensions contain identical content and are fully interchangeable. The choice of extension signals intent and default application behavior, not format differences.

Note: CueScript tools may accept .txt files as input when the content conforms to CueScript syntax, but .txt is not a recognized CueScript file extension.

Design Principles

Plain-Text & Fountain-Compatible — CueScript files are plain UTF-8 text that open in any Fountain-compatible editor, where cues render as readable action lines. CueScript notation is an independent syntax layer, not a Fountain extension.
Domain-Agnostic — Universal format that works across theatre, film, live events, broadcast, and any production context
Non-Invasive — Doesn’t interfere with screenplay writing or reading experience
Progressive Enhancement — Start simple, add detail as production develops
Parser-Friendly — Clear, unambiguous patterns for reliable automated processing
Human-Readable — Cues are immediately understandable without specialized tools
Open & Extensible — Custom cue types and metadata keys welcome; specialized tools can build on the open format

Core Syntax

Basic Cue Format

CUETYPE (LABEL NUMBER) TRIGGER [METADATA]: DESCRIPTION

A cue must be written on a single line. Line breaks within a cue are not permitted and will cause a parse error.

Components

CUETYPE: Production element identifier (typically 2-6 uppercase letters)
- Must be uppercase letters (A-Z) only
- Single word, no spaces
- Based on production discipline conventions
- Examples: LX, SOUND, CAMERA, VIDEO, AUDIO
(LABEL NUMBER): The cue identifier block, enclosed in parentheses. LABEL and NUMBER must be separated by at least one space. The opening parenthesis follows the CUETYPE with optional whitespace. Parsers should be flexible with extra whitespace inside the parentheses.
```
(cue 5)      → Valid
(cue  5)     → Valid (extra space tolerated)
( cue 5)     → Valid (extra space tolerated)
(cue 5 )     → Valid (extra space tolerated)
(cue5)       → Invalid (missing space between LABEL and NUMBER)
```
LABEL: Descriptor for the cue identifier (typically “cue”, “shot”, “setup”, “take”)
- Single lowercase word, no spaces
- Pattern: One or more lowercase letters [a-z]+
- Common labels: cue, shot, setup, take, q
- Consistency rule: Each CUETYPE must use the same LABEL throughout a document
- Examples:
  - CAMERA (shot 5) - if CAMERA uses “shot”, all CAMERA cues must use “shot”
  - LIGHT (setup 3) - if LIGHT uses “setup”, all LIGHT cues must use “setup”
- Default/recommended: cue for all types
NUMBER: Cue identifier supporting insertions
- Pattern A (Letter suffix): [0-9]+[a-z]*
  - Examples: 1, 12, 5a, 23b, 100
  - Common practice: Insert 5a between 5 and 6
- Pattern B (Decimal): [0-9]+\.[0-9]+
  - Examples: 1.5, 2.5, 10.5
  - Alternative practice: Insert 5.5 between 5 and 6
- Pattern C (Prefixed): [A-Z][0-9]+[a-z]*
  - Examples: A1, V3, A5a, L12b
  - Common in workflows where the cue type is embedded in the number identifier
- Note: Choose ONE pattern per production. Mixing patterns within the same cue type may cause sorting confusion.
- Combined patterns (e.g., 5.5a) are not currently supported pending validation of real-world usage.
TRIGGER (optional): When/how the cue is triggered
- Composed of two parts, separated by a single space: a keyword followed by a value
- Keyword: a single lowercase word. Standard keywords are on, after, with — custom keywords are permitted for domain-specific workflows
- Value: depends on the keyword
  - Dialogue: quoted string, e.g. on "Juliet" (quotes required)
  - Time delay: numeric value with units, e.g. after 3s
  - Action: free-form text, e.g. with door slam
- If omitted, cue trigger is implicit from context
- Important: Dialogue triggers MUST use quotes to avoid ambiguity with descriptions
METADATA (optional): Technical implementation details in square brackets, immediately before the colon. See Metadata section for full reference.
- Format: [key=value, key2=value2]
- Example: [fade=3s, level=80%]
DESCRIPTION: Human-readable description of the cue action
- Free-form text
- Should describe what happens, not technical implementation details
- Keep concise but clear

Examples

# Theatre (using "cue")
SQ (cue 5): Door slams shut
LX (cue 12a) on "Juliet": Fade to blackout

# Film (using natural terminology)
CAMERA (shot 3): Close-up on John's face
LIGHT (setup 2a) after establishing: Key light from left
SOUND (take 1): Boom from above

# Live Events (using "cue")
VIDEO (cue 3) with speaker entrance: Switch to camera 2
AUDIO (cue 7): Fade music under speech

# Broadcast (using "cue")
GRAPHICS (cue 1): Display lower third - guest name
CAMERA (cue 5) on host question: Wide shot of panel

# Mixed in same document (valid - different CUETYPES)
CAMERA (shot 12): Close-up
LIGHT (cue 5): Key from left
SOUND (take 3): Dialogue recording

# Invalid - inconsistent within same CUETYPE
CAMERA (shot 1): Wide
CAMERA (cue 2): Close    ← ERROR: CAMERA already uses "shot"

Metadata (Optional Technical Details)

CueScript supports optional metadata for technical implementation. Metadata is added in square brackets immediately before the colon:

CUETYPE (cue NUMBER) [key=value, key2=value2]: DESCRIPTION

Syntax Rules

Enclosed in square brackets [ ], placed immediately before the colon
Key: a single lowercase word — no spaces, no special characters ([a-z]+)
Key-value separator: = with no surrounding spaces
Value: see value rules below
Multiple key-value pairs: separated by a comma , — the comma is the required separator; a single space after the comma is optional but recommended for readability: [fade=3s, level=80%]
Parsers MUST accept commas with or without trailing space: [fade=3s,level=80%] and [fade=3s, level=80%] are both valid
Custom keys are always allowed — any production can define domain-specific metadata

Value Rules

Value type	Quotes	Examples
Numeric with units	Never	`fade=3s`, `level=80%`, `duration=2m`, `prewait=500ms`
Numeric (pure)	Never	`level=0.5`
Simple string (single word, no special characters)	Optional	`fade=slow` or `fade="slow"`, `transition=cut` or `transition="cut"`
String with spaces or special characters	Required	`file="my sound.wav"`, `note="check with LD"`

Case: Keys must be lowercase ([a-z]+). Values preserve case as written — uppercase and mixed-case values are valid where domain conventions require them (e.g., frame=CU, frame=MCU, target=Cam2).

Standard Metadata Keys

CueScript defines common metadata keys that work across domains. Custom keys are always allowed — any production can define domain-specific metadata.

Universal Timing & Control

duration - How long the cue takes to execute (e.g., 5s, 2m, 45s)
fade - Fade/transition time (e.g., 3s, 500ms)
prewait - Delay before cue starts (e.g., 1s, 2s)
postwait - Delay after cue completes (e.g., 2s)
warn - Advance warning time for coordination (e.g., 30s, 2m)

Common Technical Parameters

level - Intensity/volume (e.g., 80%, 0.5, -6dB)
file - Media file reference (e.g., "thunder.wav", "intro.mp4")
target - Specific equipment/output (e.g., channel_5, cam2, speaker_left)
source - Input source (e.g., mic3, playback, laptop)
type - Variant or category (e.g., key, bounce, practical)

Theatre-Specific Examples

curve - Lighting fade curve (e.g., log, linear)
intensity - Light level (e.g., full, 50%)
position - Followspot position (e.g., center_stage, downstage_left)

Film-Specific Examples

lens - Camera lens (e.g., 50mm, wide)
angle - Camera angle (e.g., low, high, dutch)
frame - Shot framing (e.g., CU, MCU, WS, ECU)
movement - Camera movement (e.g., tracking, dolly, handheld)
plate - VFX plate type (e.g., green, blue, clean)
element - VFX element (e.g., background, foreground)

Live Event/Broadcast-Specific Examples

transition - Transition type (e.g., cut, dissolve, wipe)
preset - Equipment preset (e.g., wide_shot, single, panel)
template - Graphics template (e.g., lower_third, bug, full_screen)
position - Graphics position (e.g., lower_third, corner, center)
compression - Audio compression (e.g., light, medium, heavy)
gate - Audio gate threshold (e.g., -20dB)

Documentation

note - Production note attached to the cue (e.g., note="check with LD before show"). Parsers MAY expose or suppress this value in exported output. To hide content from formatted output entirely, use Fountain’s boneyard syntax [[ ]] — see Notes (Hidden Cues).

Format Rules

Time Values

Units MUST be specified for numeric values
Valid units: s (seconds), m (minutes), ms (milliseconds), h (hours)
Descriptive values also valid: slow, fast, instant (quotes optional)

Examples:

→ Valid   fade=3s
→ Valid   fade=slow
→ Valid   fade="slow"
→ Invalid fade=3

Level/Intensity Values

Percentage: 80%, 50%
Decimal: 0.5, 0.8
Decibels: -6dB, -3dB
Descriptive: full, half, dim (quotes optional)

String Values

Simple single-word values: quotes optional — transition=cut or transition="cut"
Values with spaces or special characters: quotes required — file="my sound.wav"

Boolean Values

Use true/false or just the key name for true
Examples: loop=true, autofollow=false

Metadata Examples

TRIGGER and METADATA are independent and fully combinable. The examples below show metadata alone for clarity, but any cue may include both.

Theatre

LX (cue 5) [fade=3s]: Fade to blackout
LX (cue 12) on "Juliet" [fade=3s]: Fade to blackout
SQ (cue 2) [file="thunder.wav", level=-3dB]: Thunder crash
SQ (cue 3) after 2s [file="thunder.wav", level=-3dB]: Thunder crash
FLY (cue 1) [warn=2m, duration=30s]: Bring in chandelier
SPOT (cue 7) [target=spot_1, level=80%]: Pick up JOHN

Film

CAMERA (setup 12) [lens=50mm, angle=low]: Close-up on actor
CAMERA (setup 13) with dolly [lens=50mm, angle=low]: Push in on actor
LIGHT (setup 3) [type=key, direction=left, intensity=2k]: Key light
SOUND (take 2) [boom=overhead, wind=reduce]: Dialogue recording
VFX (cue 8) [plate=green, element=background]: Composite shot

Live Events

VIDEO (cue 3) [source=cam2, transition=cut]: Switch to speaker cam
VIDEO (cue 4) with speaker entrance [source=cam2, transition=cut]: Switch to speaker cam
AUDIO (cue 7) [fade=2s, level=-6dB]: Music under speech
GRAPHICS (cue 1) [duration=8s, position=lower_third]: Guest name
CAMERA (cue 5) [preset=wide, speed=slow]: Audience pan

Broadcast

PLAYBACK (cue 1) [file="package_intro.mp4", audio=stereo]: Roll intro
CAMERA (cue 3) [transition=dissolve, duration=1s]: Dissolve to camera 2
CAMERA (cue 4) on "and now" [transition=dissolve, duration=1s]: Dissolve to camera 2
GRAPHICS (cue 4) [template=bug, position=corner]: Network logo
AUDIO (cue 2) [source=mic3, gate=-20dB]: Talent microphone

Descriptive values also valid

LX (cue 12) [fade=slow, target=downstage]: Warm glow
VIDEO (cue 8) [transition=fast]: Quick cut
AUDIO (cue 3) [level=full]: Music at full volume

Progressive Enhancement Workflow

TRIGGER and METADATA are both optional. A cue can start as a minimal placeholder and grow richer as production decisions are made.

Phase 1: Initial Writing/Planning

LX (cue 5):
CAMERA (cue 12):

Mark where cues happen, nothing more. Description may be left empty as a placeholder — parsers supporting authoring workflows MAY accept this form and SHOULD warn rather than error.

LX (cue 5) on "Juliet": Fade to blackout
CAMERA (cue 12) [lens=50mm]: Close-up on actor's face

Add triggers (when cues fire) and initial technical decisions as they emerge. Still fully readable.

Phase 3: Technical Preparation/Production

LX (cue 5) on "Juliet" [fade=3s, warn=30s, target=all]: Fade to blackout
CAMERA (cue 12) [lens=50mm, angle=low, frame=CU]: Close-up on actor's face

Production team adds full implementation details. Export-ready for control systems.

Key principle: A cue is valid at every stage. Add detail when needed, not before.

Standby/Warning System

CueScript uses the warn metadata to indicate when production coordinators should give advance notice to operators:

LX (cue 5) on "Juliet" [warn=30s, fade=3s]: Fade to blackout
VIDEO (cue 12) [warn=1m]: Roll pre-recorded package
CAMERA (cue 8) [warn=15s]: Crane move to overhead

How it works

warn=30s tells parser to generate an advance notice 30 seconds before the cue
No warn metadata = no advance notice needed (simple cues can execute immediately)
Parser calculates placement based on script timing and trigger point

Example — What a parser might generate

Source

LX (cue 5) on "Juliet" [warn=30s, fade=3s]: Fade to blackout

Generated calling script view

[~30 seconds before "Juliet" line]
┌─ STANDBY: LX 5
│
│  ... script continues ...
│
└─ [On "Juliet"]
   LX (cue 5) GO → Fade to blackout (3s fade)

Not every cue needs advance warning. Simple cues (like quick audio transitions or camera cuts) may not require warn metadata. Complex cues (like crane moves, scenic automation, or multi-source video setups) typically benefit from longer advance warnings.

Common Cue Types

CueScript does not restrict cue types. Any uppercase identifier is valid. Productions define cue types based on their specific needs and workflows.

Below are common conventions from different production contexts. These are suggestions, not requirements.

Theatre Productions Commonly Use

Type	Full Name	Description	Example
`LX`	Lighting/Electrics	Lighting cues (UK/International)	`LX (cue 10): Sunset fade`
`LIGHT`	Lighting	Lighting cues (US alternative)	`LIGHT (cue 10): Sunset fade`
`SQ`	Sound	Sound effects and audio playback	`SQ (cue 1): Thunder crash`
`SOUND`	Sound	Sound cues (alternative)	`SOUND (cue 1): Thunder crash`
`MQ`	Music	Musical cues and underscoring	`MQ (cue 2): Opening theme`
`MUSIC`	Music	Music cues (alternative)	`MUSIC (cue 2): Opening theme`
`FLY`	Flys	Fly system/flying scenery	`FLY (cue 3): Bring in chandelier`
`SPOT`	Followspot	Follow spotlight operation	`SPOT (cue 7): Pick up JOHN`
`AUTO`	Automation	Automated scenery, turntables, lifts	`AUTO (cue 4): Revolve 180 degrees`
`VIDEO`	Video	Video playback	`VIDEO (cue 3): Display countdown`
`PROJ`	Projection	Projection mapping	`PROJ (cue 5): Show title card`

Film Productions Commonly Use

Type	Full Name	Description	Example
`CAMERA`	Camera	Camera setup and movement	`CAMERA (setup 2): Dolly in on actor`
`LIGHT`	Lighting	Lighting setup	`LIGHT (setup 2): Natural window light`
`SOUND`	Sound	Sound recording notes	`SOUND (take 1): Boom from above`
`VFX`	Visual Effects	VFX elements and plates	`VFX (cue 12): Green screen background`

Live Events Commonly Use

Type	Full Name	Description	Example
`VIDEO`	Video	Video switching and playback	`VIDEO (cue 5): Switch to camera 3`
`CAMERA`	Camera	Camera selection	`CAMERA (cue 2): Isolate speaker`
`AUDIO`	Audio	Audio mixing and playback	`AUDIO (cue 7): Mics up for panel`
`GRAPHICS`	Graphics	Lower thirds, titles	`GRAPHICS (cue 1): Display guest name`
`LIGHT`	Lighting	Stage lighting cues	`LIGHT (cue 4): Follow spot on host`
`PLAYBACK`	Playback	Media playback	`PLAYBACK (cue 3): Roll intro video`

Broadcast/Streaming Commonly Use

Type	Full Name	Description	Example
`CAMERA`	Camera	Camera switching	`CAMERA (cue 8): Cut to camera 2`
`GRAPHICS`	Graphics	On-screen graphics	`GRAPHICS (cue 3): Lower third - name`
`AUDIO`	Audio	Audio levels and sources	`AUDIO (cue 5): Fade music bed`
`PLAYBACK`	Playback	Pre-recorded content	`PLAYBACK (cue 1): Roll package`

Custom Cue Types

Custom cue types allow creative and extended uses of the format beyond standard operational workflows — from department-specific coordination to director’s annotations. Productions can define any cue type that fits their needs.

HAZE - Atmospheric effects
PYRO - Pyrotechnic effects
TRAP - Stage trap operations
DRONE - Drone camera shots
MIC - Microphone cues
PRAC - Practical effects
TALENT - Talent/actor direction
CREW - Crew position changes
SHOT - Individual shot notation (film)
STUNT - Stunt coordination (film)
MAKEUP - Makeup and prosthetics (film)
WARDROBE - Costume changes (film)
TRANSITION - Wipes, dissolves (broadcast)

The format is completely open — use whatever cue types make sense for your production.

Software Compatibility

CueScript documents are plain UTF-8 text files and can be opened and edited in any text editor, word processor, or screenplay application. In Fountain-compatible applications, cues render as readable action lines without modification. CueScript-aware tools add the ability to recognize and process the technical cue notation.

Fountain Compatibility Patterns

CueScript cues can be written using three Fountain constructs to control how they appear in Fountain-compatible applications.

1. Action Lines (Visible Cues)

In a Fountain parser, CueScript cues that appear as plain lines are treated as action lines and rendered as readable text:

John walks to the door.

SQ (cue 5): Door slams shut

He jumps back in surprise.

Result: Cue appears in formatted screenplay, visible to all readers.

Fountain Compatibility: A standard Fountain parser treats this as an action line. A CueScript-aware parser recognizes it as a technical cue.

2. Forced Action (Guaranteed Visibility)

Use Fountain’s ! prefix to force a line to be treated as action:

!SQ (cue 5): Door slams shut

Use when: You need to ensure the cue appears in formatted output even if it might otherwise be interpreted differently.

3. Notes (Hidden Cues)

Use Fountain’s note syntax [[ ]] for cues that should only be visible to technical staff:

John walks to the door.

[[SQ (cue 1): Background ambience loop]]

SQ (cue 5): Door slams shut

Result: cue 1 is parsed by CueScript tools but invisible in formatted screenplay. cue 5 is visible to all readers.

Use for

Atmospheric/background cues that don’t need to be in the reading script
Technical notes for operators
Cues that clutter the reading experience

Final Draft — A Practical Example

Final Draft is widely used in the industry, so CueScript compatibility was tested during the development of this specification. Writing cues as Action elements worked without issues and the syntax was preserved correctly. This is documented here as a practical example — not as an officially supported integration.

INT. MANSION - NIGHT

John enters cautiously.

SQ (cue 2): Distant thunder

He approaches the door.

SQ (cue 3): Door slams shut

LX (cue 4): Lights flicker

CueScript-aware tools that read the .fdx format natively (such as QBook) can parse cues directly from Final Draft files without any intermediate export step.

This was also tested by exporting from Final Draft as plain text and opening the result in QBook — CueScript syntax was preserved correctly.

Complete Examples

Theatre Production Example

INT. HAUNTED MANSION - NIGHT

John enters cautiously. The floorboards creak under his feet.

[[SQ (cue 1) [file="ambience_mansion.wav", level=0.3, loop=true]: Background ambience]]

He pauses, listening.

SQ (cue 2) [level=-6dB]: Distant thunder

He approaches the large wooden door.

!SQ (cue 3) on door contact: Door slams shut

LX (cue 4) with door slam [duration=500ms]: Lights flicker

John spins around, startled.

MQ (cue 5) [prewait=1s, fade=2s]: Tension underscore begins

JOHN
Who's there?

[[SPOT (cue 6) [warn=30s, target=spot_1]: Isolate John center stage]]

No response. Only silence.

LX (cue 7) [fade=5s, warn=30s]: Slow fade to blackout

FADE OUT.

Film Production Example

EXT. CITY STREET - DAY

Traffic moves past. Sarah walks briskly down the sidewalk.

CAMERA (shot 1) [lens=35mm, movement=tracking]: Follow Sarah medium shot

She glances over her shoulder nervously.

CAMERA (shot 2) [lens=85mm, angle=low, frame=CU]: Close-up - Sarah's eyes

A black car pulls up alongside her.

SOUND (take 1) [note="Capture car approach separately"]: Car engine close-up

Sarah stops. The window rolls down.

CAMERA (shot 3) [lens=50mm, angle=interior]: Through car window to driver

MYSTERIOUS MAN
Get in.

LIGHT (setup 2) [type=bounce, direction=left]: Soften shadows on actor

Sarah hesitates, then opens the door.

VFX (cue 4) [plate=green, element=city_background]: Background replacement

FADE TO:

Live Event Example

CONFERENCE - MAIN STAGE

House lights dim. Audience settles.

LIGHTS (cue 1) [fade=3s, preset=stage_wash]: Stage lights up

VIDEO (cue 2) [source=playback, file="intro.mp4"]: Roll intro video

Music builds. Video ends.

AUDIO (cue 3) [fade=2s, source=playback]: Fade music bed

GRAPHICS (cue 4) [template=lower_third, duration=8s]: Display "KEYNOTE SPEAKER"

Speaker walks to center stage.

CAMERA (cue 5) [preset=single_shot, transition=dissolve]: Camera 2 - speaker medium

Applause. Speaker begins.

AUDIO (cue 6) [source=lav_mic, gate=-20dB]: Activate speaker microphone

SPEAKER
Thank you all for coming today.

GRAPHICS (cue 7) [template=presentation, source=laptop]: Display slide 1

Speaker gestures to screen.

CAMERA (cue 8) [preset=wide, speed=slow]: Pull back to wide shot

The presentation continues.

Broadcast Example

NEWSCAST - STUDIO A

Opening music plays.

PLAYBACK (cue 1) [file="news_open.mp4", audio=stereo]: Roll open

Graphics animate on screen.

GRAPHICS (cue 2) [template=news_open, duration=5s]: Animated title sequence

Music fades. Camera reveals anchor desk.

CAMERA (cue 3) [source=cam1, transition=dissolve, duration=1s]: Dissolve to anchor

AUDIO (cue 4) [fade=2s, level=-12dB]: Music bed under

Anchor looks to camera.

AUDIO (cue 5) [source=anchor_mic, compression=medium]: Anchor microphone hot

ANCHOR
Good evening. Our top story tonight...

GRAPHICS (cue 6) [template=over_shoulder, image="city_hall.jpg"]: OTS graphic

Anchor continues reading.

PLAYBACK (cue 7) [file="package_city.mp4", cue_point=timecode]: Roll package

Video package plays.

TRANSITION (cue 8) with package end [type=fade, duration=1s]: Fade to black

Back to studio.

CAMERA (cue 9) [source=cam1]: Cut to anchor

Cue Numbering Conventions

Sequential Numbering

Cues are typically numbered sequentially within each type:

SQ (cue 1): ...
SQ (cue 2): ...
SQ (cue 3): ...

Insertion Methods

When cues are added during rehearsals/production, choose one of these approaches:

Method A: Letter Suffixes (Traditional)

SQ (cue 5): Original cue
SQ (cue 5a): Added during tech rehearsal
SQ (cue 5b): Added later
SQ (cue 6): Next original cue

Sorting order: 1, 1a, 1b, 2, 2a, 3, 3a, 3b, 3c, 4…

Method B: Decimal Notation (Alternative)

SQ (cue 5): Original cue
SQ (cue 5.5): Added during tech rehearsal
SQ (cue 5.7): Added later
SQ (cue 6): Next original cue

Sorting order: 1, 1.5, 2, 2.5, 3, 3.5, 4…

Choose ONE insertion method per production and stick with it. Mixing letter suffixes and decimals within the same cue type creates sorting ambiguities. This follows standard theatre practice where cues are inserted during tech rehearsals without renumbering the entire show.

Cross-Type Numbering

Each cue type maintains its own numbering sequence:

SQ (cue 1): ...
LX (cue 1): ...  ← Different type, can reuse number
SQ (cue 2): ...
LX (cue 2): ...

This is standard practice - “LX 5” and “SQ 5” are different cues.

Parser Requirements

A CueScript-compliant parser MUST:

Recognize the basic pattern: CUETYPE (LABEL NUMBER) TRIGGER [METADATA]: DESCRIPTION

Formal patterns for each component:
- CUETYPE: [A-Z]+ — one or more uppercase letters, no spaces
- ( — opening parenthesis, optionally preceded by whitespace
- LABEL: [a-z]+ — one or more lowercase letters, single word
- — at least one space between LABEL and NUMBER (required)
- NUMBER: one of:
  - Pattern A (letter suffix): [0-9]+[a-z]* (e.g., 1, 5a, 23b)
  - Pattern B (decimal): [0-9]+\.[0-9]+ (e.g., 1.5, 5.5)
  - Pattern C (Prefixed): [A-Z][0-9]+[a-z]* (e.g., A1, V3, A5a)
- ) — closing parenthesis
- TRIGGER (optional): a single lowercase keyword ([a-z]+) followed by a single space and a value. Value types:
  - Quoted string "[^"]*" — required when value is dialogue text (e.g., on "Juliet")
  - Numeric with units [0-9]+(\.[0-9]+)?(s|m|ms|h) — for time-based values (e.g., after 3s)
  - Free-form text — any text not containing [ or : (e.g., with door slam)
  - Value MUST NOT be empty — a keyword without a value is invalid
- [metadata] (optional): \[key=value(,\s*key=value)*\]
- : — colon separator, optionally surrounded by whitespace
- DESCRIPTION: non-empty free-form text (required for a formally valid cue)
Parsers MUST be flexible with whitespace between components, except inside (LABEL NUMBER) where at least one space between LABEL and NUMBER is required.
Support flexible labels: Recognize any lowercase label ([a-z]+) — not limited to cue, shot, etc.
Support all three cue number patterns: Pattern A, B, and C as defined above
Recognize cue types: Any uppercase identifier ([A-Z]+) is a valid CUETYPE
Handle optional triggers: Parse any single lowercase keyword ([a-z]+) followed by a space and a value. Value types:
- Quoted string "[^"]*" — for dialogue triggers
- Numeric with units [0-9]+(\.[0-9]+)?(s|m|ms|h) — for time-based triggers
- Free-form text (any text not containing [ or :) — for action triggers
- Standard keywords are on, after, with — custom keywords MUST also be accepted
- A trigger keyword without a value is invalid
Handle optional metadata: Parse [key=value] pairs in square brackets, immediately before the colon
- Multiple pairs are separated by a comma: [key=value, key2=value2]
- Parsers MUST accept commas with or without trailing space
- Keys: [a-z]+ — single lowercase word
- = separator with no surrounding spaces
- Values follow the rules defined in the Metadata section
Validate time units: Require units (s, m, ms, h) for numeric time values in metadata
Handle Fountain notes: Parse cues within [[ ]] as hidden cues
Preserve Fountain compatibility: Not interfere with standard Fountain parsing
Case sensitivity: CUETYPE must be uppercase; labels must be lowercase; cue number case must be preserved as written
Parse from plain text: Accept any plain text input conforming to CueScript syntax, regardless of origin

A CueScript-compliant parser SHOULD:

Warn on duplicate numbers: Flag duplicate cue numbers within the same CUETYPE
Warn on label inconsistency: Flag when same CUETYPE uses different labels (e.g., CAMERA (shot 1) then CAMERA (cue 2))
Warn on mixed CUETYPE conventions: Flag when a script uses both members of a known conventional pair (e.g., both LX and LIGHT, or both SQ and SOUND) — these typically indicate the same department and mixing them is likely unintentional
Extract Fountain structure: Document title, acts, scenes from Fountain syntax
Generate coordination cues: Calculate advance warning timing from warn metadata
Warn on mixed numbering: Flag use of both letter and decimal patterns in same CUETYPE (e.g., LX (cue 5a) and LX (cue 6.5))

A CueScript-compliant parser MAY:

Suggest standardization: Offer to normalize CUETYPE naming conventions
Warn on gaps: Identify missing numbers in sequences (gaps are valid — this is informational only)
Suggest cue numbers: Propose numbers for placeholder cues (cues without description). MUST NOT assign numbers silently without user interaction
Export to production systems: Generate cue sheets, calling scripts, or control system workspaces (e.g., QLab)
Domain-specific features: Implement workflows specific to theatre, film, broadcast, or other production contexts

Edge Cases

Cue References in Text

When dialogue or action mentions a cue without defining it, don’t parse as a cue:

STAGE MANAGER
Stand by for sound cue 5.

← Not parsed as a cue (missing colon and description)

Mixed Case

Only uppercase CUETYPE is valid:

sq (cue 1): Door slams      ← Invalid (not uppercase)
SQ (cue 1): Door slams      ← Valid
Sq (cue 1): Door slams      ← Invalid (mixed case)

Missing Components

CUETYPE, LABEL, and NUMBER are always required. DESCRIPTION is required for a formally valid cue — parsers MAY accept a missing description as a placeholder during authoring and SHOULD warn rather than error. TRIGGER and metadata are always optional:

SQ: Door slams              ← Invalid (missing cue number)
(cue 5): Door slams         ← Invalid (missing cue type)
SQ (cue 5): Door slams      ← Valid (minimal form)
SQ (cue 5):                 ← Formally invalid — parsers MAY accept as placeholder
SQ (cue 5) on "exit": Door  ← Valid (with trigger)
SQ (cue 5) [level=-3dB]: Door ← Valid (with metadata)

Whitespace

Parsers should be flexible with whitespace:

SQ (cue 5): Door slams      ← Valid
SQ(cue 5): Door slams       ← Valid (no space before parenthesis)
SQ (cue  5): Door slams     ← Valid (extra space between LABEL and NUMBER)
SQ  (cue 5):  Door slams    ← Valid (extra spaces between components)

Line Breaks

A cue must occupy exactly one line. Multi-line cues are invalid:

SQ (cue 5): Door slams      ← Valid
SQ (cue 5):                 ← Invalid (description on next line)
  Door slams

Trigger Formats

All these trigger formats are valid:

LX (cue 5) on "Juliet": Fade      ← Dialogue trigger (quotes required)
LX (cue 5) after 3s: Fade         ← Time delay
LX (cue 5) with entrance: Fade    ← Action trigger
LX (cue 5) before curtain: Fade   ← Custom keyword (valid)
LX (cue 5): Fade                  ← No trigger (implicit)

Invalid trigger forms:

LX (cue 5) on: Fade               ← Invalid (keyword without value)
LX (cue 5) after: Fade            ← Invalid (keyword without value)

Important: Dialogue triggers MUST use quotes to distinguish them from descriptions that might start with the same word. For example:

→ Valid   LX (cue 5) on "stage": Fade    ← Trigger on the word "stage"
→ Invalid LX (cue 5) on stage: Fade      ← Ambiguous - is "on stage" the description?
→ Valid   LX (cue 5): Fade on stage      ← Clear - "on stage" is part of description

Validation Rules

Required

CUETYPE must be present, uppercase letters only ([A-Z]+), single word
LABEL must be present, lowercase letters only ([a-z]+), single word
Space between LABEL and NUMBER is required (at least one)
NUMBER must match one of these patterns:
- Pattern A (letter suffix): [0-9]+[a-z]* (e.g., 1, 5a, 23b)
- Pattern B (decimal): [0-9]+\.[0-9]+ (e.g., 1.5, 5.5)
- Pattern C (prefixed): [A-Z][0-9]+[a-z]* (e.g., A1, V3, A5a)
DESCRIPTION must be present and non-empty after the colon for a formally valid cue
Trigger value must not be empty — a trigger keyword without a value is invalid (e.g., on: is invalid)
Dialogue trigger values must use quotes: on "word" not on word
Metadata keys must be lowercase letters only ([a-z]+), single word
Metadata key-value separator must be = with no surrounding spaces
Metadata pairs must be separated by a comma; space after comma is optional
Time values in metadata MUST include units (s, m, ms, h)

Recommended Warnings

Label consistency: Each CUETYPE should use the same label throughout the document
- Example: If CAMERA (shot 1) is used, CAMERA (cue 2) should trigger a warning
Numbering consistency: Mixing patterns within the same CUETYPE
- Example: LX (cue 5a) and LX (cue 6.5) should trigger a warning (mixing Pattern A and B)
- Example: LX (cue 5) and LX (cue A5) should trigger a warning (mixing Pattern A and C)
Duplicate cue numbers within same CUETYPE
Mixed CUETYPE conventions: Script uses both members of a known conventional pair (e.g., both LX and LIGHT, or both SQ and SOUND) — likely unintentional
Missing description — cue has a colon but no content after it (e.g., LX (cue 5):). Parsers MAY accept this as a valid placeholder during authoring and SHOULD warn rather than error
Unusually long description — may indicate that technical details better suited for metadata have been included in the description

Not Required

Sequential numbering across entire script
Starting from 1 (can start at any number)
Continuous sequences (gaps are allowed and common)
Using abbreviated forms (SOUND is as valid as SQ)
Triggers on every cue (optional element)
Metadata on every cue (optional element)

Best Practices

Consistency

Choose one naming convention per production (e.g., LIGHT vs LX - pick one)
Use consistent cue type names throughout the script
Number cues sequentially within each discipline

Clarity

Keep descriptions concise but clear
Describe the effect or result, not the technical implementation
Use terminology your production team understands
Save technical details for metadata
If you find yourself embedding numbers in CUETYPE names (e.g., CAM1, CAM2, MIC1, MIC2), consider which problem you’re solving:
- If the number identifies which instance (which camera, which mic): use metadata — CAMERA (setup 1) [target=cam1]
- If the number identifies sequence position: use the NUMBER component — CAM (setup 1), CAM (setup 2)

Organization

Use hidden cues [[ ]] for technical notes that shouldn’t clutter the reading script
Use visible cues for actions that all stakeholders need to see

Production Process

Start with sequential numbers (1, 2, 3…)
Add revision letters (5a, 5b) during production as needed
Avoid renumbering entire sequences mid-production
Add metadata progressively as decisions are made

Metadata Usage

Don’t add metadata until you know the values
Simple cues often don’t need metadata
Complex cues benefit from detailed metadata
Use warn metadata for cues requiring advance preparation

Domain-Specific Tips

Theatre Productions

Use warn for complex cues (fly, automation, scene changes)
Hidden cues for continuous/atmospheric elements
Visible cues for actions that affect actors

Film Productions

Film productions think in terms of setups rather than cues. CueScript’s flexible LABEL supports this naturally — using setup instead of cue speaks the language of the set:

CAMERA (setup 1): Wide shot — John at door
CAMERA (setup 2): Close-up — John's face
CAMERA (setup 2a): Close-up variant — tighter framing
LIGHT (setup 1) [type=key, direction=left, intensity=2k]: Key light
LIGHT (setup 1a) [type=key, direction=left, intensity=1.5k]: Adjusted for coverage

Letter suffixes handle setup variants without disrupting the sequence. Metadata carries the technical details that DPs and gaffers need.

Live Events Productions

Video and camera cues benefit from transition metadata
Audio cues should specify sources and routing
Graphics cues should note templates and durations

Broadcast Productions

Playback cues need file references and cue points
Camera transitions should specify type and duration
Audio cues should note levels and compression

Version History

v0.9 (Public Draft - April 2026)

Initial public specification
Core syntax definition
Domain-agnostic design
Common cue type conventions across theatre, film, live events, and broadcast
Open trigger syntax with standard keywords (on, after, with) and support for custom keywords
Optional metadata system [key=value]
Timing rules (units required for numeric values)
Standby/warning system via warn metadata
Progressive enhancement workflow
Fountain compatibility patterns
Final Draft practical example (tested during specification development)

Future Considerations

Features being considered for future versions:

Cue relationships: Syntax for linked, simultaneous, or follow-on cues
Cue grouping: A group metadata key to associate cues across types for export to control systems (e.g., QLab groups). Grouping would be a parser hint for organizational output, not an execution or timing instruction.
Role-specific cues: Tie cues to specific performers, crew positions, or equipment
Conditional cues: Cues that fire based on conditions (alternate takes, live vs recorded, etc.)
Timeline integration: Explicit timecode or time-based triggering, relevant for broadcast and film

License

CueScript is an open specification. Implementations may use any license, but the specification itself is released under CC BY-ND 4.0.

Reference Implementation

The CueScript specification was developed alongside a working implementation, demonstrating that the format is practical and production-ready. CueScript is an open format — any tool or application can implement the specification independently.

Specification repository: https://github.com/nmds/cuescript
Website: https://www.cuescript.org
Known implementations: https://www.cuescript.org/implementations

Acknowledgments

CueScript draws from production practices across theatre, film, television, live events, and broadcast industries. Thanks to production coordinators, stage managers, assistant directors, technical directors, and crew members across all disciplines for establishing the conventions that inform this specification.

Fountain

CueScript’s plain-text philosophy was inspired by Fountain, the open-source plain text markup language for screenwriting created by John August, Stu Maschwitz, and Nima Yousefi, with contributions from Martin Vilcans, Brett Terpstra, Jonathan Poritsky, Kent Tessman, and Clinton Torres.

Fountain’s elegant approach to plain text screenplay formatting — human-readable, portable, future-proof, and built on open standards — directly informed CueScript’s design principles.

Learn more about Fountain at fountain.io

CueScript Specification v0.9 (Public Draft)
Last updated: April 2026