video-overlay-kit

<p align="center">
  <img src="docs/assets/logo.png" alt="VideoOverlayKit logo" width="120" />
</p>

<h1 align="center">VideoOverlayKit</h1>

<p align="center"><strong>Make b-roll for your videos. Tell an agent what you want. Get an MP4 back.</strong></p>

<p align="center">
  <em>Free · zero per-render cost · MIT · MCP-driven · runs on your machine</em>
</p>

<p align="center">
  <img src="docs/assets/og.png" alt="VideoOverlayKit cover" width="100%" />
</p>

---

**Make b-roll for your videos. Tell an agent what you want. Get an MP4 back.**

Zero per-render cost. Wednesday Solutions design system as the default theme. Built for people who ship a lot of short-form video and don't want to learn After Effects. Works with any MCP-compatible agent — Claude Code, Codex, OpenCode, Cursor, Cline, or anything else that speaks the [Model Context Protocol](https://modelcontextprotocol.io/).

Same scene spec, both orientations. Portrait fits TikTok / Instagram Reels / YouTube Shorts. Landscape fits YouTube / desktop / TV. The kit auto-flips the layout based on the canvas aspect.

### `list-reveal` · a title and three points appearing on cue

<table>
  <tr>
    <td align="center" width="36%"><img src="examples/list-reveal.gif" alt="list-reveal portrait" width="100%" /><br/><sub>Portrait · 1080×1920</sub></td>
    <td align="center" width="64%"><img src="examples/list-reveal-landscape.gif" alt="list-reveal landscape" width="100%" /><br/><sub>Landscape · 1920×1080</sub></td>
  </tr>
</table>

<sub>Portrait <a href="examples/list-reveal.json">spec</a> · <a href="examples/list-reveal.mp4">mp4</a> &nbsp; • &nbsp; Landscape <a href="examples/list-reveal-landscape.json">spec</a> · <a href="examples/list-reveal-landscape.mp4">mp4</a></sub>

### `flow` · a process from A to B to C

<table>
  <tr>
    <td align="center" width="36%"><img src="examples/flow.gif" alt="flow portrait" width="100%" /><br/><sub>Portrait · 1080×1920</sub></td>
    <td align="center" width="64%"><img src="examples/flow-landscape.gif" alt="flow landscape" width="100%" /><br/><sub>Landscape · 1920×1080</sub></td>
  </tr>
</table>

<sub>Portrait <a href="examples/flow.json">spec</a> · <a href="examples/flow.mp4">mp4</a> &nbsp; • &nbsp; Landscape <a href="examples/flow-landscape.json">spec</a> · <a href="examples/flow-landscape.mp4">mp4</a></sub>

### `comparison` · two things in contrast

<table>
  <tr>
    <td align="center" width="36%"><img src="examples/comparison.gif" alt="comparison portrait" width="100%" /><br/><sub>Portrait · 1080×1920</sub></td>
    <td align="center" width="64%"><img src="examples/comparison-landscape.gif" alt="comparison landscape" width="100%" /><br/><sub>Landscape · 1920×1080</sub></td>
  </tr>
</table>

<sub>Portrait <a href="examples/comparison.json">spec</a> · <a href="examples/comparison.mp4">mp4</a> &nbsp; • &nbsp; Landscape <a href="examples/comparison-landscape.json">spec</a> · <a href="examples/comparison-landscape.mp4">mp4</a></sub>

### `hub` · a centre concept with satellites pointing in

<table>
  <tr>
    <td align="center" width="36%"><img src="examples/hub.gif" alt="hub portrait" width="100%" /><br/><sub>Portrait · 1080×1920</sub></td>
    <td align="center" width="64%"><img src="examples/hub-landscape.gif" alt="hub landscape" width="100%" /><br/><sub>Landscape · 1920×1080</sub></td>
  </tr>
</table>

<sub>Portrait <a href="examples/hub.json">spec</a> · <a href="examples/hub.mp4">mp4</a> &nbsp; • &nbsp; Landscape <a href="examples/hub-landscape.json">spec</a> · <a href="examples/hub-landscape.mp4">mp4</a></sub>

Every clip above is real output. 5 to 6 seconds. Wednesday Solutions design system as the default theme. Click any `mp4` link for the full-quality version.

---

## Start here

Paste this into a fresh session of any MCP-compatible coding agent (Claude Code, Codex, OpenCode, Cursor, Cline, etc). The agent does the whole setup. It clones the repo, installs deps, wires the MCP into your config, and verifies it works.

```
Set up github.com/alichherawalla/video-overlay-kit as an MCP server in
my coding agent.

1. Clone the repo to ~/code/video-overlay-kit (or ask me where to put it
   if that path is taken).
2. Run `npm install` inside the cloned directory.
3. Find my MCP config file and add a `video-overlay-kit` entry that runs
   `node <absolute-cloned-path>/bin/mcp.mjs`. Pick the right path for my
   agent:
     - Claude Code: `.mcp.json` in the current repo, otherwise
       `~/.claude/mcp_settings.json`.
     - Codex / OpenCode: their MCP config (usually `~/.codex/mcp.json`
       or similar — ask me if you can't find it).
     - Cursor / Cline: their MCP settings in the IDE config.
   Preserve any existing MCP servers in the config.
4. Verify the server starts by sending it a `tools/list` JSON-RPC request
   over stdio and confirming the tools `list_icons`, `validate_scene`, and
   `render_scene` come back.
5. Tell me to restart my agent so the new MCP server is picked up.

After setup, read the README at the cloned repo so you know how to author
scene specs. Default to the Wednesday Solutions light theme and 5-second
duration unless I say otherwise.
```

