Verify

decktalk verify is the last stage and the only one that makes no artifact. It opens the finished mp4 and measures it against the clock the earlier stages promised it would keep. It changes nothing a later run reads: the only files it touches are its own events file and the build lock it holds while it measures. This is the page to read when a number it printed is not the number you expected. Five things are measured. Every section must open on a real picture past its dip to black. The narration must be quiet in the window before each cut, so no cut lands on a word. A section that declares itself seamless must open on the picture the section before it ended on. Every cue must change the picture, by enough to be seen, within the offset limit of the word it was promised to, with every declared motion around it masked out. And every declared motion must depart and arrive on its own lane within that same limit of its words. Beside those five it repeats what every recording log already judged, rather than measuring it again, so a page that threw or an equation that was never typeset is still a finding after the build that recorded it, and after a build somebody else recorded.

Running it

decktalk verify
decktalk verify --section 2
decktalk verify --json

--section N narrows every measurement to those sections, taking 3, 3,5 or 7-9 and repeating. --fail-on and --allow decide what fails the run, as Which findings fail a run says. decktalk verify --help prints every flag. The stage inside decktalk build is the same call, so a build measures everything a bare verify would. Three refusals come before any measurement. A film that is not there is NOT_BUILT, and so is a film that carries no placements file and has no section files to read a shape from. Both say to run decktalk assemble first. A film whose recorded page sections have no recording log under build/recordings/ is NOT_BUILT too, because without the logs verify would repeat none of the recorder’s findings and measure none of the motion, so a film moved to another machine takes build/recordings/ with it. A section the film filled with black was never recorded and needs none.

What it prints

Verifying build/final/my-lesson.mp4, 0:50 long.

 Section   Cue           Spoken   Shown   Offset   Masked
 ────────────────────────────────────────────────────────
       1.1:title     0.50     0.52    +0.02
       1.1:files     1.93     1.96    +0.04
       1.2:script    8.56     8.60    +0.04
       1.2:deck      11.87    11.88   +0.01
       1.2:word      17.08    17.12   +0.04
       2.1:average   21.23    21.28   +0.05
       2.1:formula   25.46    25.48   +0.02
       2.1:code      29.22    29.24   +0.02
       2.1:waited    31.10    31.12   +0.02
       3.1:idea      37.09    37.12   +0.03
       3.1:again     43.47    43.52   +0.05
       3.1:make      44.39    44.40   +0.01

The table holds one row per cue that was measured all the way to an onset. A cue that was skipped has no row, and neither has one that changed nothing or whose reveal never stepped. Each of those raises a finding of its own, except a cue that cues.json opted out of, which is silent by design. The starts, the cuts and the seams print no table at all: their numbers are in decktalk verify --json, and what is wrong about any of them is a finding.

Column	JSON field	Meaning
`Section`	`section`	The section number, which is the number in `decktalk.toml` and not the scene number.
`Cue`	`cue`	The cue id, which is the slide id, a colon and the cue name the page wrote.
`Spoken`	`spoken`	When the cue’s word is spoken in the film, in seconds. After a build on placeholders this is where the click for that word actually sounds. After a voiced build it is the cue’s own second in the film.
`Shown`	`shown`	When the picture changed, in seconds, which is the onset.
`Offset`	`offset_seconds`	`Shown` less `Spoken`, in seconds. A negative value means the picture moved early.
`Masked`	`masked_percent`	How much of the frame declared motion masked out of this cue, or empty when nothing did. Motions says what is masked.

A deck that declares motions prints a second table under the first, with one row per landing that was measured. Motions gives its columns. change_percent is in the JSON and not in the table: it is how much of the picture the reported probe found changed.

The frame of reference

Every second on this page is a second in the finished film. verify reads the film’s own placements, build/final/placements.json, for where each section starts and how long the whole film runs, because that file is the film’s own record of its shape. With no placements file it adds up the section files instead and says on its stream that it did. Shares are measured on a quarter-size copy of the frame, which is verify.probe_width by verify.probe_height, both derived from the frame size. A share is the percentage of pixels whose luma differs by more than a level, so the comparison reads brightness and never colour: a reveal that changes only colour at the same brightness reads as no change, and the way to keep such a cue is "verify": false in cues.json.

