makevideo

# makevideo

[![GitHub release](https://img.shields.io/github/v/release/random00000000/makevideo)](https://github.com/random00000000/makevideo/releases) [![ci](https://github.com/random00000000/makevideo/actions/workflows/ci.yml/badge.svg)](https://github.com/random00000000/makevideo/actions/workflows/ci.yml) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.random00000000%2Fmakevideo-5ad1ff)](https://registry.modelcontextprotocol.io/v0/servers?search=makevideo) [![docs](https://img.shields.io/badge/docs-guides-ffb547)](https://random00000000.github.io/makevideo/) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE) [![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-d97757)](#use-it-from-claude-code-plugin) ![CPU only](https://img.shields.io/badge/GPU-not%20needed-success) ![no API key](https://img.shields.io/badge/API%20key-not%20needed-success)

**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.

[![poster](docs/showcase.jpg)](docs/showcase.mp4)

▶ **[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](examples/agents-make-videos.json)) · ▶ **[Watch the 87-second showcase](docs/showcase.mp4)**, rendered from [`examples/showcase.json`](examples/showcase.json) on a laptop CPU, faster than it plays.

<img src="docs/tiktok.gif" width="220" align="right" alt="TikTok-style demo">

**Short-form too:** `"format": "shorts"` gives 1080×1920 with big word-by-word captions. ▶ [Watch the TikTok-style demo](docs/tiktok.mp4) ([`examples/tiktok.json`](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](docs/whats-new-0.6.mp4) ([spec](examples/whats-new-0.6.md)) · ▶ [Neon Drift game trailer](docs/neon-drift-trailer.mp4) ([beat sheet](examples/game/trailer.md)) · ▶ [What's new in 0.5: documentaries](docs/whats-new-0.5.mp4) ([spec](examples/whats-new-0.5.md)) · ▶ [59-second demo](docs/makevideo-reddit.mp4) ([spec](examples/reddit-demo.md)) · ▶ [The house voice](examples/house-voice.md) · ▶ [Distribution recap](examples/recap-distribution.md) · ▶ [What's new in 0.4: closer to every agent](docs/whats-new-0.4.mp4) ([spec](examples/whats-new-0.4.md)) · ▶ [What's new in 0.3: speed](docs/whats-new-0.3.mp4) ([spec](examples/whats-new-0.3.md)) · ▶ [What's new in 0.2](docs/whats-new-0.2.mp4) (made from [one Markdown file](examples/whats-new-0.2.md)) · ▶ [Why use makevideo instead of building from scratch](docs/why-makevideo.mp4) ([spec](examples/why-makevideo.json)) · ▶ [Changelog video for v0.1](docs/changelog-0.1.mp4) ([spec](examples/changelog-0.1.json)): 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.
<br clear="right">

```bash
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
```

```js
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:

| | ad-hoc agent videos | `makevideo` |
|---|---|---|
| Format | a new script every time | one JSON spec ([schema](schema.json)) |
| Voice | random TTS, sometimes none | **Kokoro-82M**, same voice every time (`af_heart`) |
| Narration | must be requested | **on by default**: every scene has `say` |
| Timing | guessed | measured from the generated audio, per sentence |
| Captions | rarely | burned in, plus an `.srt` sidecar |
| Speed | minutes | **faster than real time on a CPU** (see [Performance](#performance)) |
| Verification | watch the whole thing | `makevideo preview` makes a contact sheet in about 1 s |

## 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:

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

## Tyrannosaurus rex
![Tyrannosaurus rex skeleton museum]()
The tyrant lizard king
> Sixty six million years ago, the largest predator in its world...

## Chapter: Built to kill
![Tyrannosaurus rex skull]()
> 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.** `![description]()` (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](docs/t-rex.mp4) ([script](examples/t-rex.md)): 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

```md
---
theme: midnight
brand: My Game
---
# Patch 1.2
The siege update
> Here is what changed in patch one point two.

## Rams breach gates
![](captures/ram.mp4)
- 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
<!-- highlight: Now -->
- Before: 12 s
- Now: 3 s

## Decisions
- Ship Friday?
```

```bash
npx makevideo patch-notes.md
```

Each `#`/`##` he