Communitygithub.com

documentary-video

Make YouTube history documentaries in a hand-embroidered medieval tapestry style - short (~2 min) or long-form built in 2-minute parts over several days with saved progress. Script, ElevenLabs voiceover, Google Flow images (free) and a few Flow image-to-video clips, assembled with ffmpeg and joined seamlessly. Use when the user asks for a "tapestry / embroidered / Bayeux-style" history video, a documentary like the Lindisfarne 793 one, the next part of an existing long video, or "make a new video with the tapestry skill".

What is documentary-video?

documentary-video is a Claude Code agent skill that make YouTube history documentaries in a hand-embroidered medieval tapestry style - short (~2 min) or long-form built in 2-minute parts over several days with saved progress. Script, ElevenLabs voiceover, Google Flow images (free) and a few Flow image-to-video clips, assembled with ffmpeg and joined seamlessly. Use when the user asks for a "tapestry / embroidered / Bayeux-style" history video, a documentary like the Lindisfarne 793 one, the next part of an existing long video, or "make a new video with the tapestry skill".

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/xajeel/make-video-skills/tree/HEAD/documentary-video

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Documentary video skill (tapestry style)

Proven on "793: The Raid That Started the Viking Age" (doc-test/lindisfarne_793_documentary.mp4). Each part: 1920x1080, ~2:00, British narrator, 15 scenes. Scenes 1, 2, 3, 5 and 8 are real-motion Flow clips; the rest are images with a very slight slow zoom.

Look at the references first:

  • references/style/: the user's target look. Muted cream, slate blue, moss green, ochre and rust stitching, swirling stitched clouds and waves.
  • references/approved-examples/: generated stills the user accepted. They are full frame, with no border and no white margin.
  • references/avoid/: what the user rejected:
    1. A cloth edge or white margin around the picture.
    2. A decorative animal-frieze border band along the bottom.

User rules (important)

  • If a message has a question plus a task, answer the question and wait before spending any credits.
  • Only the user's own words count as instructions. Be economical with credits, make no unrequested side work, and report briefly.
  • Animation pattern: animate scenes 1, 2, 3, then 5, then 8 of each part with real Flow image-to-video. That's 5 clips, about 120 credits per part. Every other scene uses its image with a very small slow zoom (about 3%, alternating in and out). assemble.py does this automatically.
    • Never present zooming images as "the videos". Real clips must come from Flow.
    • Say the cost (24 credits per clip) before submitting. If the user picks a different set of scenes, record it with project.py decide.
  • One Flow project per video. Create it once and always pass its id. Never use --project-name per call, because that creates a new project every time.
  • The user often interrupts. After an interruption, check what is still running or charged before doing anything else.

Long-form: build in 2-minute parts, over several days

An 8-minute video is 4 parts of about 2 minutes, made one part at a time. Each part goes through two reviews:

  1. A free draft review.
  2. A final review after credits are spent.

All state lives in the project folder, so a fresh session can always continue.

Starting a session on an existing video:

  1. Read <project>/PROGRESS.md.
  2. Run python3 scripts/project.py status <project>. It prints the decisions, each part's status and NEXT, the action to take.
  3. Continue from NEXT. Never redo finished parts, and never change a decision (voice, style, Flow project, pattern) without the user's OK.

Project layout (create with project.py new doc-test/videos --title "..." --minutes 8):

doc-test/videos/<slug>/
  project.json      decisions (voice_id, style, flow_project_id, animation_pattern, zoom...) + per-part status/credits
  PROGRESS.md       dated log of every step and decision - append via project.py, never rewrite
  outline.md        whole-video arc + per part: covers / opening line / closing hand-off line
  parts/partNN/     scenes.json, voiceover.mp3, timing.json, images/, clips/, draft.mp4, partNN.mp4
  final/<slug>_full.mp4

Part status flow: planned → script_review → draft_review → final_review → final. Set each status with project.py set <project> <n> <status> --note "..." [--credits N].