Section starts

For each section that the film plays, verify reads the frame verify.after_dip_seconds past the section’s start and takes its brightest luma. A frame whose brightest pixel is at or under verify.black_max_luma is black, and the section opens on nothing. The probe sits a fixed distance past the start whatever the dip is, so a dip longer than the default needs after_dip_seconds raised past it. A clip section gets a row like any other.

Cuts

For each section that has a take, verify measures the level of the narration track alone over the window before the section’s narration ends. The window is verify.cut_window_seconds or the take’s own span, whichever is shorter, and the level is an RMS. Above verify.cut_max_dbfs the cut is falling on a word. The narration track is read alone on purpose, so music or a sound effect at a boundary is never taken for speech. A clip section carries its own audio and has no row. Each row also carries a step, which is how far the level of the finished film jumps across the cut, measured over a twentieth of a second on each side. It is reported for a reader and no limit is held against it.

Seams

A section that sets seamless = true in decktalk.toml claims it opens on the picture the section before it ended on. verify compares the outgoing section’s last whole frame with the incoming section’s first, both taken outside any dip so that a fade through black is never read as a jump. Over verify.cut_change_max_percent of the frame changing is a visible seam, and verify raises CUT_POP against it. A seam is only ever a seamless cut, so a section that does not set seamless has no row here and its cut is never judged for the picture. The recorder steps the section clock, so a seamless section opens on the very frame the section before it ended on, and the first frame alone decides CUT_POP. A picture that arrives even one frame late is a frame a viewer sees jump. When the two do not match, the next three frames are read as well, so the row can say how late the outgoing picture arrived: drift_seconds is how far past the cut it was found, in seconds, and it is zero when the seam matched straight away.

Cues

A cue check asks one question: did the picture change because of this cue, and did it change when the word was said. It is answered in stages, and each stage has its own way of failing.

Reference frame

The reference frame is the picture before the cue, and every probe is compared against it. It sits the whole reference lead before the cue.

verify.reference_lead_seconds = verify.cue_offset_max_ms / 1000
                              + GUARD_FRAMES / video.fps
                              + verify.reference_lead_extra_ms / 1000

GUARD_FRAMES is 1.5, which is half a frame of rounding guard on each side of the window the offset limit allows, and video.fps is the rate the recorder steps the section clock at, so the guard is always one and a half of the film’s own frames. The lead has to be at least that wide: a reveal that lands at the early edge of the offset limit would otherwise already be showing in the reference frame, and the check would measure the change only once the reveal had settled. verify.reference_lead_extra_ms is the escape hatch for a deck whose reference frame is still inside its own reveal. It defaults to 0 because the lead is already as wide as the limit implies. The reference may not sit inside the section’s fade-in, where the picture is still coming up from black, and it must sit at least one frame before the cue. When no frame satisfies both, the cue is skipped with at_section_start as its reason.

Probes

A probe is the frame a fixed delay after the cue. verify.probe_delays_seconds names the delays, 0.7 and 1.5 seconds by default, and the later one is what catches a slow reveal. A probe that would fall within 0.05 seconds of the section’s end is dropped, and a cue whose probes are all dropped is skipped with too_close_to_end as its reason. Each probe gets a control share, which measures motion that has nothing to do with the cue. The control is the quieter of two back-to-back spans of the probe’s own length that end at the reference frame. Steady motion, such as a camera push, shows in both spans. An earlier reveal that is still settling shows in only one, so taking the smaller of the two leaves it out. A span that would start before the section’s floor is dropped, and with both dropped the control is zero.

The figure shows the arrangement rather than this release’s numbers, which were measured on an earlier one. Run decktalk verify --json for what your own film measures.

The neighbour allowance

Another cue of the same section can spoil a probe. Its own reveal would count as this cue’s change if it can fall inside the probe’s span, or as motion that was always there if it can fall inside every control span that is measured. The allowance that decides whether a neighbour reaches into a span is deliberately not symmetric.

Backward it is the reference lead, which is verify.cue_offset_max_ms / 1000 plus the guard frames over the capture rate plus verify.reference_lead_extra_ms / 1000. A reveal may legally land that early and still pass, so the check has to assume a neighbour might.
Forward it is the neighbouring effect’s own declared span, taken from the attribute registry through the catalog the page published and scaled by motion.scale. An effect stops moving when its own animation ends, and not a fixed distance later.

