VoxDown

VoxDown

Version 1.3, 14 November 2026, by Etienne Ackermann (@eackermann). © 2026 Etienne Ackermann. This specification is licensed under CC BY 4.0. Its examples are also published as conformance.json (§15). What changed since the drafts is in CHANGELOG.md, and every mark fits on one page in CHEATSHEET.md.

VoxDown is a plain-text format for stories that are read aloud. It records:

A file in this format is a Markdown story with light marks in it. Take the marks out and you have the printed story. Leave them in and you have a script that a narrator, a cast, or a speech engine can perform.

## The cave
Then he heard a deep rumble. [deep rumbling, from inside a cave]
The dragon was snoring. @Gerald [snores]
::: whispering
Sir Percival crept inside.
Clank.
{page}
The dragon opened one eye.
:::
@Gerald (deep, polite and utterly unbothered) “Could you not?”
Sir Percival stopped.
@Gerald “I’ve only just got to sleep,” said the dragon.

Contents

  1. Goals
  2. The marks at a glance
  3. How to read this spec
  4. The file
  5. Who speaks
  6. How it is said
  7. Groups
  8. Sounds
  9. Pages, pauses and what is printed
  10. Notes
  11. Markdown inside the story
  12. The two readings
  13. Tools that edit files
  14. Rendering
  15. Conformance
  16. Versions
  17. Beyond 1.0

1. Goals

2. The marks at a glance

You want You write
A character's line @Gerald “Could you not?”
A line inside narration @Gerald “I’ve only just got to sleep,” said the dragon.
How it is said @Gerald (yawning) “I’m tired.”
A direction for the narrator @(warmly) Once upon a time…
A change of direction mid-line @Gerald “I know. @(yawning) I’m tired.”
Back to no direction @(nervously) The fox looked around, @() and then relaxed.
A few words by a character, then the narrator again Whenever I find @Gerald myself pausing @/ before the door.
A direction over several lines ::: whispering … :::
Several lines by one character ::: @Wanda reading the letter … :::
A sound The broom fell over. [wooden clatter]
A sound a character makes @Gerald [snores], or @[sneezes] inside his line
A page turn {page}
A pause {pause} or {pause 2s}
Printed, not read aloud {book only} First published 1902.
Read aloud, not printed {audio only} Turn the page when you hear the bell.
A note for the performer %% Leave a clear pause after this line. %%
A comment for yourself <!-- Was it raining in chapter one? --> (§10.1)
Title, chapter, scene # Title, ## Chapter 1, ### A scene (§4.4)
A scene break ---
The cast Front matter: cast: (§4.3)

The one rule to remember: on each line, the quotes after a name belong to it, and everything else belongs to the narrator.

3. How to read this spec

Each rule comes with examples. An example shows the input, then a line with a single dot, and then the spoken script: what a listener hears, in order (§12.1). Some examples add a second dot and the book text: what a reader sees in print (§12.2).

The spoken script has one line per thing heard. A line is either:

A new line in the file starts a new line in the script. A blank line separates paragraphs. Headings start with # and scene breaks are ---. §12.1 gives the details.

You write
@Gerald (yawning) “I’ve only just got to sleep,” said the dragon.
A listener hears
Gerald (yawning): I’ve only just got to sleep,
Narrator: said the dragon.

The examples are also the conformance tests: a parser follows this spec when it produces every example's output.

4. The file

4.1 Overall shape

A file is UTF-8 text. It starts with optional front matter, followed by the story. Line endings may be LF or CRLF. Tools keep whichever a file uses.

Files use the .vxd extension. Every VoxDown file is also a Markdown file, so a file may use .md instead where it is mostly read in Markdown tools; tools that read VoxDown accept both. The suggested media type is text/markdown; variant=VoxDown (RFC 7763).

4.2 Front matter

Front matter is YAML between two --- lines at the very top of the file. It is metadata: none of it is read aloud.

---
voxdown: 1.1
title: The Tale of Peter Rabbit
author: Beatrix Potter
language: en-GB
cast:
  Narrator:
  Peter: Peter Rabbit
  Mother:
    name: Mrs. Rabbit
    about: Peter’s mother. Kind, brisk, and firm about gardens.
  McGregor: Mr. McGregor
---
Key Meaning
voxdown The version of this spec the file follows, such as 1.1 (§16). Recommended.
title, subtitle, author The book's details.
language The story's main language, as a BCP 47 tag such as en-GB or de.
narrator Which cast member reads everything not marked otherwise. Defaults to Narrator (§5.1).
cast The characters, in the order a tool should list them (§4.3).

Any other key is allowed and must be kept by tools that rewrite the file. A tool's own data should sit under one key named after the tool, for example recorder:.

Front matter is YAML, and a reader understands at least this part of it: maps nested by indentation; plain, single-quoted and double-quoted values, including ones continued on more indented lines; block values (|, > and their - and + forms); lists written as - item or [a, b]; and comments. A tool that writes front matter keeps to that part. Anything else (anchors, aliases, tags, {…} maps) may be read as plain text, with a warning.

A value the format reads as text (a title, an author, a language, a name) is that text as written, even where YAML would read a number or true: title: 1.10 is the title 1.10, not 1.1.

You write
---
title: The Tale of Peter Rabbit
author: Beatrix Potter
---
Once upon a time there were four little Rabbits.
A listener hears
Narrator: Once upon a time there were four little Rabbits.

4.3 The cast

cast maps each character's name, the one word written after @, to one of:

A character does not need to be in the cast to speak. An undeclared name is a character whose full name is that word (and a tool may warn about it). The cast exists for full names, descriptions, ordering, and characters who never speak but still matter, such as a silent broom.

You write
---
cast:
  Clown: The Silly Clown
---
@Clown “Honk!”
A listener hears
Clown: Honk!
You write
@Shepherd “Just count the sheep,” said the shepherd.
A listener hears
Shepherd: Just count the sheep,
Narrator: said the shepherd.

4.4 The story

After the front matter comes the story, made of:

Notes (§10) can sit anywhere, even across blank lines.

Blank lines around headings, scene breaks and group lines are optional. Each of them is always on a line of its own and ends the paragraph before it. (Markdown viewers show the line above a --- with no blank line as a heading, so leave blank lines there if the file will also be read in one.)

Inside a paragraph, a line break is kept: a reader sees it in the book text, and it is heard as an ordinary space. This differs from Markdown, which joins lines. Picture books, verse, letters and signs all depend on their line breaks, and story writers rarely wrap lines by hand. Marks also work line by line (§5.3).