Per part:

  1. Script (part 1 also fills in outline.md for the whole video first).
    • Write parts/partNN/scenes.json, using templates/scenes.example.json as the template. Keep the style string from project.json.
    • The first scene must pick up from the previous part's closing line. The last line hands off to the next part.
    • Visually, the last scene of part N and the first scene of part N+1 should share setting and palette, so the dissolve between them feels natural.
    • Send the script to the user, then set ... script_review.
  2. After the user approves the script, do the whole part in one go:
    • Generate the voiceover (step A) and the timing (step D), then the images (step B; usually the user's extension from image_prompts.txt).
    • Animate the pattern scenes 1, 2, 3, 5 and 8 in Flow (step C). The user expects the real clips in the first version they review.
    • Run assemble.py parts/partNN for the 1080p partNN.mp4.
    • Send the full path to the user and open it with xdg-open.
    • Then set ... final_review --credits <spent>.
    • Never send a draft made only of zooming images as "the video". --draft is only for a quick private check.
  3. (The draft_review status is optional. Skip it unless the user asks for a cheap preview first.)
  4. After the user approves the final render: set ... final.
  5. When all parts are final: run python3 scripts/join_parts.py <project>, which writes final/<slug>_full.mp4. Then spot-check each seam (sound and picture).

Why the joins are smooth (don't break this):

  • assemble.py renders every part with identical format: 1920x1080, 30 fps, yuv420p, AAC 48 kHz stereo, voice loudness-normalised to -16 LUFS.
  • Every part also has identical edges: 0.4 s of picture before the first word and 1.2 s of quiet picture after the last word.
  • join_parts.py dissolves the picture over 1 s inside that quiet tail and cuts the audio inside the silence, so no words overlap and the level doesn't jump.
  • Tested: the seam gap was 0.84 s, the same as a normal paragraph pause, and loudness was -16.4 vs -16.5 LUFS on either side.
  • Always use the same voice_id and tts_model for every part, as recorded in project.json.

Production steps (used inside each part)

A. Voiceover (ElevenLabs MCP)

  1. Call creative_generate_speech with:
    • model_id: the project's tts_model, eleven_v4
    • voice_id: the project's voice_id, QngvLQR8bsLR5bzoa6Vv ("Michael Dan – British Documentary Narrator")
    • prompt: the part's narrations joined with blank lines between them
  2. Poll creative_get_flow_run_status until it finishes. It returns 2 takes, about 1650 ElevenLabs credits (≈$0.30) each.
  3. Download take 1 with curl from content_url to parts/partNN/voiceover.mp3.

Write years as words, e.g. "seven ninety-three", so the narrator says them correctly.

B. Images (free) - the user usually makes them with their own browser extension

Images are made from a text prompt only (style string + scene). No reference image is passed: gflow refuses reference images on this account, and the reference folders are only for checking results by eye.

Preferred (user's extension): do the voiceover and timing.py first, so the scene times are known, then write parts/partNN/image_prompts.txt and give the user that path. The format is exactly one prompt per scene, then a blank line:

[0.00-0.06] <style>. Scene: <image>. IMPORTANT: do not write the time, any numbers, any label or any text anywhere in the image.

[0.06-0.14] ...
  • The times are m.ss from timing.json.
  • The user passes the file to the extension and sends back a folder, e.g. ~/Downloads/zapi-img-doc/. It contains files named NN_[mss-mss]_....webp, sometimes _1/_2 takes.
  • Review every image on labelled contact sheets. Look for a cloth edge or stripe, a margin, a border band, stray text, the wrong subject, or a style mismatch. Pick the best take and convert it to parts/partNN/images/sceneNN.jpg.
  • Regenerate only the bad ones with gflow (free), and tell the user which ones and why.

Fallback (gflow MCP):

  1. Run gflow_generate_image with prompt "<style>. Scene: <image>.", aspect "16:9", model nano2 and project <flow_project_id>.
  2. For the very first image of a new video, omit project and pass project_name. Then run project.py decide <p> flow_project_id <id>.
  3. Copy the file from ~/Downloads/gflow-cli/images/<date>/<media>_1.jpg to parts/partNN/images/sceneNN.jpg.

Contact sheet: ffmpeg -pattern_type glob -i 'images/scene*.jpg' -vf "scale=344:192,tile=5x3" -frames:v 1 contact.jpg

C. Animate the pattern scenes (Flow website, costs credits)

gflow's i2v is refused on this account: Flow serves it the "agent-only composer" (gflow issue #799). The refusal costs nothing. Use the website instead. Flow's layout changed in Nov 2026: there is no agent chat or Approve step any more.

If the user also wants to make the clips themselves, write parts/partNN/video_prompts.txt in the same [m.ss-m.ss] prompt format. Use the "Animate this exact image..." text plus the scene's motion, one per animated scene, and list which sceneNN.jpg goes with each.

  1. Check credits with gflow_get_credits. It costs nothing.
  2. Run scripts/launch_flow_chrome.sh "https://flow.google.com/project/<id>".
  3. Run ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_animate.py --project <id> --part parts/partNN --upload --prefix <short>_pN_ 1 2 3 5 8.
    • --upload puts the scene images into the Flow project. It's needed when the user's extension made them.
    • It switches the composer to Video → Frames → x1, so the clip starts from the exact image. That's Omni 1.2 Flash, 720p, 8 s, 24 credits per clip.
    • It picks each start frame, types the motion prompt, submits, and waits.
    • Never submit while the composer is on Image/Nano Banana. That makes 2 images, not a video. They're free, but nothing gets animated.
  4. Run ~/.local/share/uv/tools/gflow-cli/bin/python scripts/flow_download.py --project <id> --part parts/partNN 1 2 3 5 8.
    • It downloads the newest videos (Original size) and files each one as clips/sceneNN.mp4 by matching its first frame to the scene image.
    • The match distance should be about 4 for the right scene and over 30 for the others.
  5. Check frames from each clip: same tapestry look, no text.
  6. Close the CDP Chrome window with CDP Browser.close. gflow MCP calls fail while it holds the profile.
  7. Check credits again. The drop should be exactly 24 × the number of clips.

D. Timing and assembly

  1. python3 scripts/timing.py parts/partNN: snaps scene boundaries to paragraph pauses in the voiceover. Check the printed durations. Anything under 5 s or over 11 s is a bad snap, so fix it by hand in timing.json.
  2. python3 scripts/assemble.py parts/partNN --draft makes a review copy. Without --draft it makes the final render.
  3. Spot-check frames before sending.

E. YouTube title

Keep it under 60 characters, put the hook first and include the year. Example: "The Day the Viking Age Began (793 AD)". Offer 3–5 options plus a thumbnail idea with 2–3 words of text.

Environment notes / gotchas

  • gflow MCP: registered through ~/.local/bin/gflow-clean (copy in scripts/gflow-clean). The wrapper strips VS Code snap GTK/GIO environment variables. Without it, Chrome crashes on launch, which gflow misreports as "Profile locked".
  • Account: the gflow profile is sajeel135. Image generation is free; videos cost credits.
  • Chrome must use --password-store=basic: any Chrome opened on the gflow profile needs --password-store=basic, which launch_flow_chrome.sh now sets. Without it, Chrome re-encrypts the cookies with the system keyring. gflow can't read them and lands on flow.google.com/about (exit 31), and the user has to sign in again.
    • When Flow shows /about but Google is signed in, open the CDP window, press "Create with Google Flow", let the user finish any sign-in, then close it cleanly with CDP Browser.close.
  • Stale locks: remove stale Singleton* lock files in ~/.local/share/gflow-cli/profile_sajeel135/, but only when no Chrome is using that profile (launch_flow_chrome.sh does this).
  • Stopping processes: don't run pkill -f <name> from a shell whose own command line contains that name, because it kills itself. Kill by PID instead.
  • Long renders: a final part render takes a few minutes. Run long renders in the background if the tool call might time out.

Related Skills