One symmetric constant cannot serve both directions. It is too short for a draw, which keeps moving for most of half a second, and too long for a cut, which is over the instant it fires. Reading the span the effect itself declares is what makes a tight passage of cues measurable at all. A neighbour closer to this cue than the backward allowance is not a neighbour. It cannot be told apart from the cue being measured, so it is part of the same reveal. When a probe is spoiled, it is fitted to the longest shorter delay that nothing spoils, down to one frame past the offset limit, so a reveal at the late edge of that limit still shows. Two probes fitted to the same delay count once. verify says on its stream which cue was fitted and to what, as a detail line that -v prints, because a fitted probe is how a close pair is measured and not a problem.

Cue 1.1:title in section 1 sits close to another cue, so verify compared the picture 0.7 s and 1.281 s after its word instead of at the usual delays. This is how a close pair is measured, not a problem.
Cue 1.1:files in section 1 sits close to another cue, so verify compared the picture 0.7 s and 1.14 s after its word instead of at the usual delays. This is how a close pair is measured, not a problem.
Cue 3.1:again in section 3 sits close to another cue, so verify compared the picture 0.7 s and 0.772 s after its word instead of at the usual delays. This is how a close pair is measured, not a problem.
Cue 3.1:make in section 3 sits close to another cue, so verify compared the picture 0.62 s and 1.5 s after its word instead of at the usual delays. This is how a close pair is measured, not a problem.

Change test

margin         = changed share - control share
reported probe = the probe with the largest margin, the earlier one on a tie
passes when    changed share >= verify.changed_share_min_percent
               and margin    >= verify.margin_min_points
thin when      changed share <  verify.thin_change_factor * verify.changed_share_min_percent
               or  margin    <  verify.thin_change_factor * verify.margin_min_points

Both shares are measured at verify.probe_diff_luma. A cue that fails the test raises CUE_NO_CHANGE and nothing further is measured for it. A cue that passes by less than the factor raises CUE_THIN_CHANGE, which is a warning: the cue did pass, and a slightly smaller reveal or a little more motion around it would not have been measured at all. Setting verify.thin_change_factor to 1 turns that second opinion off. The change_percent in the JSON is the reported probe’s share, which is not always the largest share measured, because the reported probe is chosen on margin.

`PAGE_THIN_DRAW`

decktalk check runs the same arithmetic over two frozen frames rather than over the film, and it has one code of its own for the case a stroke makes. PAGE_THIN_DRAW is a warning, and it says that an entrance drawn as a stroke sweeps less of the frame than a change has to cross to be seen. A stroke that thin is a stroke nobody will see rather than a reveal that never happened, which is why it is not CUE_NO_CHANGE. It is measured in Python from the frozen frames and never raised by the page itself, because the floor it is read against is verify.changed_share_min_percent, a settings key no browser can read. video.crf moves it too, since the encoder’s own ringing competes with a thin stroke.

The onset

Once a cue has passed the change test, verify finds the frame the reveal began on.

It measures the changed share of every frame from the reference frame up to the reported probe, each compared with the reference frame at verify.onset_diff_luma.
It measures the same series again with both frames scaled to verify.block_width by verify.block_height, which is one pixel per H.264 transform block.
The onset is the first frame after the reference whose share rises by at least verify.onset_rise_points over the frame before it, and whose block share is above zero.
When no frame rises that much, the onset is the first frame after the reference whose share passes a floor, and whose block share is above zero. That floor is the larger of verify.onset_rise_points and the largest share measured up to the point that sits the offset limit plus half a frame before the cue, so a picture that was already moving before the cue cannot pass for the reveal.
When no frame does either, the cue raises CUE_NO_ONSET and has no row in the table.

A reveal is a step: between two consecutive frames the changed share jumps. Motion that was always there, such as a curve still drawing, is a slope that grows a little every frame and never jumps, which is why the first test looks for a rise rather than for a level. The fallback catches a reveal that grows slowly, such as a number counting up. The block series is what keeps the encoder out of the answer. The x264 encoder leaves a little ringing on a still picture in the frame or two before a change. Ringing is as much lighter as darker, so it cancels over a block and leaves the block share at zero, while a real reveal changes whole blocks and its first frame has a block share above zero. The onset may sit before the cue.

