Vincentwei1021/anything2explainer

English | 简体中文

Topic in, narrated explainer video out. anything2explainer is a Claude Code / Codex skill that turns any topic into a black-canvas motion-graphics explainer video with TTS voiceover, subtitles and a chapter progress bar, in Chinese or English. Every frame is drawn in code with Remotion (React + TypeScript). No stock footage, no generative video model, no frames lifted from anyone else's work.

It is not a CLI. What ships here is the whole method an AI coding agent needs to finish the film: a compilable Remotion template, a primitives and lighting library, tooling for voiceover / storyboard / rendering / quantitative QC, written style and motion specs, a multi-agent division-of-labour protocol, and one complete reference film as the quality bar.

English cut — RAG & Knowledge Bases, 5′02″, 44 lines / 785 words, voiced by kokoro-82m am_liam at natural speed:

Chinese cut — RAG 与知识库 v2, 4′54″, 44 lines / 1490 characters, dot-field backdrop (bg: 'dots'), voiced through the bring-your-own-TTS path (Volcengine TTS 2.0 + forced alignment):

Both cuts share one storyboard and 44 shots; the English cut re-times every shot to the English voiceover. The full paper trail of the original Chinese cut (4′35″, star-field backdrop, 8 build agents in parallel for 40 minutes, two QC rounds) lives in examples/rag/ (research → narration → storyboard → shot source → QC reports → delivery notes); rendered frames are in examples/rag/frames/.

• Input: a topic ("explain vector databases"), or an article / document you want turned into a video. You also pick the length and the language.
• Output: a 1280×720 H.264 MP4 with synchronized voiceover, word-boundary-aligned subtitles, chapter cards, a top HUD and a bottom chapter progress bar, plus the full paper trail (research doc with sources, narration, storyboard, per-shot source code, QC reports).
• How: the agent researches the topic with sources, writes the narration, generates the voiceover and frame-accurate timeline, storyboards every shot, then dispatches parallel build agents that write one Remotion component per shot. QC agents review the rendered frames against written criteria before delivery.
• Time: roughly 1 to 3 hours of wall clock depending on length, most of it agents building shots in parallel. You are consulted at exactly four checkpoints.

Length drives how much ground the film covers, and the size of the whole pipeline:

Chapter count follows the content, within limits set by length: under 3 minutes use a single chapter (no chapter cards), 3–5 minutes 3–4 chapters of at least 60 s each, 5–8 minutes 4–6. The progress bar splits evenly across however many chapters the narration declares. A blank line in the narration marks a paragraph, which is also one shot: sentences inside a paragraph are separated by 10 frames, paragraph ends by 30, so the pause lands where the picture changes and every shot holds 1–1.5 s after its last element lands. The finished video runs 5–8% longer than the raw speech by design.

git clone https://github.com/Vincentwei1021/anything2explainer.git
ln -s "$PWD/anything2explainer" ~/.claude/skills/anything2explainer   # Claude Code
ln -s "$PWD/anything2explainer" ~/.codex/skills/anything2explainer    # Codex

Dependencies:

# Node ≥18 (the template's npm install pulls remotion 4.0.507 / react 19)
brew install ffmpeg          # frame extraction / transcoding, required

python3 -m venv ~/.venvs/a2e && source ~/.venvs/a2e/bin/activate
pip install 'edge-tts==7.2.8' numpy pillow scipy   # pin edge-tts: it tracks a Microsoft endpoint and breaks across upgrades (7.2.0+ needs word boundaries requested explicitly; the script does)

# only needed for English narration (kokoro-82m runs locally)
pip install kokoro soundfile && brew install espeak-ng

scipy is only used by the QC script frame_metrics.py. The shell scripts are zsh + Python 3, developed and verified on macOS; Linux should work, Windows is untested.

Verified on a Raspberry Pi 5 (ARM64, Python 3.13). Three things differ from macOS:

sudo apt install zsh espeak-ng                 # scripts are #!/bin/zsh; espeak-ng for kokoro/piper G2P

# Remotion has no linux-arm64 headless browser → point it at system Chromium:
sudo apt install chromium                       # or chromium-browser
export REMOTION_BROWSER_EXECUTABLE=/usr/bin/chromium   # read by template/remotion.config.ts (no-op on macOS)

