How it works

What does a video project contain?

Every video is a folder with a few files:

videos/<name>/
  video.json    the look, size, language, voice, music and captions
  script.md     what the voice says, one "## scene" per scene
  scenes.js     one drawing function per scene
  post.json     the words for a post, optional
  recordings/   the steps for recording a real app, optional
  assets/       your images, clips, recordings, music and fonts
  build/        the voice, the timing and the sound that explainroo makes
  out/          the video, subtitles, cover, stills, contact sheets and packages
  history/      what was paid for and what was rendered

The agent writes three of these files. script.md holds the words the voice says. scenes.js is a bit of JavaScript that draws the pictures. video.json holds the settings. explainroo makes everything in build/ and out/.

history/ is the project’s record of what you paid for and what you rendered. With it, the same request never buys twice, and deleting build/ costs nothing. Keep history/ with the project. explainroo history prints the record, with the command that continues any paid job that is still open. A new project’s .gitignore keeps .env and the private parts of history/ out of git, along with the files explainroo makes.

Where does the voice come from?

Kokoro, an open voice model, reads the script aloud. It has 28 English voices and voices for seven other languages. It runs on your computer’s processor through ONNX Runtime, the software that runs the model, so it needs no graphics card. You don’t need an account or an API key for it.

Kokoro speaks each sentence on its own. explainroo cuts the silence around each one and puts a short pause between sentences. That keeps the pace even.

You can also use a paid voice or a recording you make yourself. The paid voices come from ElevenLabs and Cartesia. They receive your script and make the narration on their servers. A recording stays on your computer. One take is split into scenes using the script, or you can give each scene its own file. The voices and languages page explains both.

How does a picture appear on the right word?

When the narration is ready, Whisper listens to the recording. It writes down when each word starts and ends. explainroo matches these words with the script, and every word in the script gets a time.

In scenes.js a picture can then appear on a word. With at: 'database' it shows up the moment the voice says “database”. This step also shows when the voice said a word differently from the script. That is how explainroo catches misread names and abbreviations.

Who draws the frames?

explainroo starts Chrome in the background and loads its own drawing code. For every frame, it calls the scene function with the time of that frame. The function then draws the whole picture. Each frame depends only on the time, so the same project always gives the same video.

The frames can hold hand-drawn lines, icons, charts, code, math formulas and video clips. The lines come from Rough.js, and the 1,854 icons come from Lucide. The fonts come with explainroo.

Where do the music and the sound effects come from?

explainroo writes the music itself, as long as each video. It picks chords and instruments in a style that fits the look. The music gets quieter while the voice speaks or a clip plays sound. The sound effects follow what is on screen. A box that appears pops or makes a marker scribble, depending on the look. An arrow whooshes, and each list item plays a note.

Both the music and the sound effects are made in JavaScript. There are no sound files and no sample licenses. You can also use a music file of your own, or play a sound file on a word. See your own music.

How is the MP4 made?

explainroo draws the frames in several Chrome pages at once and hands them to ffmpeg. ffmpeg packs them into H.264 video. The sound is mixed on its own and set to a loudness of -14 LUFS. That is a common level for online video. Its peaks stay at -1 dBTP or lower, so the sound never clips. Then ffmpeg joins the picture and the sound into one MP4.

How does the agent check the video?

An agent can’t watch a video. So explainroo shows it still pictures of every scene and contact sheets. It also checks the layout, for text that is cut off or on top of other text, and the pronunciation, for words the voice got wrong. All of that happens before the final video. The checking page explains each check.

How long does it take?

A final render draws six samples per frame for the motion blur, so it takes several times as long as a draft. Once your computer has made one final, render says about how long the next one takes, from the speed it measured. render --quality fast makes a full-size video without motion blur.

Making the voice takes a little less time than the narration lasts. While it works, voice numbers each scene, like “scene 2/6”, and says about how long the rest takes. When you change the script, only the changed scenes get a new voice. Moving a marker keeps the narration and only moves the cue times.

What leaves my computer?

With Kokoro or your own recording, everything that makes the video runs on your computer. It sends no narration elsewhere and costs nothing. The speech models are downloaded from Hugging Face on first use. Japanese and Chinese also download their fonts from GitHub. On Debian and Ubuntu, doctor --fetch can download espeak-ng’s packages from your computer’s own package sources, when a language needs it. Nothing of yours goes along with these downloads. Set EXPLAINROO_OFFLINE=1 if you want to be sure no model files are fetched after that. explainroo has no telemetry, so it sends nothing about how you use it.

Some commands send something to an outside service, and only when you or your agent run them:

You run	What leaves your computer	Where it goes
connect	a test request with your key, or the code from your sign-in	that service
voice with ElevenLabs or Cartesia	the narration text	that company
voices --provider	your key, to list the voices it may use	ElevenLabs or Cartesia
image or clip	the prompt and any reference images	OpenRouter and the company that runs the model
clip --dry-run or services	a request for the list of video models and their prices, without your prompt or a key	OpenRouter
share	nothing for now, because the hosted service doesn’t run yet. Once it runs, the video file and its title	explainroo.com
publish	the video or a link to it, and the words of the post	the service you post through
publish --dry-run	your login, to read your channels or accounts	the service you post through
capture	requests for the page you name and the files it loads	that site and the servers it loads from

services sends its request at most once a day, and only when it lists clips. With ElevenLabs or Cartesia, the commands that make missing narration, like check and render, send the narration text too. Before a post that uses a link to the video, publish and its dry run ask that link for the size of its file.

Your coding agent is a separate service with its own terms and costs. The connected services page lists every outside service with what it costs.