Pinned

---
name: explainer-video
description: Turn any topic into a 3Blue1Brown-style animated explainer video (MP4) via a five-stage pipeline of factual grounding, scene-contract planning, Manim code generation, render plus visual-QA verification, and assembly. Works for ALL topics, whether mathematical (algorithms, physics, statistics), scientific, technical (architecture, networking), or fully general and humanities topics (history, policy comparisons, X-versus-Y questions, how-things-work). Use this skill whenever the user asks for an explainer video, animated explanation, educational video, a video like 3blue1brown, an animated lesson, or to turn a topic, lesson, or module into a video, even if they never say the word video but want an animated or visual walkthrough of a concept. Also use when a course-generation pipeline needs a video artifact for a lesson or module. Produces the full artifact set of scene_contracts.json, generated Manim Python source, per-scene MP4s, QA frames, and the final MP4.
---

# Explainer Video Pipeline

Transform a topic into a short (30–90s per module) animated explainer video with the
visual quality of a hand-crafted educational animation. The pipeline is five stages
with three verifier gates. Every stage emits an inspectable artifact, so a failed run
is debuggable and a partial run is resumable at scene granularity.

```
topic ─► [0 GROUND] ─► [1 PLAN] ─► [2.5 VOICE/TIMING] ─► [2 CODE] ─► [3 RENDER+VERIFY] ─► [4 ASSEMBLE+MUX]
              │              │            │               │                    │
        sources list   scene_contracts  scenes.py    per-scene MP4s        final.mp4
                           .json                     + QA frames           + artifacts
```

**Why scene-granular:** the scene is the unit of caching, retry, and cost control. A
failed scene re-renders alone; never re-roll the whole video for one broken scene.

## Stage 0 — Factual grounding (general topics; skip for pure formal topics)

If the narration will make empirical claims (numbers, rankings, "X is better than Y",
historical facts), gather grounded values FIRST, before planning. Use web search or
provided source documents. Record every key figure with its source. A wrong number in
a beautiful chart is the worst failure mode this pipeline has: it renders perfectly,
looks authoritative, and is silently false. Formal topics (an algorithm's mechanics, a
mathematical identity) self-verify and can skip this stage.

Output: a list of grounded claims that Stage 1 must embed in the contracts.

## Stage 1 — Plan: write scene_contracts.json

Read `references/contract-schema.md` for the exact schema, then write
`scene_contracts.json`. Key decisions made here (this stage sets the quality ceiling —
spend the thinking budget here, not in the code):

1. **Pick 3–5 scenes**, each 15–30 seconds. Standard arc:
   problem/hook → key insight → mechanism step-by-step → consequence/scale → verdict.
2. **Assign each scene a visual archetype** from `references/archetypes.md`. Read that
   file before planning — it is the taxonomy that makes this work for ANY topic, and
   it includes the selection heuristics. Never invent a free-form visual when an
   archetype fits; archetypes have known-good implementations.
3. **Write the narration per scene.** Narration is a contract field, not an
   afterthought — it drives TTS later and is what the factual gate audits.
4. **Attach `sources` per scene** listing which grounded claims (Stage 0) the scene's
   narration relies on. Write "framing only - no empirical claims" when true.
5. **Find the one inspired beat.** Competent-archetype output is the floor; one scene
   should have a move where the visual's *form* carries the argument (example that
   worked: a linear-scale bar chart where clean-energy bars "barely register" — the
   chart's limitation IS the point, then a zoom inset resolves it). If every scene is
   a generic template fill, revise the plan.

## Stage 2 — Code: generate the Manim file

Read `references/manim-patterns.md` BEFORE writing any code — it contains the
known-good patterns and, more importantly, the spatial pitfalls that caused every
defect in validation runs. The non-negotiables, because each one eliminated an entire
failure class:

- **Manim Community Edition** (`manim`), never manimgl.
- **No LaTeX anywhere.** Use `Text()` only — never `MathTex`/`Tex`/`Axes` with
  `include_numbers=True` (Axes numbers secretly invoke LaTeX). This removes the
  largest dependency and a whole hallucination surface. Hand-roll axes from `Line` +
  `Text` (pattern in the reference).
- **Style tokens from `assets/style_tokens.py`.** Copy it next to the scene file and
  import from it. Consistent palette/typography across all scenes of a course is what
  makes output feel designed rather than generated. Honor any user/project design
  system by editing the token values, not by scattering literals.
- One `Scene` subclass per contract scene, named after the contract `id`.
- Every scene ends by fading out all mobjects (clean concat boundaries), except a
  final closing card.