TTS on Linux/ARM. kokoro (the default English engine) is hard to install on ARM/Python 3.13 (it pins an old numpy and pulls spaCy → blis, which lack aarch64 wheels). Two local engines that install cleanly instead — pass one via TTS_ENGINE:

# kokoro_onnx — natural voice, onnxruntime (no torch/spaCy). Download model + voices from
#   github.com/thewh1teagle/kokoro-onnx releases (kokoro-v1.0.onnx, voices-v1.0.bin)
pip install kokoro-onnx
TTS_ENGINE=kokoro_onnx KOKORO_ONNX_MODEL=…/kokoro-v1.0.onnx KOKORO_ONNX_VOICES=…/voices-v1.0.bin \
  KOKORO_ONNX_VOICE=am_michael python3 scripts/tts_build.py

# piper — fastest local, robotic; a Pi-native fallback. Voice .onnx from github.com/rhasspy/piper
pip install piper-tts
TTS_ENGINE=piper PIPER_MODEL=…/en_US-ryan-medium.onnx python3 scripts/tts_build.py

The edge engine (natural, free, word-boundary timing) also works on Linux and needs no local model — it's a cloud call to Microsoft: TTS_ENGINE=edge VOICE=en-US-AndrewNeural python3 scripts/tts_build.py.

In Claude Code or Codex, just say what you want. The skill triggers itself:

Make me an explainer video about vector databases.

讲一下向量数据库，做成一条讲解视频

It then walks the 9 stages in SKILL.md:

1. Scaffold the Remotion project from the template.
2. Research (1 agent): a sourced research doc with a list of numbers and analogies, every item with a URL.
3. Narration & timeline: the script, then TTS voiceover with per-word boundaries turned into a frame-accurate timeline and subtitle table.
4. Storyboard: one line per shot with frame range, beat, visuals, motion, hero element and lighting.
5. Overlays & primitives: title, chapter cards, HUD, pipeline rail, plus 2–5 topic-specific icons.
6. Pilot (1 agent): the first shot group, then a 30-second cut for you to judge the look.
7. Parallel build: the remaining groups, 5–7 shots per agent, each writing pure-function Remotion components.
8. Render the full film and run quantitative frame metrics.
9. QC & fixes: one QC agent per chapter, fix agents per group, re-verification, then delivery notes.

You can also drive the template by hand:

template/scripts/new_project.sh ~/work/my-video myslug
cd ~/work/my-video
# 1. research/调研.md          2. script/narration.txt → python3 scripts/tts_build.py
# 3. script/storyboard_src.md → python3 scripts/render_storyboard.py     4. edit src/config.ts
# 5. src/shots/G1..Gn          6. scripts/preview.sh 30   (first 30 seconds)
# 7. VER=v1 scripts/render.sh + python3 scripts/frame_metrics.py         8. QC → fix → v2/v3

The run stops and waits for you at exactly four points instead of ploughing through (details in SKILL.md):

1. Length and language: before the script is written. Length decides the line count, shot count and how many agents run in parallel, i.e. how much the film can actually cover; language flips lang in src/config.ts, which drives typography, subtitle budgets and the default voice.
2. Narration sign-off: before voiceover. Once locked, frame numbers are hard-coded into every shot; changing one word re-times the whole film. This is the cheapest place to intervene.
3. Voiceover: before TTS runs you get asked whether you have a preferred engine. If not, defaults apply (edge-tts Yunxi for Chinese, kokoro-82m Liam for English). You can also hand over finished audio and fill the per-line timeline yourself.
4. First 30 seconds: only the first build group is done, then 30 seconds get rendered for you to judge the look. Fixing the style here costs one group; after the full render it costs every group.

Which AI coding agents does it work with? It is written for Claude Code and Codex, and those two are what it has been run with. The skill itself is plain Markdown plus a Remotion project, so any agent that reads SKILL.md-style skill folders and can run shell commands should be able to follow it.

Does it need a GPU? No. Remotion renders through headless Chromium on the CPU. The Chinese default voice (edge-tts) is a cloud call to a Microsoft endpoint; the English default (kokoro-82m) is an 82M-parameter model that runs locally on CPU.

