Skip to content
Back to search

explainroo

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vincentsch--explainroo/badge.svg)](/listings/vincentsch--explainroo)

HTML

<a href="/listings/vincentsch--explainroo"><img src="/api/listings/vincentsch--explainroo/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need Node.js 20.11 or newer, ffmpeg, and Chrome or Chromium. The first setup downloads the voice and timing models once, about 400 MB together. You don't need a graphics card. I develop and test explainroo on Linux. It should work on macOS and Windows, but I have tested it less there.

git clone https://github.com/vincentsch/explainroo.git
cd explainroo
npm install
node bin/explainroo.js doctor --fetch

Then start your agent in the `explainroo` folder and ask for a video, for example "Make a 60 second video about how HTTPS keeps a password secret." The agent follows [AGENTS.md](AGENTS.md) and saves the video as `videos/<name>/out/video.mp4`. The example videos are in [examples/](examples/), and the full documentation is on [explainroo.com](https://www.explainroo.com/docs/).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 426 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://www.explainroo.com">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="docs/media/logo-dark.png">
  5. <img src="docs/media/logo-light.png" alt="explainroo" width="340">
  6. </picture>
  7. </a>
  8. </p>
  9. <p align="center">
  10. <b>The video studio your AI agent runs.</b><br>
  11. Free and open source. The voice, the timing and the rendering run on your computer.
  12. </p>
  13. <p align="center">
  14. <a href="https://www.explainroo.com">Website</a> &nbsp;·&nbsp;
  15. <a href="https://www.explainroo.com/videos/">Example videos</a> &nbsp;·&nbsp;
  16. <a href="https://www.explainroo.com/docs/">Docs</a> &nbsp;·&nbsp;
  17. <a href="AGENTS.md">AGENTS.md</a>
  18. </p>
  19. https://github.com/user-attachments/assets/6dd5dc32-c975-4e0e-8cd4-2ef3ccc11e61
  20. <p align="center">
  21. <sub>A coding agent made this video with explainroo. You can also watch it on <a href="https://www.explainroo.com/videos/how-explainroo-makes-a-video/">explainroo.com</a>.</sub>
  22. </p>
  23. ## News
  24. - **Nov 10, 2026**: [explainroo 0.6](https://www.explainroo.com/news/explainroo-0-6/) records your real app with `explainroo record`, and a scene plays that recording with a pointer and zooms that land on the narration. New projects start in the studio look, and formats give one kind of video a ready shape. `check` and `verify` work on any video file, and `cut` edits your own recording by its words. The list of sizes moved to `explainroo sizes`.
  25. - **Nov 9, 2026**: [explainroo 0.5](https://www.explainroo.com/news/explainroo-0-5/) runs with npx, so you don't have to clone it. It can also use outside services on your own key, like AI video clips and posting to your channels. German narration works with a paid voice or your own recording. A project made before keeps its look, frame for frame, until you add `"defaults": "0.5"` to its `video.json`, which brings the new look, like bigger arrow labels.
  26. - **Oct 20, 2026**: [explainroo 0.4.1](https://www.explainroo.com/news/explainroo-0-4-1/) keeps arrow and chart labels whole while a shot holds.
  27. - **Oct 15, 2026**: [explainroo 0.4](https://www.explainroo.com/news/explainroo-0-4/) films each scene with a camera that follows the narration.
  28. - **Oct 13, 2026**: [explainroo 0.3](https://www.explainroo.com/news/explainroo-0-3/) narrates in Japanese and Mandarin Chinese, and adds the editorial look.
  29. - **Oct 13, 2026**: [explainroo 0.2](https://www.explainroo.com/news/explainroo-0-2/) adds five more languages, other voices and video clips.
  30. All news is on [explainroo.com/news](https://www.explainroo.com/news/).
  31. ## Make a video
  32. > [!TIP]
  33. > **Tell your coding agent to use explainroo, and what the video should explain.**
  34. > It works with Claude Code, Codex, Pi and other coding agents. Right now it
  35. > works best with Claude Code and Opus 5.5.
  36. Copy this into your agent and put your topic in place of the brackets:
  37. ```text
  38. Make me a short explainer video about [your topic].
  39. Use explainroo for it: run npx --yes explainroo docs and follow what it prints.
  40. ```
  41. The agent sets up explainroo, makes the video and checks it. You get an MP4
  42. file.
  43. ## How does it work?
  44. An explainer video is a short video where a voice explains a topic and
  45. drawings appear while it speaks. For explainroo, the agent writes two files.
  46. `script.md` has the words the voice says. `scenes.js` draws the pictures with
  47. a bit of JavaScript, and each drawing can appear on a word from the script.
  48. explainroo does the rest:
  49. - **Voice.** [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), an open
  50. voice model, reads the script aloud in English, Spanish, French, Italian,
  51. Brazilian Portuguese, Hindi, Japanese or Mandarin Chinese. It has 54 voices
  52. and needs no account or API key. You can also use an
  53. [ElevenLabs](https://elevenlabs.io) or [Cartesia](https://cartesia.ai) voice,
  54. or record the narration yourself. German works with one of these, because
  55. Kokoro has no German voice. One project can make the same video in several
  56. languages, with a script for each.
  57. - **Timing.** [Whisper](https://github.com/openai/whisper) listens to the
  58. narration and notes when each word is spoken.
  59. - **Pictures.** Chrome runs in the background and draws the frames. The lines
  60. can look hand drawn ([Rough.js](https://roughjs.com)), and there are 1,800
  61. icons from [Lucide](https://lucide.dev). A scene can also show charts, math
  62. formulas, code that changes step by step, your own screenshots and video
  63. clips such as screen recordings.
  64. - **Camera.** A camera films each scene. It moves in on what the voice talks
  65. about when there is time, and pulls back at the end so the last frame shows
  66. the whole idea. Cards and labels are never cut in half while a shot holds.
  67. Things arrive with a little spring, and the final video has motion blur,
  68. like a film camera.
  69. - **Sound.** explainroo makes its own background music for each video and
  70. adds small sound effects. The music gets quieter while the voice speaks.
  71. - **File.** ffmpeg puts it all together into an MP4, with subtitle files,
  72. YouTube chapters and a cover image.
  73. An agent can't watch a video, so explainroo gives it other ways to check its
  74. work. It saves stills of the scenes and a sheet of small frames for the whole
  75. video. A layout check finds text that is cut off or overlaps, and a speech
  76. check finds words the voice got wrong. For a feed-sized player,
  77. `explainroo check videos/<name> --view-width 854` also flags small text.
  78. ## Check or cut any video
  79. `check` and `verify` also take a video file made with any tool:
  80. ```bash
  81. npx --yes explainroo check talk.mp4 --script script.txt
  82. ```
  83. They report:
  84. - black or blank frames, and stretches where the picture stands still
  85. - silence, the loudness and the true peak
  86. - text too small to read on a phone, found in frames of the video
  87. - with `--script`, the words of your script that the speech model didn't hear
  88. `--json` gives the same report for your agent.
  89. `explainroo cut talk.mp4` edits your own recording by its words. It writes
  90. `talk.cut.md`, one sentence a line with the time of each word. Your agent
  91. deletes words and long pauses there. Then `explainroo cut talk.mp4 --apply`
  92. writes `talk.cut.mp4`, with a short crossfade at every join so the cuts don't
  93. click. Both run on your computer, like the rest of explainroo.
  94. ## What leaves your computer
  95. Making a video needs no account and no key, and it costs nothing. The voice,
  96. the timing, the music and the rendering run on your computer. Your coding agent
  97. is a separate service with its own terms and prices.
  98. Some commands send something to an outside service, and only when you or your
  99. agent run them:
  100. | You run | What leaves your computer | Where it goes |
  101. | --- | --- | --- |
  102. | `connect` | A test request with your key, or the code from your sign-in | That service |
  103. | `voice` with ElevenLabs or Cartesia | The narration text | That company |
  104. | `voices --provider elevenlabs` or `cartesia` | Your key, to list its voices | That company |
  105. | `image` or `clip` | The prompt and any reference images | OpenRouter and the model's provider |
  106. | `clip --dry-run` | A request for the list of video models and their prices, without your prompt or a key | OpenRouter |
  107. | `services`, when it lists clips | The same request as `clip --dry-run`, at most once a day. It asks for the list of video models and their prices, without your prompt or a key | OpenRouter |
  108. | `share` | Nothing in this version, because the hosted service is coming. Once it runs, the video file and its title | explainroo.com |
  109. | `publish` | The video or a link to it, its title and its text. With a link, first a request for the size of the file there | YouTube, Buffer or Blotato, and whatever they send it to. The size request goes to the host of the link |
  110. | `publish --dry-run` | Your login, to read your channels or accounts, and the same size request | YouTube, Buffer or Blotato, and the host of the link |
  111. | `capture` | Requests for the page you name and the files it loads | That site and the servers it loads from |
  112. | `formats add --yes` | A git clone of the address you name. Without `--yes` it only prints what it will run | The host of that Git repository |
  113. | `presenter` | The narration of one scene, as sound, and the id of the avatar. `--avatars` and `--dry-run` send only your key | The presenter service you set up. None is built in yet |
  114. With ElevenLabs or Cartesia, the commands that make missing narration, like
  115. `check` and `render`, send the narration text too.
  116. The first run downloads the voice and speech models from Hugging Face. Other
  117. languages need one more speech model, which downloads the first time, and
  118. Japanese and Chinese also download their fonts from GitHub. On Debian and
  119. Ubuntu, `doctor --fetch` downloads espeak-ng's packages from the computer's own
  120. package sources when a language needs it. Nothing of yours goes along with
  121. these downloads. explainroo has no telemetry, so it sends
  122. nothing about how you use it.
  123. Nothing uploads to the hosted service without the explicit `explainroo share`
  124. command. In this version `share` sends nothing at all, because the service
  125. doesn't run yet.
  126. ## Looks
  127. There are seven looks: studio, paper, clean, chalk, blueprint, midnight and
  128. editorial. A new project starts in studio, which is light and calm, with white
  129. cards and lists on cards. You change a video's look with one setting in
  130. `video.json`. A project can also bring its own look, a small JSON file with its
  131. colors, fonts and background. Here is one frame in six of the built-in looks,
  132. from the example videos.
  133. <p align="center">
  134. <picture>
  135. <source media="(prefers-color-scheme: dark)" srcset="docs/media/looks-dark.webp">
  136. <img src="docs/media/looks-light.webp" alt="Frames from six example videos, one in each look: paper, clean, chalk, blueprint, midnight and editorial" width="820">
  137. </picture>
  138. </p>
  139. ## Sizes
  140. You pick the size for the place the video goes. YouTube videos are wide, and
  141. Shorts, TikTok and Reels are tall. Instagram and LinkedIn posts use 4:5, and
  142. there is a square size too. Shorts, TikTok and Reels put their own buttons
  143. over the video, and explainroo keeps your text out of those spots.
  144. <p align="center">
  145. <picture>
  146. <source media="(prefers-color-scheme: dark)" srcset="docs/media/sizes-dark.webp">
  147. <img src="docs/media/sizes-light.webp" alt="Frames from example videos in four sizes: YouTube 16:9, TikTok 9:16, LinkedIn 4:5 and square" width="820">
  148. </picture>
  149. </p>
  150. Tall, 4:5 and square videos get captions that light up word by word.
  151. `"captions": "bold"` shows two to four big words at a time instead, with
  152. numbers and marked words in color. For Shorts, TikTok and Reels, `s.short`
  153. draws the parts short videos often have, like a hook title that is there on the
  154. first frame (`explainroo docs short-video`). One project can render several
  155. sizes: `explainroo render videos/demo --size tiktok` writes the TikTok version
  156. next to the wide one. `"sizes"` in `video.json` gives one size settings of its
  157. own, like bold captions and a quicker pace for TikTok only.
  158. ## More than an MP4
  159. Every render also writes subtitle files (`.srt` and `.vtt`) that YouTube and
  160. LinkedIn accept, a cover image for the thumbnail, and YouTube chapters when
  161. the script names them. `--format gif` makes a GIF for a README or a post.
  162. `--transparent --format mov` makes a video with a transparent background, for
  163. putting a diagram over camera footage in a video editor. `explainroo export`
  164. writes a small web player that draws the video sharp at any size and embeds
  165. with an iframe.
  166. ## Pace
  167. `"pace": 1.2` in a video's `video.json` makes the voice, the pauses and the
  168. animations 20% quicker. The music gets a little quicker too. Pace goes from
  169. 0.7 to 1.6, and 1 is normal.
  170. ## Product demos
  171. explainroo can also make product demos, the videos software companies make to
  172. show their app. The agent rebuilds the app's screens from its code or its
  173. website, with the same colors, fonts and button labels. A mouse pointer then
  174. clicks through the screens and types into the fields. Tell your agent which
  175. product it is and where to find its code or website. `explainroo capture`
  176. saves the live site's screenshots, colors, font files, logo and wording first,
  177. with the page's text and a list of its images. A real screen recording can
  178. play inside a scene too.
  179. <p align="center">
  180. <a href="https://www.explainroo.com/videos/unspar-product-demo/">
  181. <img src="docs/media/product-demo.webp" alt="A frame from the Unspar product demo: a form with a website field and an open dropdown" width="820">
  182. </a>
  183. </p>
  184. Here are the demos for [Unspar](https://www.explainroo.com/videos/unspar-product-demo/)
  185. and [Vroni](https://www.explainroo.com/videos/vroni-product-demo/), two of my
  186. own products. The files for the Unspar demo are in
  187. [examples/unspar-demo](examples/unspar-demo). explainroo.com also has
  188. unofficial demos of [Gmail, ChatGPT and Claude](https://www.explainroo.com/videos/#product-demos).
  189. ## Formats
  190. A format is a ready way of making one kind of video, with a short guide for
  191. your agent, scene helpers, settings and a whole example video. Four come with
  192. explainroo:
  193. | Format | For |
  194. | --- | --- |
  195. | `product-launch` | a launch video of about a minute |
  196. | `narrated-explainer` | one idea explained in about a minute |
  197. | `vertical-short` | a short for Shorts, TikTok and Reels, with the hook in the first second |
  198. | `product-ad` | an ad of 15 to 30 seconds for a feed |
  199. `explainroo init videos/acme --format product-launch` starts from one.
  200. Anyone can publish a format as a Git repository, and
  201. `explainroo formats add <address>` installs it. It first prints the git
  202. commands it will run and installs only with `--yes`. A format's code runs
  203. only when you make a video from it, and its author is named in the credits of
  204. every package (`explainroo docs formats`).
  205. ## Outside services
  206. Each step of making a video has a free choice first. The services that cost
  207. money use your own account and key:
  208. | Step | Free | Costs money |
  209. | --- | --- | --- |
  210. | Voice | Kokoro, or your own recording | ElevenLabs, Cartesia |
  211. | Timing | Whisper | |
  212. | Images | The built-in icons and your own files | OpenRouter |
  213. | Clips | Your own footage | OpenRouter |
  214. | Presenters | Film yourself | An AI presenter service (coming, none built in yet) |
  215. | Music | The built-in music, your own file, or Soundroo | |
  216. | Sharing | A web player for your own site, or a link from `share` (coming) | |
  217. | Posting | A package you upload yourself, YouTube, or Buffer on its free plan | Blotato |
  218. `explainroo services` lists every choice with what it costs and what data
  219. leaves your computer. For clips it also shows today's price per second.
  220. `explainroo connect <service>` sets one up and tests your key or login. One
  221. OpenRouter key makes images and clips. explainroo's instructions tell your
  222. agent to show you the options, free ones first, and to let you choose.
  223. A project keeps a record of what was paid for in its `history/` folder. The
  224. same request again uses the file it already bought. After a crash, a clip that
  225. was already ordered is picked up again, and a request whose outcome is unknown
  226. is never sent again by itself. `explainroo history` shows the record, and
  227. `explainroo docs connectors` says how to add a service.
  228. ## Presenters
  229. A presenter is a person who talks on screen next to the product. The free
  230. choice is to film yourself. `explainroo presenter` can also make a clip of an
  231. AI presenter who speaks the narration of a scene, through a presenter service
  232. you pick. The code and its rules are built, and no presenter service is built
  233. in yet. explainroo never makes a real person's face or voice without the
  234. service's consent flow, and every package of a video with an AI presenter gets
  235. the AI label (`explainroo docs presenters`).
  236. ## AI video clips
  237. `explainroo clip` buys a short video clip that an AI model makes from a text
  238. prompt. It goes through OpenRouter on your own key, and the clip plays in a
  239. scene like any other video file. `--dry-run` shows the price and spends
  240. nothing, also before you have a project, and it lists the lengths the model
  241. takes. A paid run needs `--max-cost` or a budget. Before it buys, `clip` checks
  242. the price against that cap and stops when the price is higher. The final cost
  243. is known only after the job, and it can come out a little higher than the
  244. price. `"clipBudget": 0.40` in `video.json`, or `--budget 0.40`, is one
  245. budget for all clips of a video. With it `--max-cost` is optional, and `clip`
  246. stops before a clip that would go over it. Clips work for short shots of the real world,
  247. like a street or food. They get text and diagrams wrong, and a character looks
  248. different in each clip.
  249. `explainroo docs clips` has the details.
  250. ## Music and sound files
  251. A video can play your own music file instead of the built-in music. explainroo
  252. brings it to the level of the built-in music and lowers it while the voice
  253. speaks. `s.sound` plays a sound file on a word. [Soundroo](https://www.soundroo.com)
  254. is a free tool where your agent writes original music, and it renders the
  255. track on your computer. `explainroo docs music` has the details.
  256. ## Posting a video
  257. `explainroo package` writes a folder with everything needed to post a video on
  258. one platform: YouTube, Shorts, TikTok, Reels, LinkedIn or X. Next to the video
  259. at the right size, it holds the words for the post. It also says whether to mark
  260. the post as made with AI, and why. You can upload the folder yourself.
  261. `explainroo share` uploads a finished video to explainroo.com and gives back a
  262. page link. That hosted service is coming. Until it runs, `share` sends nothing,
  263. says so and makes no link.
  264. `explainroo publish` posts a package through YouTube, Buffer or Blotato, with
  265. your own account. `--dry-run` shows the exact post first, and a real run posts
  266. only after a yes. `explainroo docs publishing` has the details.
  267. ## Partners
  268. Partners are coming. A partner will be a company that pays to be built in as
  269. one of the choices for a step. There are none yet. `explainroo services`
  270. always labels a partner as a "paid partner", and the free choices stay first
  271. in every step. explainroo's instructions tell your agent never to pick a paid
  272. service for you.
  273. ## Install it yourself
  274. ```bash
  275. npx --yes explainroo doctor --fetch
  276. ```
  277. This checks your computer and downloads the voice and timing models once,
  278. about 400 MB together. You don't have to clone anything. You need Node.js
  279. 20.11 or newer, ffmpeg, and Chrome or Chromium. You don't need a graphics
  280. card. I develop explainroo on Linux, and its tests run on Linux, macOS and
  281. Windows for every change.
  282. On Linux, installing explainroo also makes ONNX Runtime, which the voice uses,
  283. download its graphics card files from GitHub. explainroo doesn't use them. When
  284. GitHub is slow, that download fails and `npx` stops without a word. Put
  285. `ONNXRUNTIME_NODE_INSTALL_CUDA=skip` in front of the command to leave the
  286. download out:
  287. ```bash
  288. ONNXRUNTIME_NODE_INSTALL_CUDA=skip npx --yes explainroo doctor --fetch
  289. ```
  290. For narration with Kokoro, the free voice, in Spanish, French, Italian,
  291. Portuguese or Hindi, also install
  292. [espeak-ng](https://github.com/espeak-ng/espeak-ng), for example with
  293. `sudo apt install espeak-ng` or `brew install espeak-ng`.
  294. `npx --yes explainroo doctor --language es` checks what Spanish needs. On Debian
  295. and Ubuntu without root, `npx --yes explainroo doctor --fetch --language es`
  296. puts a copy of espeak-ng in explainroo's cache folder instead. Japanese and
  297. Chinese need Python with [misaki](https://github.com/hexgrad/misaki) instead,
  298. as described in [docs/japanese-and-chinese.md](docs/japanese-and-chinese.md).
  299. German narration needs neither, and it works with ElevenLabs, Cartesia or your
  300. own recording, as [docs/languages.md](docs/languages.md) describes.
  301. Then ask your agent for a video in any folder, for example "Make a 60 second
  302. video about how HTTPS keeps a password secret. Use explainroo: run
  303. npx --yes explainroo docs and follow what it prints." The agent saves the
  304. video in its project folder as `out/video.mp4`. The example videos are in
  305. [examples/](examples/), and their sources come with the package too, in the
  306. folder that `explainroo doctor` prints. The full documentation is on
  307. [explainroo.com](https://www.explainroo.com/docs/).
  308. Your agent can also keep explainroo as a plugin or skill, so it knows the tool
  309. without being told:
  310. - Claude Code: `/plugin marketplace add vincentsch/explainroo`, then
  311. `/plugin install explainroo@explainroo`
  312. - Codex: `codex plugin marketplace add vincentsch/explainroo`, then
  313. `codex plugin add explainroo@explainroo`
  314. - skills.sh: `npx skills add vincentsch/explainroo`
  315. To change the code, clone it instead:
  316. ```bash
  317. git clone https://github.com/vincentsch/explainroo.git
  318. cd explainroo
  319. npm install
  320. node bin/explainroo.js doctor --fetch
  321. ```
  322. ## The watermark
  323. Each video has a small "explainroo.com" in one corner. `"watermark": false` in
  324. `video.json` turns it off. Please keep it if you can, because that is how
  325. other people find explainroo. A TikTok package has no watermark, because
  326. TikTok's rules don't allow apps to add one. The
  327. [publishing page](docs/publishing.md#why-the-tiktok-file-has-no-watermark)
  328. quotes them.
  329. ## Credits and license
  330. explainroo is MIT licensed. The voice comes from
  331. [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), and the word timing from
  332. [Whisper](https://github.com/openai/whisper) through
  333. [Transformers.js](https://github.com/huggingface/transformers.js). The
  334. drawings use [Rough.js](https://roughjs.com) and [Lucide](https://lucide.dev)
  335. icons. [MathJax](https://www.mathjax.org) typesets the formulas.
  336. [Playwright](https://playwright.dev) runs Chrome, and
  337. [ffmpeg](https://ffmpeg.org) makes the video file. For other languages,
  338. explainroo runs [espeak-ng](https://github.com/espeak-ng/espeak-ng) as a
  339. separate program, with phoneme rules from Kokoro's
  340. [misaki](https://github.com/hexgrad/misaki), and misaki itself for Japanese
  341. and Chinese. [OpenCC](https://github.com/nk2028/opencc-js) and
  342. [pinyin-pro](https://github.com/zh-lx/pinyin-pro) help the speech check
  343. compare Chinese, and [HarfBuzz](https://github.com/harfbuzz/harfbuzzjs) keeps
  344. web player fonts small. The fonts, including Noto Sans CJK for Japanese and
  345. Chinese, are under the SIL Open Font License.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.