Skip to main content
A clip section plays a video file of your own, with its own audio, as one section of the video. Use this guide to fill the scaffold’s clip sections, to open on camera, to add B-roll between page sections, or to close on a clip.

​
Before you start

The steps use the scaffold that decktalk init writes. The scaffold has two clip sections, 5 and 7. They are the BEFORE and AFTER clips of the edit, and the scaffold ships no file for either. Both set optional = true, so each plays a titled slate until its file is in place. The scaffold’s decktalk.toml also has a section 0 in comments, which opens the video on a clip.

​
Put a clip in a clip section

These steps put a test clip in section 5 of a new scaffold named clip-lesson.
1

Create a scaffold

2

Go into the project

3

Find the clip section in decktalk.toml

decktalk.toml
  • clip names your video file, relative to the project.
  • words names a words file for the captions. Caption the speech in a clip explains it.
  • slate_seconds sets how long the slate plays while the file is missing.
  • optional = true lets --strict play the slate. Build with —strict explains it.
4

Build the video

Run a silent build.
Each section gets a [cut ] line. Neither clip file exists yet, so sections 5 and 7 play titled slates.
5

Put the clip file in place

Save your video as media/edit-before.mov. If you have no video, make a 4 s test clip. This command needs ffmpeg on your PATH.
  • A clip that is not 1920 by 1080 is scaled to fit and padded with black.
  • A clip with no audio track plays silent, and assemble prints a warning.
6

Cut the clip into the video

A new clip file changes no narration and no recording, so run only assemble.
Check that section 5 reads edit-before.mov (own audio). The test clip has no words file, so its sound has no captions. Then run decktalk verify to check the video.

​
Build with —strict

--strict on build or assemble turns a missing clip into an error. A clip section with optional = true still plays its slate. Before the test clip was in place, decktalk assemble --strict exited 0 and printed this warning for each clip section.
A clip section without optional = true fails under --strict when its file is missing. The command exits 1.
After your clip is in place, delete the optional line. --strict then catches the file if it goes missing later.

​
Add a clip section of your own

A section’s number sets its place in the video. To add a clip between two page sections, give it the next number and renumber every section after it.
  1. In decktalk.toml, add 1 to the number of every section after the new clip, from the last one up.
  2. Add the clip section’s table in its place.
    decktalk.toml
  3. In script.md, renumber the same headings, and add a heading for the clip.
    script.md
    The voice speaks nothing in a clip section, so the body can be a stage direction.
  4. In cues.json, rename each later section key, from the last one up. The cue ids stay the same. They start with a scene number, and the scenes of the page do not change.
  5. Run decktalk build.
A renumbered section keeps its narration. narrate finds the take by its hash and copies it to the new file name.

​
How the narration splits

build/audio/narration.mp3 holds the spoken sections back to back, with no gap for a clip. assemble splits the narration at each clip between page sections.
Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before section 6 and another before section 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the starts of sections 1, 2, 3, 4, and 9, because sections 4 to 8 share one title.Lanes on one time axis. The narration.mp3 lane holds sections 1, 2, 3, 4, 6, 8, and 9 back to back, with a split before section 6 and another before section 8. The video lane plays the 4 s clip of section 5 after section 4 and the 5.04 s slate of section 7 after section 6, and dashed leads move sections 6, 8, and 9 later. Captions sit under page sections only. Chapters mark the starts of sections 1, 2, 3, 4, and 9, because sections 4 to 8 share one title.

The narration pauses for each clip, and resumes with the next page section.

  • Each part of the narration starts where its first page section starts in the video.
  • A slate splits the narration the same way a clip does.
  • No caption covers a clip section, unless the section sets words. Caption the speech in a clip explains it.
  • A clip section gets its own chapter, unless the section before it has the same title.
Example: in clip-lesson with the test clip, section 6 starts at 196.70 s in timeline.json and at 200.72 s in the final mp4. The 4 s clip of section 5 sits between them, with 0.02 s of frame rounding. Build artifacts explains the two time bases.
The narration does not depend on the length of a clip. After you replace a clip file, run only decktalk assemble, then decktalk verify.

​
The clip’s sound

The clip’s own audio joins the mix at its section start.
  • The audio is trimmed to the clip’s picture.
  • The audio fades in and out over 20 ms, so a cut never clicks.
  • The narration is silent while the clip plays.
  • The underscore ducks under the whole clip. Sound explains ducking.
verify checks the start of a clip section, but a clip section has no cut row. The click search of the a/v check never reaches into a clip’s audio.

​
Caption the speech in a clip

The captions come from the narration’s word times, so a clip’s own speech has no captions by default. Set words on the clip section to caption it.
  1. Write a words file for the clip. It is a JSON list with one object per word, in seconds after the clip starts.
    media/interview.words.json
    Give each word its own punctuation and case. The captions break at the sentence ends it marks.
  2. Name the file in the clip section.
    decktalk.toml
  3. Run decktalk assemble.
  • A word that starts after the clip’s picture ends has no caption.
  • A slate or a clip with no audio track has no captions.
  • If the words file is missing, assemble prints a warning and the clip has no captions.