You write
And their names were—
Flopsy,
Mopsy,
Cotton-tail,
and Peter.
A listener hears
Narrator: And their names were—
Narrator: Flopsy,
Narrator: Mopsy,
Narrator: Cotton-tail,
Narrator: and Peter.
A reader sees
And their names were—
Flopsy,
Mopsy,
Cotton-tail,
and Peter.

Spaces at the start of a line are ignored.

A file that starts with a --- line has front matter only if a second --- line closes it. To start a story with a scene break, use ***.

New in 1.1. A scene break's signs may have spaces between them, as in Markdown: * * * and - - - are scene breaks.

New in 1.1
You write
The door closed.

* * *

Morning came.
A listener hears
Narrator: The door closed.

---

Narrator: Morning came.
A reader sees
The door closed.

* * *

Morning came.

Headings are part of the story: they are read aloud by the narrator unless marked {book only} or {hidden} (§9.3). The spec gives the levels no other meaning, but a book's chapters are found from them in one way, so that a story divides the same in every tool that divides it (an audiobook, an ebook, an outline): its chapters are its headings of the highest level used at least twice.

You write
# The Tale of Peter Rabbit

Once upon a time there were four little Rabbits.
A listener hears
# Narrator: The Tale of Peter Rabbit

Narrator: Once upon a time there were four little Rabbits.
You write
Until Tuesday.

---

On Tuesday morning, the king summoned him.
A listener hears
Narrator: Until Tuesday.

---

Narrator: On Tuesday morning, the king summoned him.

The same story written without blank lines means the same thing:

You write
Until Tuesday.
---
On Tuesday morning, the king summoned him.
A listener hears
Narrator: Until Tuesday.

---

Narrator: On Tuesday morning, the king summoned him.
You write
Mount Mumble was very tall.
## The cave
Then he heard a deep rumble.
A listener hears
Narrator: Mount Mumble was very tall.

## Narrator: The cave

Narrator: Then he heard a deep rumble.

5. Who speaks

5.1 The narrator

Everything is read by the narrator unless it is marked. The narrator is the cast member named Narrator, or the one the front matter's narrator: key names, for example in a story told in the first person. That includes quotations: an unmarked quote is the narrator reading it, as in a single-narrator audiobook.

You write
“Stop thief!” cried Mr. McGregor.
A listener hears
Narrator: “Stop thief!” cried Mr. McGregor.
You write
---
narrator: Peter
---
I ran. @Mother “Peter!”
A listener hears
Peter: I ran.
Mother: Peter!

5.2 Names

@ followed by a name is a character mark. A name is one word: it starts with a letter and continues with letters, digits, - and _, and apostrophes between two letters, as in @O’Brien. Any script's letters count, so @Zoë and @花子 are both names.

A character with a longer name gets a short one in the cast (Clown: The Silly Clown, then @Clown), or the words are joined (@SillyClown). Tools show the full name; the short one only appears in the raw text.

You write
@SillyClown “Honk!”
A listener hears
SillyClown: Honk!

Names ignore case: @clown, @Clown and @CLOWN are the same character. The spoken script uses the cast's spelling, or else the spelling the file uses first. The narrator is written as the cast or the narrator: key spells it, or else Narrator.

You write
---
cast:
  Clown: The Silly Clown
---
@clown “Honk!” @CLOWN “Honk honk!”
A listener hears
Clown: Honk!
Clown: Honk honk!
You write
@clown “Honk!”
@Clown “Honk honk!”
A listener hears
clown: Honk!
clown: Honk honk!

New in 1.1. Names ignore the kind of apostrophe too: @O'Brien and @O’Brien are one character.

New in 1.1
You write
@O'Brien “Hello.” @O’Brien “Goodbye.”
A listener hears
O'Brien: Hello.
O'Brien: Goodbye.
You write
@narrator (warmly) Once upon a time.
A listener hears
Narrator (warmly): Once upon a time.

