makevideo

makevideo

Fast, standard video generation for AI agents. One JSON script in, one finished MP4 out, rendered the same way every time. You write scenes, each with a line to say. makevideo voices them with one consistent neural voice, times every scene to the real audio, adds captions, and renders an MP4 with a bundled ffmpeg. It runs on the CPU only: no browser, no GPU, no API key and no cloud.

▶ [Your agent can make videos now](docs/your-agent-can-make-videos.mp4) (1:39, written, voiced and rendered by an agent from one JSON file) · ▶ [Watch the 87-second showcase](docs/showcase.mp4), rendered from examples/showcase.json on a laptop CPU, faster than it plays.

Short-form too: "format": "shorts" gives 1080×1920 with big word-by-word captions. ▶ Watch the TikTok-style demo (examples/tiktok.json): 23 s of video rendered in 15 s, plus an auto-exported GIF.

More examples, all made with makevideo: ▶ What's new in 0.6: game trailers (spec) · ▶ Neon Drift game trailer (beat sheet) · ▶ What's new in 0.5: documentaries (spec) · ▶ 59-second demo (spec) · ▶ The house voice · ▶ Distribution recap · ▶ What's new in 0.4: closer to every agent (spec) · ▶ What's new in 0.3: speed (spec) · ▶ What's new in 0.2 (made from one Markdown file) · ▶ Why use makevideo instead of building from scratch (spec) · ▶ Changelog video for v0.1 (spec): changelog and recap videos are a core use case.

What it does: game trailers cut on the beat, with shots filmed from your Electron + Three.js game · narrated slides · automatic transitions (push, slide, zoom, wipe) · kinetic statements · animated charts · split media + text · write Markdown, get a video · screenshots · gameplay/video clips · GIFs in and out · code · stats · quotes · before/after · TikTok/Reels/Shorts captions · custom fonts · background music · screen recording for trailers · .srt captions · poster frames.

npm i github:random00000000/makevideo

npx makevideo init # writes video.json (or: init --style documentary | shorts | explainer) npx makevideo video.json # → video.mp4 + video.srt + video.report.json + video.jpg npx makevideo video.json --fast # same, about 3x faster on a first render

import { video } from 'makevideo';

await video({ title: 'Patch notes 1.2', scenes: [ { type: 'title', title: 'Patch 1.2', subtitle: 'Siege update', say: 'Here is what is new in patch one point two.' }, { type: 'clip', src: 'siege.mp4', title: 'Rams breach gates', say: 'Rams can now breach wooden gates.' }, { type: 'bullets', title: 'Also new', items: ['Faster pathing', 'New HUD'], say: 'Also new. Pathing is faster. And the HUD is redesigned.' }, { type: 'decisions', items: ['Ship Friday?'], say: 'One decision for you. Do we ship on Friday?' }, ], });

---

Why

Agents get asked for videos all the time, and every agent builds them differently. Each video ends up with a new pipeline, a different voice, no narration unless someone asks for it, and a render that can take ten minutes. makevideo makes that one standard:

Premium by default

The goal is that an agent's *first* attempt looks finished. Without any extra config you get:

• Transitions that blend real frames. Every scene flows from the previous scene's actual last frame. auto picks push, zoom, wipe or fade based on what is cut to what. Override with "transition" globally or per scene.
• Typography that ships with the package. Inter, Montserrat and JetBrains Mono (OFL) are bundled, so a bare cloud Linux box renders exactly like your laptop.
• Depth: key-light gradient, vignette and soft panel shadows on every theme.
• Speech cleanup: write naturally. 42%, v1.2, $3M, 4.6x, 35 s, e.g. and -> are all spoken correctly, and captions keep what you wrote.
• Lint: check flags walls of text, too many bullets, unsynced lists, overlong statements, dense scenes in portrait and repetitive pacing, and says how to fix each one.

YouTube documentaries (history, science, dinosaurs)

One switch, style, sets the whole look and sound: documentary (history channels), history (adds a war-drum score), or nature (science and dinosaurs). Then write the script and say which images you want:

---

title: Tyrannosaurus rex, the tyrant lizard king style: nature thumbnailText: The real T. rex

---

Tyrannosaurus rex