A NN-slug.words.json file from build/audio has this format. decktalk clip writes the words file of a clip that it cuts from a build. Cut a clip from a build shows how.

​
Cut a clip from a build

decktalk clip cuts a span of a built page section into a clip and its words file. Use it to play part of the video again in a clip section, such as the Open’s count inside a later scene. These steps use a scaffold after decktalk build --silent. After a voiced build, the clip carries the real voice.
1

Find the span

Print the words of section 1 with their times, in seconds after the section starts.
The count runs from the start of “Watch” at 2.879 s to the end of “three.” at 8.308 s.
2

Cut the clip

  • The picture comes from build/out/01-section.mp4. --from and --to round to whole frames.
  • The sound is section 1’s mp3 over the same span. --hold 0.5 adds 0.48 s of the last frame in silence.
  • media/count.words.json lists the 10 words from “Watch” to “three.”, in seconds after the clip starts.
  • A span that cuts a word in two leaves that word out of the words file, and clip prints a warning.
3

Play the clip in a clip section

Add a clip section that names both files, and renumber the sections after it as Add a clip section of your own describes.
decktalk.toml
Then run decktalk assemble, and check that the section reads count.mp4 (own audio).
  • --gain changes the clip’s level in dB, so a clip cut from another build can match the voice around it.
  • The clip keeps the section’s full picture. Fill the edit’s two clips places a clip inside a player by hand.
  • decktalk clip lists every option.

​
Keep one chapter across several sections

Each section starts a chapter. Consecutive sections with the same title share one chapter instead. The scaffold’s sections 4 to 8 all have title = "The edit", so the video shows one chapter that spans the three pages and both clips.

​
Fill the edit’s two clips

The scaffold’s edit steps out of the lesson and plays the Open twice inside a video player. Section 5 plays the Open as first built. Section 7 plays it again with a fourth count. The scaffold ships no clip files, because a clip carries a real voice. Each clip is the last frame of the page before it, with the Open playing in the player’s video area. That area is 1152 by 648 at 384, 72. The pages around the clips show stills in deck/edit/. The scaffold’s stills come from the demo video and match a fresh scaffold. Cut new ones after you change the Open or the end of the lesson. These steps need ffmpeg and python3 on your PATH. Run them in the project after a voiced build. The commands use bash variables.
1

Build the AFTER copy

Copy the project. In the copy, add the fourth count as the quickstart does, then build its first two sections.
2

Find each clip's times, and write its words file

Save this script as clip_words.py. It picks the span from “Watch” to the last count word, prints its start and end in seconds, and writes the words inside it, shifted to the clip’s start.
clip_words.py
3

Cut the stills

Each still is a lossless WebP. -update 1 keeps the last frame of the span.
4

Record the edit's pages again

The pages now show the new stills, and each clip needs the last frame of its page.
5

Cut the clips

The first two commands take the last frame of sections 4 and 6. Each clip holds its last frame for 0.5 s, and the page’s strip at y 706 goes back on top, so the progress line stays in place.
6

Play the clips

Delete optional = true from sections 5 and 7 in decktalk.toml. Set slate_seconds to each clip’s length, so a missing file keeps the timing. Then cut and check the video.
Check that sections 5 and 7 read (own audio).
The numbers the pages show are constants near the top of the edit’s code in deck/index.html. They are the count times in ED_BEFORE_TIMES and ED_AFTER_TIMES, the build log in ED_LOG, and the verify totals in ED_VERIFY. They hold the demo video’s values. Set them from your builds, then record the edit’s pages again.

​
Choose where the clip plays

A clip section can sit anywhere in the order of sections.
  • cues.json names the cues of a section by its section number, such as "8" for the edit’s last page.
  • A section’s scene names the scene in the page. Section 8 of the scaffold plays scene 7, so its cue ids start with 7.1.
  • If you add or remove a clip section, renumber the sections in decktalk.toml, script.md, and cues.json. The pages stay the same.
  • hold_seconds on a page section pauses the narration too, the same way a clip does.

​
Open the video on a clip

These steps turn on section 0 of a scaffold, such as my-lesson from the quickstart. Section 0 needs no renumbering.
1

Uncomment section 0 in decktalk.toml

Remove the leading # from the five lines of section 0.
decktalk.toml
2

Dip the cut out of the clip to black

In the existing [transition] table, change dips = [] to dips = [[0, 1]].
decktalk.toml
dips lists each cut that dips to black, as a [from, to] pair of section numbers. The scaffold sets dips = [], so every cut is straight. If you delete the key, every cut dips.
3

Add a heading to script.md

Add ## 0. On camera above section 1. A clip section needs no heading, but the heading keeps the script in the order of the video.
script.md
4

Put the clip file in place

Save your video as media/open.mp4.If the file is not ready, skip this step. A missing clip plays a titled slate for slate_seconds, with the section title and the path where the file belongs.
5

Build the video

Run a silent build.
Section 0 has no optional key, so its warning ends with (drop your clip at that path). --strict fails on this section until the file exists.

​
Next