Paper-cutout explainer Shorts (multi-agent)
Output: 1080×1920, 24 fps, 60–95 s MP4 with narration, ducked music and synced sound effects. Look: flat SVG props with white "sticker" outline + drop shadow, halftone-dot or sunburst backgrounds, English ALL-CAPS caption tags on torn paper (Bebas Neue), slight RGB split + film grain + vignette.
Everything is rendered from HTML/SVG by headless Chrome frame-by-frame (deterministic), so scenes are
plain JS files written by agents against a tiny engine (template/engine.js, documented in template/ENGINE.md).
Requirements
- Python 3 venv with:
playwright(uses system Chrome viaCHROME_PATH, orplaywright install chromium),numpy,opencv-python-headless(optional),faster-whisper(timing/QA),edge-tts(free fallback voice). ffmpeg,curl,bc. Optional: ElevenLabs MCP connector for the narrator + music.
Pipeline (follow in order)
1. Research + script agent (background)
Spawn ONE general-purpose agent with the prompt in references/agent_prompts.md#research. It must web-verify
every fact, attribute claims, flag rumours, and return: SCRIPT (14–17 short spoken lines, ~950–1,150 chars,
numbers spelled as words, names in the narration script), TABLE (caption tags / visual idea / background per line),
FACTS with URLs, UNCERTAIN/NOT USED. For very recent topics tell it today's date and ask it to first confirm
what the topic actually refers to. While it runs: scripts/new_project.sh <dir> and draw any shared props
the story needs (one consistent design per recurring object/person) at the end of <dir>/engine.js;
render one test frame to check them.
2. Voiceover
- Preferred: ElevenLabs
eleven_v4, a documentary narrator (e.g. Hindi "Natraj – Informative Documentary Host"), 2 takes, script with sparing[curious]/[dramatic]/[thoughtful]tags. Check credits first. - Fallback (free, gives exact per-line timings): put the plain lines in
<dir>/script.txt, runscripts/edge_tts_lines.sh <dir> hi-IN-MadhurNeural +20%→vo.wav+lines.txt. - QA every take: TTS models can garble numbers/dates. Transcribe with
scripts/words.py; Whisper itself mis-formats Hindi numbers, so re-check suspicious years with digits suppressed (seereferences/qa.md). Pick the take that says every number right. - Line timings for a single-file take: silence detection (
ffmpeg -af silencedetect=n=-38dB:d=0.15) + word timings;scripts/align_lines.pygives a first guess. Writelines.txt(lNN start= end= | text) with the video offset you will use (e.g. +0.25 s) and a shiftedwords.txt.
3. Three scene agents in parallel (background)
Split the timeline at line gaps into ~25–30 s parts. Spawn three general-purpose agents in ONE message using
references/agent_prompts.md#scene — each owns only scenes_N.js, gets its exact time range, its narration
lines with start/end times, key-word beats, a storyboard (from the TABLE), the shared assets, and the rules:
IIFE + pN_ prefixes, scenes tile the range exactly, top tag ~0.1 s after a cut, something new every ~1 s,
render test frames and LOOK at them, delete PNGs.
4. Integrate + review (you)
- Render ~30 evenly spaced frames into a contact sheet (
render_html.py ... 999 t1,t2,...thenffmpeg -pattern_type glob -i 'test_*.png' -vf scale=170:-1,tile=11x3) and Read it. - Fix: invented numbers/claims on screen (agents sometimes add them — remove), inaccurate maps/borders, logos, caricatures of real people, overlaps, off-screen text, empty frames.
5. Render, mix, publish
scripts/render_video.sh <dir> <duration> <narration> <music> <vo_delay_ms> <out.mp4> renders all frames,
builds the SFX track from engine events, ducks the music under the voice (~-14 LUFS), and muxes.
To re-voice an existing video without rebuilding scenes, render with WARP=anchors.json (maps new line
starts → old line starts; see references/qa.md). Deliver via the user's preferred channel.
Content rules (always)
- Facts only from the research agent's sourced list; money/box-office/poll numbers labelled "REPORTED"/sourced; uncertain counts shown as floors ("250+").
- Real people: generic
A.figbust + English name tag, never caricature; no religious deities drawn — use abstract motifs; no brand/party logos (draw generic badges/birds/letters). - Maps: avoid outline maps of countries with disputed/sensitive borders; use borderless boards or tile grids, and label illustrative visuals as such.
- Politics: neutral, attributed, no mockery or predictions.
Files
template/—index.html,engine.js(engine + asset packs),ENGINE.md(API for agents),scenes_1..3.jsexamples/— four finished videos' scene code (Streisand Effect, Statue of Liberty, Twitter blue tick, 2026 US midterms): the quality/pacing bar for agentsscripts/— render, SFX, alignment, transcription, free TTS, project bootstrap, final mixreferences/agent_prompts.md,references/qa.md