A row of frames one frame apart, starting at the reference frame before the cue. Each frame is labelled with the share of the picture that changed against the reference. The first frames read zero, and the frame just after the cue steps up to a larger share and is outlined as the onset. A shaded band marks the offset limit on each side of the cue. — Consecutive frames from the reference frame onward, each with its share against the reference, and the first frame that steps up is the onset.

The figure shows the shape of the scan rather than this release’s numbers. Its shares are measured at verify.onset_diff_luma, which is a much lower luma difference than the change test’s verify.probe_diff_luma, so the same cue reads a different share here than in change_percent.

The word the onset is measured against

After a build on placeholders, the narration is click audio with a click at every word start and one where the last word ends, so the film’s own audio can be measured against its own picture. verify searches verify.click_search_seconds on each side of the cue’s second, inside that cue’s section alone, and takes the loudest sample. A sample under verify.click_floor_dbfs is not a click, and DeckTalk generates its own click at -24 dBFS, so a floor at or above that finds nothing at all.

When a click is found, it becomes the row’s Spoken, and Offset is the onset less the click. That measures the picture against the film’s own audio, so it covers the recording, the trim at the start of the section clock, the cut, the join and the mix in one number.
When no click is found, and after a voiced build, Spoken is the cue’s own second in the film and Offset is the onset less that.

Limits

CUE_OFF when |Offset| > verify.cue_offset_max_ms / 1000 + half a frame
CUE_OFF when the click sits further than verify.av_offset_max_ms from the second the cue was promised

The half frame is there so a limit written in frames is not failed by its own rounding. The sound has its own wider limit because an mp3 frame smears a transient across about 26 milliseconds and the encode adds its own, which is why verify.av_offset_max_ms may not be set under 80. Both limits raise CUE_OFF, and each message says which of the two it is. A whole run that lands a frame or two late is usually a slow machine rather than a bad deck. Build in CI and offline shows how to widen a limit on one runner.

Motions

A page declares everything that moves for longer than a moment, as a motion, a loop or the region a frame hook draws in, and a render section’s program may write the same declarations as its landings. The recorder keeps one lane for each in the recording log, with the box it swept and the seconds it moved, and verify reads the lanes from there. The lane report gives their fields.

The mask

Every cue is measured with every lane alive anywhere from the start of its control spans to its last probe masked out. The mask is the union of those lanes’ boxes, scaled to the probe size, and it is taken out of the changed share, the control share and the onset scan alike, so a ring turning in a corner never reads as a reveal starting early. masked_percent is the share of the frame the mask covered. Over verify.motion_mask_max_percent, which is 40 by default, verify raises MOTION_MASK_LARGE. It is a warning, because the cue was still measured, on the part of the picture that was left.

Landings

A cue that is only a motion’s departure or arrival, where the page reveals nothing else, has no step in the frame to read. It is skipped in the cue rows as motion_landing and measured on the motion’s own lane instead. A cue where the page also reveals something is measured both ways: as a reveal with the motion masked, and as a landing on the lane. Inside the lane, frame by frame, the motion counts as moving while more than verify.motion_floor_percent of the moving element’s own area changes from one frame to the next, which is 0.5 percent by default. The comparison is made at verify.onset_diff_luma.

departure = the first moving frame at or after the cue less verify.reference_lead_seconds
arrival   = the last moving frame up to the later of the cue and the lane's last second,
            plus the offset limit and two frames

The landing table holds one row per landing, in film order.

Column	JSON field	Meaning
`Section`	`section`	The section number.
`Motion`	`cue`	The cue id the motion lands on.
`Landing`	`kind`	`depart` or `arrive`.
`Spoken`	`spoken`	When the cue’s word is spoken in the film, in seconds.
`Shown`	`shown`	The first moving frame for a departure or the last for an arrival, or null when the lane never moved.
`Offset`	`offset_seconds`	`Shown` less `Spoken`, in seconds.

