> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Add a clip section
> Play a video clip with its own audio as an opening, between page sections, or as a close.
A clip section plays a video file of your own, with its own audio, as one section of the video. Use this guide
to open on camera, to add B-roll between page sections, or to close on a clip.
## Before you start
The steps use the starter that `decktalk init` writes. The starter is three page sections and no clip, so the
steps below add section 4 as a clip of its own, after the Close.
A clip section names its file with `clip`. `optional = true` plays a titled slate until the file is in place, so
a project can carry a clip section before its clip exists.
## Put a clip in a clip section
These steps add a test clip as section 4 of a new project named `clip-lesson`.
```console theme={null}
decktalk init clip-lesson
```
```console theme={null}
cd clip-lesson
```
Paste this table after the section 3 table. A clip section has no `page` and no `scene`, and
`script.md` and `cues.json` say nothing about it, because the clip carries its own sound.
```toml decktalk.toml theme={null}
[[section]]
number = 4
chapter = "On camera"
clip = "media/intro.mov" # your video, with its own audio
words = "media/intro.words.json" # the words spoken inside it, for the captions
slate_seconds = 4 # a titled slate plays for this long while the file is missing
optional = true # plays the slate under --strict until the clip is in place
```
* `clip` names your video file, relative to the project.
* `words` names a words file for the captions. [Caption the speech in a clip](#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](#build-with-strict) explains it.
Run a build without voice.
```console theme={null}
decktalk build --no-voice
```
```text theme={null}
[cut ] 01 01.webm (t0 1.4s trimmed) -> 01.mp4 (14.280s)
[cut ] 02 02.webm (t0 1.44s trimmed) -> 02.mp4 (15.880s)
[cut ] 03 03.webm (t0 1.44s trimmed) -> 03.mp4 (14.720s)
section 04: media/intro.mov is missing, so a slate plays for 4s. Drop your clip at that path. The section is optional, so --strict allows the slate
[cut ] 04 slate -> 04.mp4 (4.000s)
[cat ] 4 sections, straight cuts
```
Each section gets a `[cut ]` line. The clip file does not exist yet, so section 4 plays a titled slate for its `slate_seconds`.
Save your video as `media/intro.mov`. If you have no video, make a 4 s test clip. This command needs
`ffmpeg` on your PATH.
```console theme={null}
ffmpeg -f lavfi -i testsrc2=size=1920x1080:rate=25 -f lavfi -i sine=frequency=440 -t 4 -pix_fmt yuv420p media/intro.mov
```
* 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.
A new clip file changes no narration and no recording, so run only `assemble`.
```console theme={null}
decktalk assemble
```
```text theme={null}
[cut ] 03 03.webm (t0 1.44s trimmed) -> 03.mp4 (14.720s)
[cut ] 04 intro.mov (own audio) -> 04.mp4 (4.000s)
[cat ] 4 sections, straight cuts
[mix ] 3 audio input(s) -> clip-lesson.mp4
section 04: the words file media/intro.words.json is missing, so the clip plays without captions
```
Check that section 4 reads `intro.mov (own audio)`. The mix gains a third input, which is the clip's own
sound. The test clip has no words file, so that 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 the clip
section.
```text theme={null}
section 04: media/intro.mov is missing, so a slate plays for 4s. Drop your clip at that path. The section is optional, so --strict allows the slate
```
A clip section without `optional = true` stops `--strict` when its file is missing. That is an error rather than a
finding, so the command exits 3 and writes no video.
```text theme={null}
error[MISSING_INPUT]: section 4: clip missing: ~/clip-lesson/media/intro.mov. Put your clip at that path, or set optional = true on the section to play its slate under --strict.
```
`decktalk status` reports the same thing without building. The missing clip is a `MISSING` row, and `status`
exits 1.
```text theme={null}
sections 4, cut 4, final True | 1 certain, 0 uncertain finding(s)
MISSING media/intro.mov: section 04 names a clip that is not there
```
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.
```toml decktalk.toml theme={null}
[[section]]
number = 4
chapter = "Interview"
clip = "media/interview.mp4"
slate_seconds = 4
optional = true # plays the slate under --strict until the clip is in place
```
3. In `script.md`, renumber the same headings, and add a heading for the clip.
```md script.md theme={null}
## 4. Interview
[The clip at media/interview.mp4 plays here, with its own sound.]
```
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/narration/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.
* 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](#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: with a 4 s clip in section 5, section 6 starts about 4 s later in the final mp4 than it does on the
narration clock, plus the frame rounding of every cut before it. `decktalk status` prints the narration times
and `build/out/cuts.json` the final ones. [Build artifacts](/reference/artifacts#time-bases) explains the two
time bases.
```text theme={null}
01 deck/index.html?scene=1 rec cut
02 deck/index.html?scene=2 rec cut
03 deck/index.html?scene=3 rec cut
04 clip media/intro.mov cut
```
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 music ducks under the whole clip. [Sound](/concepts/sound#ducking) 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.
```json media/interview.words.json theme={null}
[
{ "word": "Watch", "start": 0.15, "end": 0.42 },
{ "word": "it.", "start": 0.48, "end": 0.71 }
]
```
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.
```toml decktalk.toml theme={null}
[[section]]
number = 4
chapter = "Interview"
clip = "media/interview.mp4"
words = "media/interview.words.json"
```
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 `.words.json` file from `build/narration` has this format. `decktalk clip` writes the words file of a clip that
it cuts from a build. [Cut a clip 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 project after `decktalk build --no-voice`. After a voiced build, the clip carries the real voice.
Print the words of section 1 with their times, in seconds after the section starts.
```console theme={null}
decktalk words --only 1
```
```text theme={null}
sections 1, words 26
== 01 Open (14.29s, lead 0.5s, estimated)
start end word
0.500 0.961 This
0.981 1.442 is
1.462 1.922 DeckTalk.
1.942 2.403 You
2.423 2.884 write
2.904 3.365 what
3.385 3.845 you
3.865 4.326 will
4.346 4.807 say,
```
The opening sentence runs from the start of "This" at 0.500 s to the end of "DeckTalk." at 1.922 s.
```console theme={null}
decktalk clip 1 --start 0.48 --end 1.92 --hold 0.5 --out media/open-line.mp4
```
```text theme={null}
section 01: the span cuts the word 'DeckTalk.' in two, so the words file leaves it out
section 01: the narration is a silent placeholder, so the word times are estimates
seconds 1.92, words 2 | 0 certain, 1 uncertain finding(s)
wrote media/open-line.mp4 (1.92s: frames 12 to 47 of sections/01.mp4, 0.48 to 1.92s, hold 0.48s, gain +0 dB)
wrote media/open-line.words.json (2 words)
use it in a clip section: clip = "media/open-line.mp4" and words = "media/open-line.words.json"
```
* The picture comes from `build/sections/01.mp4`. `--start` and `--end` round to whole frames, so the span
ran to 1.92 s rather than 1.93 s.
* The sound is section 1's narration over the same span. `--hold 0.5` adds 0.48 s of the last frame in silence.
* `media/open-line.words.json` lists the two whole words inside the span, in seconds after the clip starts.
* The frame grid put the end inside "DeckTalk.", so that word is left out of the words file and `clip` reports
it as an uncertain finding. Move `--end` into the silence beside the word to keep it.
Add a clip section that names both files, and renumber the sections after it as
[Add a clip section of your own](#add-a-clip-section-of-your-own) describes.
```toml decktalk.toml theme={null}
[[section]]
number = 4
chapter = "The opening line again"
clip = "media/open-line.mp4"
words = "media/open-line.words.json"
```
Then run `decktalk assemble`, and check that the section reads `open-line.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, so a clip cut from a slide plays that whole slide.
* [`decktalk clip`](/reference/cli#decktalk-clip) lists every option.
## Keep one chapter across several sections
Each section starts a chapter. Consecutive sections with the same `chapter` share one chapter instead, so a page
section, a clip and the page section after it can read as one part of the video.
## Choose where the clip plays
A clip section can sit anywhere in the order of sections.
| Position | Example | What the narration does |
| ----------------------------- | -------------------- | -------------------------------------------------------------------------------------------- |
| Before the first page section | section 0 | The narration starts with the first page section, after the clip. |
| Between two page sections | a clip in the middle | The narration pauses for the clip. It continues on the first frame of the next page section. |
| After the last page section | a closing clip | The narration has ended before the clip starts. |
* `cues.json` names the cues of a section by its section number, such as `"4"`.
* A section's `scene` names the scene in the page, and the cue ids of that section start with a slide id of that
scene. A page keeps its scene numbers when a clip section renumbers the sections around it, so a section number
and its scene can differ.
* 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 add a section 0 to a project, such as `my-lesson` from the [quickstart](/quickstart). Section 0
comes before section 1, so it needs no renumbering.
Put this table above the section 1 table.
```toml decktalk.toml theme={null}
[[section]]
number = 0
chapter = "On camera"
clip = "media/open.mp4"
slate_seconds = 6 # a titled slate plays for this long when the file is missing
```
In the existing `[transition]` table, change `dips = []` to `dips = [[0, 1]]`.
```toml decktalk.toml theme={null}
dips = [[0, 1]]
```
`dips` lists each cut that dips to black, as a `[from, to]` pair of section numbers. The starter sets
`dips = []`, so every cut is straight. If you delete the key, every cut dips.
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.
```md script.md theme={null}
## 0. On camera
[Your clip at media/open.mp4 plays here, with its own sound.]
## 1. Open
```
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's chapter and the path where the file belongs.
Run a build without voice.
```console theme={null}
decktalk build --no-voice
```
```text theme={null}
section 00: media/open.mp4 is missing, so a slate plays for 6s. Drop your clip at that path
[cut ] 00 slate -> 00.mp4 (6.000s)
[cut ] 01 01.webm (t0 1.44s trimmed) -> 01.mp4 (14.280s)
```
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
* **Look up every section key:** [decktalk.toml](/reference/decktalk-toml)
* **Rebuild after you replace a clip:** [Rebuild one section](/guides/rebuild-one-section)
* **Understand the mix:** [Sound](/concepts/sound)