Skip to content

Documentaries

github-actions[bot] edited this page Nov 21, 2026 · 3 revisions

clippa doc builds a narrated mini-documentary from a plan you write by hand: your script, the subject's own clips, cover shots cut to the words. It buys the narration (or takes your own recording of it), builds the timeline in DaVinci Resolve, masters the render to YouTube's loudness, checks the result for anything that must not be in it, and writes the publish kit.

It differs from a story cut: a story is planned by a model and rendered by ffmpeg as cards and clips; a documentary is your script and your edit, finished in Resolve. Research for one still comes from clippa story run, archives and b-roll.

Order of work

  1. clippa doc new <slug>: the piece's folder.
  2. Fill in banned.txt and write plan.toml. Lock the script before buying narration: most rebuilds are narration changes.
  3. clippa doc voice <slug> --dry-run, then without --dry-run. Listen to every take. Reading it yourself: record each take into vo/read/ first (Your own voice).
  4. clippa doc build <slug>: a new timeline version in Resolve. Watch it, change the plan, build again.
  5. clippa doc master <slug>: the render, the loudness, the leak check.
  6. clippa doc kit <slug>: chapters, description, credits. You upload in Studio by hand.

The piece's folder

A piece is [paths] documentaries/<slug>/, beside clipper.toml and never in the repo:

  • plan.toml: the script and the edit.
  • banned.txt: what must never be heard in the render or written in the kit.
  • reels/: the subject's own video. overlays/: cards, labels, text. music/, sfx/. A file is named in the plan by its name without the extension. A file kept elsewhere goes in the plan's [media] table (name = "path").
  • vo/read/: your own recordings of takes, when you read the narration yourself.
  • vo/ (the narration), work/ (the build, caches), renders/, kit.md: written by the commands.

The plan

plan.toml starts with the piece's own settings, then [[seq]] entries in the order they play.

title = "The Lighthouse"
project = "Lighthouse"        # the Resolve project that must be open for build (optional)
voice_id = "..."              # this piece's narrator; without it, [doc] voice_id
description = "..."           # for the kit
credits = ["Room tone: Freesound 123456 by Someone (CC0)"]
pinned = "The pinned comment."

[clips.wave]                  # a named stretch of the subject's video
reel = "reel_a"
from = 10.0
to = 14.0

[[music]]                     # a cue from a section on
file = "cue1"
at = "COLD OPEN"

[room_tone]
file = "roomtone"

[[seq]]
section = "COLD OPEN"

[[seq]]
card = "card_open"
seconds = 5

[[seq]]
say = "He climbed the stairs every night for forty years."
take = "open"
shots = [["reel_a", 1.0], ["reel_b", 5, "every night"]]

[[seq]]
clip = "wave"

Each entry is one of four kinds:

  • section = "NAME": a red marker on the timeline and a YouTube chapter. chapter = "Title" gives the chapter its own wording; chapter = false keeps it out of the kit.
  • card = "overlay" with seconds: a full-screen card. silent = true stops the music under it, and the room tone too unless the card has a sound. sound = "thump" plays an effect from the card's start; sound_before = "swell" ends one there.
  • clip = "name": the subject's own picture and sound, from [clips.name] or from reel, from and to on the entry. mute = [[9.07, 9.5]] cuts those seconds of the reel out of the sound and leaves the picture. over = "overlay" puts text over it; note = "..." leaves a yellow marker; hard_out = true stops its sound from running on under what follows.
  • say = "...": a narration line. shots are its cover shots: a reel, where the shot starts in the reel, and (from the second shot on) the words of this line it cuts in on. A fourth item is an overlay for that shot. silent, over and label = false work as on a clip.

A cue is checked against the line's own words when the plan is read, so a cue that isn't there fails before anything is bought. A mistake is reported with its line in plan.toml.

A still image (a label, a headline) is turned into a short movie in work/stills/ for the build, because Resolve gives a still its own length on a timeline whatever it is asked for.

A reel gets a label on the second video track when overlays/label_<reel> exists, or when [labels] names another overlay for it.

Takes

say lines that share a take are voiced in one read, in script order, so they sound like one performance even with clips between them. The read is cut in the pause before each line. Two lines that follow each other directly are cut in the middle of that pause, with no fade. A line with no take is a read of its own.

Narration

clippa doc voice buys each take from ElevenLabs once ([narrate]'s key and tts_model, the plan's voice_id or [doc] voice_id), unless you recorded it yourself. --dry-run checks the plan and prints how many characters it would buy. A take is bought again only when its words, the voice or the voice settings change.

Each bought read then goes through [doc] vo_filter (a light 2:1 compressor), has its pauses cut down to [doc] max_pause_s (max_pause = 0.9 on a line keeps longer ones in its take), and gets its word times from a small local Whisper (free; it needs faster-whisper, which the gpu extra installs). Changing the compressor or the pause cap processes the takes again without buying them.

The narration is refused when a line contains a term from banned.txt.

Your own voice

