Documentary video
The user gives a topic. You deliver a finished film: out/<slug>.mp4 (1920x1080, H.264/AAC), plus .srt, CREDITS.md, the script and sources. The user should not have to install, research, write or render anything themselves. Stop only when a decision is genuinely theirs: a paid generation, a download that needs permission, or a factual claim that cannot be verified.
SKILL_DIR is this folder. DOC means python3 "$SKILL_DIR/scripts/doc.py".
1. Frame it before you write
Ask at most two questions, and only if they change the film: length (default 3 minutes) and angle (what the film argues, not just its subject). Everything else you decide.
A documentary is an argument with pictures, not a summary. Pick one claim a viewer can repeat after watching -- "the lighthouse keeper didn't lose to technology, he lost to a spreadsheet" -- and cut everything that does not serve it.
Never film a list of facts. Film a change: something was true, then it stopped being true, and here is what that cost.
2. Set up (first run only)
DOC doctor
Needs python3 and ffmpeg with libx264. Termux: pkg install ffmpeg. macOS: brew install ffmpeg. If only ffmpeg is missing, install it and re-run. Write nothing else until doctor says Ready.
DOC new <project> --title "The Last Lightkeeper" --subtitle "1985 -- 1997"
That creates project.json, shots.json, research.md, script.md, and work/img, work/audio, out.
3. Research
Use web search. Aim for four to six solid sources: primary documents, archives, university or agency pages, reputable journalism, one book. Read enough to explain the mechanism, not just the outcome.
Save to research.md:
# Research
## Thesis
One sentence the film argues.
## Facts (each with a source)
- 1841: <fact> -- <source url>
- <number>: <fact> -- <source url>
## Contested / unknown
- <what sources disagree on and how the film will phrase it>
## Visual material
- <archives, collections, likely public-domain image searches>
Every sentence in the narration must trace to a line here. If two sources disagree, either say so on screen or drop the fact. Do not invent a number, a date, a quote or an anecdote. A missing fact is a plot problem; a fake one is a fraud.
4. Write the script
Read references/script-craft.md before writing. In short:
- 155 words per minute. 3 min = ~460 words. Budget by act, not by vibe.
- Four movements: the world before (hook), the mechanism (how the change worked), the cost (what it did to people), the echo (return to the hook, changed).
- One idea per sentence. One breath per line. No sentence over 22 words.
- Concrete over abstract. "He climbed 117 steps twice a night" beats "the job was demanding".
- Present tense for the story, past tense for the verdict.
- Narration carries the argument; captions carry the evidence (names, dates, places). Never say on the soundtrack what the caption already proves.
Write it in script.md as acts, one sentence per line, because shots.json lines must match verbatim:
## Act I -- the world before
For two hundred years, someone had to stay awake so that ships could find the shore.
...
Then show the user the whole script in one message -- roughly 30 lines -- and continue. Do not wait for approval unless they asked to review it.
5. Shot list
Read references/shot-list.md for every field and a complete example, then write shots.json:
{"shots": [
{"id": "s01", "kind": "card", "text": "The Last Lightkeeper",
"sub": "A job that vanished in twelve years", "hold": 4.0},
{"id": "s02", "line": "For two hundred years, someone had to stay awake.",
"img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
"caption": "Cape Byron, 1891"}
]}
Rules that matter:
lineis the narration, verbatim from the script, in order. Duration comes from the audio, so a changed line changes the edit.- 3.5 -- 6 seconds per shot. A still needs longer than you think. Never under 2.5 s except a deliberate flash.
- One image, one idea. If a shot needs two images, it is two shots.
- Move the camera, not the world.
zoom-infor intimacy,zoom-outfor consequence,pan-*for landscape and documents,staticfor faces and text. - A card is a chapter break. Use 2-4 in a 3-minute film: title, one date or number, and a last card that lands. Cards have no narration.
captionis the small on-screen evidence line: place, year, source. Keep under 6 words.
6. Stills
Prefer real archival material. It is the difference between a documentary and a slideshow.
DOC archive <project> --query "Cape Byron lighthouse 1900" --n 3
This searches Wikimedia Commons, downloads usable images into work/img/, and writes sources.json + CREDITS.md with author and licence. Default keeps public domain, CC0 and CC BY / BY-SA only, because a published film usually needs commercial use. Add --license pd for strict public domain, --license any to see everything (then check each licence yourself).
If the archive has nothing, in order of preference:
- Other open collections -- Library of Congress, Smithsonian Open Access, NASA, Internet Archive, Europeana. Ask the user before downloading from a new site, and record the licence and URL in
CREDITS.md. - Generate an image with any image tool you have, using
references/image-prompts.md. Mark generated frames inCREDITS.mdas AI-generated reconstruction, and caption them so a viewer is never misled into thinking they are photographs. - Typographic and object shots -- a document, a map, a page of a logbook, an abstract plate. Honest and cheap.
Never present an AI image as archival. That single line is the whole ethics of the format.
7. Narration
DOC tts <project>
Uses ElevenLabs when ELEVENLABS_API_KEY is set (best), otherwise an offline voice (espeak-ng, Android termux-tts-speak, macOS say). One take. Write for the ear: short sentences, no tongue-twisters, numbers spelled the way they are said.
If there is no voice at all, the film still renders with estimated timings -- say so, and deliver the .srt so the user can record their own narration later. Keep line unchanged so a re-record drops straight in.
Recording quality beats model quality: a phone recording in a quiet room is better than a synthetic voice for most documentaries. Offer that.
8. Build and watch it
DOC build <project> --draft # fast pass while iterating
DOC build <project> --subs # final, captions burned in
DOC sheet <project> # 12-frame contact sheet
Look at out/contact.jpg every time. Check:
- nothing important sits under a caption, and no caption runs off frame;
- cuts land on sentence ends, and no shot holds on an empty or irrelevant part of an image;
- the grade is consistent, faces are not crushed, and text images are readable;
- the last card arrives after the narration stops, not on top of it.
Fix by editing shots.json (image, motion, caption, order) and rebuilding. Interior clips are cached by shot id, so only changed shots re-render.
Speed. Rendering is CPU-bound. At 1080p a three-minute film takes about a minute on a laptop and 10-20 minutes on a phone. Always iterate with --draft (half resolution, fast preset), and do one full pass at the end. build prints each shot as it goes, so you can stop a render that is obviously wrong.
9. Music
Ask before adding music. Suggest a source, check the licence, put the file at public/music/bed.mp3, then:
DOC build <project> --music public/music/bed.mp3
It loops, sits at ~14% and ducks under the voice automatically. Silence is a legitimate choice and often the better one for a serious film.
10. Deliver
Give the user:
- the MP4;
- the
.srt(also useful on YouTube); CREDITS.md-- every still, author, licence, link;- the script, one paragraph on the angle, and 3-5 source links;
- a straight note on what is archival, what is generated, and what was cut for lack of evidence.
Then offer one next step: a longer cut, a different opening, a second act, or the same film as a vertical 60-second cut.
Good judgment
- The film is the argument, not the footage. If the images are beautiful but the claim is vague, rewrite.
- Cut the third example. Two prove a pattern; three is a list.
- Sources on screen, not just in the description. A caption with a year and place is what makes a viewer trust the rest.
- Say what you don't know. "Nobody agrees on the number" is a stronger line than a confident wrong one.
- Respect the dead. Real people, real events: no invented dialogue, no reenactment presented as record, no generated faces for named individuals.
- Length is a promise. If the material only supports 90 seconds, deliver 90 seconds.
Files
scripts/doc.py-- the whole pipeline (DOC -hfor every flag).references/script-craft.md-- how to write narration that sounds like a film.references/shot-list.md-- completeshots.jsonschema and worked example.references/sourcing.md-- archives, licence rules, attribution format.references/image-prompts.md-- prompts for generated stills that cut with archival.examples/last-lightkeeper/-- a finished 3-shot example (script + shots).