@ is only a mark when it is not preceded by a letter or digit, and when it is followed by a name, ( or [. So email addresses and a lone @ are just text. In a script written without spaces between words (Chinese, Japanese, Thai, Lao, Khmer, Burmese), a mark may follow a letter directly: 最怕打雷的雷公@雷公 [笑]. Write \@ for a literal @ anywhere.

You write
Write to tom@example.com, or meet me @ noon.
A listener hears
Narrator: Write to tom@example.com, or meet me @ noon.
You write
雷公听见了@雷公 [笑]
A listener hears
Narrator: 雷公听见了
雷公 [笑]
You write
\@Gerald is my username.
A listener hears
Narrator: @Gerald is my username.

5.3 One line at a time

A paragraph can have several lines. Marks work line by line: who speaks and how end at the end of the line. Two things run longer:

So the one rule to remember is: on each line, the quotes after a name belong to it, and everything else belongs to the narrator.

A quote that runs over several lines keeps its character and direction until it closes.

5.4 Quoted speech

A character mark gives the character the quotes after it on its line. The character says everything inside the first quote after the mark, up to the matching closing mark, unless another character mark comes between them. Everything outside the quotes is narration. Between the mark and the quote there may be a direction (§6), then a sound the character makes (§8.2), then narration.

You write
@Gerald “Could you not?”
A listener hears
Gerald: Could you not?
You write
@Gerald “I’ve only just got to sleep,” said the dragon.
A listener hears
Gerald: I’ve only just got to sleep,
Narrator: said the dragon.

The mark can sit directly before the quote, or at the start of the line. Both mean the same.

You write
Gerald put on his spectacles. @Gerald “I thought perhaps librarian.”
A listener hears
Narrator: Gerald put on his spectacles.
Gerald: I thought perhaps librarian.
You write
@Gerald Gerald put on his spectacles. “I thought perhaps librarian.”
A listener hears
Narrator: Gerald put on his spectacles.
Gerald: I thought perhaps librarian.
You write
@Baker And out of the blue, “Just a little flame,” said the baker. “Gently.”
A listener hears
Narrator: And out of the blue,
Baker: Just a little flame,
Narrator: said the baker.
Baker: Gently.

A direction on the mark goes with the character's speech, not with the narration before it.

You write
@Baker (nervously) And out of the blue, “Just a little flame,” said the baker.
A listener hears
Narrator: And out of the blue,
Baker (nervously): Just a little flame,
Narrator: said the baker.

A mark never reaches back to a quote before it. It is not a word, either: it disappears from the printed text, so said @Gerald prints as "said".

You write
“Could you not?” said @Gerald.
A listener hears
Narrator: “Could you not?” said
A reader sees
“Could you not?” said .

Several characters can speak on one line, each with their own mark.

You write
@Wanda “Fine!” @Marmalade “Hm.”
A listener hears
Wanda: Fine!
Marmalade: Hm.

The quotation marks are printed but not spoken: the spoken script leaves out the speech's own opening and closing marks. Quotes inside a speech are kept.

You write
@Gerald “‘But you are a chicken,’ said the duke.”
A listener hears
Gerald: ‘But you are a chicken,’ said the duke.

5.5 Quotation marks

Each opening mark has its own closing marks:

Opening Closes with Used in
“ ” English
‘ ’ British English
" " Plain text
' ' Plain text
„ “ or ” German, Polish, Dutch
‚ ‘ or ’ German (inner)
« » French, Italian, Spanish, Russian
» « or » Danish, Swedish
‹ › French (inner)
「 」 Japanese, Chinese
『 』 Japanese, Chinese (inner)

Some marks double as apostrophes and measurements, so three rules keep them apart:

A quotation mark with nothing after it on its line opens nothing; it stays in the text as an ordinary character.

You write
@Mother ‘Now run along, and don’t get into mischief.’
A listener hears
Mother: Now run along, and don’t get into mischief.
You write
@Gerald "Could you not?" said the dragon.
A listener hears
Gerald: Could you not?
Narrator: said the dragon.
You write
@Anna „Guten Morgen“, sagte Anna.
A listener hears
Anna: Guten Morgen
Narrator: , sagte Anna.

A plural possessive inside single quotes, such as rabbits’ burrow, looks like a closing mark. Write \’ for it.

You write
@Mother ‘Mind the rabbits\’ burrow.’
A listener hears
Mother: Mind the rabbits’ burrow.
You write
@Gerald "Fine," he said, 'cause he was tired.
A listener hears
Gerald: Fine,
Narrator: he said, 'cause he was tired.

A mark straight after a letter is not a mark (§5.2), so in languages written without spaces, put the mark at the start of the line. It still claims the quote after it.

You write
@Hanako 花子は「はい」と言った。
A listener hears
Narrator: 花子は
Hanako: はい
Narrator: と言った。
A reader sees
花子は「はい」と言った。

5.6 A speech interrupted by narration

On the line where a character's speech ends, an unmarked quote that comes after it carries that speech on, as if the narration had only interrupted it. It keeps the same character, and the direction the speech had when it was interrupted. This is how books write a line broken by "said the baker".

You write
@Baker “Just a little flame,” said the baker. “Gently.”
A listener hears
Baker: Just a little flame,
Narrator: said the baker.
Baker: Gently.
You write
@Advisor (urgent, formal whisper) “Sire,” whispered his advisor. “This is where you shout ‘Attack!’”
A listener hears
Advisor (urgent, formal whisper): Sire,
Narrator: whispered his advisor.
Advisor (urgent, formal whisper): This is where you shout ‘Attack!’
You write
@Gerald “I know. @(yawning) I’m tired,” he said. “Very.”
A listener hears
Gerald: I know.
Gerald (yawning): I’m tired,
Narrator: he said.
Gerald (yawning): Very.

A carried-on quote follows the most recent speech on the line.

You write
@Wanda “Fine,” she said. @Marmalade “Good,” said the cat. “Very good.”
A listener hears
Wanda: Fine,
Narrator: she said.
Marmalade: Good,
Narrator: said the cat.
Marmalade: Very good.

A closed speech is never carried on to the next line, so a quote on a new line with no mark is narration. A new speaker always needs a mark. A forgotten mark falls back to the narrator, where it is easy to hear, rather than to the wrong character.

You write
@Percival “Aren’t you going to roar?”
The dragon sighed.
“Rooooar.”
A listener hears
Percival: Aren’t you going to roar?
Narrator: The dragon sighed.
Narrator: “Rooooar.”
You write
@Percival “Aren’t you going to roar?”
The dragon sighed.
@Gerald “Rooooar.”
A listener hears
Percival: Aren’t you going to roar?
Narrator: The dragon sighed.
Gerald: Rooooar.
You write
@Wanda “Fine.”

“Fine,” said someone else.
A listener hears
Wanda: Fine.

Narrator: “Fine,” said someone else.

The cost falls on text wrapped by hand, where an interrupted speech goes on after a line break. Join the lines, or mark the speaker again.

You write
@Mother ‘Now my dears,’ said old Mrs. Rabbit one
morning, ‘you may go into the fields.’
A listener hears
Mother: Now my dears,
Narrator: said old Mrs. Rabbit one
Narrator: morning, ‘you may go into the fields.’

To keep a quote in narration as narration, put a backslash before its opening mark.

You write
@Wanda “Fine,” she said, in her \‘polite’ voice.
A listener hears
Wanda: Fine,
Narrator: she said, in her ‘polite’ voice.

5.7 A speech over several lines or paragraphs

A quote runs to its closing mark, even over several lines of a paragraph, as a song or a poem does. (A straight ' quote is the exception: it always closes on its own line, §5.5.)

You write
@Gerald (softly) “Twinkle, twinkle, little star,
How I wonder what you are.”
He yawned.
A listener hears
Gerald (softly): Twinkle, twinkle, little star,
Gerald (softly): How I wonder what you are.
Narrator: He yawned.

The speech ends on its second line, so a quote later on that line carries it on (§5.6).

You write
@Gerald “Twinkle, twinkle, little star,
How I wonder what you are,” he sang. “Up above the world so high.”
A listener hears
Gerald: Twinkle, twinkle, little star,
Gerald: How I wonder what you are,
Narrator: he sang.
Gerald: Up above the world so high.

A quote with no closing mark ends with its paragraph. If the next paragraph begins with the same opening mark, that paragraph carries the speech on, with the same character and direction. This is the book convention for one character speaking over several paragraphs. Paragraphs holding only page turns, pauses, other instructions or notes are skipped when looking for the next paragraph.

You write
@Gerald “Oh no, I’m going to
A listener hears
Gerald: Oh no, I’m going to
You write
@Gerald “Once upon a time there was a chicken.

“He believed he was the king of France.”

Twenty children laughed.
A listener hears
Gerald: Once upon a time there was a chicken.

Gerald: He believed he was the king of France.

Narrator: Twenty children laughed.
You write
@Gerald “Once upon a time there was a chicken.

{page}

“He believed he was the king of France.”
A listener hears
Gerald: Once upon a time there was a chicken.

{page}

Gerald: He believed he was the king of France.

5.8 Speech without quotes

When a mark has no quote of its own (no quote after it on its line before the next character mark), the character says the rest of the line, up to that next mark, unless the mark is followed by a sound, directly or after its direction (§8.2). This suits scripts written without quotation marks. Directions, sounds, instructions, notes and images inside it don't end it.

You write
@Gerald Could you not? I’ve only just got to sleep.
A listener hears
Gerald: Could you not? I’ve only just got to sleep.
You write
@Gerald Could you not? @Percival Sorry.
A listener hears
Gerald: Could you not?
Percival: Sorry.
You write
@Gerald Well, @Percival “Sorry.”
A listener hears
Gerald: Well,
Percival: Sorry.
You write
@Gerald Could you not? @(yawning) I’m tired.
A listener hears
Gerald: Could you not?
Gerald (yawning): I’m tired.
You write
@Gerald Could you not? [a distant clang] I’m tired.
A listener hears
Gerald: Could you not?
[a distant clang]
Gerald: I’m tired.

Like everything else, it ends with the line.

You write
@Gerald Could you not?
I’ve only just got to sleep.
A listener hears
Gerald: Could you not?
Narrator: I’ve only just got to sleep.

A script line without outer quotes but with a quote inside it gives that quote to the character, and the rest to the narrator. Give such a line its outer quotes, or put it in a group (§7.2).

You write
@Gerald They charge into my cave shouting, ‘PREPARE TO MEET THY DOOM!’
A listener hears
Narrator: They charge into my cave shouting,
Gerald: PREPARE TO MEET THY DOOM!
You write
@Gerald “They charge into my cave shouting, ‘PREPARE TO MEET THY DOOM!’”
A listener hears
Gerald: They charge into my cave shouting, ‘PREPARE TO MEET THY DOOM!’

@Narrator is a character mark like any other, so it claims the quotes on its line too. To give narration a direction, @(…) (§6.2) is usually what you want.

You write
@Narrator (warmly) Once upon a time, “Hello,” said the cat.
A listener hears
Narrator: Once upon a time,
Narrator (warmly): Hello,
Narrator: said the cat.
You write
@(warmly) Once upon a time, “Hello,” said the cat.
A listener hears
Narrator (warmly): Once upon a time, “Hello,” said the cat.

5.9 Back to the narrator

New in 1.2. @/ ends a speech without quotes (§5.8): from there to the end of the line, the narrator speaks again, or the group's character inside a group (§7.2). It is to who speaks what @() is to how (§6.3), and it never changes a word: a few words in the middle of a line can be given to a character with no quotation marks added.

New in 1.2
You write
Whenever I find @Gerald myself pausing before @/ coffin warehouses.
A listener hears
Narrator: Whenever I find
Gerald: myself pausing before
Narrator: coffin warehouses.

It claims no quote. A mark with a quote after it on its line claims the quote (§5.4); with @/ before the quote, the mark says its own words and the quote is read as if they had no mark.

New in 1.2
You write
@Gerald Myself pausing, @/ he thought. “Stop!” she cried.
A listener hears
Gerald: Myself pausing,
Narrator: he thought. “Stop!” she cried.

What comes after it has no direction of its own (§6.4), and inside a group it is the group's character who speaks again.

New in 1.2
You write
@(warmly) It was late. @Gerald Could you not? @/ he said.
A listener hears
Narrator (warmly): It was late.
Gerald: Could you not?
Narrator: he said.
New in 1.2
You write
::: @Wanda
I read it twice. @Gerald Read what? @/ The letter.
:::
A listener hears
Wanda: I read it twice.
Gerald: Read what?
Wanda: The letter.

A quote ends only at its closing mark: inside one, @/ changes nothing, and a parser warns of it (idle-end, §12.3), as it does of a @/ where the narrator already speaks. @/ is the mark only where @ would begin one (not straight after a letter or digit), and only when no letter, digit or second / follows: @/lib and name@/path are text.

New in 1.2
You write
@Gerald “I know. @/ I’m tired.” See @/lib.
A listener hears
Gerald: I know. I’m tired.
Narrator: See @/lib.

6. How it is said

6.1 Directions

A direction is free text in parentheses straight after a character mark. It says how the speech is performed, in the author's own words. Directions are never read aloud or printed.

You write
@Gerald (deep, polite and utterly unbothered) “Could you not?”
A listener hears
Gerald (deep, polite and utterly unbothered): Could you not?
You write
@Narrator (warmly) Sir Percival had been training his entire life.
A listener hears
Narrator (warmly): Sir Percival had been training his entire life.

Parentheses anywhere else are part of the story, read aloud and printed. Stories use them all the time, so only the @ makes a direction.

You write
Her broom (which was old) creaked. @Wanda (sighing) “Come on.”
A listener hears
Narrator: Her broom (which was old) creaked.
Wanda (sighing): Come on.
You write
@Clown (happily) "Just you wait!" said the clown, (sadly) "I've been waiting for you".
A listener hears
Clown (happily): Just you wait!
Narrator: said the clown, (sadly)
Clown (happily): I've been waiting for you

Without parentheses, words after a name are story text.

You write
@Gerald yawning “I’m tired.”
A listener hears
Narrator: yawning
Gerald: I’m tired.

A direction ends at its matching closing parenthesis. Parentheses inside it must balance, or be written \( and \).

You write
@Gerald (deep (very deep)) “Hello.”
A listener hears
Gerald (deep (very deep)): Hello.

6.2 A direction for whoever is speaking

@ followed straight away by a direction, with no name, gives a direction to whoever is speaking at that point. It never changes who speaks. In narration, that is the narrator.

You write
@(warmly) Sir Percival had been training his entire life.
A listener hears
Narrator (warmly): Sir Percival had been training his entire life.

Inside a speech, it changes the direction from that point.

You write
@Gerald “I know. @(yawning) I’m tired.”
A listener hears
Gerald: I know.
Gerald (yawning): I’m tired.

When only spaces separate it from a quote, it belongs to that quote, ahead of any direction the quote would carry over. This is how a speech carried on after narration (§5.6) gets a new direction.

You write
@King “Those poor children!” cried the king. @(quieter) “Oh dear.”
A listener hears
King: Those poor children!
Narrator: cried the king.
King (quieter): Oh dear.
You write
@Clown (happily) "Just you wait!" said the clown, @(sadly) "I've been waiting for you".
A listener hears
Clown (happily): Just you wait!
Narrator: said the clown,
Clown (sadly): I've been waiting for you

If no character claims that quote, the quote is narration, and the direction is the narrator's until the line ends or a speech begins.

You write
@(quieter) “Oh dear,” he said.
A listener hears
Narrator (quieter): “Oh dear,” he said.

After a speech ends on a line, the narrator is speaking, so @(…) there directs the narration. The narrator's direction ends where the next speech begins, and the speech carried on keeps its own direction.

You write
@Clown (happily) "Just you wait!" @(frostily) said the clown, "I've been waiting for you", he smirked.
A listener hears
Clown (happily): Just you wait!
Narrator (frostily): said the clown,
Clown (happily): I've been waiting for you
Narrator: , he smirked.

A stray quotation mark at the end of a line opens nothing (§5.5). It stays in the narration as an ordinary character, and the next line is unaffected.

You write
@Clown (happily) "Just you wait!" @(frostily) said the clown, "I've been waiting for you", he smirked."
A listener hears
Clown (happily): Just you wait!
Narrator (frostily): said the clown,
Clown (happily): I've been waiting for you
Narrator: , he smirked."
You write
@Clown "Just you wait!" he smirked."
The children giggled.
A listener hears
Clown: Just you wait!
Narrator: he smirked."
Narrator: The children giggled.

6.3 Back to no direction

@(), an empty direction, ends the current direction early. From there, the stretch has no direction of its own.

You write
@(nervously) The big fox looked around, @() and then relaxed.
A listener hears
Narrator (nervously): The big fox looked around,
Narrator: and then relaxed.
You write
@Clown (happily) "Just you wait! @() I mean it."
A listener hears
Clown (happily): Just you wait!
Clown: I mean it.

Inside a group, the group's direction applies again (§7). To be plain inside a group, name it, for example @(normal voice).

You write
::: whispering
@(nervously) The big fox looked around, @() and then relaxed.
:::
A listener hears
Narrator (nervously): The big fox looked around,
Narrator (whispering): and then relaxed.

6.4 How long a direction lasts

A direction belongs to one stretch of speech or narration, and lasts until that stretch ends:

A later @(…) replaces a direction and @() removes it. Directions are never combined.

You write
@(nervously) The big fox looked around.
He relaxed.
A listener hears
Narrator (nervously): The big fox looked around.
Narrator: He relaxed.

For any stretch, the direction is the first of these that exists:

  1. its own direction: from the nearest @(…) directly before it or earlier inside it; else carried over from the speech it carries on; else from its mark;
  2. the direction of the innermost group around it that applies to that character and has a direction (§7);
  3. none.

7. Groups

A group gives a direction, a character, or both, to several lines and paragraphs at once. It opens with a line of three or more colons followed by what applies, and closes with a line of three or more colons.

::: whispering
…
:::

The opening line holds no story text, only what applies to the group:

7.1 A direction for everyone

A group with a direction and no character gives that direction to everyone inside it who has no direction of their own.

You write
::: whispering
Sir Percival crept inside.

Clank.
:::

The dragon opened one eye.
A listener hears
Narrator (whispering): Sir Percival crept inside.

Narrator (whispering): Clank.

Narrator: The dragon opened one eye.
You write
::: (softly)
The knight stopped.

@Knight “Who goes there?”

@Percival (barely a whisper) “He’s only just got to sleep.”
:::
A listener hears
Narrator (softly): The knight stopped.

Knight (softly): Who goes there?

Percival (barely a whisper): He’s only just got to sleep.

Blank lines are optional here too. This is the same kind of passage, written one sentence to a line:

You write
::: whispering
Sir Percival crept inside.
Clank.
{page}
The dragon opened one eye.
:::
@Gerald (deep, polite and utterly unbothered) “Could you not?”
Sir Percival stopped.
@Gerald (yawning) “I’ve only just got to sleep,” said the dragon.
@Percival “Aren’t you going to roar?”
The dragon sighed.
A listener hears
Narrator (whispering): Sir Percival crept inside.
Narrator (whispering): Clank.
{page}
Narrator (whispering): The dragon opened one eye.

Gerald (deep, polite and utterly unbothered): Could you not?
Narrator: Sir Percival stopped.
Gerald (yawning): I’ve only just got to sleep,
Narrator: said the dragon.
Percival: Aren’t you going to roar?
Narrator: The dragon sighed.

7.2 One character for several lines

A group with a character mark gives everything unmarked inside it to that character instead of the narrator. Its direction is that character's direction; other characters who speak inside the group do not get it.

You write
::: @Wanda reading the letter
Dear Management,

Due to unacceptable working conditions, I am officially refusing to fly.
:::
A listener hears
Wanda (reading the letter): Dear Management,

Wanda (reading the letter): Due to unacceptable working conditions, I am officially refusing to fly.

Inside such a group, quotes in the character's own text are read as written, just as the narrator reads them outside a group.

You write
::: @Gerald
They charge into my cave shouting, ‘PREPARE TO MEET THY DOOM!’
:::
A listener hears
Gerald: They charge into my cave shouting, ‘PREPARE TO MEET THY DOOM!’

Another character's speech still carries on along its line (§5.6), so an interruption is best on a line of its own.

You write
::: @Gerald reading aloud
‘But you are a chicken,’ said the duke. @Wanda “Ha!” ‘I’m aware,’ said the chicken.
:::
A listener hears
Gerald (reading aloud): ‘But you are a chicken,’ said the duke.
Wanda: Ha!
Wanda: I’m aware,
Gerald (reading aloud): said the chicken.
You write
::: @Gerald reading aloud
‘But you are a chicken,’ said the duke.
@Wanda “Ha!”
‘I’m aware,’ said the chicken.
:::
A listener hears
Gerald (reading aloud): ‘But you are a chicken,’ said the duke.
Wanda: Ha!
Gerald (reading aloud): ‘I’m aware,’ said the chicken.

7.3 Nesting and closing

Groups can be nested. A line of colons closes the innermost open group. A group left open runs to the end of the file, and a line of colons with no group open is ignored (a tool may warn about either).

You write
::: softly, close to a whisper
At midnight, something came up the mountain.

::: @Gerald sleepy
Very heroic.
:::

And he went back to sleep.
:::
A listener hears
Narrator (softly, close to a whisper): At midnight, something came up the mountain.

Gerald (sleepy): Very heroic.

Narrator (softly, close to a whisper): And he went back to sleep.

An inner group that gives no direction leaves the outer one in place.

You write
::: whispering
::: @Gerald
Could you not?
:::
:::
A listener hears
Gerald (whispering): Could you not?

8. Sounds

8.1 Sounds

Text in square brackets is a sound the listener hears at that point. It is not read aloud or printed. The description is free text. By convention, a short name comes first and details follow a semicolon.

You write
The broom fell over. [wooden clatter; one broom handle dropping flat onto flagstones]
A listener hears
Narrator: The broom fell over.
[wooden clatter; one broom handle dropping flat onto flagstones]
You write
The broom shot sideways into a hedge. [crash through leaves] Only its bristles stuck out.
A listener hears
Narrator: The broom shot sideways into a hedge.
[crash through leaves]
Narrator: Only its bristles stuck out.
A reader sees
The broom shot sideways into a hedge. Only its bristles stuck out.
You write
On Tuesday morning, the king summoned him.

[royal trumpet fanfare]

@King “Sir Percival!”
A listener hears
Narrator: On Tuesday morning, the king summoned him.

[royal trumpet fanfare]

King: Sir Percival!

A sound mark records where a sound starts. How long it lasts, how loud it is, and whether it overlaps the words are decisions for production.

A sound inside a character's speech is still a sound in the world, not the character's.

You write
@Wanda “Come in— [door slams] oh.”
A listener hears
Wanda: Come in—
[door slams]
Wanda: oh.

8.2 Sounds a character makes

A character mark followed by a sound, directly or after its direction, gives that one sound to the character: a snore, a gasp, a sigh. A second sound straight after it is a sound in the world; mark the character again for another of theirs. If the line has a quote after the sound, that quote is the character's, as in §5.4. Text that isn't in quotes stays with the narrator; after its own sound, a mark never makes the character say unquoted text. A sound further along, after some narration, is a sound in the world.

You write
The dragon was snoring. @Gerald [snores]
A listener hears
Narrator: The dragon was snoring.
Gerald [snores]
You write
@Wanda [gasp] “My broom is on strike!”
A listener hears
Wanda [gasp]
Wanda: My broom is on strike!
You write
@Wanda [gasp] She stared at the broom.
A listener hears
Wanda [gasp]
Narrator: She stared at the broom.
You write
@Wanda [gasp] She stared at the broom. “On strike?”
A listener hears
Wanda [gasp]
Narrator: She stared at the broom.
Wanda: On strike?
You write
@Pickle [tiny peep] [a brief tumble] @Pickle [yawn]
A listener hears
Pickle [tiny peep]
[a brief tumble]
Pickle [yawn]
You write
@Wanda She stared at the broom. [gasp] “On strike?”
A listener hears
Narrator: She stared at the broom.
[gasp]
Wanda: On strike?
You write
@Gerald (softly) [snores]
A listener hears
Gerald (softly) [snores]

@ followed straight away by a sound gives the sound to whoever is speaking: inside a speech, the character; in narration, the narrator.

You write
@Gerald “Oh no. I’m going to— @[sneezes]”
A listener hears
Gerald: Oh no. I’m going to—
Gerald [sneezes]
You write
The fox froze. @[gasps]
A listener hears
Narrator: The fox froze.
Narrator [gasps]

8.3 Square brackets that are not sounds

A Markdown link, [text](address), stays a link: its text is read aloud and printed. So a sound followed directly by a parenthesis would become a link. Leave a space between them. A link is written on one line, as marks are (§5.3): its text, address and title end on the line they start on. One that runs onto the next line is read as a sound and text, and warned about.

You write
Read more at [our website](https://example.com).
A listener hears
Narrator: Read more at our website.

The same holds straight after an @: @[text](address) is an @ and a link, not a sound the speaker makes.

You write
@Gerald “Read [this](https://example.com) @[now](https://example.com).”
A listener hears
Gerald: Read this @now.

An image, ![description](file), is shown in the book and not heard.

You write
![Peter squeezing under the gate](peter-gate.png)
A listener hears
![Peter squeezing under the gate](peter-gate.png)

An image may be a link's text, as in Markdown: it is still an image, shown and not heard, and links where the link does.

You write
[![A map of the garden](garden.png)](garden-large.png)
A listener hears
[![A map of the garden](garden.png)](garden-large.png)

Write \[ for a literal square bracket.

9. Pages, pauses and what is printed

Instructions in curly braces shape the book and the timing. Each is a name, optionally followed by a value.

9.1 Page turns

{page} marks a page turn. It can stand on a line of its own or sit inside a line, where a page ends mid-sentence. An optional value labels the page that begins, such as {page 12} or {page 8–9} for a spread.

You write
He slipped underneath the gate.

{page}

Mr. McGregor hung up the little jacket.
A listener hears
Narrator: He slipped underneath the gate.

{page}

Narrator: Mr. McGregor hung up the little jacket.
You write
He went back to his work. {page} Peter sat down to rest.
A listener hears
Narrator: He went back to his work.
{page}
Narrator: Peter sat down to rest.
A reader sees
He went back to his work. Peter sat down to rest.
You write
{page 8–9}
A listener hears
{page 8–9}

How a page turn sounds (a chime, a rest, or nothing) is up to the player.

9.2 Pauses

{pause} is a pause. A beat's length is up to the performer. A value sets the length in seconds or milliseconds: {pause 2s}, {pause 500ms}.

You write
@Wanda “Could you perhaps be in love somewhat more urgently?”

{pause 2s}

He went on being in love at exactly the same speed.
A listener hears
Wanda: Could you perhaps be in love somewhat more urgently?

{pause 2s}

Narrator: He went on being in love at exactly the same speed.

9.3 Printed or read aloud

{book only} in a paragraph or heading means it is printed and not read aloud. {audio only} means it is read aloud and not printed. {hidden} means neither: a label for tools, such as the name of a scene. Each applies to its whole paragraph or heading wherever it sits. By convention it goes at the start of a paragraph and at the end of a heading.

You write
{book only} First published 1902.

Once upon a time…
A listener hears
{book only} First published 1902.

Narrator: Once upon a time…
A reader sees
First published 1902.

Once upon a time…
You write
{book only} First published 1902.
Frederick Warne & Co.
A listener hears
{book only} First published 1902.
{book only} Frederick Warne & Co.
You write
{audio only} Turn the page when you hear the bell.

Once upon a time…
A listener hears
Narrator: Turn the page when you hear the bell.

Narrator: Once upon a time…
A reader sees
Once upon a time…
You write
## The cave {hidden}

Mount Mumble was very tall.
A listener hears
## The cave {hidden}

Narrator: Mount Mumble was very tall.
A reader sees
Mount Mumble was very tall.

9.4 On a group

Visibility instructions on a group's opening line apply to every paragraph inside it.

You write
::: {book only}
First published 1902.

Printed in Great Britain.
:::
A listener hears
{book only} First published 1902.

{book only} Printed in Great Britain.

9.5 Other instructions

An instruction with any other name is kept in place, never read or printed, and ignored by tools that don't know it. This is how tools add their own marks. A tool's instructions should start with its name and a colon, such as {recorder:take 3}.

You write
The broom fell over. {recorder:take 3}
A listener hears
Narrator: The broom fell over.
{recorder:take 3}

Write \{ for a literal curly brace.

10. Notes

Text between %% and %% is a note for whoever performs or produces the story. It is kept in place and never read aloud or printed. A note can sit inside a line, on its own line, or run over several lines and paragraphs. A note on its own line is usually about what follows.

You write
%% Leave a clear pause after this line. %%

He went on being in love at exactly the same speed.
A listener hears
%% Leave a clear pause after this line. %%

Narrator: He went on being in love at exactly the same speed.
A reader sees
He went on being in love at exactly the same speed.
You write
@Marmalade “Clause five.” %% Clause and claws sound the same. %%
A listener hears
Marmalade: Clause five.
%% Clause and claws sound the same. %%
You write
%%
Hushed from here to the end, because Gerald is asleep.

The knight’s cry is the only loud line.
%%
A listener hears
%% Hushed from here to the end, because Gerald is asleep. The knight’s cry is the only loud line. %%

A note that runs over a line break leaves the lines two lines: what a mark does still ends with its line (§5.3), so the words after the note are the next line's. A quote left open carries on over it, as over any line break.

You write
@Alice “Hello.” %% A note for the
producer. %% “Goodbye.”
A listener hears
Alice: Hello.
%% A note for the producer. %%
Narrator: “Goodbye.”
A reader sees
“Hello.” “Goodbye.”

Write \% for a literal percent sign where it would otherwise start a note.

10.1 Comments

New in 1.3. Text between <!-- and --> is the writer's own comment, as in Markdown and HTML: a reminder, a question, a line set aside. It is kept in place and never read aloud, printed or given to a performer, so unlike a note it is not in the spoken script. A Markdown viewer hides it too. A comment can sit inside a line, on its own line, or run over several lines and paragraphs, and like a note it leaves the lines it runs over two lines (§5.3).

You write
Night fell. <!-- Was it raining in chapter one? --> The harbour was quiet.
A listener hears
Narrator: Night fell.
Narrator: The harbour was quiet.
A reader sees
Night fell. The harbour was quiet.

Inside a comment nothing is a mark: names, quotes, %% and the rest are its text, and the first --> ends it. A <!-- inside a note is the note's text. A comment that is never closed is read as text, with a warning.

You write
<!--
@Gerald “Could you not?”
Too much? It slows the scene down.
-->

@Percival “Real sheep?”
A listener hears
Percival: Real sheep?
A reader sees
“Real sheep?”

11. Markdown inside the story

Emphasis works as in Markdown. *a word* or _a word_ is printed in italics and stressed when read; **words** or __words__ is printed in bold. The spoken script keeps emphasis as written, so a speech engine can use it.

You write
@Gerald “I don’t *even* like treasure.”
A listener hears
Gerald: I don’t *even* like treasure.
You write
The page said: **JOBS AVAILABLE**
A listener hears
Narrator: The page said: **JOBS AVAILABLE**

A backslash before any ASCII punctuation character, or before a quotation mark, makes it literal. The backslash itself is neither printed nor read.

You write
She wrote \[sic\] and \{page\} on the board.
A listener hears
Narrator: She wrote [sic] and {page} on the board.

New in 1.1. A character reference stands for its character, as in Markdown: &amp;, &quot;, &#8217;, &#x2019; and every name the HTML Standard gives one. It is heard and printed as that character, and a character written this way is never a mark: &quot; opens no quote. A name the HTML Standard doesn't know, or one without its ;, is ordinary text.

New in 1.1
You write
Tom &amp; Jerry said &quot;hello&quot;.
A listener hears
Narrator: Tom & Jerry said "hello".
A reader sees
Tom & Jerry said "hello".

Links and images work as in Markdown (§8.3). Other Markdown blocks (lists, block quotes, tables, code, HTML) are not part of version 1.0. Their lines are treated as ordinary paragraph text, except HTML comments, which are the writer's own (§10.1).

12. The two readings

A file has two readings. Tools derive both from the same text, so they cannot drift apart.

12.1 The spoken script

The spoken script is everything heard, in order, each with its voice: speech and narration, sounds characters make, sounds, page turns and pauses. It also keeps notes and unknown instructions in place, and marks headings, scene breaks and paragraphs. Paragraphs marked {book only} or {hidden} are listed but not heard.

The examples write it like this:

Line Meaning
Character: text Speech or narration.
Character (direction): text The same, with a direction.
Character [description], Character (direction) [description] A sound made by a character.
[description] A sound.
{page}, {page 12}, {pause}, {pause 2s}, {name value} An instruction.
%% text %% A note.
![description](file) An image.
[![description](file)](address) An image that is a link.
# Character: text A heading read aloud, with as many # as its level.
## text {hidden}, ## text {book only} A heading that is not read aloud.
{book only} text, {hidden} text A paragraph that is not read aloud.
--- A scene break.
A blank line Between paragraphs, and around headings and breaks.

How lines are formed:

Group boundaries are not shown; their effect is visible in each line's character and direction.

12.2 The book text

The book text is the printed story as plain Markdown. It is the file with these removed:

What remains keeps its line breaks, quotation marks, emphasis, links and images, and {book only} text without its instruction. Where a removed mark leaves two spaces, one remains. Spaces left at the start or end of a line are removed, and paragraphs left empty are dropped.

You write
@Percival (muffled, echoing) “I meant to do that,” said Sir Percival, from inside the vase. [armor wobbles]
A listener hears
Percival (muffled, echoing): I meant to do that,
Narrator: said Sir Percival, from inside the vase.
[armor wobbles]
A reader sees
“I meant to do that,” said Sir Percival, from inside the vase.
You write
@Wanda (strained and extremely polite) “Could we perhaps travel somewhat more urgently?”

%% The broom considers this. %%

{pause}

The broom considered this.
A listener hears
Wanda (strained and extremely polite): Could we perhaps travel somewhat more urgently?

%% The broom considers this. %%

{pause}

Narrator: The broom considered this.
A reader sees
“Could we perhaps travel somewhat more urgently?”

The broom considered this.

12.3 Warnings

A parser never rejects a file. It should report these warnings, each with its line and column. The codes are stable: tools may match on them, and a later version adds codes but never changes what one means.

Code When Level
unclosed-quote A quote is never closed. warning
quote-over-line-break A quote runs over a line break (fine for verse, but often a missing closing mark). warning
unclosed-group A group is never closed. warning
stray-group-close A line of colons closes no group. warning
idle-mark A character mark gives its character nothing to say or do. warning
idle-end A @/ ends nothing: it is inside a quote, or the line's own voice already speaks (new in 1.2). warning
stray-quote A quotation mark has nothing after it on its line. warning
unknown-character A name is not in the cast, when the file has a cast. warning
name-case A name is written with different capitals in different places. warning
silent-cast-member A cast member never speaks. info
unknown-instruction An instruction this spec does not know has no tool prefix. warning
pause-value {pause} has a value that is not a length. warning
sound-looks-like-link A sound is followed directly by (, which Markdown reads as a link. warning
unclosed-note A %% is never closed, so it is read as text. warning
unclosed-comment A <!-- is never closed, so it is read as text (new in 1.3). warning
front-matter The front matter uses YAML outside the part a reader must understand (§4.2), or its cast is not a map. warning

13. Tools that edit files

The format is meant to be edited both by hand and through a visual editor. A visual editor works on the rendered story and writes the change back into the text. The rules below keep the text the author's own.

  1. Round trip. Reading a file and writing it back without changes produces identical bytes.
  2. Small edits. An edit changes only the characters it must. Tools never reflow text, change quotation styles, normalize spacing or reorder front matter, unless the author asks them to (rule 8).
  3. New marks are written in one way:
    • a character mark and direction go directly before the speech's opening quote, with the cast's spelling: @Gerald (yawning) “…;
    • a direction for narration goes before its first word: @(warmly) Once…;
    • a direction for a speech that takes its direction from its mark goes in the mark, so it covers the whole speech, over the paragraphs that carry it on; a stretch with a @(…) of its own has that one replaced instead;
    • a direction of its own for a paragraph that carries a speech on (§5.7) goes just inside its opening mark, so the paragraph still carries the speech on: “@(softly)Two.”;
    • a sound follows the word it belongs to, after one space: fell over. [clatter];
    • a page turn, pause or note between lines goes on a line of its own;
    • between two characters with no space between them, a mark goes without the space after it, which would show in the book: “Hi.”@Ann—he said. Where the mark would then run on into what follows, as a name runs on into a word's letters, there is no way to write it without changing the book.
  4. Changing who says a line. Replace the name in its mark. If the speech had no mark because it carried on an earlier one (§5.6), add a mark to it. If a later quote on the same line carried this one on, add a mark to that quote too, so its speaker stays the same. A speech over paragraphs (§5.7) is given away whole, from any of its paragraphs: the mark goes before the quote it starts with.
  5. Removing a direction. Delete the parentheses, their content and one space. If the remaining character mark is not needed, remove it too.
  6. Renaming a character. Changing a full name touches only the front matter. Changing a short name replaces it in the cast and in every mark.
  7. A tool's own divisions are never line breaks or words. How a tool cuts the spoken script into pieces of its own, such as one audio recording per sentence, is the tool's business. A tool that keeps such a division in the file writes its own instruction (§9.5), such as a recording tool's {recorder:join} between two sentences it records as one; it never adds a line break or changes the words to make one.
  8. Formatting is asked for. A formatter tidies a file only when its author runs it, and never changes who says what, how, or in what order: words change only in their spaces and, when asked, their quotation marks. It may remove spaces at the start and end of lines, make runs of spaces and of blank lines one, put one blank line after the front matter and around headings and scene breaks, end the file with one line break, and write each name as the cast spells it. It keeps the front matter, line endings and group lines as they are. Changing straight quotation marks to curly ones is a separate choice, made for the story's language; an apostrophe becomes ’, and a mark after a digit, such as 6", stays as it is.

14. Rendering

This section is advice, not a rule.

A renderer can show the file in two ways. The book view is the book text, typeset. The script view is a script for reading aloud, in which:

The quotation marks stay visible in both views. They are part of the story.

15. Conformance

A tool can follow this spec at two levels.

A reader reads VoxDown files: a player, a speech pipeline, a converter, a viewer. A reader

  1. accepts every file, never refusing one (§1);
  2. produces the spoken script of every example in this spec, line for line (§12.1): who says each stretch, with which direction, and every sound, instruction, note and image in its place;
  3. produces the book text of every example that gives one (§12.2);
  4. ignores, without failing, instructions and front matter keys it does not know (§4.2, §9.5).

A reader should also report the warnings in §12.3, with their codes. A viewer that only shows the printed story may stop at the book text and say so.

A writer changes VoxDown files: an editor, a formatter, a tool that adds its own marks. A writer is a reader that also

  1. writes an unchanged file back byte for byte (§13, rule 1), keeping its line endings and any byte order mark;
  2. keeps every front matter key, instruction, note and escape it does not change, where it was written;
  3. writes new marks in the one way §13 rule 3 gives, and edits as rules 4 to 7 say;
  4. changes spacing or quotation marks only when its author asks (§13, rule 8).

The conformance file. Every example in this spec is also in conformance.json, so an implementation can test itself without reading this document. It is a list with one entry per example:

Field Meaning
example The example's number, from 1, in the order this spec gives them.
section The section it is in, such as 5.6.
line The line of this file its fence opens on.
input The file.
script The spoken script, as written in the examples (§3). Required of every reader.
book The book text, when the example gives one. Required of every reader.
lines The spoken script as data: one object per line heard, as the reference parser exports them.
warnings The warnings the reference parser reports: code, line and column. Recommended, not required.

The examples are the tests, and the spec is the authority: if the file and this document ever disagree, this document is right and the file has a bug.

16. Versions

This spec has a version, major.minor, separate from the version of any tool. A file says which it follows with the voxdown front matter key (§4.2).

A file without a voxdown key is read by the latest version the reader knows.

17. Beyond 1.0

Questions for later versions. None of them changes a 1.0 file.