Skip to content

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.

README in plain words, product demos further down

Vincent Schmalbachd88f6bda217f
diff --git a/AGENTS.md b/AGENTS.md
index 999b7ef..e01f38d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -247,12 +247,12 @@ video.
## Product demos
-A product demo shows an app being used, like the launch videos software
-companies make. The app's screens are drawn again with `s.ui`: cards, fields,
-buttons, dropdowns, toggles and status pills that look like the real app. A
-cursor moves, clicks and types. The camera zooms in on what the voice talks
-about, and big headlines blur in word by word. See `examples/unspar-demo` for
-a full one.
+A product demo is the kind of video software companies make to show their
+app. You rebuild the app's screens with `s.ui`, which has cards, fields,
+buttons, dropdowns, toggles and status labels in the app's colors and fonts.
+A mouse pointer clicks through the screens and types into the fields, and the
+camera zooms in on what the voice talks about. `examples/unspar-demo` is a
+complete one.
**Keep it true.** A demo is advertising, so everything in it has to be right.
diff --git a/README.md b/README.md
index c2f2b67..6b8c7d6 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@
<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.
+ Free and open source. The voice, the timing and the rendering run on your computer.
</p>
<p align="center">
@@ -22,13 +22,13 @@
https://github.com/user-attachments/assets/6dd5dc32-c975-4e0e-8cd4-2ef3ccc11e61
<p align="center">
- <sub>A coding agent made this video with explainroo. It also plays on <a href="https://www.explainroo.com/videos/how-explainroo-makes-a-video/">explainroo.com</a>.</sub>
+ <sub>A coding agent made this video with explainroo. You can also watch it on <a href="https://www.explainroo.com/videos/how-explainroo-makes-a-video/">explainroo.com</a>.</sub>
</p>
## Make a video
> [!TIP]
-> **Point your AI agent at this repo and tell it what video you want.**
+> **Give your coding agent this repo and tell it what the video should explain.**
> It works with Claude Code, Codex, Pi and other coding agents. Right now it
> works best with Claude Code and Opus 5.5.
@@ -40,70 +40,45 @@ Use explainroo for it: clone https://github.com/vincentsch/explainroo,
read its AGENTS.md and follow the steps.
```
-The agent downloads explainroo, sets it up, writes the video and checks it.
-At the end you have an MP4 file.
+The agent sets up explainroo, makes the video and checks it. You get an MP4
+file.
-## What explainroo does
+## How does it work?
-explainroo is a free tool that lets a coding agent make explainer videos.
-Those are the short videos where a voice explains a topic and simple drawings
-show up while it speaks.
-
-The agent writes two files. `script.md` has the words the voice will say.
-`scenes.js` draws the pictures with a bit of JavaScript. Each drawing can be
-tied to a word in the script, so it shows up when the voice says that word.
+An explainer video is a short video where a voice explains a topic and
+drawings appear while it speaks. For explainroo, the agent writes two files.
+`script.md` has the words the voice says. `scenes.js` draws the pictures with
+a bit of JavaScript, and each drawing can appear on a word from the script.
explainroo does the rest:
-- **The voice.** [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) is an
- open voice model. It reads the script aloud on your own computer. You can
- pick from 28 voices. You don't need an account or an API key.
-- **The timing.** [Whisper](https://github.com/openai/whisper) listens to the
- recording and writes down when each word is spoken. That is how a picture
- shows up right when the voice names it.
-- **The pictures.** Chrome runs in the background and draws each frame of the
- video. It can draw lines that look hand drawn 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 and adds
- small sound effects. It turns the music down whenever the voice speaks.
-- **The file.** ffmpeg puts the voice, the pictures and the music together
- into an MP4 at the right loudness.
+- **Voice.** [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), an open
+ voice model, reads the script aloud. It has 28 voices and needs no account
+ or API key.
+- **Timing.** [Whisper](https://github.com/openai/whisper) listens to the
+ recording and notes when each word is spoken.
+- **Pictures.** Chrome runs in the background and draws the frames. The lines
+ can look hand drawn ([Rough.js](https://roughjs.com)), and there are 1,800
+ icons from [Lucide](https://lucide.dev). A scene can also show charts, code
+ or your own screenshots.
+- **Sound.** explainroo makes its own background music for each video and
+ adds small sound effects. The music gets quieter while the voice speaks.
+- **File.** ffmpeg puts it all together into an MP4.
An agent can't watch a video, so explainroo gives it other ways to check its
-work. It can save a still picture of each scene. It can make a sheet of small
-frames that shows how the video moves along. A layout check finds text that
-is cut off or sits on top of something else. A speech check catches words the
-voice got wrong.
-
-explainroo's own part runs on your computer. The voice, the timing and the
-drawing of the frames send nothing anywhere and cost nothing. Your coding
-agent is a separate service with its own terms and costs. For how-to topics
-the agent can also make illustrations with an AI image model through
-OpenRouter. That is optional, and you pay per image.
-
-## Product demos
-
-explainroo can also make launch videos for software. The agent draws the
-app's screens again, in the product's own colors, fonts and wording. A cursor
-clicks and types through them while the voice explains what is happening.
-Tell your agent which product it is and where its code or website is.
-
-<p align="center">
- <a href="https://www.explainroo.com/videos/unspar-product-demo/">
- <img src="docs/media/product-demo.webp" alt="A frame from the Unspar product demo: a form with a website field and an open dropdown" width="820">
- </a>
-</p>
+work. It saves stills of the scenes and a sheet of small frames for the whole
+video. A layout check finds text that is cut off or overlaps, and a speech
+check finds words the voice got wrong.
-[Watch the Unspar demo](https://www.explainroo.com/videos/unspar-product-demo/)
-or the [Vroni demo](https://www.explainroo.com/videos/vroni-product-demo/).
-The files for the Unspar demo are in
-[examples/unspar-demo](examples/unspar-demo).
+None of this leaves your computer, and it costs nothing. Your coding agent is
+a separate service with its own terms and prices. If you want, the agent can
+also make illustrations with an AI image model through OpenRouter, and you pay
+for each image.
## Looks
-There are five looks: paper, clean, chalk, blueprint and midnight. These are
-frames from example videos, one in each look. The same video works in any of
-them.
+There are five looks: paper, clean, chalk, blueprint and midnight. You change
+a video's look with one setting in `video.json`. Here is one frame in each
+look, from the example videos.
<p align="center">
<picture>
@@ -114,10 +89,10 @@ them.
## Sizes
-Each video gets the size of the place it goes. There are sizes for YouTube,
-YouTube Shorts, TikTok, Instagram Reels, Instagram and LinkedIn feed posts,
-and a square one. On Shorts, TikTok and Reels, explainroo keeps the text away
-from the buttons the app puts on top of the video.
+You pick the size for the place the video goes. YouTube videos are wide, and
+Shorts, TikTok and Reels are tall. Instagram and LinkedIn posts use 4:5, and
+there is a square size too. Shorts, TikTok and Reels put their own buttons
+over the video, and explainroo keeps your text out of those spots.
<p align="center">
<picture>
@@ -126,24 +101,40 @@ from the buttons the app puts on top of the video.
</picture>
</p>
-Vertical, 4:5 and square videos also get captions that light up word by word,
-because many people watch those with the sound off.
+Tall, 4:5 and square videos get captions that light up word by word.
## Pace
-Pace makes the whole video quicker or slower. Set `"pace": 1.2` in the
-video's `video.json` and everything gets 20% quicker: the voice, the pauses
-and each animation. The music speeds up a little too. Pace goes from 0.7 to
-1.6, and 1 is normal.
+`"pace": 1.2` in a video's `video.json` makes the voice, the pauses and the
+animations 20% quicker. The music gets a little quicker too. Pace goes from
+0.7 to 1.6, and 1 is normal.
+
+## Product demos
+
+explainroo can also make product demos, the videos software companies make to
+show their app. The agent rebuilds the app's screens from its code or its
+website, with the same colors, fonts and button labels. A mouse pointer then
+clicks through the screens and types into the fields. Tell your agent which
+product it is and where to find its code or website.
+
+<p align="center">
+ <a href="https://www.explainroo.com/videos/unspar-product-demo/">
+ <img src="docs/media/product-demo.webp" alt="A frame from the Unspar product demo: a form with a website field and an open dropdown" width="820">
+ </a>
+</p>
+
+Here are the demos for [Unspar](https://www.explainroo.com/videos/unspar-product-demo/)
+and [Vroni](https://www.explainroo.com/videos/vroni-product-demo/), two of my
+own products. The files for the Unspar demo are in
+[examples/unspar-demo](examples/unspar-demo). explainroo.com also has
+unofficial demos of [Gmail, ChatGPT and Claude](https://www.explainroo.com/videos/#product-demos).
## Install it yourself
-You need three things on your computer. Node.js 20.11 or newer runs
-explainroo. ffmpeg builds the video file. Chrome or Chromium draws the
-pictures. The first setup downloads the voice model and the word timing model
-once, about 400 MB together. You don't need a graphics card. I develop and
-test explainroo on Linux. It should work on macOS and Windows too, but I have
-tested it less there so far.
+You need Node.js 20.11 or newer, ffmpeg, and Chrome or Chromium. The first
+setup downloads the voice and timing models once, about 400 MB together. You
+don't need a graphics card. I develop and test explainroo on Linux. It should
+work on macOS and Windows, but I have tested it less there.
```bash
git clone https://github.com/vincentsch/explainroo.git
@@ -153,27 +144,25 @@ node bin/explainroo.js doctor --fetch
```
Then start your agent in the `explainroo` folder and ask for a video, for
-example "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`. The files for the example videos
-are in [examples/](examples/). The full documentation is on
+example "Make a 60 second video about how HTTPS keeps a password secret." The
+agent follows [AGENTS.md](AGENTS.md) and saves the video as
+`videos/<name>/out/video.mp4`. The example videos are in
+[examples/](examples/), and the full documentation is on
[explainroo.com](https://www.explainroo.com/docs/).
## The watermark
-Each video has a small "explainroo.com" in one corner. You can turn it off
-with `"watermark": false` in the video's `video.json`. I'd ask you to keep it
-if you can. It helps other people find this free project, and that is the
-best way to give something back.
+Each video has a small "explainroo.com" in one corner. `"watermark": false` in
+`video.json` turns it off. Please keep it if you can, because that is how
+other people find explainroo.
## Credits and license
-The voice comes from [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M).
-The word timing comes from [Whisper](https://github.com/openai/whisper),
-which runs through
+explainroo is MIT licensed. The voice comes from
+[Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), and the word timing from
+[Whisper](https://github.com/openai/whisper) through
[Transformers.js](https://github.com/huggingface/transformers.js). The
drawings use [Rough.js](https://roughjs.com) and [Lucide](https://lucide.dev)
-icons. [Playwright](https://playwright.dev) runs Chrome in the background.
-The fonts are under the SIL Open Font License, and
-[ffmpeg](https://ffmpeg.org) makes the video file. explainroo itself is MIT
-licensed.
+icons. [Playwright](https://playwright.dev) runs Chrome, and
+[ffmpeg](https://ffmpeg.org) makes the video file. The fonts are under the SIL
+Open Font License.