To read a take yourself, record it and save it as vo/read/<take>.wav in the piece's folder, named for the take (take = "open" in the plan is vo/read/open.wav; .flac, .aif, .mp3, .m4a, .aac, .ogg and .opus work too; Open.wav is the same take). clippa doc voice then uses your recording for that take and buys nothing for it. A piece can mix the two: takes with a recording are yours, the rest are bought. --dry-run lists which is which, and names any file in vo/read/ that matches no take.

  • Give every line you read a take. A line with none can't have a recording, because its place in the plan is its only name.
  • Read the take's lines in script order, in one file, with a clear pause between lines: the file is cut apart in those pauses.
  • Your read gets the same treatment as a bought one: the compressor, pauses cut down to [doc] max_pause_s (max_pause = 1.2 on a line keeps longer ones in its take), and word times from the local Whisper. In a room louder than [doc] silence_db no pause is found and nothing is trimmed: raise it (towards 0) until the pauses are.
  • The words are matched to the script. When under 80% of a take's words are heard, clippa doc voice says so each time it runs: change the lines in plan.toml to what you said, or read the take again.
  • A new recording under the same name is processed again; run clippa doc voice after saving it, then build.

When every take in the last build is your own, the kit leaves out the AI-voice line (see Kit): build again after recording, since a recording counts once a build has used it. A file whose name starts with a dot is never a recording.

Build

clippa doc build turns the plan into frames (work/build.json) and builds a new timeline named <title> vNN in the open Resolve project. An earlier version is never changed. --dry-run stops before Resolve.

The timeline has three video tracks (picture, labels, text and cards) and seven audio tracks: clip sound, narration, effects, clip sound under the narration, two score tracks and room tone.

  • Sound at the joins: a clip's sound fades out for [doc] tail_s under the next line, and the next clip's sound fades in for [doc] lead_in_s under a line's last words.
  • Levels: every clip and every narration take gets a clip gain that brings it to [doc] dialogue_lufs, held back where its peak would pass [doc] peak_ceiling.
  • Music: each [[music]] cue runs from its section (at, plus at_s seconds) into a [doc] crossfade_s crossover with the next cue, on alternating tracks, [doc] music_under LU under the dialogue. A cue stops at a silent stretch, and one whose section opens on a silent card starts after it. tail = true places a cue so its own ending lands on its last frame.
  • Room tone: the [room_tone] file looped with one-second crossfades for the whole piece, [doc] tone_under LU under the dialogue.

The project's timeline frame rate must be the plan's (fps in plan.toml, else [doc] fps); a build into a project at another rate is refused before anything is placed. Only whole frame rates are supported (24, 25, 30, 60), and reels at another rate than the timeline are untried: conform them first.

After building, every item is read back from Resolve; an item that isn't where the plan put it, or a gain or fade Resolve refused, is an error.

Resolve

Resolve Studio must be running on the same machine, with Preferences > System > General > "External scripting using" set to Local. Clippa finds the scripting module where Resolve installs it; [doc] resolve_api and resolve_lib (or RESOLVE_SCRIPT_API and RESOLVE_SCRIPT_LIB) name another place. clippa doctor reports whether it is found once a piece exists.

Master

clippa doc master renders the last built timeline to renders/ (--timeline NAME for another, --file for a render you made yourself), measures it, and writes <name>.master.mp4 with the sound brought to [doc] lufs (-14 for YouTube) by gain and a limiter at [doc] true_peak. The picture is copied, not re-encoded. It prints the loudness before and after. When the result is more than 1 LU off, raise [doc] dialogue_lufs and build again rather than push the master harder.

Then it runs the leak check; --no-leak skips it.

Leak check

clippa doc leak transcribes the mastered render on Modal (a few cents, mostly the container's start; --dry-run prints the estimate) and fails when a term from banned.txt is heard, printing the time and the words. It also reads kit.md. A transcript is kept per file, so a second run on the same render costs nothing.

banned.txt is one term per line; # starts a comment. A term matches the same words (and their plural or possessive: Ann also finds Ann's and Anns, not Anna; a hyphen, slash or dash ends a word, so Kent is found in Kent-based), the same letters split or joined differently, and, for terms of five letters or more, letters close enough that a transcript's spelling of a name still counts ([doc] leak_fuzzy). Add the spellings you expect anyway. A line starting with ! marks heard words that look like a term but are fine.

The check hears only the sound. On-screen text, and the channel's older titles and replies, are yours to read.

Kit

clippa doc kit writes kit.md from the plan and the last build: the title, the description with chapters (from the sections: the first at 0:00, each at least ten seconds after the one before and before the end, none when there are fewer than three), the credits (the plan's credits and each credit on a music cue or the room tone), the disclosure lines, the pinned comment and a checklist. The disclosure lines are [doc] disclosures ("The narration is an AI voice."), or [doc] own_voice_disclosures (none) when the last build bought no take because you read them all; the plan's own disclosures replace either (disclosures = false for none). It fails when the text contains a banned term.

Clone this wiki locally