Can I use my own voice or a different TTS? Yes. Put the finished audio at public/assets/<slug>/audio.wav and fill src/common/timeline.ts and subs.ts by hand (format documented at the top of tts_build.py). Everything downstream is unchanged.

Can I change the visual style? There is one visual style, on purpose, with a single switch: the backdrop, bg in src/config.ts ('dots' dot-field wave by default, 'stars' star field with fog). To change anything else, edit reference/style-guide.md and src/ui.tsx; the shot code only uses those primitives.

Are the renders reproducible? Yes. Every animation is a pure function of the frame number with seeded randomness, and text fitting is computed rather than measured in the DOM, so re-rendering produces identical frames.

Can I use it commercially? The toolkit is licensed under PolyForm Noncommercial: free for noncommercial use, commercial use requires prior authorization from the author. The videos you make with it are yours. See License.

Does it do vertical (9:16) video? Not currently. The template and every safe-area rule assume 1280×720 landscape.

Which languages? Chinese and English. Each has its own pacing model, subtitle budget and default voice. Both cuts are embedded at the top of this page; the written paper trail in examples/rag/ is from the Chinese cut.

SKILL.md                  the process: 9 stages, four checkpoints, quality bar
reference/                specs written for the main session and the agents
  style-guide.md            safe areas, palette, fonts, primitive catalogue, layout habits
  motion-vocabulary.md      entrance / emphasis / light / exit / camera formulas and frame counts
  composition-and-light.md  three size tiers, light follows the hero, set-piece choreography, QC metrics
  narration-storyboard.md   how to write narration, voiceover params, storyboard tokens, shot pattern table
  research-brief.md         researcher prompt and fact rules
  agent-build-rules.md      build-agent protocol
  agent-qc-rules.md         QC-agent protocol
  prompts.md                six prompt templates: research / build / QC / fix / recheck / final pass
  lessons.md                every trap hit across three films, with root causes
template/                 the compilable Remotion 4 project (copy it with scripts/new_project.sh)
  src/common/               fog, star field, dot-field wave, glitch, easings, subtitles, progress bar, footage layer
  src/ui.tsx  src/fx.tsx    primitives and palette / light, depth and camera primitives
  src/overlay/              title, chapter cards, HUD, pipeline rail, ending
  scripts/                  voiceover, storyboard, stills, test render, 30s preview, full render, QC metrics
  public/fonts/             four fonts + their OFL license
examples/rag/             the reference film's full paper trail and rendered frames
examples/contrast/        6 bad/good frame pairs — the yardstick for composition and light

The visual language and the quality bar are inspired by the Douyin creator @图灵宇宙 — black canvas, white line art with purple accents, ultra-bold headline type: that vocabulary was learned from their videos. Everything in this repo is drawn from scratch in code; none of their frames, assets or project files are used. If you feel this crosses a line, please open an issue.

• Every frame is drawn in code. No frames or clips from existing videos. Optional live-action B-roll must come from royalty-free sources and be logged in a MANIFEST (sha256 / source URL / license / usage).
• Every fact is sourced. Every number, year, organisation and English term shown on screen must trace back to a source URL in that film's research document. Anything unverified stays off the screen and out of the narration.

The toolkit: PolyForm Noncommercial 1.0.0 — free for noncommercial use; commercial use requires prior authorization from the author. Videos you make with it are yours. The four bundled fonts (Noto Sans SC / Orbitron / Exo 2 / Audiowide) are licensed separately under SIL OFL 1.1; see template/public/fonts/LICENSE.md. Remotion itself has its own license terms for companies — see remotion.dev/license.

• Chinese and English are both supported (lang: 'zh' | 'en'), each with its own pacing, subtitle budget (16 chars / 48 characters per block) and default voice. Both cuts are embedded above; the paper trail in examples/rag/ is from the Chinese cut. One visual style with two backdrops (bg: 'stars' | 'dots'); changing anything else means editing reference/style-guide.md + src/ui.tsx.
• Not for: replicating an existing video, talking-head presenter footage, or films that are mostly live action.
• Once the narration is voiced, the words are frozen — shot code hard-codes frame numbers, so a rewrite re-times everything.
• Parallel builds are demanding: several agents bundle Remotion at once, so keep ≥5 GB free; tmux panes are capped, so past ~12 you have to dispatch in waves.