The page contract

A DeckTalk page is an HTML file that the recorder can drive from the narration. The contract consists of a few URL parameters and one global. The file decktalk-runtime.js implements it, and a page can also implement it by hand. Slides are plain HTML that you style yourself, and the runtime adds no styling beyond the stage.

URL parameters

Parameter	Meaning
`scene=N`	Play scene N. Scene ids are strings, and the scaffold uses the script’s section numbers.
`beats=id@s,id@s,…`	Beat mode. Fire cue `id` at `s` seconds after narration t=0. The times come from `build/audio/beats.json` and are relative to the section’s start in the continuous narration.
`t0=S`	The number of seconds after the page’s `load` event at which narration t=0 falls. `t0=signal` makes the page wait for `DeckTalk.startClock()` instead. The recorder uses the signal form: it covers the page in magenta until it starts the clock, and the assembler cuts at the first clean frame.
`step=ID`	Freeze mode. Mount step ID with every reveal in its end state and its handler cues fired. The `shots` command uses it, and so can you.
`speed=X`	The autoplay time scale. Beat mode ignores it.
`hud=1`	Overlay the mode, scene, step, and clock. Never record with it on.
none	Show the index page, which lists every scene and step with play and freeze links.

Globals

window.__sceneReady is an optional Promise. The recorder awaits it before it starts the clock, so a page can wait for fonts, images, or data. The runtime sets it to document.fonts.ready unless the page has set its own.
window.__decktalk exposes { mode, scene, step, cues, fired, catalog, now() }. The catalog field lists every scene and its step ids, and the shots command reads it. The fired field lists the cue ids fired so far.
The runtime sets document.body.dataset.done = "1" once the last step has mounted.

Timing in beat mode

The runtime sorts the cues by time. Each cue belongs to a step. The owner is the step with the same id. Failing that, it is the step whose cues list names the cue, or the step whose id is the longest prefix of the cue id. For example, 4.2b1 belongs to 4.2, and 9a belongs to 9.
A step mounts at the earliest of its cues. The first cued step mounts at t=0 regardless, so a section never opens on an empty stage. A step with no cue never shows. The last cued step holds until the recorder stops.
When a step mounts, any element whose data-cue is in the list stays hidden until that cue fires. Every other reveal fires data-at seconds after the mount, and the default is 0. That covers an element with data-at, and an element whose data-cue is not in the list.
When a cue fires, the matching data-cue elements reveal first. Then the step’s on[id] handler runs, and then every DeckTalk.on(id, fn) handler runs.

Without beats=, the page autoplays. The steps mount in order, and each one holds for hold seconds divided by speed. Reveals fire at data-at, and a step’s cues: { id: seconds } object fires handler cues at those seconds after the mount.

Authoring API

DeckTalk.scene(id, {
  name: "Shown on the index",
  camera: "push",                       // a slow 1.00 -> 1.03 push over the scene; omit for none
  steps: [{
    id: "3.1",                          // also a cue id; the default is "<scene>.<n>"
    hold: 8,                            // autoplay seconds
    cues: ["3.1draw"] | { "3.1draw": 0.5 },  // ownership, and autoplay timing for handler cues
    render: ({ scene, step, frozen }) => "<div class='slide'>…</div>",
    enter: (slideEl, { frozen }) => {}, // runs after the mount, for imperative setup
    on: { "3.1draw": () => {} },        // per-step cue handlers
  }],
});
DeckTalk.on("3.1draw", fn);             // a global cue handler
DeckTalk.start();                       // runs automatically on DOMContentLoaded when scenes exist

The markup attributes inside a step are data-cue, data-at, data-fx, data-dur, data-count, data-type, and data-tex. The data-fx attribute selects the reveal animation. The default is rise, and the others are fade, draw for SVG paths with pathLength="1", drop, pop, dim, and none. The data-dur attribute sets the animation length in seconds, and a count-up defaults to 0.9. The data-count attribute counts the last number in the text up from zero, and data-count="first" counts the first number instead. The data-type attribute types the text at the given milliseconds per character, with a default of 40. The data-tex attribute typesets its value with KaTeX when KaTeX is on the page, and data-display selects display math. The runtime creates #dt-stage, a 1920 by 1080 stage that scales to fit the window, with #dt-cam and #dt-pan inside it. Slides are .dt-slide children of the pan layer. You style the stage and your slides however you like. The runtime’s own CSS uses the dt- prefix.

Build artifacts a page or a script may read

File	Shape
`build/audio/timeline.json`	`{narration, total_seconds, estimated, sections: {"NN": {title, start, end, duration, speech_end, words: [{word, start, end}]}}}`. The seconds are absolute within `narration.mp3`.
`build/audio/beats.json`	`{"NN": "cue@seconds,…"}`. The seconds are relative to the section start.
`build/audio/manifest.json`	One entry per narrated section, with its file, its words file, its hash, and its durations.
`build/rec/NN-scene.json`	What the recorder did, and where narration t=0 sits in the webm.

Recording alignment

The recorder covers the page in magenta from its first paint. It opens the page with t0=signal, waits for load, awaits __sceneReady, waits the settle time and at least min_lead_seconds after the recorder was created, and then removes the cover and calls DeckTalk.startClock() in the same tick. The measure command finds the first clean frame after the magenta run and writes it to the sidecar as lead_in_seconds. The assembler trims the recording there, so video t=0 equals narration t=0 to within a frame on every platform. How it works has the picture. A page that implements the contract by hand must honor t0=signal by starting its clock in DeckTalk.startClock() or an equivalent global, or it will start early.

Get started

Concepts

Reference

Help

The page contract

URL parameters

Globals

Timing in beat mode

Authoring API

Build artifacts a page or a script may read

Recording alignment

​URL parameters

​Globals

​Timing in beat mode

​Authoring API

​Build artifacts a page or a script may read

​Recording alignment

URL parameters

Globals

Timing in beat mode

Authoring API

Build artifacts a page or a script may read

Recording alignment