Build artifacts

DeckTalk writes every generated file under build/, and your own tools can read any of them. This page lists each file, its time base, and its fields. Field names in the JSON files match the dataclasses in decktalk.artifacts. The file shapes are part of the stable surface that the changelog tracks.

build/
  audio/   NN-slug.mp3, NN-slug.words.json, manifest.json, narration.mp3, timeline.json,
           beats.json, beats.anchors.json
  rec/     NN-scene.webm, NN-scene.json
  out/     NN-section.mp4, <name>.mp4, <name>-YYYYMMDD-HHMM.mp4, <name>.srt, <name>.vtt,
           <name>.chapters.txt, slates/NN-slate.png
  shots/   [<page>/]step-<id>.png, [<page>/]step-<id>-cue-<cue>.png, section-NN-at-<S>s.png
  sfx/     ambience.mp3, <name>.mp3, and a manifest file next to each
  music/   underscore.mp3, its chunk files, and its manifest file

NN is the two-digit section number. slug comes from the section title in script.md. <name> is [project] name in decktalk.toml. A clip section has no mp3, words file, or recording.

Time bases

Each time in these files counts from a fixed starting point, its time base. Read the time base before you compare times from two files.

Value	Counts from
`NN-slug.words.json` `start` and `end`	The start of that section’s mp3. The first spoken section includes `lead_break_seconds`.
`timeline.json` section and word times	The start of `narration.mp3`, which holds the spoken sections back to back.
`beats.json`, `beats.anchors.json`, `?beats=`, `?words=`, `decktalk words`, `decktalk clip --from` and `--to`	The section’s own start, which is narration t=0 of its recording.
A words file that `decktalk clip` writes	The start of that clip.
Sidecar `lead_in_seconds`	The start of the webm.
Sidecar `frame_gaps` seconds	Narration t=0 of that recording, or `null` for a gap that ended before t=0.
`.srt`, `.vtt`, `.chapters.txt`, and the verify `at` and `cut at` columns	The start of the final mp4.

A clip section adds its length to the final mp4, but not to narration.mp3. After a clip between two page sections, a time in the final mp4 is the narration time plus the length of every earlier clip. A clip before the first page section shifts every time. Page sections are cut on whole frames, so the two times can also differ by up to one frame. Example: in the silent build of the scaffold, section 6 starts at 196.70 s in timeline.json and at 201.08 s in the final mp4. The 4.36 s slate of clip section 5 sits between them, and the whole-frame cuts before it add 0.02 s. decktalk status prints narration times.

`build/audio/NN-slug.words.json`

A words file lists each spoken word of one section, with its times in that section’s mp3.