MOTION_NO_EDGE when an arrival shows earlier than its word by more than the offset limit, or never moved
MOTION_OFF     when a departure never moved, or any other landing is outside the offset limit

The limit is verify.cue_offset_max_ms plus half a frame, as it is for a cue. An arrival that came to rest early is MOTION_NO_EDGE rather than MOTION_OFF, because the fix is the ease rather than the cue: a motion that eases to rest has no edge on its word, and firm gives it one. A landing on a cue that cues.json marks "verify": false has no row and no finding, which is how a settle or spring arrival is written.

A render section

A render section’s lanes are the landings its program wrote. When it wrote none, nothing says what moves in its picture, so every cue of that section is skipped as rendered and verify says once on its stream that it measured none of them. Such a cue is never passed.

Every finding `verify` can raise

Code	Severity	What it means	Keys that move it
`RECORD_BLACK`	error	A section opens on a frame with nothing visible in it.	`verify.after_dip_seconds`, `verify.black_max_luma`
`CUT_SPEECH`	error	Speech is still sounding at a section cut, so the film slices a word in two.	`verify.cut_window_seconds`, `verify.cut_max_dbfs`, `narration.tail_seconds`, `narration.sound_end_noise_dbfs`, `narration.sound_end_min_run_seconds`
`CUT_POP`	error	A seamless section’s cut shows, because too much of the picture changes across it.	`verify.cut_change_max_percent`
`CUE_NO_CHANGE`	error	Nothing measurable happened at the cue’s second.	`verify.changed_share_min_percent`, `verify.margin_min_points`, `verify.probe_delays_seconds`, `verify.probe_diff_luma`, `video.crf`
`CUE_THIN_CHANGE`	warning	The cue passed the change test by less than the thin factor.	`verify.thin_change_factor`, `verify.changed_share_min_percent`, `verify.margin_min_points`, `verify.probe_diff_luma`, `video.crf`
`CUE_NO_ONSET`	warning	The reveal changed the picture and no frame of it steps, so there is no second to compare with the word.	`verify.onset_rise_points`, `verify.onset_diff_luma`
`CUE_OFF`	error	The change lands further from its word than the offset limit allows, or the click does.	`verify.cue_offset_max_ms`, `verify.av_offset_max_ms`, `verify.onset_rise_points`, `verify.onset_diff_luma`, `verify.click_search_seconds`, `verify.click_floor_dbfs`, `verify.reference_lead_extra_ms`
`CUE_UNRESOLVED`	error	`cues.json` lists a cue that no run could give a second to, so the film never plays it.	none
`MOTION_OFF`	error	A declared motion departed or arrived outside the offset limit of its word, or a departure never moved.	`verify.cue_offset_max_ms`, `verify.motion_floor_percent`
`MOTION_NO_EDGE`	error	A declared motion came to rest before its word, so no frame shows it land on the word.	`verify.cue_offset_max_ms`, `verify.motion_floor_percent`
`MOTION_MASK_LARGE`	warning	Declared motion covered more of the frame around a cue than the mask allows before it says so.	`verify.motion_mask_max_percent`
`CUE_STALE`	error	The cue times on disk were placed from a different `cues.json` than the project’s, so the film was cut to moments nobody asks for now. Run `decktalk build`.	none

verify also raises again every finding the recording logs hold, such as RECORD_TRUNCATED, PAGE_KATEX_ERROR and every warning the runtime reported while it recorded. Those are read from the log rather than measured, which is why recording that section again is the only thing that clears one. Each finding has a page of its own under /reference/findings/, and Configuration is the same index in reverse. decktalk schema prints every code with the keys that decide it as JSON, in its decides list.

Skipped cues

A skipped cue has no shown, no offset_seconds and no change_percent, and its skipped field says why it has none. Two of the eight reasons carry a finding, and the table says which.

