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.

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/>_{Portrait · 1080×1920}</td> <td align="center" width="64%"><img src="examples/list-reveal-landscape.gif" alt="list-reveal landscape" width="100%" /><br/>_{Landscape · 1920×1080}</td> </tr> </table>

_{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>}

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/>_{Portrait · 1080×1920}</td> <td align="center" width="64%"><img src="examples/flow-landscape.gif" alt="flow landscape" width="100%" /><br/>_{Landscape · 1920×1080}</td> </tr> </table>

_{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>}

comparison · two things in contrast

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

_{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>}

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/>_{Portrait · 1080×1920}</td> <td align="center" width="64%"><img src="examples/hub-landscape.gif" alt="hub landscape" width="100%" /><br/>_{Landscape · 1920×1080}</td> </tr> </table>

_{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>}

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.

---

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.

{ "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>

{ "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>

{ "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>

{ "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>

{ "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.

{ "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.

---

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.

Everything is configurable through the scene spec. You don't edit JSON, you ask the agent in plain language.

| Tell the agent | What happens in the spec | |---|---| | "Render it in dark mode" | theme: "dark" | | "Use a black background" | background: "#000000" | | "Flat background, no bloom" | bloom: false | | "Solid colour title, no gradient" | titleGradient: false | | "Put the team photo behind it" | backgroundImage: { source: "team.jpg" } | | "Make the accent red instead of lavender" | palette: { accent: "#E74C3C" } | | "Transparent background, I'll composite it myself" | background: "transparent" |

The codec auto-switches. Solid backgrounds render as H.264 MP4. The transparent setting renders as ProRes 4444 MOV with a real alpha channel.

If you want to change the default theme for every scene without saying so each time, edit src/scene/theme.ts. The palette is one object. Change the hex values and every component picks them up.

---

Manual setup

Skip this if you used the one-shot prompt above.

git clone git@github.com:alichherawalla/video-overlay-kit.git
cd video-overlay-kit
npm install

Add the kit to your project's .mcp.json or your global ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "video-overlay-kit": {
      "command": "node",
      "args": ["/absolute/path/to/video-overlay-kit/bin/mcp.mjs"]
    }
  }
}

Restart Claude Code. Three tools appear under video-overlay-kit:

• list_icons(query?, limit?) searches the Tabler library by substring. About 5,000 line icons.
• validate_scene(spec) runs the schema check before render.
• render_scene(spec, outPath?) renders to an MP4 (or .mov if the background is transparent) and returns the file path.

First render downloads a headless Chrome (about 93 MB) one time.

---

CLI

Skip the MCP entirely if you want.

npm run render examples/list-reveal.json
# -> examples/list-reveal.mp4

npm run render path/to/spec.json /where/to/save.mp4

For live iteration on a spec with auto-reload as you edit the JSON:

npm run preview
# opens Remotion Studio at http://localhost:3000

---

Why this exists

Most short-form B2B video is a talking head with overlay graphics. A title at the top. A list of three points on cue. An icon or two. Done well, the overlays carry as much of the message as the speaker.

The three paths today: hire an editor (₹500-2000 per reel, slow loop, dependency on a person), subscribe to a SaaS like Submagic ($20/month, fixed style, AI-generated quality varies), or learn After Effects (real time investment, not scriptable from your terminal).

This kit is the fourth path. A small library of components keeps the visual language consistent across every reel. The agent writes the scene spec, the renderer produces the MP4, everything runs locally.

---

Reference

Everything below is the full schema. Keep it open as a lookup when you author specs by hand.

Scene spec, top-level

| Field | Type | Default | Description | |---|---|---|---| | id | string | required | Slug for the scene. Used as the default output filename. | | durationFrames | int | required | Total length in frames. Must be 4 to 6 seconds at the given fps. Validated. | | fps | int | 30 | Frame rate. | | width | int | 1080 | Canvas width in px. | | height | int | 1920 | Canvas height in px. Default is 9:16 vertical. | | theme | "light" \| "dark" | "light" | Selects the palette. Light is the Wednesday Solutions default. | | background | string | (from theme) | CSS color or "transparent". Overrides the theme's canvas color. | | backgroundImage | object | none | { source, opacity, fit, tint, tintOpacity }. Renders behind the tracks. | | palette | object | none | Per-scene partial palette override. See Palette. | | tracks | Track[] | required | The list of tracks. |

Common track fields

| Field | Type | Default | Description | |---|---|---|---| | kind | enum | required | title-overlay, list-reveal, flow, comparison, hub, icon, text, lottie. | | id | string | required | Unique within the scene. | | startFrame | int | required | Frame at which the track becomes visible. | | endFrame | int | required | Frame at which the track is removed. | | enter | Motion | { kind: "fade", durationFrames: 8 } | Entry animation. | | exit | Motion | { kind: "none", durationFrames: 8 } | Exit animation. |

Motion (enter and exit)

{ kind, durationFrames, ease }. Available kind values:

| kind | Behavior | |---|---| | fade | Opacity ramp. | | slide-up / slide-down / slide-left / slide-right | Enters translating from 80px in the named direction. | | scale | Scale-in from 0.85 to 1.0 with opacity. | | none | No motion. |

ease: linear, easeIn, easeOut, easeInOut. Default easeOut.

Position

All track position fields are { x, y } as 0..1 fractions of the canvas. The track's geometric center is placed at that point.

Palette

Tokens defined in src/scene/theme.ts. The light palette (default):

| Token | Color | Used for | |---|---|---| | background | #F0EDF8 | Canvas | | ink | #0B0B0D | Primary text and icon strokes | | inkMuted | #3A3A4A | Secondary text | | inkDim | #6B6B7E | Tertiary text | | accent | #7A5BDC | Lavender, used for connectors and the title accent bar | | accentDeep | #5A3DB8 | Deeper lavender, reserved for pressed states | | hairline | #CCCAE0 | Hairline borders |

Dark palette inverts these. Per-scene override via palette: { accent: "#E74C3C", ... }.

Per-track field reference

Each track kind below lists the fields it accepts beyond the common fields above.

title-overlay

| Field | Type | Description | |---|---|---| | text | string | The title text. |

Position is fixed at the top of the frame. There is no position field.

list-reveal

| Field | Type | Description | |---|---|---| | position | { x, y } | Center of the list block. | | rows | Row[] (1-5) | The list rows. | | rows[].text | string | Row label. | | rows[].iconName | string? | Optional Tabler icon name. | | rows[].revealAtFrame | int | Frame (relative to startFrame) when this row appears. |

flow

| Field | Type | Description | |---|---|---| | position | { x, y } | Center of the flow block. | | nodes | Node[] (2-5) | The sequence. | | nodes[].iconName | string | Tabler icon. | | nodes[].label | string | Label below the icon. | | direction | "horizontal" | Only horizontal in v1. | | revealCadenceFrames | int | Frames between successive nodes. Default 35. |

comparison

| Field | Type | Description | |---|---|---| | position | { x, y } | Center of the comparison block. | | left, right | Side | Each: { iconName, label, subLabel? }. | | divider.label | string | Center text. Default "vs". | | divider.showLine | boolean | Whether to draw the vertical line. Default true. | | revealCadenceFrames | int | Frames between left, right, and divider reveal. Default 25. |

hub

| Field | Type | Description | |---|---|---| | position | { x, y } | Center of the hub. | | center.iconName, center.label | string | The central node. | | satellites | Satellite[] (2-4) | Each: { iconName, label }. | | revealCadenceFrames | int | Frames between center and each satellite reveal. Default 22. |

Layout is automatic by count. 2 satellites sit top and bottom. 3 form a triangle pointing up. 4 sit at cardinal positions.

icon

| Field | Type | Default | Description | |---|---|---|---| | name | string | required | Tabler icon name. | | position | { x, y } | required | Position on the canvas. | | sizePx | int | 160 | Icon size. | | color | string | (theme ink) | CSS color. | | strokeWidth | number | 2 | Stroke width. |

text

| Field | Type | Default | Description | |---|---|---|---| | text | string | required | The text. Supports \n. | | position | { x, y } | required | Position on the canvas. | | fontSizePx | int | 56 | Font size. | | color | string | (theme ink) | CSS color. | | fontWeight | 400 \| 500 \| 600 \| 700 \| 800 | 600 | Weight. | | fontFamily | string | (kit's Aeonik stack) | CSS font stack. | | align | "left" \| "center" \| "right" | "center" | Alignment. | | maxWidthPx | int | unbounded | Wrap width. |

lottie

| Field | Type | Default | Description | |---|---|---|---| | source | string | required | URL or path relative to public/. | | position | { x, y } | required | Position. | | sizePx | int | 400 | Width and height (square). | | loop | boolean | false | Loop the animation. | | playbackRate | number | 1 | Speed multiplier. |

backgroundImage

| Field | Type | Default | Description | |---|---|---|---| | source | string | required | URL, data:, or public/ path. | | opacity | number | 1 | 0..1. | | fit | "cover" \| "contain" | "cover" | CSS object-fit. | | tint | string? | none | CSS color drawn over the image. | | tintOpacity | number | 0 | Opacity of the tint layer. |

Layers stack as background color, then image, then tint, then tracks.

Constraints

• Duration is 4 to 6 seconds. Validated.
• Aspect is 9:16, 1080×1920. Default.
• Frame rate is 30 fps.
• Only Tabler icons and line-style Lottie are supported.
• Theme is the Wednesday Solutions palette. Editable in src/scene/theme.ts.

Output formats

| Background | Codec | Container | Use case | |---|---|---|---| | Any CSS color | H.264 | .mp4 | Full-frame b-roll cut into your reel. | | "transparent" | ProRes 4444 | .mov | Compositing over talking-head footage with alpha. |

Project structure

video-overlay-kit/
├── bin/mcp.mjs              # MCP launcher
├── mcp/server.ts            # MCP server: list_icons, validate_scene, render_scene
├── scripts/render.ts        # CLI entry (npm run render)
├── src/
│   ├── Root.tsx, index.ts   # Remotion entry
│   ├── scene/
│   │   ├── types.ts         # Zod schema for the whole spec
│   │   ├── theme.ts         # Palette and font family
│   │   └── Scene.tsx        # Top-level renderer
│   ├── components/          # One file per track kind
│   ├── motion/              # Enter and exit transforms
│   └── lib/render.ts        # Shared by CLI and MCP
└── examples/                # Sample specs with their rendered MP4s and GIFs

Extending

To add a new track kind (quote for example):

1. Add QuoteTrackSchema in src/scene/types.ts, include it in TrackSchema, export the type.
2. Build src/components/Quote.tsx. Use useCurrentFrame() from Remotion and trackStyle from ../motion/primitives. Read colors from usePalette() and the font from FONT_FAMILY in src/scene/theme.ts.
3. Register the case in src/scene/Scene.tsx.
4. Update the schema hint in mcp/server.ts so the agent knows the new kind exists.

The renderer and MCP tool handlers do not need changes. Copy Flow.tsx or Hub.tsx as a starting point for choreographed components.

---

Cost

Zero per render. Local CPU and disk only. Free for individual use and small teams. Check each dependency's license if you are shipping commercially.

Credits

• Remotion is the React-based video rendering engine.
• Tabler Icons is the icon library.
• LottieFiles is the Lottie animation marketplace.
• Model Context Protocol is the standard used to expose the kit to Claude Code.

Support the project

VideoOverlayKit is free and MIT-licensed. If the kit saves you time or render budget, the easiest way to give back is to sponsor the project on GitHub. Sponsorships fund new components, better defaults, and bug fixes that ship faster than I can do them in evenings.

Wednesday Solutions (wednesday.is) is the studio behind the design system. If you want a custom build, a theme that matches your brand, or production help shipping AI features for a regulated industry, that's the way to reach the team.

---

<p align="center">Made with ♥ by <a href="https://wednesday.is">Wednesday Solutions</a></p>

License

MIT.

Issues, contributions

File issues at github.com/alichherawalla/video-overlay-kit. The schema in src/scene/types.ts is the contract. Propose the spec shape first when adding a new track kind, then the component.