audio@0.1

Grammar

Distilled for this page. audio@0.1 shares the envelope, inline-field and preservation rules with every other spec, and nothing else — it has no items, so the shared item vocabulary (priority, due, owner) is not recognized here. Those keys are unknown fields in a manuscript: preserved, never narrated, never an error.

---
markdownto: audio@0.1
title: Field notes, week 32   # optional, reserved — never narrated
voice: warm-narrator          # optional, spec-defined
pace: relaxed                 # optional, spec-defined
pronunciations:               # optional, spec-defined
  agentsFS: agents F S
  mdto: em dee tee oh
  Kaufmann: KOWF-mun
---

voice

A single token matching [A-Za-z][A-Za-z0-9._-]* (MDTO300), resolved against the provider’s catalogue at production time, not at validation time.

pace

slow | relaxed | natural | brisk | fast. Case-insensitive; default natural (MDTO301).

pronunciations

Written form to spoken form. Matching is case-insensitive on whole-word boundaries; multi-word keys are allowed; when several keys could match at one position, the longest wins and ties break by source order. That is the whole of the determinism rule, and it is why the IR carries them as an ordered array rather than a map.

A chapter is opened by a heading at the document’s chapter level. The chapter level is ## if the document contains at least one ## heading, and # otherwise. The level is decided once, for the whole document, by a single pass over its headings. It never varies within a file.

# Three letters to a younger engineer
# On being slow
# On being wrong
        no `##` anywhere, so `#` is the chapter level

# Field notes, week 32
## The idea
## What I built
        the file contains `##`, so `##` is the chapter
        level and that `#` is the leading title heading

below the level

### under ## chapters is ordinary narrated content. It is read where it stands and opens nothing — which is what makes a long chapter with sections in it a legal manuscript rather than a structural error.

above the level

Permitted only as the first block after the frontmatter, where it is the document’s title heading. Anywhere else it is MDTO310: it is narrated in place and opens nothing, so the prose beneath it cannot silently migrate.

the implicit chapter

Narratable content before the first chapter heading forms a leading chapter titled null — a preface, or a whole document with no headings at all. It exists only when there is such content.

numbering

1..N in document order, counting the implicit chapter. These are the numbers preview --chapter N addresses and the numbers that prefix output filenames. Titles need not be unique; chapters are addressed by number, never by name.

Within a narrated block the rule is what a person would read aloud off the page: link text but not the URL, a wikilink’s name but not its brackets, a tag’s word but not its #, the emphasized words but not the markers. An inline code span is read as its literal characters; only block code is excluded. An image contributes nothing, because alt text describes a picture and turning it into speech would be the spec guessing.

narrated

Paragraphs · headings at any level, including the one that opens the chapter · lists of every kind, each item its own utterance · blockquotes.

never narrated

Fenced and indented code · tables · HTML blocks · thematic breaks, which insert nothing, not even silence. Excluded by kind, permanently: speech is linear and these are not, and there is nowhere on a fence line to write a direction field, so a default that could be overridden would be one nobody could reach.

never narrated, ever

Inline fields, in any Markdown To spec. That is exactly what makes them usable as direction here. List markers, ordinal numbers and task checkboxes are not read either — - [x] Water within reach is read as “Water within reach”.

nothing at all

A document with no narratable content is MDTO330: it names itself a manuscript and gives produce nothing to say.

A direction field applies to the top-level block that contains it, wherever in that block it is written — position is never meaningful, here or in any other spec. The one finer grain is the list item, because a list is a sequence of separate utterances rather than one run of prose.

Then we put it on a slide.

[pause:: 2s]

Kaufmann pointed out that we had all been
saying it differently for a month.

> [narration:: skip] Clear this anecdote with him first.

[narration:: skip]

The block it appears in is not narrated. skip is the only value in 0.1 (MDTO320). On a chapter heading it silences the title only — the chapter still exists, is still numbered, and its blocks are still narrated.

[pause:: …]

Holds silence after the block. A number and a unit, ms or s; greater than 0 and at most 60s. The unit is required — a bare 2 is MDTO321, because seconds and milliseconds are three orders of magnitude apart and guessing is not worth being wrong once.

at most one of each

Per block. A repeat is the shared MDTO023: two values with no defined precedence is ambiguity.

Read audio@0.1 in full — the normative text Shared conventions

Diagnostics carry the repair

Direction is the part of a manuscript a reader cannot proof-read, so its diagnostics work hardest. Each one names the offending value, says why the spec refuses it, and — where the mistake has a common cause — says what the author probably meant.

---
markdownto: audio@0.1
title: Rehearsal notes
---

The room went quiet. [pause:: 2]

Then the door opened. [pause:: two seconds]

She still did not look up. [pause:: 0s]

[pause:: 90s]

[narration:: whisper] Say this next part gently.

[narration:: skip] Cut this line for now. [pause:: 3s]

[narration:: skip]

And that is the whole scene, which takes four minutes and feels like ten.