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.

Release 0.2.0 (#21)

Vincent Schmalbach640a50853cc8
diff --git a/AGENTS.md b/AGENTS.md
index 70c8429..8e65d17 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -38,7 +38,8 @@ node bin/explainroo.js doctor --fetch
English speech models, about 400 MB, the first time only. Other languages
fetch their speech check model on first use. If the user ran `npm link`, you
can write `explainroo` instead of `node bin/explainroo.js` in the commands
-below. Every command takes the project folder first and accepts `--json`.
+below. Commands that work on a video take the project folder first, and every
+command accepts `--json`.
### When to ask the user
@@ -979,6 +980,10 @@ s.path('M0 0 C 200 -150 400 150 600 0', { x: 660, y: 540, at: 3 });
(hand-drawn looks: `solid`, `hachure`, `cross-hatch`, `zigzag`, `dots`).
`s.circle({ r, label })` takes the same options.
+`s.line(points, options)` and `s.path(d, options)` take `color`, `width`,
+`dashed`, `fill` and `glow`. `s.path` also takes `fillStyle`, and
+`single: true` draws a hand-drawn path with one stroke instead of two.
+
`s.arrow(from, to, options)` draws an arrow. `from` and `to` are `[x, y]`,
`{ x, y }` or the `id` of an element drawn earlier. With an `id`, the arrow
stops at the edge of that element. Options: `bend` (about -1 to 1), `head`
@@ -1027,6 +1032,10 @@ Frames are extracted once at the project's fps and saved in `build/clips/`.
They are at most 1920 pixels wide. Renders, stills and sheets use these
frames. The preview may show a nearby frame while the right one loads.
`s.video` still holds the whole video's duration, frames, fps and size.
+Playback starts at `at`, so `at: -1` starts a clip one second into it. To
+show a clip from its first frame when the scene starts, use
+`at: 0, enter: 'none'`. `check` cannot read text inside a clip, so look at
+stills of those moments.
### Pointing things out
@@ -1112,7 +1121,8 @@ or `{ out, at, color }`. Options: `w`, `size`, `rows`, `title`, `prompt`,
set of elements together. Inside the group, positions count from `x`, `y`.
- `s.draw({ x, y, at, out }, (ctx, life) => { ... })` gives you the canvas 2D
context, so you can draw anything the other methods cannot. `life.p` is the
- entrance progress from 0 to 1. `s.ctx` is also available.
+ entrance progress from 0 to 1, and `life.local` the seconds since `at`, for
+ motion that keeps going. `s.ctx` is also available.
- `s.burst({ x, y, at, count, colors })` fires confetti.
- `s.bg(color)` paints over the background.
- `s.rand(i)`, `s.noise(x)` and `s.wiggle(amount, speed)` give random values
diff --git a/README.md b/README.md
index 90045b0..e6eacec 100644
--- a/README.md
+++ b/README.md
@@ -52,17 +52,21 @@ a bit of JavaScript, and each drawing can appear on a word from the script.
explainroo does the rest:
- **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.
+ voice model, reads the script aloud in English, Spanish, French, Italian,
+ Brazilian Portuguese or Hindi. It has 41 voices and needs no account or API
+ key. You can also use an [ElevenLabs](https://elevenlabs.io) voice or
+ record the narration yourself.
- **Timing.** [Whisper](https://github.com/openai/whisper) listens to the
- recording and notes when each word is spoken.
+ narration 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.
+ icons from [Lucide](https://lucide.dev). A scene can also show charts, math
+ formulas, code that changes step by step, your own screenshots and video
+ clips such as screen recordings.
- **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.
+- **File.** ffmpeg puts it all together into an MP4, with subtitle files,
+ YouTube chapters and a cover image.
An agent can't watch a video, so explainroo gives it other ways to check its
work. It saves stills of the scenes and a sheet of small frames for the whole
@@ -78,8 +82,9 @@ for each image.
## Looks
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.
+a video's look with one setting in `video.json`. A project can also bring its
+own look, a small JSON file with its colors, fonts and background. Here is one
+frame in each built-in look, from the example videos.
<p align="center">
<picture>
@@ -102,7 +107,19 @@ over the video, and explainroo keeps your text out of those spots.
</picture>
</p>
-Tall, 4:5 and square videos get captions that light up word by word.
+Tall, 4:5 and square videos get captions that light up word by word. One
+project can render several sizes: `explainroo render videos/demo --size tiktok`
+writes the TikTok version next to the wide one.
+
+## More than an MP4
+
+Every render also writes subtitle files (`.srt` and `.vtt`) that YouTube and
+LinkedIn accept, a cover image for the thumbnail, and YouTube chapters when
+the script names them. `--format gif` makes a GIF for a README or a post.
+`--transparent --format mov` makes a video with a transparent background, for
+putting a diagram over camera footage in a video editor. `explainroo export`
+writes a small web player that draws the video sharp at any size and embeds
+with an iframe.
## Pace
@@ -116,7 +133,9 @@ 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.
+product it is and where to find its code or website. `explainroo capture`
+saves the live site's screenshots, colors, fonts, logo and wording first, and
+a real screen recording can play inside a scene too.
<p align="center">
<a href="https://www.explainroo.com/videos/unspar-product-demo/">
@@ -144,6 +163,10 @@ npm install
node bin/explainroo.js doctor --fetch
```
+For narration in Spanish, French, Italian, Portuguese or Hindi, also install
+[espeak-ng](https://github.com/espeak-ng/espeak-ng), for example with
+`sudo apt install espeak-ng` or `brew install espeak-ng`.
+
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." The
agent follows [AGENTS.md](AGENTS.md) and saves the video as
@@ -164,6 +187,10 @@ explainroo is MIT licensed. The voice comes 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, and
-[ffmpeg](https://ffmpeg.org) makes the video file. The fonts are under the SIL
-Open Font License.
+icons. [MathJax](https://www.mathjax.org) typesets the formulas.
+[Playwright](https://playwright.dev) runs Chrome, and
+[ffmpeg](https://ffmpeg.org) makes the video file. For other languages,
+explainroo runs [espeak-ng](https://github.com/espeak-ng/espeak-ng) as a
+separate program, with phoneme rules from Kokoro's
+[misaki](https://github.com/hexgrad/misaki). The fonts are under the SIL Open
+Font License.
diff --git a/package-lock.json b/package-lock.json
index 653b202..67f3cab 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "explainroo",
- "version": "0.1.1",
+ "version": "0.2.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "explainroo",
- "version": "0.1.1",
+ "version": "0.2.0",
"license": "MIT",
"dependencies": {
"@huggingface/transformers": "3.8.1",
diff --git a/package.json b/package.json
index 1273ab6..6a77847 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "explainroo",
- "version": "0.1.1",
+ "version": "0.2.0",
"description": "Narrated explainer videos made by your coding agent. Pure JavaScript, local voice, no API keys.",
"keywords": [
"video",