Skip to main content
A clip is one thing in DeckTalk, which is a short video file. The word is used two ways on this page and means the same thing each time.
  • A [[section]] with clip = "media/intro.mp4" plays a video file you supply, with its own audio, as one section of the film. The voice says nothing there, because the clip carries its own sound.
  • decktalk clip writes a video file cut from a section of the finished film, with its own audio and its own words file, so a piece of the film can be played again or handed to somebody else.
One noun names a short video file whoever made it, so a clip you supply, a film DeckTalk built and a clip DeckTalk cuts are the same kind of thing, and a clip section plays any of them the same way.

​
A section that plays your own video

A clip section names its file and nothing else about the picture. It has no page and no scene, cues.json says nothing about it, and script.md needs no heading for it.
decktalk.toml
A clip that is not the project’s frame size is scaled to fit and padded with black, so a portrait phone video plays in a letterbox rather than distorted. A clip with no audio track plays silent, and assemble says so on the stream.

​
While the file is not there

A clip section whose file is missing plays a titled slate for slate_seconds, so a project can carry the section before the video exists and everyone can watch the film with a hole labelled rather than a hole. The slate carries the section number, the line Your clip goes here, and the path to drop the file at. It is kept under build/stills/ by everything it shows, so a renamed chapter or a new colour draws it again. It is drawn on the colour [video] slate_color names, and [mix] slate points at an image of your own to use in its place. Nothing about a slate is silent about itself: decktalk status reports the missing file as an error, FILE_MISSING, naming the section and the path, and a build writes the film with the slate in it and then stops before verify. A section marked optional is the one exception, because it has said the slate is allowed, so its film is measured and the build exits 0.

​
Putting one between two page sections

A section’s number is its place in the film, so adding a clip in the middle renumbers what follows it.
  1. In decktalk.toml, add 1 to the number of every section after the new clip, from the last one upward, then add the clip section’s own table.
  2. In script.md, renumber the same headings. The clip section needs no heading of its own, and a heading there is never voiced, because the voice reads every section that does not play a clip.
  3. In cues.json, rename each later section key, from the last one upward. The cue ids do not move, because they name slides, and the slides of the page are untouched by a renumbering of the film.
  4. Run decktalk build.
A renumbered section is voiced again by nothing. A take is named by the digest of what was sent to the voice, and the section number is not one of those things, so the take is found by its content and the run buys nothing. Rebuild one section is the whole of that rule.

​
How a clip splits the narration

The joined narration holds the spoken sections back to back with no gap, and the film does not. A clip between two page sections pauses the narration, and the next page section resumes it on its own first frame. So the track plays in runs of consecutive page sections, and each run starts where its first section starts in the film.
The narration track holds sections 1, 2, 3, 4, 6, 8 and 9 back to back. The video plays section 5, a clip of 4.00 seconds, after section 4, and section 7, a clip of 5.04 seconds, after section 6. The narration splits before each page section that follows a clip, and sections 6, 8 and 9 start later in the video. Captions sit under page sections only. Each chapter starts with a section, and consecutive sections with the same title share one.The narration track holds sections 1, 2, 3, 4, 6, 8 and 9 back to back. The video plays section 5, a clip of 4.00 seconds, after section 4, and section 7, a clip of 5.04 seconds, after section 6. The narration splits before each page section that follows a clip, and sections 6, 8 and 9 start later in the video. Captions sit under page sections only. Each chapter starts with a section, and consecutive sections with the same title share one.

A nine-section film: the narration pauses for each clip and resumes with the next page section.

One rule places the track, and the captions and the cut check read it too, so all three agree about where a moment of the narration plays.
  • A page section’s hold_seconds splits the narration exactly as a clip does, because the hold is picture with no speech under it.
  • The clip’s own audio joins the mix at its section start, matched to the narration’s loudness, trimmed to its picture and faded over twenty milliseconds at each edge, so a cut into it never clicks.
  • The music ducks under the whole of a clip, because a clip’s dialogue is its own. Sound is the whole mix.
  • A clip section gets its own chapter marker, unless the section before it carries the same chapter, in which case the two share one.
  • The narration does not depend on how long a clip runs. After you replace a clip file, run decktalk assemble and then decktalk verify, and nothing is voiced or recorded.

​
Play a film DeckTalk built

A film DeckTalk built writes its words beside itself, as build/final/<name>.words.json: every word the film says, as its captions show it, with its voice and its turn. Copy the film and that file into the project under one name, such as media/larkbill.mp4 and media/larkbill.words.json, and a clip section that plays the film has its speech captioned on this film’s clock.

​
Caption the speech inside a clip

The captions are built from the narration’s word times, so a clip’s own speech is captioned from the words file beside the clip, <clip>.words.json, and by nothing when there is none. A words file is one object with a words list, and each word carries its span in seconds after the clip starts.
media/intro.words.json
Give each word its own punctuation and case, because the captions break where the sentences end. Save it beside the clip under the clip’s name, as media/intro.words.json beside media/intro.mp4, and run decktalk assemble. decktalk clip writes this file beside every clip it cuts, and every build beside its film.
  • A word that starts after the clip’s picture ends is left out.
  • A slate has no captions, and neither has a clip with no audio track.
  • A clip with no words file beside it plays with no captions.
  • The transcript page carries the same words as one paragraph, so a reader is not left with a silent gap where the clip is.
A take’s own <digest>.words.json in takes/ has this shape, and so does the file decktalk clip writes beside every clip it cuts. A word may also carry voice and turn, which decktalk clip and a build’s <name>.words.json write: a caption of it carries them as data-voice and data-turn in the captioned copy, so a page sets it by its voice, and no caption file names them.

​
Cut a clip out of the film

decktalk clip cuts a span of one built page or render section into its own file. The picture is a run of whole frames of build/sections/NN.mp4 and the sound is the finished film’s over the same span, so a clip is a piece of the film rather than a second render of it: it carries the voice, the effects and the score, as the film mixed them. The clock is the section’s own. Zero is where the section starts, and the lead of silence before its first word is part of the span like anything else.
1

Find the span

decktalk words is the one command that maps script text to seconds, and it is the clock --start and --end are written against.
Each row is one word with its start and its end, in seconds after the section starts.
2

Cut it

A clip without --end is refused as a USAGE error, which exits 2, before anything is read.The span is rounded outward to whole frames, because a clip that began part way through a frame would play its first frame twice. At the default twenty-five frames a second, that is a fortieth of a second either way.Two files are written: the clip, and <name>.words.json beside it, holding every word wholly inside the span in seconds after the clip starts. A word the span cuts in two is left out and said aloud on the stream, so move --end into the silence beside the word to keep it.
A span that cuts a word adds one line before those, such as The span from 0.48s to 1.68s cuts the word 'DeckTalk.' in two, so the words file leaves it out.
3

Play it in a clip section

A clip section names the clip, and its captions come from the words file the command wrote beside it.
decktalk.toml
Then run decktalk assemble and decktalk verify.
The JSON is one flat object, so a caller reads what was written without parsing a line.
seconds is the whole clip, the span and the hold together, and hold_seconds is the hold as whole frames. estimated is true when the section carries placeholder narration, which is the one fact that decides whether the word times in the file beside the clip can be trusted.

​
What it refuses, and why

clip reads two things the pipeline wrote, so it refuses rather than guessing when either is not there. Each refusal names the command that makes what is missing.