explainer-video

AI skill that turns a topic into a fully animated, narrated explainer video. Runs locally. Free forever. Works with any AI coding agent.

---

You give your agent a topic. It writes a custom animation page, generates a free voiceover, records the page in a headless browser, and merges the audio in with ffmpeg. You get a finished MP4.

No API keys. No subscriptions. No watermarks.

Demo

The demo.mp4 in this repo was generated by the skill itself, using Claude Code.

# the entire build command:
node lib/pipeline.js --config config.json --out demo.mp4

Why this exists

Every other AI explainer video tool wants $30–$80/month and locks you into one visual style. This skill takes the opposite approach:

• The agent writes the visuals — fresh HTML/CSS/GSAP design for every topic, no templates
• The voiceover is free — uses Microsoft Edge’s neural TTS, no account needed
• Everything runs locally — no upload, no SaaS, no watermark
• One artifact — drop the folder into any agent’s skills directory and it just works

How it works

1. Agent writes the narration script (split into segments)
2. Agent writes a custom HTML animation page (GSAP + SVG)
3. Pipeline calls Microsoft Edge TTS per segment → MP3
4. Pipeline measures durations and exposes them to the page
5. Headless Chromium records the animation
6. ffmpeg muxes in the voiceover → final MP4

Each scene’s animation timing is driven by window.__SEGMENT_DURATIONS so the visuals stay locked to the narration — no manual sync.

Install

This skill follows the open SKILL.md spec and works with any agent that supports it.

Claude Code

git clone https://github.com/Mng-dev-ai/explainer-video.git \
  ~/.claude/skills/explainer-video

Restart your Claude Code session. Then say “make an explainer video about X” and the skill will trigger.

Codex CLI

git clone https://github.com/Mng-dev-ai/explainer-video.git \
  ~/.codex/skills/explainer-video

Restart Codex. Invoke explicitly with $explainer-video or describe the task and Codex will pick it.

Cursor

Cursor scopes skills per-project. Clone into the project where you want it:

git clone https://github.com/Mng-dev-ai/explainer-video.git \
  .cursor/skills/explainer-video

Then reload the window (Cmd/Ctrl+Shift+P → “Developer: Reload Window”).

Universal install (one location, all agents)

If you use multiple agents, install once in ~/.agents/skills/ and symlink from each agent dir:

git clone https://github.com/Mng-dev-ai/explainer-video.git \
  ~/.agents/skills/explainer-video

ln -s ../../.agents/skills/explainer-video ~/.claude/skills/explainer-video
ln -s ../../.agents/skills/explainer-video ~/.codex/skills/explainer-video

First-run setup

After cloning, install the Node dependencies:

cd ~/.agents/skills/explainer-video/lib   # or wherever you cloned it
npm install --silent

You also need ffmpeg on your PATH (brew install ffmpeg on macOS, apt install ffmpeg on Debian/Ubuntu, choco install ffmpeg on Windows).

Usage

Through your agent (recommended)

Just ask it:

“Make me an explainer video about how compound interest works.”

The agent will write the script, build the HTML, and run the pipeline — you get an MP4 path back.

Directly from the CLI

node lib/pipeline.js \
  --html /path/to/page.html \
  --script /path/to/script.txt \
  --voice brian \
  --out /path/to/output.mp4

Or with a single config JSON (recommended — supports per-segment audio):

{
  "title": "Quantum Computing",
  "voice": "brian",
  "html": "page.html",
  "scriptSegments": [
    "What if a computer could be in two places at once?",
    "That's not science fiction. It's quantum computing.",
    "..."
  ]
}

node lib/pipeline.js --config config.json --out video.mp4

Voices

Friendly names map to Azure neural voices via Edge TTS:

You can also pass any Azure neural voice ID directly (e.g. en-AU-NatashaNeural, es-ES-ElviraNeural).

The HTML contract

When the agent writes the animation page, it must:

1. Set viewport to 1280×720 (html, body { width: 1280px; height: 720px })
2. Load GSAP from jsdelivr
3. Read window.__AUDIO_DURATION (seconds, float) — the total narration length, injected by the pipeline
4. Optionally read window.__SEGMENT_DURATIONS — an array of per-segment durations (when scriptSegments is used) for frame-perfect sync
5. Set window.__done = true when the animation finishes

That’s the entire contract. Everything else — design, palette, animation language — is freshly invented per topic.

See examples/quantum.html for a reference page.

Caching

Voiceover MP3s are cached by sha256(voice + text) at ~/.cache/explainer-video/voice/.mp3. Re-running with the same script reuses the cached audio. Iterate freely on visuals without re-calling the TTS endpoint.

To use a pre-existing audio file (bypassing TTS entirely):

node lib/pipeline.js --html page.html --script script.txt --audio my-voice.mp3 --out video.mp4

Project structure

explainer-video/
├── SKILL.md            ← skill spec (agent reads this)
├── README.md           ← you are here
├── lib/
│   ├── pipeline.js     ← orchestrator CLI
│   ├── edge-tts.js     ← free TTS wrapper
│   ├── render.js       ← headless Chromium recording
│   └── package.json
└── examples/
    └── quantum.html    ← reference HTML page

Contributing

Issues and PRs welcome. Particularly interested in:

• More voice provider adapters (Piper, Coqui XTTS, OpenAI TTS, etc.)
• Vertical (9:16) rendering for TikTok/Shorts/Reels
• Background music support
• Additional reference examples for different topic categories

License

MIT — see LICENSE.