Explainer videos and product demos made by your AI agent. Free and open source: a local voice (Kokoro), word timing (Whisper) and a canvas renderer turn a script into a narrated MP4.
JavaScript ai-agentsanimationcanvasclaude-codecodexexplainer-videoffmpegjavascriptkokoroproduct-demotext-to-speechvideo-generationwhisper
Polish the README: logo, a short explanation with how it works, the prompt in a wrapped block, looks, sizes and pace
Vincent Schmalbache11c620eaf12
diff --git a/README.md b/README.mdindex 4325e59..89469df 100644--- a/README.md+++ b/README.md@@ -1,30 +1,102 @@-# explainroo--## Point your AI agent (Claude Code, Codex, Pi and others) at this repo and tell it what video you want.--Copy this into your AI agent and put your topic in place of the brackets:+<p align="center">+ <a href="https://www.explainroo.com">+ <picture>+ <source media="(prefers-color-scheme: dark)" srcset="docs/media/logo-dark.png">+ <img src="docs/media/logo-light.png" alt="explainroo" width="340">+ </picture>+ </a>+</p>++<p align="center">+ <b>Explainer videos made by your AI agent.</b><br>+ Free and open source. The voice, the timing and the rendering all run on your computer.+</p>++<p align="center">+ <a href="https://www.explainroo.com">Website</a> · + <a href="https://www.explainroo.com/videos/">Example videos</a> · + <a href="https://www.explainroo.com/docs/">Docs</a> · + <a href="AGENTS.md">AGENTS.md</a>+</p>++<p align="center">+ <a href="https://www.explainroo.com/videos/how-explainroo-makes-a-video/">+ <img src="docs/media/intro.gif" alt="The explainroo intro video" width="720">+ </a>+ <br>+ <sub>A coding agent made this video with explainroo. <a href="https://www.explainroo.com/videos/how-explainroo-makes-a-video/">Watch it with sound</a>.</sub>+</p>++## Make a video++> [!TIP]+> **Point your AI agent at this repo and tell it what video you want.**+> It works with Claude Code, Codex, Pi and other coding agents. Right now it+> works best with Claude Code and Opus 5.5.++Copy this into your agent and put your topic in place of the brackets:```text-Make me a short explainer video about [your topic]. Use explainroo for it: clone https://github.com/vincentsch/explainroo, read its AGENTS.md and follow the steps.+Make me a short explainer video about [your topic].+Use explainroo for it: clone https://github.com/vincentsch/explainroo,+read its AGENTS.md and follow the steps.```-> Right now explainroo works best with Claude Code and Opus 5.5.--[](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4)--*This video explains explainroo, and a coding agent made it with explainroo-([watch it with sound](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4)).*--explainroo is a free, open source kit that coding agents use to make-narrated explainer videos. The agent writes the script and a bit of-JavaScript that draws the pictures. explainroo reads the script aloud with a-voice model on your computer, shows each picture when the voice mentions it,-adds music and sound effects, and saves an MP4. You don't need an API key,-unless you want AI images.--## Getting started--You need Node.js 20 or newer, ffmpeg, and Chrome or Chromium.+The agent clones explainroo, sets it up, writes the video and checks it. You+get an MP4.++## What explainroo does++You know those short videos where someone explains a topic while simple+drawings appear right when they are mentioned? explainroo lets a coding agent+make them, from the script to the last frame.++The agent writes two files. `script.md` holds the words the voice says.+`scenes.js` draws the pictures with a bit of JavaScript, and every drawing+can appear on a word from the script. explainroo does the rest:++- **The voice.** [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), an open+ voice model, reads the script aloud on your own computer. There are 28+ voices, and you don't need an account or an API key.+- **The timing.** [Whisper](https://github.com/openai/whisper) listens to the+ recording and notes when each word is spoken, so a picture shows up when the+ voice names it.+- **The pictures.** Chrome runs in the background and draws every frame on a+ canvas: hand-drawn lines with [Rough.js](https://roughjs.com), 1,800+ [Lucide](https://lucide.dev) icons, charts, code and your own screenshots.+- **The sound.** explainroo writes background music for each video, adds small+ sound effects, and turns the music down whenever the voice speaks.+- **The file.** ffmpeg puts it all together into an MP4 at the right loudness.++An agent can't watch a video, so explainroo gives it other ways to check its+work: still pictures of every scene, contact sheets, a layout check that finds+cut-off or overlapping text, and a speech check that catches words the voice+got wrong.++Nothing leaves your computer, and making a video costs nothing. The one+exception is optional: for how-to topics the agent can make illustrations+with an AI image model through OpenRouter, which you pay per image.++## Looks, sizes and pace++<p align="center">+ <img src="docs/media/looks.jpg" alt="The same diagram in the paper, clean, chalk, blueprint and midnight looks" width="720">+</p>++- **Five looks:** paper, clean, chalk, blueprint and midnight. The same video+ works in each of them.+- **A size for every platform:** YouTube, YouTube Shorts, TikTok, Instagram+ Reels, Instagram and LinkedIn feed posts, and square. On Shorts, TikTok and+ Reels, explainroo keeps text away from the buttons the app draws on top.+- **Pace:** set `pace` to 1.2 and the whole video gets 20% quicker, from the+ voice and the pauses to every animation.+- **Captions** that light up word by word, for vertical and square videos.++## Install it yourself++You need Node.js 20 or newer, ffmpeg, and Chrome or Chromium. The first setup+downloads the speech models once (about 400 MB). You don't need a graphics+card.```bashgit clone https://github.com/vincentsch/explainroo.git@@ -35,18 +107,14 @@ node bin/explainroo.js doctor --fetchThen start your agent in the `explainroo` folder and ask for a video, forexample "Make a 60 second video about how HTTPS keeps a password secret."-Everything the agent needs is in [AGENTS.md](AGENTS.md). The finished video-ends up in `videos/<name>/out/video.mp4`.--## More--- The full documentation and more videos made with explainroo:- [explainroo.com](https://www.explainroo.com)-- The source of three example videos: [examples/](examples/)+Everything the agent needs is in [AGENTS.md](AGENTS.md), and the finished video+ends up in `videos/<name>/out/video.mp4`. The source of three example videos+is in [examples/](examples/), and the full documentation is on+[explainroo.com](https://www.explainroo.com/docs/).## The watermark-Videos have a small "explainroo.com" in the corner. You can turn it off with+Videos have a small "explainroo.com" in a corner. You can turn it off with`"watermark": false` in the video's `video.json`. I'd ask you to keep it ifyou can. It helps other people find this free project, and that is the bestway to give something back.diff --git a/docs/media/logo-dark.png b/docs/media/logo-dark.pngnew file mode 100644index 0000000..47730c3Binary files /dev/null and b/docs/media/logo-dark.png differdiff --git a/docs/media/logo-light.png b/docs/media/logo-light.pngnew file mode 100644index 0000000..113862aBinary files /dev/null and b/docs/media/logo-light.png differ