[
 {
  "word": "A",
  "start": 0.7,
  "end": 1.225
 },
 {
  "word": "bowl",
  "start": 1.245,
  "end": 1.77
 },

Field	Type	Meaning
`word`	string	The spoken word, with punctuation removed.
`start`	number	Start of the word, in seconds.
`end`	number	End of the word, in seconds.

Note: A silent build writes estimated words, spaced evenly at silent_words_per_minute. Each estimated word ends 0.02 s before the next one starts. Note: decktalk words prints the same words in seconds after the section starts, with the script’s punctuation and case.

`build/audio/manifest.json`

The manifest is the narration cache. It holds one entry per spoken section.

{
  "script": "script.md",
  "model": "silent-placeholder",
  "output_format": "mp3_44100_128",
  "estimated": true,
  "estimate_basis": "150 wpm + declared pauses",
  "segments": {
    "01": {
      "index": 1,
      "title": "Open",
      "file": "01-open.mp3",
      "words_file": "01-open.words.json",
      "hash": "silent",
      "words": 29,
      "est_seconds": 12.4,
      "duration_seconds": 17.832,
      "target_seconds": null,
      "speech_end_seconds": 16.48,
      "tail_padded_seconds": 0.0,
      "spoken": "A bowl. A ball. Watch it step down on my count. One. Two, three. I wrote the words and drew the pictures, and each picture waits for its word."
    },

Field	Type	Meaning
`script`	string	Path of the script, relative to the project.
`model`	string	Speech model. `silent-placeholder` after a silent build.
`output_format`	string	Audio format that the speech provider returned.
`estimated`	boolean	True after a silent build.
`estimate_basis`	string	Pacing of a silent build, such as `150 wpm + declared pauses`. Empty after a voiced build.
`segments`	table	One entry per spoken section, keyed by `NN`.
`segments.NN.index`	integer	Section number.
`segments.NN.title`	string	Section title from the script heading.
`segments.NN.file`	string	Name of the section’s mp3.
`segments.NN.words_file`	string	Name of the section’s words file.
`segments.NN.hash`	string	Cache key of the section. `silent` after a silent build.
`segments.NN.words`	integer	Word count of the spoken text.
`segments.NN.est_seconds`	number	Length estimate at `words_per_minute`.
`segments.NN.duration_seconds`	number	Real length of the mp3.
`segments.NN.target_seconds`	number or null	Time budget from the time range in the heading, or `null` when the heading has none.
`segments.NN.speech_end_seconds`	number or null	End of the last spoken word.
`segments.NN.tail_padded_seconds`	number	Silence that `narrate` added after the last word. A take with a value above 0 is not padded again while its tail is within 0.06 s of `min_tail_seconds`.
`segments.NN.spoken`	string	The words sent to the voice, with the script’s punctuation and case, and without break tags.
`total_seconds`	number	Sum of every `duration_seconds`.

Note: Captions take their spelling from spoken, so they match the audio even after the script changes. A manifest without spoken falls back to the current script. Rebuild one section explains what the hash covers.

`build/audio/timeline.json`

The timeline gives section and word times in narration.mp3.

{
 "narration": "narration.mp3",
 "total_seconds": 245.8,
 "sections": {
  "01": {
   "title": "Open",
   "start": 0.0,
   "end": 17.8,
   "duration": 17.8,
   "speech_end": 16.48,
   "words": [
    {
     "word": "A",
     "start": 0.7,
     "end": 1.225
    },

Field	Type	Meaning
`narration`	string	File name of the narration track.
`total_seconds`	number	Length of the narration track.
`sections`	table	One entry per spoken section, keyed by `NN`.
`sections.NN.title`	string	Section title.
`sections.NN.start`	number	Start of the section in `narration.mp3`, where its `lead_seconds` of silence begins.
`sections.NN.end`	number	End of the section, including the silence after its last word.
`sections.NN.duration`	number	`end` minus `start`.
`sections.NN.speech_end`	number or null	End of the section’s last spoken word, in `narration.mp3`.
`sections.NN.words`	array of tables	The words of the section, with `word`, `start`, and `end` in `narration.mp3`.
`sections.NN.lead_seconds`	number	Silence joined in before the section’s mp3, from the section’s `lead_seconds`. `duration` and the word times include it.
`estimated`	boolean	True after a silent build.

Note: The section span runs from start to end. The spoken span runs from start to speech_end.

`build/audio/beats.json`

The beats file holds the cue times of each section, as the string the page receives in ?beats=. A section with no resolved cue is not in the file.

{
  "01": "1.1bowl@1.25,1.1ball@2.33,1.1count@6.15,1.1one@6.69,1.1two@7.24,1.1three@7.78,1.1word@15.41",
  "02": "2.1mark@1.46,2.1script@2.92,2.1aloud@5.85,2.1word@9.26,2.1follows@14.62,2.1lesson@17.06",
  "03": "3.1examples@2.48,3.1rules@3.47,3.1ml@7.43,3.1box@11.39,3.1guess@13.38,3.1wrong@15.85,3.1turn@19.82,3.1right@23.29,3.1lower@25.76,3.1next@27.75,3.1fix@29.73,3.1again@31.71,3.2way@35.67,3.2one@41.62,3.2billions@44.59,3.2instead@47.56,3.2all@52.02,3.3two@54.5,3.3floor@55.98,3.3height@59.95,3.3bowl@64.41,3.4ball@65.4,3.4see@70.85,3.4steps@77.29,3.4again@78.28,3.4name@84.72,3.5setting@90.17,3.5long@93.64,3.5short@97.6,3.6zoom@101.07,3.6low@107.02,3.6lowest@109.99,3.7ai@110.48,3.7inside@114.94,3.7num@117.91,3.7tensor@118.91,3.8gpu@120.39,3.8row@122.87,3.8once@124.36,3.8calc@129.31,3.8llm@134.26,3.8split@137.73",
  "04": "4.1out@2.65,4.1video@7.42,4.1parts@9.0,4.1script@11.12,4.1start@12.71",
  "06": "6.1step@2.61,6.1four@5.22,6.1box@7.32,6.1build@10.97,6.1aloud@14.11,6.1kept@16.2,6.1new@19.86",
  "08": "7.1box@2.39,7.1moved@5.26,7.1checked@10.03,7.1back@11.47",
  "09": "5.1clear@0.91,5.1made@4.1,5.1cap@4.56,5.1url@10.03"
}

Each item is cue id@cue time, and a comma separates the items. Section 08 plays scene 7, so its cue ids start with 7.. The page parser splits each item at the last @.

`build/audio/beats.anchors.json`

The anchors file holds the start of each cued word without its offset key, per section. verify uses it after a silent build to find the click at the cued word.

{
 "01": {
  "1.1bowl": 1.25,
  "1.1ball": 2.33,
  "1.1count": 6.15,
  "1.1one": 6.69,
  "1.1two": 7.24,
  "1.1three": 7.78,
  "1.1word": 15.41
 },

Note: A cue with no offset key has the same time in both files. The a/v value explains why the anchor matters.

`build/rec/NN-scene.json`

The sidecar lists what the recorder did for one page section, and where narration t=0 sits in the webm.

{
  "url": "file://~/my-lesson/deck/index.html?scene=7&beats=7.1box%402.39%2C7.1moved%405.26%2C7.1checked%4010.03%2C7.1back%4011.47&words=One%400.00%2Cmore%400.48%2Ccount%400.96%2Cone%401.43%2Cmore%401.91%2Cbox%402.39%2CEvery%402.87%2Cpicture%403.34%2Cin%403.82%2Cthe%404.30%2Cstart%404.78%2Cmoved%405.26%2Cto%405.73%2Cstay%406.21%2Con%406.69%2Cits%407.17%2Cword%407.64%2Cand%408.12%2Ceach%408.60%2Cone%409.08%2Cis%409.56%2Cchecked%4010.03%2CNow%4010.51%2Clet%27s%4010.99%2Cstep%4011.47%2Cback%4011.94%2Cin%4012.42&prevwords=Say%400.00%2CI%400.52%2Cwant%401.05%2Cone%401.57%2Cmore%402.09%2Cstep%402.61%2CI%403.14%2Cadd%403.66%2Cone%404.18%2Cword%404.70%2Cfour%405.23%2Cand%405.75%2Ctell%406.27%2Ca%406.79%2Cnew%407.31%2Cbox%407.84%2Cto%408.36%2Cwait%408.88%2Cfor%409.41%2Cit%409.93%2CI%4010.45%2Cpress%4010.97%2Cbuild%4011.50%2COnly%4012.02%2Cpart%4012.54%2Cone%4013.06%2Cis%4013.59%2Cread%4014.11%2Caloud%4014.63%2Cagain%4015.15%2CThe%4015.68%2Crest%4016.20%2Ckeep%4016.72%2Ctheir%4017.24%2Cvoice%4017.77%2CHere%4018.29%2Cis%4018.81%2Cthe%4019.33%2Cnew%4019.86%2Cstart%4020.38&t0=signal",
  "requested_seconds": 14.49999999999999,
  "settle_seconds": 1.452,
  "load_seconds": 0.05,
  "lead_seconds": 1.502,
  "lead_in_seconds": 1.44,
  "lead_method": "cover (36 magenta frames)",
  "warnings": [],
  "page_errors": [],
  "frame_gaps": [],
  "sync_log": [],
  "cue_log": [
    {
      "id": "7.1box",
      "due": 2.39,
      "ran": 2.392,
      "frame": 2.392,
      "next": 2.4,
      "after": 2.408
    },
    {
      "id": "7.1moved",
      "due": 5.26,
      "ran": 5.266,
      "frame": 5.266,
      "next": 5.275,
      "after": 5.283
    },
    {
      "id": "7.1checked",
      "due": 10.03,
      "ran": 10.034,
      "frame": 10.034,
      "next": 10.042,
      "after": 10.05
    },
    {
      "id": "7.1back",
      "due": 11.47,
      "ran": 11.475,
      "frame": 11.475,
      "next": 11.483,
      "after": 11.492
    }
  ],
  "long_frames": []
}

Field	Type	Meaning
`url`	string	Page URL that the recorder opened, with `scene`, `beats`, `words`, `prevwords`, `t0=signal`, and any section `params`.
`requested_seconds`	number	Recording length after narration t=0: the section span plus `extra_seconds`.
`settle_seconds`	number	Wall-clock seconds from the page’s `load` event to narration t=0.
`load_seconds`	number	Wall-clock seconds from the recorder’s start to the page’s `load` event.
`lead_seconds`	number	Wall-clock seconds from the recorder’s start to narration t=0. Not the same as `[verify] lead_seconds`.
`lead_in_seconds`	number or null	Time of the first frame after the magenta cover, in the webm. `measure` writes it, and `assemble` trims there.
`lead_method`	string or null	How `measure` found `lead_in_seconds`. A value that starts with `NO COVER` is a guess.
`lead_in_hash`	string or null	The first 16 hex digits of the sha256 of the webm that `measure` read. A sidecar from an older `measure` has none.
`warnings`	array of strings	`window.__decktalk.warnings`, read after the recording, such as an unknown cue id.
`page_errors`	array of strings	One line per uncaught exception, plus one line when the page has no runtime catalog.
`frame_gaps`	array	`[seconds, ms]` pairs from `window.__decktalk.frameGaps`, one per long gap between two page frames.
`sync_log`	array of tables	One `{ text, cueAt, runAt, n, firstOn }` table per `data-sync` element that matched.
`cue_log`	array of tables	One `{ id, due, ran, frame, next, after }` table per cue, from `window.__decktalk.cueLog`. Times are seconds after narration t=0.
`long_frames`	array of tables	One `{ start, ms, render, presented }` table per page frame over 50 ms after t=0, from `window.__decktalk.longFrames`.

Note: check reports PAGE ERROR for any entry in page_errors, and decktalk build stops. check reports STALLED when the part of a frame gap after t=0 is longer than [align] stall_ms. record sets lead_in_seconds to null, and measure fills it. assemble prints STALE MEASUREMENT when lead_in_seconds is null, when lead_in_hash does not match the webm, or, with no lead_in_hash, when the webm is newer than the sidecar.

`build/out/`

The out directory holds each cut section, the final video, its captions, and its chapters.

File	Meaning
`NN-section.mp4`	One section cut to its span, at the project’s frame size, with no audio. `assemble` and `verify` read only the files of sections in `decktalk.toml`, and warn about any other file with this name.
`<name>.mp4`	The final video, with one chapter per section. Consecutive sections with the same title share a chapter.
`<name>-YYYYMMDD-HHMM.mp4`	A timestamped copy of the final video.
`<name>.srt`, `<name>.vtt`	Captions from the word times, in final mp4 time, with the script’s punctuation and case.
`<name>.chapters.txt`	An ffmetadata file with one `[CHAPTER]` per section, titled from `decktalk.toml`. Consecutive sections with the same title share one `[CHAPTER]`.
`slates/NN-slate.png`	The slate image of a clip section whose file is missing.

Captions break at sentence ends.

A caption never spans two sections.
No caption covers a clip section, unless the section sets words. Those captions come from the clip’s words file.
A caption also ends before any silence of 1 s or more.
Whole sentences share a caption when they fit. A sentence too long for one caption splits at the comma nearest its middle, or else between two words that are not short words like “of” or “the”. Each part keeps at least three words.
A caption holds at most two lines of 42 characters. The line break goes after a sentence end or a comma when the two lines stay balanced.
No caption and no line is a single word, unless that word is a whole sentence.
A caption starts at its first word and ends 0.2 s after its last word, or when the next caption starts.

build/out/my-lesson.srt

1
00:00:00,700 --> 00:00:02,879
A bowl. A ball.

2
00:00:02,879 --> 00:00:08,328
Watch it step down on my count.
One. Two, three.

build/out/my-lesson.chapters.txt

;FFMETADATA1

[CHAPTER]
TIMEBASE=1/1000
START=0
END=17800
title=Open

`build/shots/`

decktalk shots writes screenshots here. With two or more pages, it writes one folder per page, named after the page file.

wrote build/shots/index/step-1.1.png
wrote build/shots/index/step-2.1.png
wrote build/shots/index/step-4.1.png
wrote build/shots/index/step-6.1.png
wrote build/shots/index/step-7.1.png
wrote build/shots/index/step-5.1.png
wrote build/shots/lesson/step-3.1.png

File	Written by
`step-<id>.png`	`decktalk shots`, one per step
`step-<id>-cue-<cue>.png`	`decktalk shots --step ID --cue CUE`, one per cue
`section-NN-at-<S>s.png`	`decktalk shots --section N --at S`, one per time

Note: --page with one page file writes no page folder. --section frames never go in a page folder.

How files are written

DeckTalk writes files so that a reader never sees half of one.

Stages run one after another, and one build runs one Chromium.
manifest.json, timeline.json, beats.json, each words file, and each sidecar go to a temporary file first. A rename then puts each one in place.
The final mp4 is written to a work file, then renamed to build/out/<name>.mp4. The timestamped copy comes after the rename.
narrate saves the manifest after each paid request, so an interrupted voiced run keeps the sections it paid for.
An error is a DeckTalkError subclass that names the file or field. The command line prints it as error: … and exits 1.

See how the stages use these files: How it works
Check the final video: Verify
Read the files from Python: Python API

Get started

Guides

Concepts

Reference

Help

Time bases

`build/audio/NN-slug.words.json`

`build/audio/manifest.json`

`build/audio/timeline.json`

`build/audio/beats.json`

`build/audio/beats.anchors.json`

`build/rec/NN-scene.json`

`build/out/`

`build/shots/`

How files are written

​Time bases

​build/audio/NN-slug.words.json

​build/audio/manifest.json

​build/audio/timeline.json

​build/audio/beats.json

​build/audio/beats.anchors.json

​build/rec/NN-scene.json

​build/out/

​build/shots/

​How files are written

​Related

Time bases

`build/audio/NN-slug.words.json`

`build/audio/manifest.json`

`build/audio/timeline.json`

`build/audio/beats.json`

`build/audio/beats.anchors.json`

`build/rec/NN-scene.json`

`build/out/`

`build/shots/`

How files are written

Related