# Narration Script Format

A narration script is a Markdown file that describes a voice-over essay: what to say, when to say it, and what visual lands beside it. Narrator parses this format and turns it into a dubbing-style teleprompter with a synced timeline.

The format is intentionally small. Three things matter: **chapters**, **timestamped events**, and (optionally) a header. Everything else is ignored.

---

## 1. File header (optional)

A YAML-style frontmatter block at the top of the file:

```markdown
---
title: Soustraction
lang: fr
target_duration: 4:32
notes: calm declarative, polished persona
---
```

All fields are optional and informational only — the parser does not require any of them. Useful for AI generators that want to record context.

## 2. Chapter headings

Use `##` followed by a chapter title and a duration range in parentheses with `MM:SS` timestamps:

```markdown
## OUVERTURE (0:00 - 0:12)
## CHAPITRE I — UN COCKPIT (0:12 - 1:12)
## FERMETURE (4:25 - 4:32)
```

The duration range is the chapter's **start and end timestamps**. Chapters must be in chronological order. The first chapter's start should be `0:00`.

Chapter titles are free-form text. Roman numerals, em-dashes, accents — all fine. The title appears in the timeline bar and the chapter label.

## 3. Timestamped events

Every event line begins with a backtick-wrapped timestamp:

```markdown
`[00:18]` Je travaille dans le sous-sol d'une maison a Montreal.
```

The text after the timestamp determines the event type:

### Spoken line

Plain text after the timestamp = words to speak.

```markdown
`[00:18]` Je travaille dans le sous-sol d'une maison a Montreal.
`[00:22]` Les tuiles du plafond sont blanches.
```

### Visual cue

Starts with `//` after the timestamp = a stage direction or visual cue (shown in the sidebar, never spoken).

```markdown
`[00:38]` // visual: overhead tabletop — three printed sheets labeled NOW / PROJECTS / ARTIFACTS
`[02:13]` // music drops to silence, piano enters
```

### Marker

Timestamp with no content after = pure marker (silent beat, no spoken text, used to anchor visual transitions).

```markdown
`[00:00]`
```

---

## 4. Timestamp rules

- Format: `MM:SS`, zero-padded. Examples: `00:00`, `04:32`, `12:08`.
- Backticks around timestamps are recommended (`` `[MM:SS]` ``) but the parser tolerates unwrapped `[MM:SS]` too.
- Multiple events can share the same timestamp (typical: a visual cue + a spoken line landing together).
- Order should match chronology, but the parser stable-sorts by timestamp to be safe.
- A spoken line's **duration** is computed automatically from the gap to the next event. No need to specify end times for individual lines.

## 5. Soft conventions (decorative, parser ignores)

These don't affect parsing but help humans read the script:

- Blockquote prefix `>` for grouping spoken lines visually — the parser strips it.
- `(pause N)` and `(beat)` annotations between events — informational only; the actual pause is the gap between timestamps.
- `// stage` comments inside blockquotes — treated as visual cues.
- Markdown emphasis (`**bold**`, `*italic*`) inside spoken text — the parser preserves it as-is; the teleprompter renders the raw characters.

---

## 6. Minimal example

```markdown
---
title: Demo
lang: en
target_duration: 0:15
---

## INTRO (0:00 - 0:08)
`[00:00]` // visual: black screen, hold 3 s
`[00:03]` Welcome to the demo.
`[00:06]` // visual: fade to wide shot

## END (0:08 - 0:15)
`[00:08]` This is what a minimal narration script looks like.
`[00:13]` // visual: end card
```

## 7. What the parser produces

For each line of the file, Narrator produces an event object:

```json
{ "type": "chapter", "time": 12, "endTime": 72, "title": "CHAPITRE I — UN COCKPIT" }
{ "type": "visual",  "time": 38, "text": "overhead tabletop — three printed sheets..." }
{ "type": "spoken",  "time": 38, "endTime": 52, "text": "Le premier dit ce qui compte..." }
{ "type": "marker",  "time": 0,  "text": "" }
```

The full event list, sorted by time, drives:
- The timeline bar (chapter blocks + tick marks per event).
- The teleprompter (only `spoken` events appear in the main reading area).
- The visual cue sidebar (most recent `visual` event at or before current time).
- The chapter label (current chapter based on time).
- The pace readout (delta between current playback time and the active spoken event's start).

## 8. Format is dubbing-first, not ASR-style

This format records **when to say things**, not **when things were said**. The timestamps are targets for delivery, not transcription marks. The teleprompter auto-advances ON the markers regardless of how fast or slow the reader speaks — if you finish a line early, you sit in silence until the next mark; if you take longer, you fall behind and a pace readout warns you.

That's the difference between a teleprompter (reader sets the pace, script scrolls to match) and Narrator (script sets the pace, reader matches it). This format is for the second model.