Skip to content
explainroo

Docs

Getting started

What you need, how to run explainroo with npx, and how to get your first video.

What do I need?

  • A coding agent. explainroo works with Claude Code, Codex, Pi and other agents that can run commands and read files. Right now it works best with Claude Code and Opus 5.5.
  • Node.js 20.11 or newer.
  • ffmpeg.
  • Google Chrome or Chromium. If you have neither, run npx playwright install chromium-headless-shell. It installs a small version of Chromium that explainroo can use.
  • About 400 MB of free disk space for the speech models.

You don’t need a graphics card. Kokoro, the free voice, and your own recordings need no API key. The outside services that cost money work with your own key, and the connected services page lists them. I develop explainroo on Linux, and its tests run on macOS and Windows too, for every change.

How do I install it?

You don’t have to clone anything. explainroo runs with npx, which comes with Node.js. Run this once, in any folder:

npx --yes explainroo doctor --fetch

--yes stops npx from waiting on its install question. doctor checks the programs explainroo needs, and the extra programs some languages need. It marks each part ready or missing, and it says how to get what is missing. A part your setup doesn’t use is not needed. --fetch also downloads the voice model and the English speech check model from Hugging Face, about 400 MB together. They go into ~/.cache/explainroo/models, and that download happens only once.

On Linux, the install also makes ONNX Runtime, which the voice uses, download its graphics card files from GitHub. explainroo doesn’t use them. When GitHub is slow, that download fails and npx stops without a word. Then put ONNXRUNTIME_NODE_INSTALL_CUDA=skip in front of the command:

ONNXRUNTIME_NODE_INSTALL_CUDA=skip npx --yes explainroo doctor --fetch

Kokoro needs espeak-ng for Spanish, French, Italian, Brazilian Portuguese and Hindi, and Python with misaki for Japanese and Chinese. English needs neither, and neither do the paid voices or recordings. Before you have a project, npx --yes explainroo doctor --language es checks what Spanish needs. npx --yes explainroo doctor --fetch --language es downloads what Spanish needs instead. That is the multilingual speech check model, 252 MB, and on Debian and Ubuntu it also sets up espeak-ng without root. Without it, the speech check model of another language downloads on first use. The voices and languages page has the install steps.

npx does not add an explainroo command to your computer. In these docs, explainroo voice and the other commands are short for npx --yes explainroo voice and so on.

Can my agent keep explainroo as a plugin?

Yes. Then the agent knows explainroo without being told about it:

  • Claude Code: /plugin marketplace add vincentsch/explainroo, then /plugin install explainroo@explainroo
  • Codex: codex plugin marketplace add vincentsch/explainroo, then codex plugin add explainroo@explainroo
  • skills.sh: npx skills add vincentsch/explainroo

How do I get my first video?

The quickest way is to copy this prompt into your agent. Put your topic in place of the brackets:

Make me a short explainer video about [your topic].
Use explainroo for it: run npx --yes explainroo docs and follow what it prints.

explainroo docs prints the instructions for coding agents. They tell the agent how to make a video and which topic to read for each step, like explainroo docs writing for the script. The agent writes the script and the scenes in a project folder. Then it makes the voice and checks its work before it saves the video. The finished file is out/video.mp4 in the project folder, for example videos/<name>/out/video.mp4. It comes with subtitle files and a cover image. The publishing page explains how to use them.

You can tell the agent more, like the length or the look. You can also ask for a tall video for Shorts, or give it your own screenshots to use. The agent asks you when it can’t go on without an answer. That happens when you want AI images or a paid voice and have no key yet, for example. When you ask for something an outside service can do, the agent shows you the choices for that step, free ones first, and you choose.

Can I make a video without an agent?

Yes. The agent only writes files and runs commands, and you can do the same:

npx --yes explainroo init videos/hello --size 16:9 --title "Hello"
npx --yes explainroo voice videos/hello
npx --yes explainroo preview videos/hello
npx --yes explainroo render videos/hello

init creates a small starter project with three scenes in the studio look, and its script.md says what to write in each one. --format product-launch starts from a whole example video instead. See formats. A project can go in any folder. voice makes the narration. preview shows the video in your browser while you work on it. It reloads when you save script.md or scenes.js. render makes the video file and writes it to videos/hello/out/video.mp4.

The example projects come with explainroo, and explainroo doctor prints their folder. Each one has its script.md and scenes.js, so you can see how a finished video is written.

The next pages explain how explainroo works, how to write the script and how to draw the scenes.

How do I change explainroo itself?

Clone it and install it:

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

In a clone, you type node bin/explainroo.js where these docs say explainroo. If you run npm link in the folder, you can type explainroo instead.