Explainer videos and product demos made by your AI agent. Free and open source: a local voice (Kokoro), word timing (Whisper) and a canvas renderer turn a script into a narrated MP4.
JavaScript ai-agentsanimationcanvasclaude-codecodexexplainer-videoffmpegjavascriptkokoroproduct-demotext-to-speechvideo-generationwhisper
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/.gitignoreindex b958f11..24214f4 100644--- a/.gitignore+++ b/.gitignore@@ -8,3 +8,4 @@ build/out/.cache/.scratch/+.envdiff --git a/AGENTS.md b/AGENTS.mdindex 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:```bashnpm 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 scenescenes.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.mdindex 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.-[](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).*+[](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--| | | |-|---|---|---|-| [](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/explainroo-intro.mp4) | [](https://github.com/vincentsch/explainroo/releases/download/v0.1.0/how-dns-works.mp4) | [](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.```bashgit clone https://github.com/vincentsch/explainroo.gitcd explainroonpm 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`.----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-```----`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.mddeleted file mode 100644index 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.jsindex 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.jsindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.mdindex 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 explainrools "${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.```bashgit clone https://github.com/vincentsch/explainroo.git "$HOME/.explainroo"@@ -26,27 +27,21 @@ cd "$HOME/.explainroo" && npm installnode 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`:```bashexplainroo 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.jsindex 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 videorender [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+Referencevoices list voices; "explainroo say 'text' --voice am_michael" to hear onethemes list looks@@ -35,7 +41,7 @@ Referencedoctor 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.jsnew file mode 100644index 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.jsindex 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.jsindex 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) {