Write a page by hand

Most pages should include decktalk-runtime.js and skip this guide. Use this guide only when a page comes from another framework and cannot include the runtime. It lists what the recorder and decktalk shots need, and it shows a small page that does all of it.

Before you start

You need to write JavaScript. Read The page contract first.

Meet the needs of the recorder

The recorder drives the page through its URL and a few globals. This table pairs each action of the recorder with what your page does.

What the recorder does	What your page does
The recorder opens `page.html?scene=N&beats=id@s,…&t0=signal`, with any `params` from the section.	The page reads `scene` and `beats`. It schedules cue `id` at `s` seconds after the clock starts.
The recorder adds `&words=word@s,…` when the timeline has words for the section.	The page can use the words to show text one word at a time, or it can ignore them.
The recorder adds `&prevwords=word@s,…` when the section just before has words.	A page that opens on the previous section’s last frame can read them, or it can ignore them.
The recorder awaits `document.fonts.ready`, then `window.__sceneReady` when it is a Promise.	The page sets `window.__sceneReady` to a Promise that resolves when the page is ready.
The recorder calls `window.DeckTalk.startClock()` one time, at narration t=0.	The page starts its clock in that call and nowhere else.
The recorder reads `window.__decktalk.catalog` after the recording.	The page lists at least one scene in `catalog`. A missing or empty list is a page error.
The recorder reads `window.__decktalk.warnings`, `frameGaps`, and `syncLog`.	The page adds a string to `warnings` for anything it cannot do. `frameGaps` and `syncLog` are optional.
The recorder uses a browser window of `[video] width` by `height`.	The page draws at 1920 by 1080, or it scales a 1920 by 1080 element to fit the window.

The magenta cover belongs to the recorder, so a page needs no cover of its own. How it works explains what the cover does.

Support decktalk shots

decktalk shots uses the page in three ways:

It opens the page with no query and reads window.__decktalk.catalog. If the page has no catalog, shots warns and skips the page.
It opens ?step=ID for each step id in the catalog. With --cue, it opens ?step=ID&cue=CUE.
In frame mode, shots --section N --at S opens the recorder’s URL. It logs window.__decktalk.fired with each frame.

decktalk preflight also reads catalog[].cues, which maps each step id to its cue ids in autoplay order. It opens ?step=ID&cue=CUE and ?step=ID&before=CUE. A page whose catalog has no cues gets every cue skipped as RUNTIME_OUTDATED.

Write the minimal page

Start the page clock only inside DeckTalk.startClock(). A page that starts its clock at load fires every cue early, and every reveal in the video comes before its word.

The page below follows the whole contract in about forty lines. It has one scene with one step. Each cue shows the element with the matching data-cue.

deck/plain.html

<!doctype html>
<meta charset="utf-8">
<style>
  html, body { margin: 0; background: #0b0f14; color: #f4f6f8; font: 44px/1.3 Inter, sans-serif; }
  #stage { position: absolute; left: 0; top: 0; width: 1920px; height: 1080px; padding: 100px 160px; box-sizing: border-box; }
  [data-cue] { opacity: 0; transition: opacity .35s; }
  [data-cue].on { opacity: 1; }
</style>
<div id="stage">
  <h1 data-cue="1.1a">A page by hand</h1>
  <p data-cue="1.1b">It follows the contract without the runtime.</p>
</div>
<script>
  const params = new URLSearchParams(location.search);
  const state = { mode: "index", scene: params.get("scene"), step: "1.1", cues: [], fired: [], warnings: [], origin: null,
                  catalog: [{ scene: "1", name: "By hand", steps: ["1.1"] }], now: () => state.origin === null ? -Infinity : (performance.now() - state.origin) / 1000 };
  window.__decktalk = state;
  window.__sceneReady = document.fonts.ready;

  const cues = (params.get("beats") || "").split(",").filter(Boolean).map((tok) => {
    const i = tok.lastIndexOf("@");
    return { id: tok.slice(0, i), t: parseFloat(tok.slice(i + 1)) };
  });
  state.cues = cues;
  for (const c of cues) if (!document.querySelector(`[data-cue="${c.id}"]`)) state.warnings.push(`unknown cue id ${c.id}`);

  function fire(id) {
    state.fired.push(id);
    document.querySelectorAll(`[data-cue="${id}"]`).forEach((el) => el.classList.add("on"));
  }
  function startClock() {
    if (state.origin !== null) return;
    state.origin = performance.now();
    if (cues.length) state.mode = "cues";
    for (const c of cues) setTimeout(() => fire(c.id), c.t * 1000);
  }
  window.DeckTalk = { startClock };

  if (params.has("step")) { state.mode = "frozen"; document.querySelectorAll("[data-cue]").forEach((el) => el.classList.add("on")); }
  else if (params.get("t0") !== "signal") startClock();   // a browser preview starts at once
</script>

To use the page in a project, follow these steps:

Save the page as deck/plain.html.
Add a [[section]] with page = "deck/plain.html" and scene = 1.
Add cues 1.1a and 1.1b for that section in cues.json.
Open deck/plain.html?step=1.1 in a browser to see every element.

The page has no autoplay timing. A browser preview with ?scene=1 shows nothing until you add &beats=1.1a@1,1.1b@2 to the URL.

Compare with the runtime

The runtime gives a page more than this minimal page does:

an index of scenes and steps
autoplay from hold and data-at
reveal effects, count-ups, typewriting, and word sync
KaTeX typesetting, with a wait for the library
a camera push
a warning for each mismatch between cues and steps
a list of gaps between animation frames

Runtime lists all of it. A page by hand can add any of these features.

Learn how a page plays: The page contract
Look up the runtime’s fields: Runtime
Write a page with the runtime: Your first deck

Get started

Guides

Concepts

Reference

Help

Write a page by hand

Before you start

Meet the needs of the recorder

Support decktalk shots

Write the minimal page

Compare with the runtime

Next

​Before you start

​Meet the needs of the recorder

​Support decktalk shots

​Write the minimal page

​Compare with the runtime

​Next

Before you start

Meet the needs of the recorder

Support decktalk shots

Write the minimal page

Compare with the runtime

Next