The tyrant lizard king

Sixty six million years ago, the largest predator in its world...

Chapter: Built to kill

Chapter two. Built to kill.

Timeline

• 68 Mya: T. rex appears
• 66 Mya: Asteroid impact

Its story fits on one line. It appears sixty eight million years ago. It vanishes when the asteroid hits.

What you get, with no other settings:

• Image check: preview lists which file each search picked, and flags with "?" any pick whose title doesn't match the query (for example a different species). Agents can refine the search before rendering.
• Real images, licensed for publishing. (or "search": "..." in JSON) searches Wikimedia Commons. It keeps only publish-safe licenses (CC0, public domain, CC BY, CC BY-SA), never reuses an image within a video, caches downloads, and shortens over-specific searches until something matches. Each image gets a small credit line, and the full attributions go into the description.
• Cinematic motion: slow Ken Burns on every still, varied by scene (in, out, left, right, up, down; set pan / focus to override), plus chapter cards (## Chapter: ...) and timelines.
• A score: an original royalty-free music bed is synthesized for the video (music: documentary | epic | wonder | tension) and ducked under the narration.
• Broadcast loudness: the final mix is normalized to −14 LUFS, YouTube's playback target.
• A publish package: video.thumbnail.jpg (1280×720), and video.description.txt with YouTube chapter timestamps (0:00 first, each at least 10 s apart) and image credits.

▶ The T. rex example (script): 2 min 37 s, rendered from one Markdown file.

From a transcript: treat another creator's transcript as research, not as a script. Have the agent write its own narration. Republishing someone else's script is copyright infringement, and YouTube demonetizes it as "reused content".

Text on screen vs. narration (the cohesion rules)

The engine enforces these, and following them in the script makes videos land:

• The screen shows keywords; the voice says sentences. Titles, bullets and labels are short ("Faster builds"); narration is the full thought ("Builds are now twice as fast").
• Big statements use the narrator's own words. Statement words appear one by one *as they are spoken*, so put the same words in say. check warns when they don't match.
• Captions never repeat the screen. Any caption whose words are already displayed is hidden on screen automatically (the .srt keeps every line). Use captions: "all" to turn this off.

Write Markdown, get a video

---

theme: midnight brand: My Game

---

Patch 1.2

The siege update

Here is what changed in patch one point two.

Rams breach gates

• Wooden gates break in 3 hits
• Stone gates still hold

Rams now breach wooden gates. Three hits and they are down. Stone gates still hold.

Load time

• Before: 12 s
• Now: 3 s

Decisions

• Ship Friday?

npx makevideo patch-notes.md

Each #/## heading starts a scene, and its body decides the type: a list gives bullets/steps/decisions, label: number items give a chart, an image or video gives image/clip (or split, when there is text too), a code fence gives code, **42%** label gives a stat, and a paragraph gives a statement. Lines starting with > are the narration. When a scene has none, its visible text is read aloud, because narration is the default. sets scene options. See examples/whats-new-0.2.md; the 0.2 release video is that one file.

Use it from Claude Code (plugin)

/plugin marketplace add random00000000/makevideo

/plugin install makevideo@makevideo

Then just say "make a video about …". Claude writes the spec, previews it, renders it, and hands you the MP4.

The plugin bundles both the skill and the MCP server.

Use it from any MCP client

Claude Desktop, Cursor, VS Code, Codex, Windsurf and other MCP clients:

{ "mcpServers": { "makevideo": { "command": "npx", "args": ["-y", "github:random00000000/makevideo", "mcp"] } } }

It's listed in the official MCP Registry as io.github.random00000000/makevideo, as a Docker image (ghcr.io/random00000000/makevideo). Without Node, run docker run -i --rm -v "$PWD:/work" -w /work ghcr.io/random00000000/makevideo mcp.

The tools are make_video (Markdown or JSON in, MP4 out, with progress notifications), preview_video (returns the contact sheet as an image the model can look at), check_video and video_reference. See the MCP guide.

Teach every agent in a repo

npx -y github:random00000000/makevideo agents --all     # AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions

npx -y github:random00000000/makevideo agents --global # this machine: Claude Code skill + Codex AGENTS.md

This writes a short