`skipped`	Cause	What to do
`opted_out`	`cues.json` marks the cue `"verify": false`.	Nothing, if the reveal is one a frame difference cannot see. Freeze it with `decktalk storyboard --after CUE` and look at it.
`no_cues`	`build/cue-times.json` has no second for this cue. A cue that `cues.json` lists and nothing resolved also raises `CUE_UNRESOLVED`.	Run `decktalk cue`, or fix the phrase that never matched.
`not_assembled`	The film has no cut for this cue’s section.	Run `decktalk assemble`.
`at_section_start`	No frame fits between the section’s floor and one frame before the cue, which is what a cue at or very near the section’s own start looks like.	Give the cue a later phrase, or an offset that moves it clear of the start.
`too_close_to_end`	Every probe would fall later than 0.05 seconds before the section ends.	Move the cue earlier, or give the section a longer hold.
`no_onset`	The picture changed and no frame of the change steps or passes the floor. This row carries `CUE_NO_ONSET`.	Make the reveal arrive in one jump rather than growing, or look at it with `decktalk storyboard`.
`motion_landing`	The cue is only a motion’s departure or arrival, and the page reveals nothing else at it.	Nothing. The landing is measured on its own lane, in `motions`.
`rendered`	The section’s picture was drawn by a `render_command` that wrote no landings.	Have the program write `{landings}`, as A render section shows.

The JSON

decktalk verify --json prints one flat object with the four reserved keys, run, and eight fields of its own.

{
  "schema": 1,
  "ok": true,
  "findings": [],
  "error": null,
  "run": "e7a28596d3d0",
  "film": "build/final/my-lesson.mp4",
  "film_seconds": 50.4,
  "starts": [
    { "section": 1, "at_seconds": 0.2, "luma": 240.0 }
  ],
  "cuts": [
    { "section": 1, "at_seconds": 19.787, "speech_dbfs": -120.0, "step_dbfs": 0.0 }
  ],
  "seams": [],
  "cues": [
    {
      "section": 1,
      "cue": "1.1:title",
      "spoken": 0.504,
      "shown": 0.52,
      "offset_seconds": 0.016,
      "change_percent": 1.88,
      "skipped": null,
      "masked_percent": null
    }
  ],
  "motions": [],
  "elapsed_seconds": 1.816
}

Field	Type	Meaning
`film`	string	The film this call measured, relative to the project.
`film_seconds`	number	How long that film runs.
`starts[]`	array	One object per section the film plays, with `section`, `at_seconds` for where the frame was read and `luma` for its brightest pixel.
`cuts[]`	array	One object per section with a take, with `section`, `at_seconds` for where its narration ends in the film, `speech_dbfs` for the level in the window before it and `step_dbfs` for the jump across it.
`seams[]`	array	One object per assembled section that sets `seamless`, with `section`, `at_seconds` and `drift_seconds`.
`cues[]`	array	One object per cue, with the columns of the printed table plus `change_percent` and `skipped`.
`motions[]`	array	One object per measured landing, with `section`, `cue`, `kind`, `spoken`, `shown` and `offset_seconds`, in film order.
`elapsed_seconds`	number	How long this call took.

A skipped cue has null in shown, offset_seconds and change_percent. A measured cue has null in skipped. What is wrong is in findings, never in a row, so a reader dispatches on a finding’s code and reads a row for the number behind it. decktalk schema verify prints the whole result model.

Run it and read every flag: CLI
Move a limit: Configuration
Read one code: Findings
Fix a failed check: Troubleshooting

Get started

Use cases

Concepts

Guides

Reference

Agents

Design decisions

Help

Running it

What it prints

The frame of reference

Section starts

Cuts

Seams

Cues

Reference frame

Probes

The neighbour allowance

Change test

`PAGE_THIN_DRAW`

The onset

The word the onset is measured against

Limits

Motions

The mask

Landings

A render section

Every finding `verify` can raise

Skipped cues

The JSON

​Running it

​What it prints

​The frame of reference

​Section starts

​Cuts

​Seams

​Cues

​Reference frame

​Probes

​The neighbour allowance

​Change test

​PAGE_THIN_DRAW

​The onset

​The word the onset is measured against

​Limits

​Motions

​The mask

​Landings

​A render section

​Every finding verify can raise

​Skipped cues

​The JSON

​Related

Running it

What it prints

The frame of reference

Section starts

Cuts

Seams

Cues

Reference frame

Probes

The neighbour allowance

Change test

`PAGE_THIN_DRAW`

The onset

The word the onset is measured against

Limits

Motions

The mask

Landings

A render section

Every finding `verify` can raise

Skipped cues

The JSON

Related