cues.json

cues.json is the cue file. It names the spoken phrase for each cue id, section by section. It is optional. A project without it plays every page with the page’s own autoplay timing. This page lists every key.

cues.json

{
  "sections": {
    "8": {
      "cues": [
        { "cue": "7.1box", "on": "box" },
        { "cue": "7.1moved", "on": "moved" },
        { "cue": "7.1checked", "on": "checked" },
        { "cue": "7.1back", "on": "step back" }
      ]
    },
    "9": {
      "cues": [
        { "cue": "5.1clear", "on": "video" },
        { "cue": "5.1made", "on": "DeckTalk" },
        { "cue": "5.1cap", "on": "Open source" },
        { "cue": "5.1url", "on": "decktalk dot app" }
      ]
    }
  }
}

Section 8 of the scaffold plays scene 7 of its page, so its cue ids start with 7.1. Section 9 plays scene 5, so its cue ids start with 5.1. The block below is a shape, not the scaffold’s values. It shows the optional keys.

cues.json

{
  "sections": {
    "<section number>": {
      "min_seconds": 30,
      "cues": [
        { "cue": "<cue id>", "on": "<phrase>", "offset": 0.2, "occurrence": 2, "case_sensitive": false, "verify": true }
      ]
    }
  }
}

Shape

The file is one object with a sections key. The load ignores every other top-level key, such as _comment. Each key of sections is a section number as a string, and it must name a [[section]] in decktalk.toml. Each section is an object with an optional min_seconds and a cues list. Every cue id must appear in its page as a quoted literal, such as data-cue="1.1bowl" or a key of a step’s cues object. Cue mismatches says what happens when an id is missing.

Section keys

Key	Type	Default	Meaning
`cues`	array	`[]`	The cues of the section.
`min_seconds`	number	none	Seconds of speech that the visuals need. Shorter speech is an uncertain finding.

Note: For short speech, decktalk beats prints the note speech <S>s is <D>s shorter than the visuals need. beats --strict exits 1 on it.

Cue keys

Key	Type	Default	Meaning
`cue`	string	required	The cue id.
`step`	string	none	Synonym for `cue`. Wins when both keys are present.
`on`	string	required	A word or short phrase from the section’s script, `$start`, or `$end`.
`offset`	number	`0`	The offset key. Seconds added to the match. Can be negative.
`occurrence`	integer	`1`	Which match of the phrase to use. When the phrase occurs more than once and this key is not set, `beats` warns.
`case_sensitive`	boolean	`false`	Matches case as written.
`verify`	boolean	`true`	`false` leaves the cue out of a plain `decktalk verify`, which shows the row as `skipped` with `OPTED_OUT`.

Note: A cue id must not contain a comma, because commas separate the pairs in ?beats=. DeckTalk does not check this. An @ in an id still works, because the page splits each pair at its last @. Avoid @ anyway, so ids stay easy to read. Note: decktalk verify still checks a "verify": false cue that you name as SECTION:CUE.

Anchors

Anchor	Cue time
`$start`	0.0 s after the section start, plus the offset key. A negative result stays negative, and the page fires it at t=0.
`$end`	The end of the section’s last spoken word, plus the offset key. Not the end of the section’s audio file.

Note: decktalk verify skips a $start cue with no offset key, as REFERENCE_CLAMPED. Note: A section’s lead_seconds moves every word, and so every phrase cue and $end, that much later. $start stays at 0. Skipped rows explains why.

Output files

decktalk beats writes build/audio/beats.json, with each section’s cue times as its ?beats= string. It also writes build/audio/beats.anchors.json, with each cue’s word start before the offset key. Build artifacts has the shape of both files.

Learn the matching rules: Cues
Write phrases that time well: Writing for the ear
Learn which step owns a cue: The page contract

Get started

Guides

Concepts

Reference

Help

Shape

Section keys

Cue keys

Anchors

Output files

​Shape

​Section keys

​Cue keys

​Anchors

​Output files

​Related

Shape

Section keys

Cue keys

Anchors

Output files

Related