Communitygithub.com

documentary-video-skill

Transforme qualquer tópico em um curta-metragem documentário completo, do início ao fim — pesquisa, roteiro com verificação de fatos, narração, imagens de arquivo com fontes, legendas, créditos, trilha sonora e um MP4 finalizado renderizado com ffmpeg.

O que é documentary-video-skill?

A habilidade 'documentary-video-skill' permite que um agente de IA produza um curta-metragem documentário completo a partir de um simples tópico fornecido pelo usuário, sem que este precise instalar, pesquisar, escrever ou renderizar nada. O processo é totalmente automatizado: o agente realiza pesquisa na web para obter fontes confiáveis (arquivos primários, artigos acadêmicos, reportagens), escreve um roteiro de narração com verificação de fatos, gera locução (usando ElevenLabs ou voz offline), busca imagens de arquivo reais em domínio público (Wikimedia Commons, Biblioteca do Congresso, etc.), compila uma lista de planos, e renderiza o vídeo final em 1920x1080 H.264/AAC com legendas e créditos. A ferramenta prioriza precisão factual e materiais de arquivo autênticos, rejeitando a invenção de dados ou o uso enganoso de imagens geradas por IA. É ideal para documentários históricos ou científicos, videoensaios, curtas no estilo 'mini-doc', ou qualquer solicitação do tipo 'faça um vídeo sobre' que exija fontes reais e uma estrutura narrativa coerente — não uma mera apresentação de slides.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  • line is 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-in for intimacy, zoom-out for consequence, pan-* for landscape and documents, static for 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.
  • caption is 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:

  1. 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.
  2. Generate an image with any image tool you have, using references/image-prompts.md. Mark generated frames in CREDITS.md as AI-generated reconstruction, and caption them so a viewer is never misled into thinking they are photographs.
  3. 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 -h for every flag).
  • references/script-craft.md -- how to write narration that sounds like a film.
  • references/shot-list.md -- complete shots.json schema 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).

Habilidades Relacionadas