Restart Claude Code. Now ask for a video:

> "Make me a 5-second overlay titled 'A runbook for every incident' with three rows: drift, prompt injection, exfil attempts."

The agent picks the icons, writes the scene spec, renders the MP4, hands you the file path. Drop it into your editor.

If you want to wire the MCP yourself instead, skip to [Manual setup](#manual-setup).

---

## What you can make

Eight building blocks. Combine any of them inside a single 4-to-6-second scene.

### `title-overlay`

The deliverable bar at the top of the frame. Use this on every scene. It is the one-line promise of what the viewer is about to see.

If a stranger reads the title and can't immediately tell what the video is about, rewrite it.

The bar lives at the top of the frame with a thin lavender accent underneath. 80pt bold, centered. You don't pick the position, it is fixed.

```jsonc
{ "kind": "title-overlay", "id": "agenda",
  "text": "How to control AI traffic",
  "startFrame": 0, "endFrame": 150 }
```

### `list-reveal`

A vertical list of 1 to 5 rows. Each row gets an optional icon and reveals on a frame you specify.

Use this when you have a list of things to show, between 1 and 5 of them.

<p align="center"><img src="examples/list-reveal.gif" alt="list-reveal preview" width="320" /></p>

```jsonc
{ "kind": "list-reveal", "id": "outcomes",
  "position": { "x": 0.5, "y": 0.55 },
  "startFrame": 20, "endFrame": 150,
  "rows": [
    { "text": "One gateway in front of every model",          "iconName": "IconShield",   "revealAtFrame":  0 },
    { "text": "Input policy. Output policy.",                 "iconName": "IconFilter",   "revealAtFrame": 35 },
    { "text": "Every prompt, every dollar, every output",     "iconName": "IconChartBar", "revealAtFrame": 70 }
  ]
}
```

### `flow`

A horizontal sequence of 2 to 5 nodes. Each node appears, an arrow draws toward the next one, the next node appears.

Use this when the meaning is in the sequence. Incident detected leads to runbook activated leads to contained.

<p align="center"><img src="examples/flow.gif" alt="flow preview" width="320" /></p>

```jsonc
{ "kind": "flow", "id": "incident-flow",
  "startFrame": 20, "endFrame": 150,
  "nodes": [
    { "iconName": "IconAlertOctagon", "label": "Incident" },
    { "iconName": "IconBook2",        "label": "Runbook" },
    { "iconName": "IconCircleCheck",  "label": "Contained" }
  ]
}
```

### `comparison`

Two icons side by side with a configurable divider in the middle. Each side has a label and an optional sub-label.

Use this for binary contrasts. Old way against new way is the canonical example.

The divider word is configurable. `"vs"` is the default for opposition; swap to `"+"` or `"→"` when the relationship is additive or transitional.

<p align="center"><img src="examples/comparison.gif" alt="comparison preview" width="320" /></p>

```jsonc
{ "kind": "comparison", "id": "old-vs-new",
  "startFrame": 20, "endFrame": 180,
  "left":  { "iconName": "IconClockHour3", "label": "Old way", "subLabel": "Manual review" },
  "right": { "iconName": "IconBolt",       "label": "New way", "subLabel": "Automated checks" },
  "divider": { "label": "vs", "showLine": true }
}
```

### `hub`

A central icon with 2 to 4 satellites around it. The center appears first, then each satellite reveals with a line drawing in from the center.

Use this when one thing is at the centre and other things hang off it. A gateway that controls policy, logging, cost, and swap is a hub.

<p align="center"><img src="examples/hub.gif" alt="hub preview" width="320" /></p>

```jsonc
{ "kind": "hub", "id": "gateway-hub",
  "startFrame": 20, "endFrame": 150,
  "center": { "iconName": "IconShield", "label": "Gateway" },
  "satellites": [
    { "iconName": "IconLock",     "label": "Policy" },
    { "iconName": "IconActivity", "label": "Logging" },
    { "iconName": "IconCoin",     "label": "Cost" },
    { "iconName": "IconRefresh",  "label": "Swap" }
  ]
}
```

### `icon`, `text`, `lottie`

The escape hatches. Drop a single Tabler icon anywhere on the canvas, a free-position text block, or a pre-animated Lottie animation. Use these when the composite components above don't fit.

```jsonc
{ "kind": "icon", "id": "hero", "name": "IconShieldCheck",
  "position": { "x": 0.5, "y": 0.45 }, "sizePx": 240,
  "startFrame": 10, "endFrame": 150 }
```

Most users never read the full field reference for these. The agent reads the schema for you. If you want every field listed out, jump to the [reference section](#reference).

---

## Customize the look

The kit ships with the Wednesday Solutions palette. Lavender accent on a warm off-white canvas. Every scene also gets an ambient bloom gradient behind the tracks and a sunset gradient on the title text by default. This is what "polished" looks like out of the box.

Everythin