- Procedural vector assets only (tier-a): build turbines, machines, icons from
  primitives. **Any group that will rotate or orbit needs an explicit invisible
  anchor `Dot` at the pivot** — never rotate about `get_center()` of an asymmetric
  group (bounding-box center ≠ pivot; this detached a turbine's blades from its
  nacelle in validation).

## Stage 3 — Render + verify (two gates, both mandatory)

Use `scripts/render_and_qa.sh` (or replicate its steps): render each scene at `-qm`
(720p30) with `--disable_caching`, then extract QA frames.

**Gate A — render gate.** Per-scene render; on exception, read the stack trace, fix,
re-render that scene only. With the no-LaTeX + patterns discipline, expect near-100%
first-attempt success; repeated API errors mean you skipped the patterns reference.

**Gate B — visual QA gate (load-bearing — do not skip).** Logically-correct code
produces visually-broken output, and no stack trace catches it. Extract frames at
~30%, ~60%, and ~90% of each scene's duration and LOOK at every frame with vision.
Check against the full checklist in `references/qa-gates.md`. The defect classes that
actually occurred in validation, all spatial: labels drifting off their anchored
object during Transform; rotation about wrong pivot; content overflowing a container
*later in the scene* (compute max extent vs container BEFORE animating growth);
baselines/axes not spanning all their elements; text overlap. Fix with targeted
edits, re-render only affected scenes, re-extract, re-look. Iterate until clean.

**Gate C — factual gate (general topics).** Diff every number and comparative claim
in the rendered text and narration against Stage 0 sources. On-screen data displays
should carry a small source attribution.

## Stage 2.5 — Voice & timing resolution (when narrated output is wanted)

Read `references/narration-sync.md` BEFORE writing scene code for a narrated video —
it changes how Stage 2 code is written. The principle: **audio drives video, never
the reverse.** Synthesize (or estimate) narration durations first, write them to
`timing.json` via `scripts/narration.py`, and make every scene read its beat
durations from the manifest instead of hardcoding `run_time`/`wait`. Sync is then
deterministic by construction; "the voice explains what's on screen right now" stops
being an alignment problem.

- With ElevenLabs access (`ELEVENLABS_API_KEY`): `narration.py synthesize` — per-beat
  clips with prosody continuity, measured durations.
- Without: `narration.py estimate` — words-per-minute timing so the entire pipeline
  still runs voice-ready; swap in measured timings later and re-render (cheap,
  scene-granular, zero code edits).
- `narration.py mix` builds one `<SceneId>.wav` per scene (clips + computed
  silences); `assemble.sh` auto-muxes any wav whose stem matches a scene MP4.
- After muxing, run **Gate D (sync gate)** from `narration-sync.md`: frame at each
  beat's audio midpoint must show what that beat's words describe.

## Stage 4 — Assemble + deliver

Concat per-scene MP4s with `scripts/assemble.sh` (stream-copy; scenes share encoding.
If per-scene wavs exist, it muxes narration automatically). Deliver ALL artifacts to
the output directory:

1. `<topic_slug>.mp4` — final video (narrated if Stage 2.5 ran)
2. `scene_contracts.json` — the plan (this is what a course-builder harness consumes
   to regenerate, translate, or re-style)
3. `<topic_slug>_scenes.py` — generated Manim source (with `style_tokens.py` if used)
4. `timing.json` + per-beat audio (when Stage 2.5 ran) — the sync manifest a harness
   needs to re-voice or localize without re-planning

## Environment setup

Run `scripts/setup_env.sh` once per session. It installs pango/cairo dev libs and
Manim CE via pip. ffmpeg is usually preinstalled; the script checks. Setup dominates
wall-time; per-scene marginal cost after it is seconds.

## Calibration (from validated runs)

- 4 scenes ≈ 40s video ≈ 720p renders in ~3–6 min total on a basic container.
- Typical defect count at Gate B: 1–3 per video, all spatial, all fixable with one
  `str_replace`-scale edit each.
- If the user's harness passes a design system (colors, fonts), map it into
  `style_tokens.py` values at Stage 2 — everything downstream inherits it.

## Reference map

| When | Read |
|---|---|
| Before Stage 1 planning | `references/archetypes.md` |
| Before Stage 2 coding | `references/manim-patterns.md` |
| Contract field details | `references/contract-schema.md` |
| Running Gates A/B/C | `references/qa-gates.md` |
| Narrated video (TTS, sync, Gate D) | `references/narration-sync.md` |