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.

Watermark on by default, optional OpenRouter images, card frame, and docs merged into a humanized AGENTS.md with a short README

Vincent Schmalbach30b4eecd3233
diff --git a/.gitignore b/.gitignore
index b958f11..24214f4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ build/
out/
.cache/
.scratch/
+.env
diff --git a/AGENTS.md b/AGENTS.md
index 7eaff70..bc271d5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,203 +1,550 @@
-# explainroo: guide for coding agents
+# explainroo for coding agents
-You are in the explainroo repository. It turns a narration script and a small
-JavaScript file into a narrated explainer video (MP4). You write the script
-and the scenes; explainroo speaks the narration with a local voice model,
-times every word, draws the frames in headless Chrome, generates music and
-sound effects, and encodes the video. No API keys and no video models are
-involved.
+This file tells you, the coding agent, how to make a video with explainroo.
+The user usually gives you a topic and maybe a length or a style. You write
+the words and the pictures, explainroo does the rest.
-Read this file once, then keep [docs/api.md](docs/api.md) open while you write
-scenes.
+explainroo turns two files into a narrated MP4. `script.md` holds what the
+voice says. `scenes.js` draws what the viewer sees, and every drawing can
+appear on a word the voice says. A voice model (Kokoro) reads the script on
+this computer, and Whisper writes down when each word is spoken. Chrome draws
+the frames in the background, explainroo adds music and sound effects, and
+ffmpeg makes the MP4. No API key is needed unless the user wants AI images.
-## Setup
+The full documentation for people is at https://explainroo.com/docs/.
+
+## Before you start
+
+Run this once in the explainroo folder:
```bash
npm install
-node bin/explainroo.js doctor --fetch # checks ffmpeg and Chrome, downloads the speech models (~400 MB once)
+node bin/explainroo.js doctor --fetch
```
-`node bin/explainroo.js` is the CLI (or `explainroo` after `npm link`). Every
-command takes the project folder as its first argument and accepts `--json`.
+`doctor` checks Node, ffmpeg and Chrome and downloads the speech models
+(about 400 MB, only the first time). In the commands below,
+`node bin/explainroo.js` can also be `explainroo` if the user ran `npm link`.
+Every command takes the project folder first and accepts `--json`.
+
+### When to ask the user
-## The workflow
+Decide the normal things yourself: the look, the length, the voice, the
+layout, the wording. Ask only when you cannot go on without an answer, and ask
+everything you need in one message. Typical reasons to ask:
-When the user asks for a video, create a project under `videos/` (it is
-ignored by git) and work through these steps in order. Do not skip the
-checks: you cannot watch the video, so stills, sheets and the check reports
-are your eyes and ears.
+- The topic is unclear, or you need a fact you cannot check.
+- The user wants AI images and there is no OpenRouter key (see Images).
+- The user wants something explainroo cannot do, like real video footage.
-1. **Understand the subject.** Read the code, docs or pages the user points
- to. Collect the facts you will state. Never invent numbers, quotes or
- claims; if a number matters and you cannot verify it, leave it out.
+## Making a video, step by step
+
+1. **Learn the subject.** Read the code, docs or pages the user points to.
+ Write down the facts you will use. Never make up numbers, quotes or claims.
+ If a number matters and you cannot check it, leave it out.
2. **Create the project.**
```bash
- node bin/explainroo.js init videos/<slug> --theme paper --title "..."
+ node bin/explainroo.js init videos/<name> --theme paper --title "..."
```
- Pick the theme for the audience: `paper` (friendly, hand-drawn, the
- default), `clean` (product and business), `chalk` (teaching), `blueprint`
- (engineering, systems), `midnight` (developer tools). Use `--size 9:16` for
- Shorts, Reels and TikTok.
-
-3. **Write `script.md` first.** The narration drives everything else.
- - Aim for 45 to 120 seconds unless the user asks otherwise. At the default
- speed a finished video carries about 150 words a minute, pauses
- included.
- - Structure: a hook that poses the question or problem, the explanation in
- small steps, one concrete example, then a short payoff line.
- - One idea per scene, usually 1 to 3 sentences (4 to 15 seconds).
- - Write for the ear: short sentences, plain words, no parentheses, no
- lists read aloud as "A, B, C, D and E" unless each one appears on screen.
- - Write the way you would explain it to someone at a table. Say who does
- what ("Whisper listens to the recording"). Every sentence adds a fact.
- - Leave out slogans and punchlines ("Just code."), "not X, but Y" twists,
- colon lists, chains of three short sentences, metaphors, and filler words
- like "just", "simply", "really" and "exactly". Cut half sentences that
- repeat what was already said.
- - Put `[#marker]` where a visual should change. Every sentence should
- trigger at least one visual.
- - Use `{shown|spoken}` for anything the voice might misread: acronyms
- (`{SQL|sequel}`, `{CLI|C L I}`), versions (`{v2.1|version two point one}`),
- symbols, domains (`{example.com|example dot com}`, the voice otherwise
- says "example comm") and URLs.
-
-4. **Generate the voice and read the report.**
+ Projects go in `videos/`, which git ignores. Pick the look for the
+ audience: `paper` (friendly, hand drawn, the default), `clean` (products
+ and business), `chalk` (teaching), `blueprint` (engineering), `midnight`
+ (developer tools). Add `--size 9:16` for Shorts, Reels and TikTok.
+
+3. **Write `script.md`.** The narration comes first and sets the timing for
+ everything else. See "How to write the narration" below.
+
+4. **Make the voice.**
```bash
- node bin/explainroo.js voice videos/<slug>
+ node bin/explainroo.js voice videos/<name>
```
- It prints each scene's length and how many words the speech check
- confirmed. Anything under 100% names the words it could not confirm: fix
- them with `{shown|spoken}` and run it again. Only changed scenes are
- regenerated.
+ It prints how long each scene is and how many words the speech check
+ confirmed. If a word is not confirmed, the voice probably said it wrong.
+ Fix it with `{shown|spoken}` in the script and run the command again. Only
+ changed scenes are made again.
-5. **Plan each scene** before coding it: what is on screen when each marker
- or key word is spoken, where it sits, and what leaves. Keep the layout
- consistent from scene to scene.
+5. **Plan the pictures.** For each scene, decide what is on screen when each
+ marker or important word is spoken, where it sits, and what leaves. Keep
+ things in the same place from scene to scene.
-6. **Write `scenes.js`.** One function per scene id. Tie every reveal to the
- narration with `at: 'word'` or `at: '#marker'`. See [docs/api.md](docs/api.md).
+6. **Make images, if the video needs them.** Icons and diagrams cover most
+ technical topics. For everyday how-to topics (cooking, cars, gardening)
+ pictures work better. See "Images" below.
-7. **Check.**
+7. **Write `scenes.js`.** One function per scene. Tie every picture to the
+ narration with `at: 'word'` or `at: '#marker'`. The scene API is at the
+ end of this file.
+
+8. **Check.**
```bash
- node bin/explainroo.js check videos/<slug>
+ node bin/explainroo.js check videos/<name>
```
- Fix every error and every warning. Hints are judgment calls.
+ Fix every error and every warning. Hints are your call.
-8. **Look at the frames.** This is the step that makes the video good.
+9. **Look at the frames.** You cannot watch the video, so this is how you see
+ it.
```bash
- node bin/explainroo.js still videos/<slug> # the end of every scene
- node bin/explainroo.js still videos/<slug> [email protected] 12.0 # any moment
- node bin/explainroo.js sheet videos/<slug> --scene intro # one scene over time
- node bin/explainroo.js sheet videos/<slug> # the whole video
+ node bin/explainroo.js still videos/<name> # the end of each scene
+ node bin/explainroo.js still videos/<name> [email protected] 12.0 # any moment
+ node bin/explainroo.js sheet videos/<name> --scene intro # one scene over time
+ node bin/explainroo.js sheet videos/<name> # the whole video
```
- Open the PNG and JPG files and look at them critically: Is the text large
- and readable? Is anything cut off, overlapping or crammed into a corner? Is
- the frame balanced, or is half of it empty? Does each scene look finished at
- its end? Does the sheet show something new every few seconds? Fix and look
- again until you would be happy to publish it.
-
-9. **Render and verify.**
+ Open the images and judge them like a viewer. Is the text big enough? Is
+ anything cut off or on top of something else? Is half the frame empty?
+ Does the sheet show something new every few seconds? Fix it and look
+ again.
+
+10. **Render and verify.**
+
+ ```bash
+ node bin/explainroo.js render videos/<name> --draft # quick half-size version
+ node bin/explainroo.js render videos/<name> # final video
+ node bin/explainroo.js verify videos/<name>
+ ```
+
+ `verify` measures the loudness, looks for black frames and silence, and
+ listens to the final mix to make sure the voice is still clear over the
+ music.
+
+11. **Tell the user** where `out/video.mp4` is, how long it is, what verify
+ said, and what you could not check.
+
+## How to write the narration
+
+Unless the user asks for another style, write the way a person explains
+something to a friend at a table.
+
+- Use regular, down-to-earth English and everyday words. Explain things in
+ simple terms. If you need a technical word, say what it means the first
+ time.
+- Keep sentences short, about 8 to 18 words, one idea each.
+- Say who does what: "The browser asks a resolver."
+- Every sentence adds a fact. Cut half sentences that repeat something.
+- Do not use em dashes or dashes between phrases. Use a comma or a new
+ sentence.
+- Leave out slogans and punchlines ("Just code."), "not X, but Y" twists,
+ colon reveals, chains of three short sentences, metaphors, and filler words
+ like "just", "simply", "really", "actually" and "exactly".
+- Do not tell the viewer to do obvious things ("Let's dive in", "Stay tuned").
+- End with a plain sentence that sums up the main point.
+
+Length and pace:
+
+- Aim for 45 to 120 seconds unless the user says otherwise. A finished video
+ carries about 150 words a minute, pauses included.
+- Start with the question or problem, explain it in small steps, give one
+ concrete example, then sum up.
+- One idea per scene, usually 1 to 3 sentences (4 to 15 seconds).
+- Lists read aloud ("A, B, C and D") only work when each item appears on
+ screen.
+
+Script syntax:
+
+```markdown
+# Title of the video
+
+## scene-id {hold=1.5}
+Narration for this scene. [#marker] A marker names a moment you can animate on.
+[pause 0.6] adds silence. {SQL|sequel} shows "SQL" in captions but says "sequel".
+> Lines starting with > are notes for you and are not spoken.
+```
- ```bash
- node bin/explainroo.js render videos/<slug> --draft # fast half-size check
- node bin/explainroo.js render videos/<slug> # final 1080p
- node bin/explainroo.js verify videos/<slug>
- ```
+- `## scene-id` starts a scene. The id must match a function in `scenes.js`.
+- Put a `[#marker]` wherever a picture should change. Every sentence should
+ trigger at least one picture.
+- Use `{shown|spoken}` for anything the voice may misread: acronyms
+ (`{CLI|C L I}`), versions (`{v2.1|version two point one}`), symbols and
+ domains (`{example.com|example dot com}`, otherwise the voice says "example
+ comm").
+- Scene attributes: `hold` (seconds after the voice, default 0.7), `min`
+ (minimum length), `lead` (seconds before the voice, default 0.35),
+ `transition` (`fade`, `slide`, `wipe`, `zoom`, `brush`, `cut`).
+- A scene without narration lasts `min` seconds (default 3).
+
+## What makes the pictures good
+
+- **Show it when it is said.** A picture appears as the voice mentions it.
+ Use word cues.
+- **Something changes every 2 to 4 seconds**: a new element, an arrow, a
+ highlight or a camera move. `check` points out long still stretches.
+- **Short screen text.** Labels, numbers and key phrases of a few words. The
+ whole narration never goes on screen. For that, turn on captions
+ (`"captions": true`), and then do not also show the sentence the voice is
+ saying.
+- **Few things at once.** At most five or six elements. Clear the stage with
+ `out` before the next idea.
+- **Big and readable.** Titles 80 to 110 px, labels 40 to 56 px, small text
+ at least 32 px on a 1920 x 1080 canvas. Stay inside `s.safe`.
+- **Same meaning, same color.** Give each thing one color and one place and
+ keep them. Use the accent color for the one thing that matters most.
+- **Real examples.** A real command, a real number with its source or a real
+ screen is better than three boxes with general words.
+- **A clear last frame** that shows the main point.
+
+## Images
+
+explainroo can make illustrations with AI image models through OpenRouter.
+This is optional and costs money on the user's OpenRouter account, roughly 7
+to 13 cents per image at the time of writing.
+
+If the user wants images and there is no key, ask them for an OpenRouter API
+key (from openrouter.ai/keys). Save it in a `.env` file in the explainroo
+folder as `OPENROUTER_API_KEY=...`, or use an environment variable. Git
+ignores `.env`. Never print the key or put it in a script, a commit or a log.
- `verify` measures loudness, looks for black frames and silence, and
- transcribes the final mix to confirm the narration is understandable over
- the music. Fix what it reports.
+```bash
+node bin/explainroo.js image videos/<name> cables "Two cars parked nose to nose with their hoods open, jumper cables between the batteries"
+node bin/explainroo.js images videos/<name> # what was made and what it cost
+```
-10. **Report back** with the path to `out/video.mp4`, its length, and the
- verify summary. Mention anything you could not verify.
+This saves `assets/cables.png`. Use it in a scene with
+`s.image('assets/cables.png', { w: 1100, frame: 'card', at: 'cables' })`.
-## What makes an explainer good
+- `--model best` (default) uses OpenAI GPT Image 2. It does what you ask and
+ is worth the price for most images.
+- `--model cheap` uses Google Gemini 3.1 Flash Image. It costs about half,
+ but often ignores parts of the prompt.
+- `--aspect 16:9` (default for landscape videos), `9:16`, `1:1`, `4:3`,
+ `3:2` and their portrait forms.
+- `--ref assets/a.png` sends an earlier image along, so a person or object
+ keeps the same look. Several files are separated by commas.
+- Every image gets a default style (flat, soft colors, no text). Set your own
+ in `video.json` with `"images": { "style": "...", "model": "best" }`, or
+ leave it off with `--no-style`.
-- **Show, then say.** The visual for an idea appears as the narrator says it,
- not before and not five seconds later. Use word cues.
-- **Something changes every 2 to 4 seconds**: a new element, an arrow, a
- highlight, a camera move. `check` flags long static stretches.
-- **Screen text summarizes.** Keep on-screen text to a few words (a label,
- a number, a key phrase). Never put the whole narration on screen; turn on
- captions instead (`"captions": true`). With captions on, do not also show
- the sentence the voice is saying.
-- **Few things at once.** At most five or six elements on screen. Clear the
- stage with `out` before building the next idea.
-- **Big and readable.** Titles 80 to 110px, labels 40 to 56px, notes at least
- 32px on a 1920x1080 canvas. Stay inside `s.safe`.
-- **Consistent meaning.** Give each actor one color and one position and keep
- them across scenes. Use the accent color for the one thing that matters most.
-- **Concrete over abstract.** One real example (a real command, a real number
- with its source, a real screen) beats three generic boxes.
-- **End on the takeaway**: one sentence and one clear final frame.
+**Always open every image and check it.** Image models get details wrong:
+extra fingers, cables on the wrong terminal, text that looks like writing but
+is not. If anything is wrong, change the prompt and make it again. Keep text
+out of images and put words on screen with `s.text` instead. Use images for
+things icons cannot show, and keep one style through the whole video.
-## Things that break
+## The watermark
-- Calling elements conditionally (`if (s.t > 3) s.box(...)`). Always call
- them and use `at` and `out`; sound effects and checks depend on it.
-- Cue words that are not spoken exactly as written (`at: 'DNS'` when the
- narration says `{DNS|D N S}` is fine; cues use the shown text).
-- Arrows or annotations that refer to an `id` drawn later in the function.
-- `s.camera()` called after other elements; it must come first.
-- `at` times later than the end of the scene; the element never appears.
- Lengthen the scene with `{hold=2}` or `{min=6}` in `script.md` instead.
-- Randomness from anything other than `s.rand()`, `s.noise()` or
- `Math.random()` inside the scene function.
+Every video gets a small "explainroo.com" in the bottom right corner. The
+user can turn it off with `"watermark": false` in `video.json`, or change it
+to their own text. If the user asks about it, tell them it is their choice,
+and that keeping it helps more people find this free project.
-## Project files
+## Project files and settings
```
-videos/<slug>/
- video.json theme, size, voice, music, captions (see below)
- script.md narration, one "## scene-id" per scene
+videos/<name>/
+ video.json look, size, voice, music, captions, watermark
+ script.md the narration, one "## scene-id" per scene
scenes.js one drawing function per scene
- assets/ your images (screenshots, logos)
- build/ generated voice, timeline and audio (safe to delete)
+ assets/ images: screenshots, logos, generated illustrations
+ build/ voice, timing and audio made by explainroo (safe to delete)
out/ video.mp4, draft.mp4, stills/, sheets, report.json
```
-`video.json` settings (all optional):
+`video.json` settings, all optional:
-| Setting | Default | Meaning |
+| Setting | Default | What it does |
|---|---|---|
-| `title` | script title | used in the preview |
+| `title` | from the script | shown in the preview |
| `theme` | `paper` | `paper`, `clean`, `chalk`, `blueprint`, `midnight` |
| `size` | `16:9` | `16:9`, `9:16`, `1:1`, `4:5` or `WIDTHxHEIGHT` |
| `fps` | 30 | 24, 25, 30, 50 or 60 |
-| `voice` | `af_heart` | run `explainroo voices` |
-| `speed` | 0.9 | 0.6 to 1.6 (voice speed) |
-| `music` | `true` | `true` (theme style), a style name, `{ "style", "volume" }` or `false` |
-| `sfx` | `true` | `true`, `"minimal"` or `false` |
-| `captions` | `"auto"` | burned-in captions; auto means on for vertical and square videos |
-| `transition` | `"auto"` | theme default, or `fade`, `slide`, `wipe`, `zoom`, `brush`, `cut` |
-| `lead`, `hold`, `end` | 0.35, 0.7, 1.4 | seconds before narration, after it, and extra at the very end |
+| `voice` | `af_heart` | see `explainroo voices` |
+| `speed` | 0.9 | voice speed, 0.6 to 1.6 |
+| `music` | `true` | `true` (the look's style), `warm`, `upbeat`, `calm`, `tech`, `playful`, `{ "style", "volume" }` or `false` |
+| `sfx` | `true` | sound effects: `true`, `"minimal"` or `false` |
+| `captions` | `"auto"` | text of the narration at the bottom; auto turns it on for vertical and square videos |
+| `transition` | `"auto"` | the look's default, or `fade`, `slide`, `wipe`, `zoom`, `brush`, `cut` |
+| `lead`, `hold`, `end` | 0.35, 0.7, 1.4 | seconds before the voice, after it, and extra at the very end |
| `sentenceGap`, `paragraphGap` | 0.3, 0.55 | pauses in the narration |
-| `loudness` | -14 | target LUFS |
-| `boil` | 0 | redraws per second of hand-drawn lines (0 keeps lines still) |
-| `watermark` | `false` | small text in the bottom right corner of every frame, like `"example.com"` |
+| `loudness` | -14 | target loudness in LUFS |
+| `boil` | 0 | redraws per second of hand-drawn lines; 0 keeps them still |
+| `watermark` | `"explainroo.com"` | text in the bottom right corner, or `false` |
+| `images` | none | `{ "model": "best" or "cheap", "style": "..." }` |
+
+The looks:
+
+| Look | What it looks like | Transition | Music |
+|---|---|---|---|
+| `paper` | marker drawings on warm paper | brush | warm |
+| `clean` | flat cards with soft shadows | slide | upbeat |
+| `chalk` | chalk on a green board | brush | calm |
+| `blueprint` | white drawings on blueprint blue | wipe | tech |
+| `midnight` | dark background with glowing colors | zoom | tech |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `init <dir>` | creates a project (`--theme`, `--size`, `--voice`, `--title`) |
+| `voice [project]` | makes the narration and the word times, cached per scene |
+| `preview [project]` | a live preview in the browser that reloads when you save |
+| `still [project] [times]` | PNG pictures at `12.5`, `scene`, `[email protected]` or `scene@end` |
+| `sheet [project]` | a contact sheet of the video or of one scene (`--scene`, `--every`) |
+| `check [project]` | finds layout, timing and pronunciation problems |
+| `render [project]` | the MP4 (`--draft`, `--from`, `--to`, `--workers`, `--out`) |
+| `verify [project]` | checks the finished file: loudness, black frames, silence, clear voice |
+| `image [project] <name> "<prompt>"` | makes an illustration with OpenRouter |
+| `images [project]` | lists the images and what they cost |
+| `voices`, `say "text"` | lists the 28 voices, or makes a sample |
+| `themes`, `icons <word>` | lists the looks, searches the 1,854 icons |
+| `doctor` | checks the setup (`--fetch` downloads the speech models) |
+
+## Scene API
+
+Each scene function draws one frame. explainroo calls it for every frame with
+a fresh `s`, so the whole scene depends only on time. Do not keep state
+between calls and do not use timers. Give each element an `at` time and the
+look animates it in. Give it an `out` time and it animates out.
+
+```js
+export default {
+ intro(s) {
+ s.title('How DNS works', { at: 0 });
+ s.icon('globe', { y: 700, at: 'browser' });
+ },
+};
+```
+
+The canvas is 1920 x 1080 for 16:9 (1080 x 1920 for 9:16, 1080 x 1080 for
+1:1, 1080 x 1350 for 4:5). Coordinates are pixels from the top left. `x` and
+`y` are the center of an element unless the method says otherwise.
+
+### Time
+
+| Member | Meaning |
+|---|---|
+| `s.t` | seconds since the scene started |
+| `s.T` | seconds since the video started |
+| `s.dur` | length of the scene in seconds |
+| `s.voice` | `{ start, end }` of the narration in the scene |
+| `s.words` | the spoken words: `{ text, start, end }` in scene seconds |
+| `s.cue(word, n = 1)` | when the n-th time a word or phrase is spoken starts |
+| `s.cueEnd(word, n = 1)` | when it ends |
+| `s.mark(name)` | the time of a `[#name]` marker |
+| `s.time(v)` | turns a number, a word or `"#marker"` into seconds |
+| `s.p(at, dur = 0.6, ease = 'inOut')` | 0 to 1 progress for your own animation |
+| `s.since(at)`, `s.between(a, b)` | seconds since a time, or whether now is between two times |
+| `s.video` | `{ duration, frames, fps, width, height, scenes }` of the whole video |
+
+Every `at` and `out` accepts seconds (`2.4`), a spoken word (`'resolver'`) or
+a marker (`'#ask'`). Word cues ignore case and punctuation, and a phrase works
+too. A wrong word or marker stops with an error that lists the closest words.
+
+Easing names: `linear`, `in`, `out`, `inOut`, `outBack`, `outElastic`,
+`outQuart`, `inOutSine`. `s.ease.out(p)`, `s.lerp(a, b, p)` and
+`s.clamp(v, lo, hi)` are there for your own math.
+
+### Layout
+
+| Member | Meaning |
+|---|---|
+| `s.W`, `s.H`, `s.cx`, `s.cy` | canvas size and center |
+| `s.safe` | `{ x, y, w, h, left, top, right, bottom }` with a 7% margin |
+| `s.row(n, { width, x })` | n x positions spread over a width |
+| `s.col(n, { height, y })` | n y positions spread over a height |
+| `s.grid(cols, rows, { x, y, w, h, gap })` | cells `{ x, y, w, h }`, row by row |
+| `s.get(id)` | size and position of an element drawn earlier with that `id` |
+
+Most elements return `{ x, y, w, h, left, right, top, bottom }`, so you can
+place the next thing below or beside them.
+
+### Options most elements take
+
+| Option | Meaning |
+|---|---|
+| `at`, `out` | when it appears and when it leaves |
+| `enter` | `draw`, `write`, `type`, `words`, `sync`, `pop`, `rise`, `fade`, `zoom`, `drop`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `none` |
+| `exit` | `fade`, `pop`, `rise`, `drop`, `slide-left`, `slide-right`, `none` |
+| `dur` | length of the entrance in seconds |
+| `id` | a name for arrows, `annotate` and `s.get` |
+| `color` | a color name (`blue`, `accent`, `ink`, `muted`, ...) or any CSS color |
+| `opacity`, `scale`, `rotate` | extra changes, `rotate` in degrees |
+| `float` | pixels of slow drift that keeps a still element alive |
+| `sfx` | the sound on entrance, or `false` |
+
+In `paper`, `chalk` and `blueprint`, shapes are drawn line by line and text is
+written on. In `clean` and `midnight`, shapes pop and text rises. Use
+`at: -1` for things that were already on screen in the previous scene: they
+are there from the start and make no sound.
+
+### Text
+
+```js
+s.title('How DNS works', { at: 0 }); // display font, 104 px, at 44% height
+s.subtitle('the phone book of the internet', { at: 1 }); // 46 px, muted, at 60% height
+s.text('Every site has an *address*', { y: 300, size: 64, at: 'address' });
+s.note('about 20 ms', { x: 1400, y: 820, at: 3 }); // 32 px, muted
+```
-Scene attributes in `script.md`: `## id {hold=1.5 min=5 lead=0.2 transition=cut}`.
+`s.text(str, options)`: `x`, `y`, `size` (48), `font` (`display`, `body`,
+`hand`, `mono`), `weight` or `bold: true`, `align` (`left` means x is the left
+edge), `valign` (`top` means y is the top), `maxWidth`, `lineHeight`, `color`,
+`mark` (color of `*starred*` words), `bg` (a card behind the text), `padding`,
+`radius`, `border`. Entrances for text include `write`, `type` (with `cps`),
+`words` and `sync`, which shows each word as the voice says it. Words in
+`*stars*` get the accent color. `\n` starts a new line.
+
+### Shapes and arrows
+
+```js
+s.box('Resolver', { id: 'res', x: 960, y: 540, icon: 'server', color: 'blue', at: 'resolver' });
+s.circle({ id: 'you', x: 400, y: 540, r: 90, label: 'You', at: 0.5 });
+s.arrow('you', 'res', { label: 'asks', at: 'asks' });
+s.arrow([300, 900], [1600, 900], { bend: 0.3, dashed: true, at: 5 });
+s.line([[200, 800], [900, 700]], { color: 'accent', at: 2 });
+s.path('M0 0 C 200 -150 400 150 600 0', { x: 660, y: 540, at: 3 });
+```
+
+`s.box(label, options)` is a card that fits its label: `w`, `h`, `minW`,
+`minH`, `size`, `font`, `icon`, `iconSize`, `iconColor`, `color` (outline and
+a light fill), `fill`, `stroke`, `width`, `dashed`, `border: false`,
+`radius`, `shape: 'ellipse'`, `textColor`, `fillStyle` (hand-drawn looks:
+`solid`, `hachure`, `cross-hatch`, `zigzag`, `dots`). `s.circle({ r, label })`
+takes the same options.
+
+`s.arrow(from, to, options)`: `from` and `to` are `[x, y]`, `{ x, y }` or the
+`id` of an element drawn earlier, and then the arrow stops at its edge.
+Options: `bend` (about -1 to 1), `head` (`end`, `start`, `both`, `none`),
+`label`, `labelSize`, `labelColor`, `labelOffset`, `gap`, `dashed`, `width`,
+`headSize`. `s.connect` is the same.
+
+### Icons and images
+
+```js
+s.icon('database', { x: 1500, y: 540, size: 140, color: 'purple', at: 'database' });
+s.icon('lock', { bg: 'circle', color: 'green', label: 'Encrypted', at: 4 });
+s.image('assets/app.png', { w: 1100, frame: 'browser', url: 'app.example.com', at: 0.5 });
+s.image('assets/cables.png', { w: 1000, frame: 'card', at: 'cables', kenburns: true });
+```
+
+The 1,854 icons come from Lucide. Search with `explainroo icons <word>`; old
+Lucide names work too. Icon options: `size` (120), `color`, `weight` (2),
+`bg` (`true`, `'circle'`, `'square'` or a color), `bgScale`, `label`,
+`labelSize`.
+
+`s.image(src, options)` draws a file from `assets/`: `w` and/or `h` (the
+image keeps its shape), `fit` (`cover` or `contain`), `radius`, `frame`
+(`none`, `card`, `browser`, `window`, `phone`), `url` (for the browser frame),
+`border`, `shadow: false`, `kenburns: true` for a slow zoom.
+
+### Pointing things out
+
+```js
+s.text('It is *not* magic', { id: 'claim', y: 400, at: 0 });
+s.annotate('claim', { type: 'underline', at: 'magic' });
+s.annotate({ x: 960, y: 700, w: 400, h: 90 }, { type: 'circle', color: 'red', at: 3 });
+```
+
+`s.annotate(target, options)` marks an element or a box: `type` is
+`underline`, `circle`, `box`, `highlight`, `strike`, `cross` or `bracket`.
+Options: `color`, `padding`, `width`, `dur`.
+
+### Lists, numbers and charts
+
+```js
+s.list(['Browser cache', 'Resolver', 'Root server'], { x: 360, y: 280, at: 'first', stagger: 1.1 });
+s.number(1500000, { suffix: ' requests', at: 'million', y: 480 });
+s.bars([{ label: '2023', value: 19 }, { label: '2024', value: 31 }], { at: 1, suffix: 'k' });
+s.lineChart([3, 5, 4, 8, 13, 21], { labels: ['M', 'T', 'W', 'T', 'F', 'S'], at: 1 });
+s.pie([{ label: 'Images', value: 55 }, { label: 'Other', value: 45 }], { donut: 0.55, at: 1 });
+```
+
+- `s.list(items, options)`: items are text or `{ text, at, icon, color, out }`.
+ `x` is the left edge and `y` the top. Options: `size` (50), `width`, `gap`,
+ `bullet` (`dot`, `dash`, `number`, `check`, `arrow` or an icon name),
+ `bulletColor`, `at` (a start time or a list of times), `stagger` (0.7),
+ `enter`.
+- `s.number(value, options)` counts up with ticks: `from`, `dur` (1.4),
+ `prefix`, `suffix`, `decimals`, `separator`, `group: false`, plus text
+ options.
+- `s.bars(data, options)`: `x`, `y`, `w`, `h`, `max`, `stagger`, `growDur`,
+ `values: false`, `prefix`, `suffix`, `format(v)`, `labelSize`,
+ `valueSize`, `fillStyle`.
+- `s.lineChart(values, options)`: `x`, `y`, `w`, `h`, `min`, `max`,
+ `labels`, `dots: false`, `area: false`, `color`, `dur`.
+- `s.pie(data, options)`: `x`, `y`, `r`, `donut` (0 to 0.8), `labels: false`,
+ `labelOffset`, `dur`.
+
+### Code and terminal
+
+```js
+s.code("const res = await fetch(url);", { lang: 'js', title: 'app.js', at: 0.5 });
+s.terminal(['$ npm install', 'added 42 packages in 3s'], { at: 1 });
+```
+
+`s.code(source, options)`: `lang` (`js`, `ts`, `py`, `go`, `rust`, `php`,
+`sh`, `sql`, `json`, `md`), `size` (32), `w`, `title` (or `false`),
+`lineNumbers: false`, `reveal` (`type`, `lines`, `none`), `cps`, `lineDelay`,
+`highlight` (line numbers) and `highlightAt`. `check` reports lines that are
+wider than the window.
+
+`s.terminal(lines, options)`: lines starting with `$ ` are typed commands,
+other lines are output. A line can also be `{ cmd, at }` or
+`{ out, at, color }`. Options: `w`, `size`, `rows`, `title`, `prompt`, `cps`
+(22), `outputDelay`, `lineGap`.
+
+### Camera, groups and your own drawing
+
+- `s.camera([{ at, x, y, zoom, dur, rotate }])` moves the view. Call it first
+ in the scene function.
+- `s.group({ x, y, scale, rotate, at, out, enter }, () => { ... })` moves a
+ set of elements together. Inside, positions are relative to `x`, `y`.
+- `s.draw({ x, y, at, out }, (ctx, life) => { ... })` gives you the canvas 2D
+ context for anything the kit does not cover. `life.p` is the 0 to 1
+ entrance progress. `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 randomness
+ that is the same on every render.
+
+### Sound
+
+Elements make sounds when they enter, chosen by the look: drawn lines
+scribble, cards pop, arrows whoosh, list items play rising notes, numbers
+tick, typing clicks, and scenes change with a swipe. `sfx: false` silences one
+element, and `"sfx": "minimal"` in `video.json` keeps only transitions and the
+sounds you add.
+
+`s.sfx(name, at, { gain, dur, pitch })` adds a sound: `pop`, `click`,
+`whoosh`, `swipe`, `tick`, `type`, `ding`, `chime`, `thud`, `scribble`,
+`chalk`, `rise`, `sparkle`, `blip`, `error`. `dur` sets the length of `type`,
+`scribble`, `chalk` and `rise` (`rise` ends at `at + dur`). The music is made
+to fit the video and gets quieter while the voice speaks.
+
+### Colors and fonts
+
+Color names: `accent`, `ink`, `muted`, `bg`, `surface`, `red`, `orange`,
+`yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Each look has its
+own version of each color, so scenes keep working when you change the look.
+`s.color(name)` returns the CSS color and `s.tint(name)` the light fill. Font
+roles: `display`, `body`, `hand`, `mono`.
+
+## Things that break
+
+- Calling an element only sometimes (`if (s.t > 3) s.box(...)`). Always call
+ it and use `at` and `out`. Sound effects and checks depend on this.
+- An arrow or annotation that points to an `id` drawn later in the function.
+- `s.camera()` after other elements. It has to come first.
+- An `at` later than the end of the scene. Make the scene longer with
+ `{hold=2}` or `{min=6}` in the script.
+- Randomness from anything other than `s.rand()`, `s.noise()` or
+ `Math.random()` inside the scene function.
+- Text in AI images. Put words on screen with `s.text`.
## Working on explainroo itself
-- `src/` is the Node side: script parsing, voice, alignment, timeline,
- server, rendering and checks. `engine/` runs in the page: the scene API
- (`stage.js`), drawing (`pen.js`), themes, transitions, captions and the
- audio engine (`engine/audio/`).
-- Run `npm test` after changes. For engine changes, render the examples in
+- `src/` is the Node side: script, voice, word timing, timeline, server,
+ rendering, checks and images. `engine/` runs in the page: the scene API
+ (`stage.js`), drawing (`pen.js`), looks, transitions, captions and audio
+ (`engine/audio/`).
+- Run `npm test` after changes. For engine changes, render the videos in
`examples/` and look at their stills and sheets.
-- `dev/audio-lab.mjs` renders every music style and sound effect and measures
- loudness, true peak and determinism with ffmpeg.
-- `npm run build:icons` rebuilds `engine/icons/` from `lucide-static`, and
- `npm run build:fonts` downloads the bundled fonts again.
-- Keep the scene API small and forgiving, with error messages that tell an
- agent exactly what to change.
+- `dev/audio-lab.mjs` renders every music style and sound and measures them.
+- `npm run build:icons` rebuilds the icons from `lucide-static`, and
+ `npm run build:fonts` downloads the fonts again.
diff --git a/README.md b/README.md
index 5c182c9..9cb3f04 100644
--- a/README.md
+++ b/README.md
@@ -1,190 +1,55 @@
# explainroo
-Narrated explainer videos made by your coding agent. Pure JavaScript, a local
-voice, no API keys and no video model.
+## Point your AI agent (Claude Code, Codex, Pi and others) at this repo and tell it what video you want.
-[![The explainroo launch video, made with explainroo](docs/media/intro.gif)](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4)
+> Right now explainroo works best with Claude Code and Opus 5.5.
-*The launch video above was made by a coding agent with explainroo, with sound
-([watch the MP4](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4)).
-Its source is in [examples/explainroo-intro](examples/explainroo-intro).*
+[![Watch the explainroo video](docs/media/intro.gif)](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4)
-Point Claude Code, Codex or any coding agent at this repository and ask for a
-video:
+*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)).*
-> Make a 60 second explainer video about how HTTPS keeps a password secret.
+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.
-The agent writes two files: a script of what to say and a few lines of
-JavaScript for what to show. explainroo does the rest:
+## Getting started
-- **Speaks the narration** with [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), a voice model that runs on your own computer.
-- **Times every word** by listening back with Whisper, so a picture can appear exactly when it is mentioned: `at: 'database'`.
-- **Draws the frames** in headless Chrome in one of five looks, from hand-drawn paper to a dark developer style.
-- **Scores it** with music and sound effects that are generated to fit and duck under the voice.
-- **Gives your agent eyes**: still frames, contact sheets, a layout check and a speech check, because an agent cannot watch a video.
-- **Renders an MP4** with ffmpeg, normalized to -14 LUFS.
-
-Nothing leaves your machine and nothing costs money per video. The speech
-models download once (about 400 MB).
-
-## Examples
-
-| | | |
-|---|---|---|
-| [![explainroo intro](docs/media/intro-poster.jpg)](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4) | [![How DNS finds a website](docs/media/dns-poster.jpg)](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/how-dns-works.mp4) | [![git merge vs rebase](docs/media/rebase-poster.jpg)](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/merge-vs-rebase.mp4) |
-| **explainroo in 86 seconds** (paper, 16:9) · [source](examples/explainroo-intro) | **How DNS finds a website** (chalk, 16:9) · [source](examples/how-dns-works) | **git merge vs rebase** (midnight, 9:16 with captions) · [source](examples/merge-vs-rebase) |
-
-## Quick start
-
-You need Node.js 20 or newer, ffmpeg, and Google Chrome or Chromium.
+You need Node.js 20 or newer, ffmpeg, and Chrome or Chromium.
```bash
git clone https://github.com/vincentsch/explainroo.git
cd explainroo
npm install
-node bin/explainroo.js doctor --fetch # checks your setup and downloads the speech models
+node bin/explainroo.js doctor --fetch
```
-Then open your coding agent in the `explainroo` folder and ask for a video.
-The agent follows [AGENTS.md](AGENTS.md), and your finished file lands in
-`videos/<name>/out/video.mp4`.
-
-To make one by hand:
-
-```bash
-node bin/explainroo.js init videos/hello --theme paper
-node bin/explainroo.js preview videos/hello # live preview in your browser
-node bin/explainroo.js render videos/hello # writes videos/hello/out/video.mp4
-```
-
-`npm link` puts `explainroo` on your PATH if you prefer the short command.
-
-## What the agent writes
-
-`script.md` holds the narration, one scene per `##` heading:
-
-```markdown
-## sync
-This way a picture can appear at the moment the voice mentions it. [#code] The
-agent writes one line of code, [#say] and when the voice says database, the
-database appears.
-```
-
-`[#code]` marks a moment to animate on. `{SQL|sequel}` shows "SQL" on screen
-but says "sequel", and `[pause 0.5]` adds silence.
-
-`scenes.js` draws each scene. Every element gets a time: seconds, a spoken
-word, or a marker:
-
-```js
-sync(s) {
- // shortened from examples/explainroo-intro/scenes.js
- s.text('Word cues', { font: 'display', size: 84, y: 160, at: 0.1 });
- s.code("s.icon('database', {\n at: 'database',\n});", { x: 640, y: 560, at: '#code' });
- s.icon('database', { x: 1450, y: 560, size: 260, color: 'purple', at: 'database' });
- s.burst({ x: 1450, y: 560, at: 'database' });
-},
-```
-
-The scene API covers titles and text (typed, written on, or revealed word by
-word as it is spoken), boxes, arrows that connect elements, 1,850+
-[Lucide](https://lucide.dev) icons, lists, counters, bar, line and pie
-charts, code and terminal windows, images in browser and phone frames,
-underlines and circles for emphasis, a camera, and a raw canvas when you need
-it. See [docs/api.md](docs/api.md).
-
-## Five looks
-
-One script, five styles: set `"theme"` in `video.json`.
-
-![paper, clean, chalk, blueprint and midnight](docs/media/looks.jpg)
-
-Each look brings its own fonts, colors, entrances, transition, sound effects
-and music style. 16:9, 9:16, 1:1 and 4:5 are supported, and vertical videos
-get burned-in captions that follow the voice word by word.
-
-## How the agent checks its work
-
-An agent cannot watch a video, so explainroo turns the video into things it
-can read.
-
-```bash
-explainroo still videos/hello # a PNG of every scene when it is fully built
-explainroo sheet videos/hello --scene intro # one scene over time
-explainroo check videos/hello # layout, timing and pronunciation problems
-explainroo verify videos/hello # the finished MP4: loudness, black frames, narration
-```
-
-![A contact sheet of one scene](docs/media/contact-sheet.jpg)
-
-`check` renders every scene at several moments and reports text that runs off
-the frame, overlaps other text, is too small or low in contrast, elements
-timed after their scene ends, and long stretches where nothing changes. It
-also compares what the voice said with what the script asked for. On the
-first draft of the DNS example it caught Kokoro reading a domain the wrong way:
-
-```
-WARN question: the voice check could not confirm "example.com?". It heard: "So
-before anything loads, your browser has to ask, what is the address of example
-calm?". If a word is mispronounced, write it as {shown|spoken} in script.md.
-```
-
-Writing `{example.com|example dot com}` in the script fixed it.
-
-`verify` transcribes the final mix to confirm the narration is still
-understandable over the music. All three examples score 100%.
-
-## Commands
-
-| Command | Does |
-|---|---|
-| `init <dir>` | creates a project (`--theme`, `--size`, `--voice`, `--title`) |
-| `voice [project]` | generates narration and word timings, cached per scene |
-| `preview [project]` | live preview in your browser that reloads on save |
-| `still [project] [times…]` | PNG stills at `12.5`, `scene`, `[email protected]` |
-| `sheet [project]` | contact sheet of the video or one scene |
-| `check [project]` | layout, timing and pronunciation problems |
-| `render [project]` | the MP4 (`--draft` for a fast half-size version, `--from`, `--to`) |
-| `verify [project]` | loudness, black frames, silence and narration in the rendered file |
-| `voices`, `say "text"` | list the 28 voices, or hear one |
-| `themes`, `icons <word>` | list the looks, search the icons |
-| `doctor` | checks Node, ffmpeg, Chrome and the speech models |
-
-Every command accepts `--json`.
-
-## Speed and limits
-
-On a laptop with an 8-core Intel i9-11950H, everything on the CPU, the
-68-second DNS example renders at 1080p in about 50 seconds once its voice is
-generated. Generating the voice takes a little less time than the narration
-lasts, and only changed scenes are generated again.
-
-- Narration is English only (Kokoro's English voices, Whisper base.en).
-- Music is synthesized, not sampled. It is meant to sit under a voice, not to
- carry a video on its own.
-- The first run downloads about 400 MB of speech models from Hugging Face.
- Set `EXPLAINROO_TTS_DTYPE=q8` for a smaller, slower voice model.
-- explainroo draws with code. It does not generate photos or video footage,
- though you can place your own images and screenshots.
+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`.
-## Use it as a skill
+## More
-[skills/explainroo/SKILL.md](skills/explainroo/SKILL.md) lets an agent make
-videos from any folder. For Claude Code, copy `skills/explainroo` into
-`~/.claude/skills/`.
+- The full documentation and a library of videos made with explainroo:
+ [explainroo.com](https://explainroo.com)
+- The source of three example videos: [examples/](examples/)
-## Credits
+## The watermark
-explainroo stands on open work:
-[Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) (Apache-2.0) through
-[kokoro-js](https://github.com/hexgrad/kokoro) (Apache-2.0),
-[Whisper](https://github.com/openai/whisper) (MIT) through
-[Transformers.js](https://github.com/huggingface/transformers.js) (Apache-2.0),
-[Rough.js](https://roughjs.com) (MIT), [Lucide](https://lucide.dev) icons
-(ISC), [Playwright](https://playwright.dev) (Apache-2.0), fonts under the SIL
-Open Font License (see [fonts/licenses](fonts/licenses)), and
-[ffmpeg](https://ffmpeg.org), which you install yourself.
+Videos have a small "explainroo.com" in the 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.
-## License
+## Credits and license
-MIT
+explainroo uses [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) for the
+voice, [Whisper](https://github.com/openai/whisper) through
+[Transformers.js](https://github.com/huggingface/transformers.js) for word
+timing, [Rough.js](https://roughjs.com), [Lucide](https://lucide.dev) icons,
+[Playwright](https://playwright.dev), fonts under the SIL Open Font License,
+and [ffmpeg](https://ffmpeg.org). explainroo itself is MIT licensed.
diff --git a/docs/api.md b/docs/api.md
deleted file mode 100644
index 185474d..0000000
--- a/docs/api.md
+++ /dev/null
@@ -1,350 +0,0 @@
-# Scene API
-
-Every scene in `script.md` has a function with the same id in `scenes.js`:
-
-```js
-export default {
- intro(s) {
- s.title('How DNS works', { at: 0 });
- s.icon('globe', { y: 700, at: 'browser' });
- },
-};
-```
-
-The function draws **one frame**. explainroo calls it for every frame with a
-fresh `s`, so the whole scene is a function of time: never keep state between
-calls, and never use timers. Give each element an `at` time and the theme
-animates it in; give it an `out` time and it animates out.
-
-The canvas is 1920x1080 for 16:9 (1080x1920 for 9:16, 1080x1080 for 1:1,
-1080x1350 for 4:5). Coordinates are pixels from the top-left. Positions (`x`,
-`y`) are the **center** of an element unless the method says otherwise.
-
-## Contents
-
-- [Time](#time)
-- [Layout](#layout)
-- [Common options](#common-options)
-- [Text](#text)
-- [Shapes and arrows](#shapes-and-arrows)
-- [Icons and images](#icons-and-images)
-- [Emphasis](#emphasis)
-- [Lists, numbers and charts](#lists-numbers-and-charts)
-- [Code and terminal](#code-and-terminal)
-- [Camera, groups and custom drawing](#camera-groups-and-custom-drawing)
-- [Sound](#sound)
-- [Colors and fonts](#colors-and-fonts)
-- [Themes](#themes)
-- [Rules](#rules)
-
-## Time
-
-| Member | Meaning |
-|---|---|
-| `s.t` | seconds since this scene started |
-| `s.T` | seconds since the video started |
-| `s.dur`, `s.end` | length of this scene in seconds |
-| `s.voice` | `{ start, end }` of the narration inside the scene |
-| `s.words` | every narrated word: `{ text, start, end }` in scene seconds |
-| `s.cue(word, n = 1)` | when the n-th occurrence of a word or phrase starts being spoken |
-| `s.cueEnd(word, n = 1)` | when it finishes |
-| `s.mark(name)` | the time of a `[#name]` marker in the narration |
-| `s.time(v)` | turns a number, a spoken word or `"#mark"` into seconds |
-| `s.p(at, dur = 0.6, ease = 'inOut')` | 0 to 1 progress of your own animation |
-| `s.since(at)` | seconds since `at` (negative before) |
-| `s.between(a, b)` | true while `a <= t < b` |
-
-Every `at` and `out` option accepts the same three forms:
-
-```js
-s.box('Resolver', { at: 2.4 }); // seconds into the scene
-s.box('Resolver', { at: 'resolver' }); // when the word "resolver" is spoken
-s.box('Resolver', { at: '#ask' }); // at the [#ask] marker in script.md
-```
-
-Word cues ignore case and punctuation. A phrase works too (`'right server'`).
-An unknown word or marker throws an error that lists the closest words, so
-`explainroo check` finds typos.
-
-Easing names: `linear`, `in`, `out`, `inOut`, `outBack`, `outElastic`,
-`outQuart`, `inOutSine`. `s.ease.out(p)` and friends are available directly,
-with `s.lerp(a, b, p)` and `s.clamp(v, lo, hi)`.
-
-## Layout
-
-| Member | Meaning |
-|---|---|
-| `s.W`, `s.H` | canvas width and height |
-| `s.cx`, `s.cy` | canvas center |
-| `s.safe` | `{ x, y, w, h, left, top, right, bottom }`, the area with a 7% margin |
-| `s.row(n, { width, x })` | n x positions spread over `width` (default 72% of W) |
-| `s.col(n, { height, y })` | n y positions spread over `height` |
-| `s.grid(cols, rows, { x, y, w, h, gap })` | cells `{ x, y, w, h }`, row by row |
-| `s.get(id)` | geometry of an element drawn earlier with that `id` |
-
-Most elements return their geometry: `{ x, y, w, h, left, right, top, bottom }`.
-Use it to place the next element:
-
-```js
-const card = s.box('Cache', { x: 500, y: 540, at: 1 });
-s.note('checked first', { x: card.x, y: card.bottom + 40, at: 1.4 });
-```
-
-## Common options
-
-Most elements accept these:
-
-| Option | Meaning |
-|---|---|
-| `at` | when it appears (default `0`) |
-| `out` | when it leaves (default: never) |
-| `enter` | `draw`, `write`, `type`, `words`, `sync`, `pop`, `rise`, `fade`, `zoom`, `drop`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `none` |
-| `exit` | `fade`, `pop`, `rise`, `drop`, `slide-left`, `slide-right`, `none` |
-| `dur` | length of the entrance in seconds |
-| `id` | a name so arrows, `annotate` and `s.get` can find it |
-| `color` | a theme color name (`blue`, `accent`, `ink`, `muted`, ...) or any CSS color |
-| `opacity`, `scale`, `rotate` | extra transform (`rotate` in degrees) |
-| `float` | pixels of gentle idle drift, to keep a still element alive |
-| `sfx` | sound on entrance: a sound name, or `false` for silence |
-
-The theme picks sensible entrances: in `paper`, `chalk` and `blueprint` shapes
-are drawn stroke by stroke and text is written on; in `clean` and `midnight`
-shapes pop and text rises.
-
-## Text
-
-```js
-s.title('How DNS works', { at: 0 }); // display font, 104px, centered at 44% height
-s.subtitle('the internet phone book', { at: 0.8 }); // body font, 46px, muted, at 60% height
-s.text('Every site has an *address*', { y: 300, size: 64, at: 'address' });
-s.note('about 20 ms', { x: 1400, y: 820, at: 3 }); // 32px, muted
-```
-
-`s.text(str, options)`:
-
-| Option | Default | Meaning |
-|---|---|---|
-| `x`, `y` | center | anchor point |
-| `size` | 48 | font size in px |
-| `font` | `body` | `display`, `body`, `hand` or `mono` |
-| `weight` / `bold` | theme | font weight, or `bold: true` |
-| `align` | `center` | `left` (x is the left edge), `center`, `right` |
-| `valign` | `middle` | `top` (y is the top), `middle`, `bottom` |
-| `maxWidth` | 80% of W | wrap width |
-| `lineHeight` | 1.24 | line spacing |
-| `color` | `ink` | text color |
-| `mark` | `accent` | color for `*accented*` words |
-| `bg` | none | `true` or a color: draws a rounded card behind the text |
-| `padding`, `radius`, `border` | | card options when `bg` is set |
-| `enter` | theme | also `write` (written on), `type` (typewriter, `cps` chars per second), `words` (word by word), `sync` (each word appears as it is spoken) |
-
-Wrap words in `*asterisks*` to color them with the accent: `'*Three* steps'`.
-A newline (`\n`) forces a line break.
-
-`enter: 'sync'` shows the words in time with the narration. It works best for
-a short quote or key phrase that the narrator says word for word.
-
-## Shapes and arrows
-
-```js
-s.box('Resolver', { id: 'res', x: 960, y: 540, icon: 'server', color: 'blue', at: 'resolver' });
-s.circle({ id: 'you', x: 400, y: 540, r: 90, label: 'You', color: 'green', at: 0.5 });
-s.arrow('you', 'res', { label: 'asks', at: 'asks' });
-s.arrow([300, 900], [1600, 900], { bend: 0.3, dashed: true, color: 'muted', at: 5 });
-s.line([[200, 800], [900, 700], [1700, 820]], { color: 'accent', at: 2 });
-s.path('M0 0 C 200 -150 400 150 600 0', { x: 660, y: 540, at: 3 });
-```
-
-`s.box(label, options)` draws a rounded card that sizes itself to its label.
-
-| Option | Meaning |
-|---|---|
-| `w`, `h`, `minW`, `minH` | fixed or minimum size (otherwise fits the label) |
-| `size`, `font`, `weight` | label font (default 44px, body font, semi-bold) |
-| `icon`, `iconSize`, `iconColor` | an icon above the label |
-| `color` | outline color and a light tint for the fill |
-| `fill` | explicit fill color (`'none'` for an outline only) |
-| `stroke`, `width`, `dashed`, `border: false` | outline options |
-| `radius` | corner radius |
-| `shape` | `rect` (default) or `ellipse` |
-| `textColor` | label color (chosen automatically for contrast otherwise) |
-| `fillStyle` | hand-drawn looks: `solid`, `hachure`, `cross-hatch`, `zigzag`, `dots` |
-
-`s.circle({ r, label, ... })` takes the same options as a box.
-
-`s.arrow(from, to, options)`: `from` and `to` are `[x, y]`, `{ x, y }` or the
-`id` of an element drawn earlier (the arrow then stops at its edge).
-
-| Option | Meaning |
-|---|---|
-| `bend` | curve amount, about -1 to 1 (0 is straight) |
-| `head` | `end` (default), `start`, `both`, `none` |
-| `label`, `labelSize`, `labelColor`, `labelOffset` | text beside the middle of the arrow |
-| `gap` | space between the arrow and the elements it connects (default 14) |
-| `dashed`, `width`, `headSize`, `color` | styling |
-
-`s.connect(a, b, options)` is the same as `s.arrow`.
-
-Arrows and lines are drawn from start to end by default.
-
-## Icons and images
-
-```js
-s.icon('database', { x: 1500, y: 540, size: 140, color: 'purple', at: 'database' });
-s.icon('lock', { bg: 'circle', color: 'green', label: 'Encrypted', at: 4 });
-s.image('assets/app.png', { w: 1100, frame: 'browser', url: 'app.example.com', at: 0.5 });
-```
-
-There are 1,854 icons from [Lucide](https://lucide.dev). Search them with
-`explainroo icons <word>`. Icon options: `size` (default 120), `color`,
-`weight` (stroke weight in icon units, default 2), `bg` (`true`, `'circle'`,
-`'square'` or a color), `bgScale`, `label`, `labelSize`.
-
-`s.image(src, options)` draws a file from the project's `assets/` folder:
-`w` and/or `h` (keeps the aspect ratio), `fit` (`cover` or `contain`),
-`radius`, `frame` (`none`, `browser`, `window`, `phone`), `url` (for the browser
-frame), `border`, `shadow: false`, `kenburns: true` for a slow push-in.
-
-## Emphasis
-
-```js
-s.text('It is *not* magic', { id: 'claim', y: 400, at: 0 });
-s.annotate('claim', { type: 'underline', at: 'magic' });
-s.annotate({ x: 960, y: 700, w: 400, h: 90 }, { type: 'circle', color: 'red', at: 3 });
-```
-
-`s.annotate(target, options)` marks an element (`id`) or a box
-`{ x, y, w, h }`. `type`: `underline`, `circle`, `box`, `highlight`, `strike`,
-`cross`, `bracket`. Options: `color` (default accent), `padding`, `width`, `dur`.
-
-## Lists, numbers and charts
-
-```js
-s.list(['Browser cache', 'Resolver', 'Root server', 'Name server'], { x: 360, y: 280, at: 'first', stagger: 1.1 });
-s.list([{ text: 'Fast', at: 'fast' }, { text: 'Free', at: 'free' }], { bullet: 'check' });
-s.number(1500000, { suffix: ' requests', at: 'million', y: 480 });
-s.bars([{ label: '2022', value: 12 }, { label: '2023', value: 19 }, { label: '2024', value: 31 }], { at: 1, suffix: 'k' });
-s.lineChart([3, 5, 4, 8, 13, 21], { labels: ['M', 'T', 'W', 'T', 'F', 'S'], at: 1 });
-s.pie([{ label: 'Images', value: 55 }, { label: 'Scripts', value: 30 }, { label: 'Other', value: 15 }], { donut: 0.55, at: 1 });
-```
-
-`s.list(items, options)`: items are strings or `{ text, at, icon, color, out }`.
-`x` is the **left** edge and `y` the **top** of the list. Options: `size` (50),
-`width`, `gap`, `bullet` (`dot`, `dash`, `number`, `check`, `arrow` or any icon
-name), `bulletColor`, `at` (first item, or an array of times), `stagger`
-(seconds between items, default 0.7), `enter`. Each item plays a rising note.
-
-`s.number(value, options)` counts up from `from` (default 0) over `dur`
-(default 1.4 s) with ticks: `prefix`, `suffix`, `decimals`, `separator`,
-`group: false`, plus text options (`size` 150, display font, accent color).
-
-`s.bars(data, options)`: `x`, `y`, `w`, `h`, `max`, `stagger`, `growDur`,
-`values: false`, `prefix`, `suffix`, `format(v)`, `labelSize`, `valueSize`,
-`fillStyle`. Each item may have its own `color`.
-
-`s.lineChart(values, options)`: `x`, `y`, `w`, `h`, `min`, `max`, `labels`,
-`dots: false`, `area: false`, `color`, `dur`.
-
-`s.pie(data, options)`: `x`, `y`, `r`, `donut` (0 to 0.8), `labels: false`,
-`labelOffset`, `dur`.
-
-## Code and terminal
-
-```js
-s.code(`const res = await fetch(url);\nconst data = await res.json();`, { lang: 'js', title: 'app.js', at: 0.5 });
-s.terminal(['$ npm install explainroo', 'added 42 packages in 3s', '$ npx explainroo render'], { at: 1 });
-```
-
-`s.code(source, options)`: `lang` (`js`, `ts`, `py`, `go`, `rust`, `php`, `sh`,
-`sql`, `json`), `size` (32), `w`, `title` (a file name, or `false` for no title
-bar), `lineNumbers: false`, `reveal` (`type` default, `lines`, `none`), `cps`
-(typing speed), `lineDelay`, `highlight` (line numbers to highlight, 1-based)
-and `highlightAt`.
-
-`s.terminal(lines, options)`: lines starting with `$ ` are typed commands,
-other lines are output. Lines can also be `{ cmd, at }` or
-`{ out, at, color }`. Options: `w`, `size`, `rows` (minimum height), `title`,
-`prompt`, `cps` (22), `outputDelay`, `lineGap`. Typing plays keyboard sounds.
-
-## Camera, groups and custom drawing
-
-```js
-intro(s) {
- s.camera([{ at: 'zoom', x: 1400, y: 500, zoom: 1.8, dur: 1.2 }, { at: '#back', x: 960, y: 540, zoom: 1 }]);
- // ...everything drawn after this call is seen through the camera
-}
-```
-
-`s.camera(keys)` must be called **first** in the scene function. Each key moves
-the view to `x`, `y` (the point shown in the center), `zoom`, and optionally
-`rotate`, over `dur` seconds (default 1.1) with `ease`.
-
-`s.group({ x, y, scale, rotate, at, out, enter }, () => { ... })` moves a set of
-elements together. Coordinates inside are relative to `x`, `y`; times stay
-scene times.
-
-`s.draw({ x, y, at, out, enter }, (ctx, life) => { ... })` is an escape hatch
-for anything the kit does not cover: `ctx` is the raw canvas 2D context moved
-to `x`, `y`, and `life.p` is the 0 to 1 entrance progress, `life.local` the
-seconds since `at`. `s.ctx` is also available directly.
-
-`s.burst({ x, y, at, count, colors, spread, power, size })` fires confetti.
-
-`s.bg(color)` paints over the theme background.
-
-`s.rand(i, seed)`, `s.noise(x, seed)` and `s.wiggle(amount, speed, seed)` give
-repeatable randomness. `Math.random()` is also repeatable inside a scene, but
-use `s.rand(i)` when an element needs its own stable value.
-
-## Sound
-
-Entrances make sounds automatically, chosen by the theme: hand-drawn strokes
-scribble, cards pop, arrows whoosh, list items play rising notes, numbers
-tick, typing clicks, and every scene change swipes. Set `sfx: false` on an
-element to silence it, or `"sfx": "minimal"` in `video.json` to keep only
-transitions and the sounds you add yourself.
-
-`s.sfx(name, at, { gain, dur, pitch })` adds a sound. Names: `pop`, `click`,
-`whoosh`, `swipe`, `tick`, `type`, `ding`, `chime`, `thud`, `scribble`,
-`chalk`, `rise`, `sparkle`, `blip`, `error`. `dur` sets the length of `type`,
-`scribble`, `chalk` and `rise` (`rise` ends at `at + dur`, so start it before
-a reveal). `pitch` picks the step of `blip` in the music's scale.
-
-Music is generated to fit the video and ducks under the narration. Choose it
-in `video.json`: `"music": "warm"` (or `upbeat`, `calm`, `tech`, `playful`),
-`"music": { "style": "calm", "volume": 0.35 }`, or `"music": false`.
-
-## Colors and fonts
-
-Color names: `accent`, `ink`, `muted`, `bg`, `surface`, `red`, `orange`,
-`yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `gray`. Each theme maps
-them to its own palette, so a scene keeps working when you switch themes.
-`s.color(name)` returns the CSS color; `s.tint(name)` returns the light fill.
-Any CSS color string also works.
-
-Font roles: `display` (titles), `body`, `hand` (handwriting), `mono` (code).
-
-## Themes
-
-| Theme | Look | Transition | Music |
-|---|---|---|---|
-| `paper` | hand-drawn marker on warm paper | brush | warm |
-| `clean` | crisp flat cards with soft shadows | slide | upbeat |
-| `chalk` | chalk on a green board, hatched fills | brush | calm |
-| `blueprint` | technical drafting on blueprint blue | wipe | tech |
-| `midnight` | dark developer look with glowing accents | zoom | tech |
-
-Set it in `video.json` (`"theme": "chalk"`). Set a scene's transition in
-`script.md` (`## intro {transition=cut}`): `fade`, `slide`, `wipe`, `zoom`,
-`brush`, `cut`.
-
-## Rules
-
-- Draw the whole frame every call. Never store state outside the function.
-- Call every element on every frame, and control visibility with `at` and
- `out` instead of `if (s.t > 3)`. Sound effects and checks rely on it.
-- Tie reveals to the narration: `at: 'word'` or `at: '#mark'`, not guessed
- seconds.
-- Keep text at 32px or larger on a 1920x1080 canvas, and inside `s.safe`.
-- Draw things you refer to by `id` before the arrows or annotations that use
- them.
diff --git a/engine/runtime.js b/engine/runtime.js
index b5df5b1..f0c7979 100644
--- a/engine/runtime.js
+++ b/engine/runtime.js
@@ -162,20 +162,30 @@ export class Engine {
}
}
- // Small text in the bottom right corner, on every frame.
+ // Small text in the bottom right corner of every frame, on a soft backing
+ // so it stays readable over any scene.
drawWatermark(ctx, text) {
const th = this.theme;
const m = Math.min(this.W, this.H);
- const size = Math.round(m * 0.024);
- const margin = Math.round(m * 0.03);
+ const size = Math.round(m * 0.028);
+ const margin = Math.round(m * 0.028);
ctx.save();
ctx.globalAlpha = 1;
ctx.globalCompositeOperation = 'source-over';
- ctx.font = fontString(th, 'body', size, th.fonts.body.family === 'Inter' ? 600 : undefined);
+ ctx.font = fontString(th, 'body', size, th.fonts.body.family === 'Inter' ? 600 : th.fonts.body.family === 'Kalam' ? 700 : undefined);
ctx.textAlign = 'right';
- ctx.textBaseline = 'alphabetic';
- ctx.fillStyle = withAlpha(th.ink, th.dark ? 0.6 : 0.5);
- ctx.fillText(text, this.W - margin, this.H - margin);
+ ctx.textBaseline = 'middle';
+ const w = ctx.measureText(text).width;
+ const padX = size * 0.6;
+ const h = size * 1.6;
+ const x = this.W - margin;
+ const y = this.H - margin - h / 2;
+ ctx.fillStyle = withAlpha(th.bg, 0.72);
+ ctx.beginPath();
+ ctx.roundRect(x - w - padX * 2, y - h / 2, w + padX * 2, h, h / 2);
+ ctx.fill();
+ ctx.fillStyle = withAlpha(th.ink, 0.82);
+ ctx.fillText(text, x - padX, y + size * 0.04);
ctx.restore();
}
diff --git a/engine/stage.js b/engine/stage.js
index c516f39..f97d00d 100644
--- a/engine/stage.js
+++ b/engine/stage.js
@@ -822,9 +822,11 @@ export class Stage {
} else if (!h) h = w / ratio;
else if (!w) w = h * ratio;
const frame = o.frame ?? 'none';
+ if (!['none', 'browser', 'window', 'phone', 'card'].includes(frame)) throw new SceneError(`image frame must be none, browser, window, phone or card, not "${frame}"`);
const bar = frame === 'browser' || frame === 'window' ? Math.max(34, h * 0.075) : 0;
- const fw = frame === 'phone' ? w + 28 : w;
- const fh = frame === 'phone' ? h + 28 : h + bar;
+ const cardPad = frame === 'card' ? Math.round(Math.min(w, h) * 0.035) + 8 : 0;
+ const fw = frame === 'phone' ? w + 28 : w + cardPad * 2;
+ const fh = frame === 'phone' ? h + 28 : h + bar + cardPad * 2;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
this._register(o.id, x, y, fw, fh);
@@ -857,6 +859,8 @@ export class Stage {
ctx.fillText(o.url, 0, 1);
ctx.restore();
}
+ } else if (frame === 'card') {
+ this.pen.draw(ctx, { kind: 'rect', w: fw, h: fh, r: r + cardPad / 2 }, { fill: th.dark ? th.surface : '#ffffff', stroke: th.stroke.rough ? th.ink : 'none', width: th.stroke.width * 0.8, shadow: th.shadow || { color: 'rgba(0,0,0,0.16)', blur: 24, y: 8 }, seed: this._seed('card', o, src), fillStyle: 'solid' }, { stroke: 1, fill: 1 });
} else if (o.shadow !== false && th.shadow) {
this.pen.draw(ctx, { kind: 'rect', w, h, r }, { fill: th.surface, stroke: 'none', width: 0, shadow: th.shadow, rough: false }, { stroke: 1, fill: 1 });
}
diff --git a/examples/explainroo-intro/video.json b/examples/explainroo-intro/video.json
index 38b880a..d9504b0 100644
--- a/examples/explainroo-intro/video.json
+++ b/examples/explainroo-intro/video.json
@@ -4,6 +4,5 @@
"size": "16:9",
"voice": "af_heart",
"music": true,
- "captions": "auto",
- "watermark": "explainroo.com"
+ "captions": "auto"
}
diff --git a/examples/how-dns-works/video.json b/examples/how-dns-works/video.json
index a9aafa9..20d2f61 100644
--- a/examples/how-dns-works/video.json
+++ b/examples/how-dns-works/video.json
@@ -4,6 +4,5 @@
"size": "16:9",
"voice": "af_heart",
"music": true,
- "captions": "auto",
- "watermark": "explainroo.com"
+ "captions": "auto"
}
diff --git a/examples/merge-vs-rebase/video.json b/examples/merge-vs-rebase/video.json
index ed87ff1..0a63da0 100644
--- a/examples/merge-vs-rebase/video.json
+++ b/examples/merge-vs-rebase/video.json
@@ -4,6 +4,5 @@
"size": "9:16",
"voice": "am_michael",
"music": true,
- "captions": "auto",
- "watermark": "explainroo.com"
+ "captions": "auto"
}
diff --git a/package.json b/package.json
index d6382cb..7f2ee86 100644
--- a/package.json
+++ b/package.json
@@ -31,7 +31,6 @@
"fonts/",
"templates/",
"skills/",
- "docs/api.md",
"AGENTS.md",
"CLAUDE.md",
"README.md",
diff --git a/skills/explainroo/SKILL.md b/skills/explainroo/SKILL.md
index df2e3d6..659462b 100644
--- a/skills/explainroo/SKILL.md
+++ b/skills/explainroo/SKILL.md
@@ -1,24 +1,25 @@
---
name: explainroo
-description: Make a narrated explainer video (MP4) from code with explainroo, using a local voice model and no API keys. Use when the user asks for an explainer, walkthrough, launch or tutorial video, an animated diagram with voice-over, or a short for YouTube, Reels or TikTok.
+description: Make a narrated explainer video (MP4) with explainroo, using a voice model on this computer and no API key. Use when the user asks for an explainer, how-to, walkthrough, launch or tutorial video, an animated diagram with a voice-over, or a short for YouTube, Reels or TikTok.
---
# Make an explainer video with explainroo
-explainroo turns a narration script and a small JavaScript scene file into a
-finished MP4: a local voice reads the script, every word is timed, frames are
-drawn in headless Chrome, and music and sound effects are generated to fit.
+explainroo turns a narration script and a small JavaScript scene file into an
+MP4. A voice model reads the script, every word gets a time, Chrome draws the
+frames, and explainroo adds music and sound effects.
-## 1. Find or install explainroo
+## Find or install explainroo
-Use the first that works:
+Try these first:
```bash
-command -v explainroo # installed with npm link
+command -v explainroo
ls "${EXPLAINROO_HOME:-$HOME/.explainroo}/bin/explainroo.js"
```
-If neither exists, install it (needs Node.js 20+, ffmpeg and Chrome or Chromium):
+If neither exists, install it. It needs Node.js 20 or newer, ffmpeg, and
+Chrome or Chromium.
```bash
git clone https://github.com/vincentsch/explainroo.git "$HOME/.explainroo"
@@ -26,27 +27,21 @@ cd "$HOME/.explainroo" && npm install
node bin/explainroo.js doctor --fetch
```
-Below, `explainroo` means either the linked command or
+Below, `explainroo` means the linked command or
`node "$HOME/.explainroo/bin/explainroo.js"`.
-## 2. Read the guide
+## Read AGENTS.md
-Read `AGENTS.md` in the explainroo folder before you start, and keep
-`docs/api.md` open while writing scenes. They define the workflow, the quality
-bar and the scene API.
+`AGENTS.md` in the explainroo folder has the steps, the writing rules, the
+settings and the full scene API. Read it before you start.
-## 3. Make the video
+## Make the video
-Create the project where the user wants it (default: `./video` in the current
-folder):
+Create the project where the user wants it, for example `./video`:
```bash
explainroo init video --theme paper --title "..."
```
-Then follow the workflow from AGENTS.md: write `script.md`, run
-`explainroo voice video`, write `scenes.js`, run `explainroo check video`,
-look at `explainroo still video` and `explainroo sheet video` output, then
-`explainroo render video` and `explainroo verify video`.
-
-Report the path to `video/out/video.mp4`, its length and the verify summary.
+Then follow the steps in AGENTS.md. Tell the user where `video/out/video.mp4`
+is, how long it is, and what `explainroo verify video` said.
diff --git a/src/cli.js b/src/cli.js
index ff9c20d..a758eaa 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -11,6 +11,7 @@ import { VOICES, loadTTS, loadASR, cacheRoot, ttsDtype, TTS_SAMPLE_RATE } from '
import { writeWav } from './wav.js';
import { ffmpegVersion } from './ffmpeg.js';
import { findChrome } from './browser.js';
+import { generateImage, imageLog, imageSpend, IMAGE_MODELS } from './images.js';
const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
@@ -28,6 +29,11 @@ Make a video
render [project] write out/video.mp4 (--draft, --from s, --to s, --workers n, --out file)
verify [project] check the rendered file: loudness, black frames, narration
+Images (optional, needs an OpenRouter API key)
+ image [project] <name> "<what to draw>" save an illustration as assets/<name>.png
+ (--model best|cheap, --aspect 16:9, --ref assets/a.png,assets/b.png, --no-style)
+ images [project] list generated images and what they cost
+
Reference
voices list voices; "explainroo say 'text' --voice am_michael" to hear one
themes list looks
@@ -35,7 +41,7 @@ Reference
doctor check ffmpeg, Chrome and the speech models (--fetch downloads them)
Options: --json for machine-readable output. The project defaults to the current folder.
-Docs: AGENTS.md (workflow for coding agents) and docs/api.md (scene API).`;
+Docs: AGENTS.md (for coding agents) and https://explainroo.com/docs/`;
function parseArgs(argv) {
const pos = [];
@@ -52,7 +58,7 @@ function parseArgs(argv) {
}
return { pos, flags };
}
-const BOOL = new Set(['json', 'draft', 'force', 'fetch', 'help', 'version', 'quiet', 'open']);
+const BOOL = new Set(['json', 'draft', 'force', 'fetch', 'help', 'version', 'quiet', 'open', 'no-style']);
function num(v, name) {
if (v === undefined) return undefined;
@@ -134,6 +140,29 @@ export async function main(argv) {
print(lines.join('\n'), r);
return r.issues.some((i) => i.level === 'error') ? 1 : 0;
}
+ case 'image': {
+ const isProject = pos[0] && fs.existsSync(path.join(pos[0], 'video.json'));
+ const project = loadProject(isProject ? pos.shift() : undefined);
+ const [name, ...rest] = pos;
+ const r = await generateImage(project, {
+ name,
+ prompt: rest.join(' '),
+ model: flags.model,
+ aspect: flags.aspect,
+ refs: flags.ref ? String(flags.ref).split(',').map((x) => x.trim()).filter(Boolean) : [],
+ style: flags['no-style'] ? false : flags.style,
+ log,
+ });
+ print(`${r.file} ${r.model} ${r.cost_usd !== null ? '$' + r.cost_usd.toFixed(4) : 'cost unknown'} (images so far: $${r.total_usd.toFixed(4)})\nOpen the image and check it before you use it.`, r);
+ return 0;
+ }
+ case 'images': {
+ const project = loadProject(pos[0]);
+ const list = imageLog(project);
+ const total = imageSpend(project);
+ print(list.length ? list.map((e) => `${e.time.slice(0, 16)} ${e.file.padEnd(28)} ${e.model.padEnd(32)} ${e.cost_usd !== null ? '$' + e.cost_usd.toFixed(4) : '?'}`).join('\n') + `\n${list.length} image request(s), $${total.toFixed(4)}` : 'no images generated yet', { images: list, total_usd: total, models: IMAGE_MODELS });
+ return 0;
+ }
case 'voices': {
print(Object.entries(VOICES).map(([k, v]) => `${k.padEnd(12)} ${v}`).join('\n'), { voices: VOICES });
return 0;
diff --git a/src/images.js b/src/images.js
new file mode 100644
index 0000000..3c508cb
--- /dev/null
+++ b/src/images.js
@@ -0,0 +1,160 @@
+// Optional illustrations through OpenRouter. Needs OPENROUTER_API_KEY in the
+// environment or in a .env file in the project folder or the explainroo
+// folder. Every request is logged with its cost in build/images/usage.jsonl.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { ROOT } from './server.js';
+import { ProjectError } from './project.js';
+
+export const IMAGE_MODELS = {
+ best: 'openai/gpt-5.4-image-2',
+ cheap: 'google/gemini-3.1-flash-image',
+};
+
+const ASPECTS = ['16:9', '9:16', '1:1', '4:3', '3:4', '3:2', '2:3'];
+
+export const DEFAULT_STYLE =
+ 'Flat illustration for a friendly how-to video, soft colors, simple shapes, clear subject in the middle, plain light background, no text, no letters, no numbers, no logos, no watermark.';
+
+function readEnvFile(file) {
+ if (!fs.existsSync(file)) return null;
+ for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+ const m = /^\s*(?:export\s+)?OPENROUTER_API_KEY\s*=\s*(.*)\s*$/.exec(line);
+ if (m) return m[1].replace(/^["']|["']$/g, '').trim() || null;
+ }
+ return null;
+}
+
+export function findKey(projectDir) {
+ if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+ return readEnvFile(path.join(projectDir, '.env')) || readEnvFile(path.join(ROOT, '.env'));
+}
+
+export function resolveModel(name) {
+ if (!name) return IMAGE_MODELS.best;
+ if (IMAGE_MODELS[name]) return IMAGE_MODELS[name];
+ if (/^[\w.-]+\/[\w.:-]+$/.test(name)) return name;
+ throw new ProjectError(`image model must be "best", "cheap" or an OpenRouter model id like ${IMAGE_MODELS.best}`);
+}
+
+function toDataUrl(file) {
+ const ext = path.extname(file).toLowerCase().slice(1);
+ const mime = ext === 'jpg' || ext === 'jpeg' ? 'image/jpeg' : ext === 'webp' ? 'image/webp' : 'image/png';
+ return `data:${mime};base64,${fs.readFileSync(file).toString('base64')}`;
+}
+
+// Generates one image and saves it as assets/<name>.<ext>.
+export async function generateImage(project, { name, prompt, model, aspect, refs = [], style, log = () => {} }) {
+ if (!name || !/^[\w-]+$/.test(name)) throw new ProjectError('the image name may only use letters, digits, "-" and "_" (it becomes assets/<name>.png)');
+ if (!prompt || prompt.trim().length < 8) throw new ProjectError('describe the image in a sentence or two');
+ const key = findKey(project.dir);
+ if (!key) {
+ throw new ProjectError('images need an OpenRouter API key. Ask the user for one (openrouter.ai/keys), then set OPENROUTER_API_KEY or put OPENROUTER_API_KEY=... in a .env file in the explainroo folder.');
+ }
+ const cfg = project.config.images || {};
+ const modelId = resolveModel(model || cfg.model);
+ const ratio = aspect || (project.config.height > project.config.width ? '9:16' : project.config.height === project.config.width ? '1:1' : '16:9');
+ if (!ASPECTS.includes(ratio)) throw new ProjectError(`aspect must be one of ${ASPECTS.join(', ')}`);
+ const styleText = style === false ? '' : (style || cfg.style || DEFAULT_STYLE);
+ const text = `${prompt.trim()}\n\nStyle: ${styleText}\nAspect ratio: ${ratio}.`.trim();
+ const content = [{ type: 'text', text }];
+ for (const r of refs) {
+ const file = path.resolve(project.dir, r);
+ if (!fs.existsSync(file)) throw new ProjectError(`reference image ${r} does not exist`);
+ content.push({ type: 'image_url', image_url: { url: toDataUrl(file) } });
+ }
+ const body = {
+ model: modelId,
+ messages: [{ role: 'user', content }],
+ modalities: ['image', 'text'],
+ image_config: { aspect_ratio: ratio },
+ usage: { include: true },
+ };
+ const t0 = Date.now();
+ let res;
+ let json;
+ for (let attempt = 1; attempt <= 2; attempt++) {
+ const ctrl = new AbortController();
+ const timer = setTimeout(() => ctrl.abort(), 300000);
+ try {
+ res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+ method: 'POST',
+ signal: ctrl.signal,
+ headers: {
+ Authorization: `Bearer ${key}`,
+ 'Content-Type': 'application/json',
+ 'HTTP-Referer': 'https://explainroo.com',
+ 'X-Title': 'explainroo',
+ },
+ body: JSON.stringify(body),
+ });
+ json = await res.json().catch(() => null);
+ } catch (e) {
+ if (attempt === 2) throw new Error(`OpenRouter request failed: ${e.name === 'AbortError' ? 'no answer after 5 minutes' : e.message}`);
+ log('OpenRouter did not answer, trying once more');
+ continue;
+ } finally {
+ clearTimeout(timer);
+ }
+ if (res.status >= 500 && attempt === 1) {
+ log(`OpenRouter returned ${res.status}, trying once more`);
+ continue;
+ }
+ break;
+ }
+ if (!res.ok) {
+ const msg = json?.error?.message || `HTTP ${res.status}`;
+ if (res.status === 401) throw new ProjectError(`OpenRouter rejected the API key (${msg}). Ask the user to check it.`);
+ if (res.status === 402) throw new ProjectError(`the OpenRouter account has no credit left (${msg}).`);
+ throw new Error(`OpenRouter error: ${msg}`);
+ }
+ const msg = json?.choices?.[0]?.message;
+ const url = msg?.images?.[0]?.image_url?.url;
+ if (!url || !url.startsWith('data:')) {
+ const said = typeof msg?.content === 'string' ? msg.content.slice(0, 300) : '';
+ throw new Error(`the model returned no image${said ? `. It said: "${said}"` : ''}. Try another wording or the other model.`);
+ }
+ const [, mime, b64] = /^data:([^;]+);base64,(.*)$/s.exec(url) || [];
+ const ext = mime === 'image/jpeg' ? 'jpg' : mime === 'image/webp' ? 'webp' : 'png';
+ const assets = path.join(project.dir, 'assets');
+ fs.mkdirSync(assets, { recursive: true });
+ for (const e of ['png', 'jpg', 'webp']) fs.rmSync(path.join(assets, `${name}.${e}`), { force: true });
+ const file = path.join(assets, `${name}.${ext}`);
+ const buf = Buffer.from(b64, 'base64');
+ fs.writeFileSync(file, buf);
+
+ const usage = json.usage || {};
+ const entry = {
+ time: new Date().toISOString(),
+ name,
+ file: path.relative(project.dir, file),
+ provider: 'openrouter',
+ model: modelId,
+ served_by: json.model || modelId,
+ aspect: ratio,
+ prompt: prompt.trim(),
+ style: styleText,
+ refs,
+ cost_usd: typeof usage.cost === 'number' ? usage.cost : null,
+ prompt_tokens: usage.prompt_tokens ?? null,
+ completion_tokens: usage.completion_tokens ?? null,
+ seconds: Math.round((Date.now() - t0) / 100) / 10,
+ bytes: buf.length,
+ sha256: crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16),
+ };
+ const logDir = path.join(project.paths.build, 'images');
+ fs.mkdirSync(logDir, { recursive: true });
+ fs.appendFileSync(path.join(logDir, 'usage.jsonl'), JSON.stringify(entry) + '\n');
+ return { ...entry, file, total_usd: imageSpend(project) };
+}
+
+export function imageLog(project) {
+ const p = path.join(project.paths.build, 'images', 'usage.jsonl');
+ if (!fs.existsSync(p)) return [];
+ return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+export function imageSpend(project) {
+ return Math.round(imageLog(project).reduce((a, e) => a + (e.cost_usd || 0), 0) * 10000) / 10000;
+}
diff --git a/src/project.js b/src/project.js
index 7374c42..2139bfc 100644
--- a/src/project.js
+++ b/src/project.js
@@ -33,7 +33,8 @@ export const DEFAULTS = {
loudness: -14,
seed: 1,
boil: 0,
- watermark: false,
+ watermark: 'explainroo.com',
+ images: null,
};
export class ProjectError extends Error {}
@@ -71,6 +72,11 @@ export function normalizeConfig(raw) {
if (cfg.watermark !== false && !(typeof cfg.watermark === 'string' && cfg.watermark.trim() && cfg.watermark.length <= 40)) {
fail('watermark must be false or a short text of up to 40 characters, like "example.com"');
}
+ if (cfg.images !== null) {
+ if (typeof cfg.images !== 'object' || Array.isArray(cfg.images)) fail('images must be an object like { "model": "best", "style": "..." }');
+ const extra = Object.keys(cfg.images).filter((k) => !['model', 'style'].includes(k));
+ if (extra.length) fail(`images has unknown setting(s): ${extra.join(', ')}. Known: model, style`);
+ }
let music = cfg.music;
if (music === true) music = { style: THEME_MUSIC[cfg.theme] };
diff --git a/templates/starter/scenes.js b/templates/starter/scenes.js
index 8d7366a..f826b27 100644
--- a/templates/starter/scenes.js
+++ b/templates/starter/scenes.js
@@ -1,7 +1,7 @@
// One function per scene in script.md. Each function draws one frame of its
-// scene; s.t is the time in seconds since the scene started. Give elements an
-// `at` time (seconds, a spoken word, or "#mark") and the theme animates them in.
-// Full API: docs/api.md in the explainroo repository.
+// scene, and s.t is the time in seconds since the scene started. Give elements
+// an `at` time (seconds, a spoken word or "#marker") and the look animates
+// them in. The full scene API is in AGENTS.md in the explainroo folder.
export default {
hook(s) {