How to Make a Narrated Explainer Video with Claude Code and explainroo

You can create a narrated explainer video without a traditional video editor by combining Claude Code with explainroo. Claude Code is the coding agent. It plans the video, writes the narration and scene instructions, runs commands, and revises the project. explainroo turns the files into a narrated MP4 on your computer.

This workflow produces animated explainers and product demos built from diagrams, icons, charts, code, screenshots, and simulated user interfaces. It does not create live-action footage or talking avatars. The strongest results explain technical ideas, teach a process, or demonstrate how software works.

A typical project contains three important files:

• script.md holds the narrator’s spoken words.
• scenes.js contains JavaScript instructions for drawing each scene.
• video.json controls settings such as format, visual style, voice, and pace.

The result is an editable video project rather than a single unchangeable generated file.

What Claude Code and explainroo each do

Claude Code is a coding agent that can read project instructions, edit files, run shell commands, and inspect generated images. explainroo is the local rendering toolkit. It uses Kokoro, an open voice model, to read the script. Whisper identifies when each word is spoken. Chrome or Chromium draws frames on an HTML canvas, and ffmpeg assembles those frames with the voice, music, and sound effects into an MP4.

Claude Code writes the project, then explainroo renders it. For the agent to review, explainroo creates still frames and contact sheets, along with layout and speech checks. Anthropic also recommends giving coding agents clear ways to check their work, such as tests and builds. See Claude Code’s best practices for the general principle.

Prepare the topic before you prompt the agent

Decide four things first: the audience, the lesson or product feature, the target platform, and the facts the narration must use. A one-minute explainer is roughly 150 spoken words, including pauses. Keep the topic narrow enough that each scene can communicate one idea.

For factual topics, provide official documentation, research, product pages, screenshots, or source code. Tell Claude Code to use only those materials and flag claims that need review. Verify medical, financial, legal, product, and time-sensitive claims yourself.

Choose the output format in advance. explainroo supports wide, vertical, portrait, and square video for common platforms. Some formats support captions that highlight words as they are spoken.

Install explainroo and its local dependencies

The documented setup requires Node.js 20.11 or newer. It also requires ffmpeg and Chrome or Chromium. The first setup downloads the voice and timing models, which require about 400 MB. A graphics card is not required. explainroo is developed and tested on Linux, while macOS and Windows have received less testing.

Run:

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

Run Claude Code from a dedicated project folder and review commands before approving them. The Claude Code permissions guidance recommends controlled permissions and isolated environments for risky work.

Give Claude Code a focused video brief

The simplest explainroo prompt is:

Make me a short explainer video about [your topic]. Use explainroo for it: clone https://github.com/vincentsch/explainroo, read its AGENTS.md and follow the steps.

A stronger brief adds the audience, format, sources, tone, and review requirements:

Create a 60-second narrated explainer video for beginners about [topic].

Use explainroo. Clone the repository, read AGENTS.md, and follow its workflow.
Use only these factual sources: [URLs or local files].
Format the video for [your target platform and supported format].
Use one main idea per scene and explain technical terms when they first appear.
Run the voice, check, still, sheet, draft render, final render, and verify steps.
Report the output path and anything that still needs human review.

The agent sets up the project and writes the files. It then checks the video and provides an MP4. explainroo’s public project changes over time, so record the repository commit used for a production video and test the workflow before publishing.

Edit the narration and synchronize the visuals

Scene headings in script.md organize the narration. Markers such as [#lock] mark when a visual should appear:

## introduction

Your browser uses HTTPS to protect information during a connection. [#lock]

## summary

The lock symbol indicates that the connection is encrypted.

Although the marker is silent, it tells the matching scene in scenes.js when to display an icon, title, arrow, or animation. You can also link visuals to a spoken word or phrase. explainroo uses Whisper to record word-level timings, so the animation follows the actual generated narration.

Use pronunciation controls for acronyms, domains, product names, and version numbers:

{CLI|C L I}
{example.com|example dot com}
{v2.1|version two point one}

The first form appears in captions while the second form is spoken.

In scenes.js, each scene function draws its visuals. For example:

export default {
  introduction(s) {
    s.title("How HTTPS protects data", { at: 0 });
    s.icon("lock", {
      x: 960,
      y: 620,
      size: 220,
      color: "accent",
      at: "#lock",
    });
  },
};

The at: "#lock" setting means the lock appears when narration reaches the lock marker. explainroo provides Lucide icons, charts, code layouts, screenshots, and optional hand-drawn lines through Rough.js. Keep labels short, use large text, and change the visual focus every few seconds.

Use explainroo for product demos

For a product demo, tell Claude Code which product to recreate and provide its website or code location. The agent can rebuild screens with the product’s colors, fonts, and button labels. A pointer can click through screens and type into fields while the narration explains each step.

This approach works well for showing a user journey or feature flow. Compare every simulated screen with the real product, especially if the video describes current behavior.

Set the overall look in video.json. explainroo includes five styles: paper, clean, chalk, blueprint, and midnight. The pace setting controls the speed of the voice, pauses, and animations. Adjust the format and theme together so the composition fits the intended platform.

Check the video before publishing

Ask the agent to run:

node bin/explainroo.js voice videos/<name>
node bin/explainroo.js check videos/<name>
node bin/explainroo.js still videos/<name>
node bin/explainroo.js sheet videos/<name>
node bin/explainroo.js render videos/<name> --draft
node bin/explainroo.js render videos/<name>
node bin/explainroo.js verify videos/<name>

The final file is saved at videos/<name>/out/video.mp4.

The checks flag cut-off or overlapping text, invalid word cues, missing icons, weak contrast, black frames, long silence, loudness problems, and speech mismatches. A contact sheet lets Claude Code review the visual rhythm across the video.

Automated checks cannot tell whether the explanation is accurate or easy to understand. Watch the draft with sound and verify the facts. Check that you have permission to use screenshots and logos. Review every AI-generated illustration. Optional image generation uses OpenRouter and is paid per image. The core explainroo rendering pipeline runs locally, while Claude Code remains a separate service with its own access and pricing.