Cues

​

The cue id

## 1. Open

This is DeckTalk. [beat] Four files sit in one folder, and you write two of them. [beat]
You write what you will say, [beat] and you write the slides that go with it. [beat]
Then every picture waits for its own word.

{ "sections": { "1": { "cues": [
  { "id": "1.1:title", "phrase": "This is DeckTalk", "occurrence": 1 },
  { "id": "1.1:files", "phrase": "Four files", "occurrence": 1 },
  { "id": "1.2:script", "phrase": "what you will say", "occurrence": 1 },
  { "id": "1.2:deck", "phrase": "the slides", "occurrence": 1 },
  { "id": "1.2:word", "phrase": "its own word", "occurrence": 1 }
] } } }

<template data-slide="1.2" data-preview-seconds="12" data-describe="the two files you write, and the promise">
  <div class="card first" data-in="script"
       data-describe="a card for script.md, the file that holds what you say">
    <div class="k">script.md</div>
    <div class="v">what you will say</div>
  </div>
</template>

​

What decktalk cue does

decktalk cue                 # resolve every section
decktalk cue --section 2,3   # resolve these sections and leave the rest of the file alone
decktalk cue --json          # the result as one flat object, carrying run, sections and file

​

Matching rules

1. It splits the phrase and the spoken words on whitespace.
2. Each token keeps its letters and digits, in any script, and its apostrophes, with a curly apostrophe read as the straight one. So café, naïve and η are tokens as written.
3. Matching ignores case unless the cue sets case_sensitive to true.
4. A token with no letter or digit left is ignored, so the phrase learning rate - matches as learning rate. A letter is never ignored, so the phrase learning rate η needs a spoken η.
5. A word that punctuation divides, such as state-of-the-art or R&D, matches whole and by its parts. The phrases state of the art and state-of-the-art both match a spoken state-of-the-art, and zig-zag matches a spoken zig zag. A phrase that starts inside such a word lands on that word’s start. A word with no letter or digit in it, such as an & or a / spoken as a word of its own, is skipped on both sides, so R & D and tools / fast resolve.
6. The stage looks through the spoken words in order for a run that matches the phrase token for token. occurrence picks which match, counting from 1, and the default is the first.
7. The second is the start of that run’s first word, plus the cue’s offset_seconds, rounded to a millisecond and never earlier than the section’s own start.
8. $start is the section’s own start, which is 0 seconds on its clock.
9. $end is the end of the section’s last spoken word.

​

Which sections have cues

​

Cue mismatches

• CUE_UNLISTED is a moment on the page that nothing in cues.json gives a second to. Add the row, or take the moment off the page. Its fix adds the row for you, which the next section describes.
• CUE_UNKNOWN is a row whose cue id no slide of the section’s scene declares. The row is named and never deleted. When exactly one stale row sits beside exactly one moment nothing lists in the same section, the two are read as a rename and an unsafe fix changes the id alone, keeping the phrase you already wrote. The phrase is what survives a rename, so the row that carries it is the row for that moment. --allow CUE_UNKNOWN carries on past it, for a deck that builds ids at run time.
• CUE_UNRESOLVED is a phrase the section does not speak. Fix the phrase, or fix the script. A section with no take at all resolves nothing, and the message says which of the two it is.
• CUE_STALE is a cue file edited after the film was built. verify measures the film on disk, and that film was cut to the cue times of the last build, so a row whose phrase or offset changed since, a row added since and a row removed since are all measured against moments nobody asks for now. Nothing is wrong with the phrase. Run decktalk build, which places the cues again and records only the sections they moved.
• CUE_NO_ONSET is a cue whose second is 0, which is where the section starts rather than where a word does, or a cue in the finished film that changed the picture with no frame rising by verify.onset_rise_points. Nothing measures its landing against a word, so the offset check cannot run for it. What a cue at 0 reveals arrives as a cut on the section’s first frame.
• CUE_OVERLAP is two cues closer together than the first one’s own motion lasts. The second moment starts while the first is still playing, so a viewer cannot tell them apart and neither can the measurement.
• CUE_NO_CHANGE is a cue where less of the picture changed than verify.changed_share_min_percent, or whose margin over its control was under verify.margin_min_points. The reveal is too small or too pale to see, or it never played.
• CUE_THIN_CHANGE is a cue that passed with less than verify.thin_change_factor times that floor. It is a second opinion rather than a failure, and setting the factor to 1 turns it off.
• CUE_OFF is a reveal whose measured onset sits further from its word than verify.cue_offset_max_ms, or a word whose click sounds further from the second it was promised than verify.av_offset_max_ms. The sound has the wider limit, because an mp3 frame smears a transient and the encode adds its own.

​

The fix that writes cues.json

decktalk check --fix   # open every page, judge it, and add the row for every missing moment
decktalk build --fix   # the same, as part of a run that goes on to make the film

​

Phrase choice

• Start the phrase with the word that names the thing that happens, because the second is the start of the phrase’s first word. A noun such as box of dials works, and so does a verb with its object, such as steps downhill. A connective such as “and then” does not.
• If a word repeats in the section, use two or three words, or set occurrence. Setting occurrence to 1 keeps the first match and silences the warning.
• Set a small positive offset_seconds, 0.1 to 0.2 seconds, so the viewer hears the word begin before the picture moves.
• Use a negative offset_seconds only when the audience has to read along, and remember that a cue can never resolve before its own section starts.
• Put a [beat] or a [pause N] before a moment that should feel like an event.
• Land a summary on $end, so it arrives as the voice stops.
• Set verify to false on a row whose change is too small or too slow for a frame difference to see, which leaves that cue out of the measurement rather than out of the film.

​

Sound on a cue

​

Terms

​

Next

• Write phrases that land well: Writing for the ear
• Look up every key of the file: cues.json
• Learn which slide owns a cue: The page contract