Video Overlay Kit

VideoOverlayKit

为视频制作 B-roll。告诉 Agent 你的需求，即可获得 MP4 文件。

免费 · 渲染零成本 · MIT · 由 MCP 驱动 · 在本机运行

---

为视频制作 B-roll。告诉 Agent 你的需求，即可获得 MP4 文件。

渲染零成本。默认采用 Wednesday Solutions 设计系统。专为经常制作短视频、又不想学习 After Effects 的人打造。适用于任何兼容 MCP 的 Agent——Claude Code、Codex、OpenCode、Cursor、Cline，或任何支持模型上下文协议的工具。

同一场景规格，适配两种方向。竖屏适用于 TikTok / Instagram Reels / YouTube Shorts。横屏适用于 YouTube / 桌面端 / 电视。工具包会根据画布宽高比自动切换布局。

list-reveal · 标题和三个要点按提示依次出现

竖屏 · 1080×1920

横屏 · 1920×1080

_{竖屏 规格 · mp4   •   横屏 规格 · mp4}

flow · 展示从 A 到 B 再到 C 的流程

竖屏 · 1080×1920

横屏 · 1920×1080

_{竖屏 规格 · mp4   •   横屏 规格 · mp4}

comparison · 对比两件事物

竖屏 · 1080×1920

横屏 · 1920×1080

_{竖屏 规格 · mp4   •   横屏 规格 · mp4}

hub · 中心概念与指向它的卫星节点

竖屏 · 1080×1920

横屏 · 1920×1080

_{竖屏 规格 · mp4   •   横屏 规格 · mp4}

以上每个片段都是真实生成的输出。时长为 5 到 6 秒。默认采用 Wednesday Solutions 设计系统。点击任意 mp4 链接即可查看完整版画质视频。

---

从这里开始

将以下内容粘贴到任意兼容 MCP 的编码 Agent 的新会话中（Claude Code、Codex、OpenCode、Cursor、Cline 等）。Agent 会完成全部设置：克隆仓库、安装依赖、将 MCP 接入配置，并验证是否正常运行。

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.

重启 Claude Code。现在请它制作一段视频：

“为我制作一个 5 秒的叠加层，标题为‘每次事件都有一份运行手册’，包含三行：漂移、提示词注入、数据外泄尝试。”

Agent 会挑选图标、编写场景规格、渲染 MP4，并把文件路径发给你。将它拖到编辑器中即可。

如果你想自己接入 MCP，请跳转到手动设置。

---

可以制作什么

八种基础组件。你可以在单个 4 到 6 秒的场景中组合使用任意组件。

title-overlay

画面顶部的标题栏。每个场景都要使用它。它用一句话概括观众即将看到的内容。

如果陌生人读完标题后仍无法立刻知道视频讲的是什么，就重写标题。

标题栏位于画面顶部，下方带有一条纤细的薰衣草色装饰线。使用 80pt 粗体，居中显示。位置固定，无法调整。

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

list-reveal

包含 1 到 5 行的垂直列表。每行都可以选择是否添加图标，并在指定帧显示。

当你需要展示 1 到 5 项内容时，使用此组件。

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

包含 2 到 5 个节点的水平序列。每个节点依次出现，箭头向下一个节点绘制，下一个节点随后出现。

当含义取决于顺序时，使用此组件。例如：检测到事件 → 启用运行手册 → 控制住事件。

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

comparison

两个图标并排显示，中间用可配置的分隔符隔开。每侧都有一个标签，以及一个可选的副标签。

当需要呈现二元对比时，使用此组件。新旧方式对比是最典型的例子。

分隔符文字可以配置。"vs" 是表示对立关系的默认值；当关系表示相加或过渡时，可改为 "+" 或 "→"。

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

一个中心图标，周围环绕 2 到 4 个卫星节点。中心图标先出现，随后每个卫星节点依次显示，并从中心绘制连线。

当一个事物位于中心，其他事物围绕它展开时，使用此组件。例如，控制策略、日志记录、成本和交换的网关就可以表示为一个中心节点。

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

这些是灵活的补充组件。可以在画布任意位置放置单个 Tabler 图标、自由定位的文本块或预先制作动画的 Lottie 动画。上面的组合组件无法满足需求时，就使用这些组件。

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

大多数用户不会阅读这些组件的完整字段参考。Agent 会为你读取架构定义。如果你想查看所有字段，请跳转到参考部分。

---

自定义外观

工具包内置 Wednesday Solutions 调色板：在暖调米白画布上搭配薰衣草色点缀。默认情况下，每个场景的轨道后方还会显示环境光晕渐变，标题文字则采用日落渐变。这就是开箱即用的「精致」效果。

所有内容都可以通过场景规范进行配置。无需编辑 JSON，只要用自然语言向 Agent 提出要求即可。

告诉 Agent	规范中的效果
“以深色模式渲染”	theme: "dark"
“使用黑色背景”	background: "#000000"
“纯色背景，不要光晕”	bloom: false
“标题使用纯色，不要渐变”	titleGradient: false
“把团队照片放在后面”	backgroundImage: { source: "team.jpg" }
“将点缀色改为红色，不要薰衣草色”	palette: { accent: "#E74C3C" }
“使用透明背景，我会自己合成”	background: "transparent"

编解码器会自动切换。纯色背景会渲染为 H.264 MP4。transparent 设置会渲染为带有真实 Alpha 通道的 ProRes 4444 MOV。

如果想在每个场景中默认使用不同主题，而不必每次都说明，请编辑 src/scene/theme.ts。调色板是一个对象。修改其中的十六进制值，所有组件都会自动采用新值。

---

手动设置

如果你使用了上面的单次提示词，可跳过此部分。

git clone [email protected]:alichherawalla/video-overlay-kit.git
cd video-overlay-kit
npm install

将工具包添加到项目的 .mcp.json 或全局 ~/.claude/mcp_settings.json 中：

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

重启 Claude Code。video-overlay-kit 下会出现三个工具：

• list_icons(query?, limit?) 按子字符串搜索 Tabler 图标库。包含约 5,000 个线性图标。
• validate_scene(spec) 在渲染前运行架构检查。
• render_scene(spec, outPath?) 渲染为 MP4（如果背景透明，则渲染为 .mov），并返回文件路径。

首次渲染时会下载一次无头 Chrome（约 93 MB）。

---

CLI

如果你愿意，也可以完全不使用 MCP。

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

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

要在编辑 JSON 时自动重新加载并实时迭代规范：

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

---

为什么要开发这个工具包

大多数短视频 B2B 视频都是人物出镜讲话，并叠加图形。顶部有个标题。适时显示三个要点。再加上一两个图标。做得好时，叠加内容和讲述者一样能传达信息。

目前有三种选择：聘请剪辑师（每条短视频 ₹500-2000，修改周期慢，还依赖个人）、订阅 Submagic 之类的 SaaS（每月 $20，风格固定，AI 生成质量参差不齐），或者学习 After Effects（需要投入大量时间，也无法通过终端脚本化操作）。

这个工具包提供了第四种选择。通过小型组件库，让每条短视频都保持统一的视觉风格。Agent 编写场景规范，渲染器生成 MP4，所有操作都在本地完成。

---

参考

以下内容是完整的架构定义。手动编写规范时，请将其作为查询参考。

场景规范：顶层

字段	类型	默认值	说明
id	string	必填	场景的 slug。用作默认输出文件名。
durationFrames	int	必填	总帧数。在给定的 fps 下，时长必须为 4 到 6 秒。会进行验证。
fps	int	30	帧率。
width	int	1080	画布宽度，单位为 px。
height	int	1920	画布高度，单位为 px。默认为 9:16 竖屏。
theme	"light" | "dark"	"light"	选择调色板。Light 是 Wednesday Solutions 的默认主题。
background	string	（取决于主题）	CSS 颜色或 "transparent"。覆盖主题的画布颜色。
backgroundImage	object	无	{ source, opacity, fit, tint, tintOpacity }。在轨道后方渲染。
palette	object	无	场景级调色板部分覆盖项。请参阅调色板。
tracks	Track[]	必填	轨道列表。

通用轨道字段

字段	类型	默认值	描述
kind	枚举	必填	title-overlay、list-reveal、flow、comparison、hub、icon、text、lottie。
id	string	必填	在场景内唯一。
startFrame	int	必填	轨道开始可见的帧。
endFrame	int	必填	移除轨道的帧。
enter	Motion	{ kind: "fade", durationFrames: 8 }	入场动画。
exit	Motion	{ kind: "none", durationFrames: 8 }	退场动画。

Motion（入场和退场）

{ kind, durationFrames, ease }。可用的 kind 值：

kind	效果
fade	透明度渐变。
slide-up / slide-down / slide-left / slide-right	从指定方向平移 80px 入场。
scale	从 0.85 缩放至 1.0，并伴随透明度变化。
none	无动画。

ease：linear、easeIn、easeOut、easeInOut。默认值为 easeOut。

位置

所有轨道的 position 字段均为 { x, y }，表示画布尺寸的 0..1 分数。轨道的几何中心位于该点。

调色板

定义于 src/scene/theme.ts 中的令牌。浅色调色板（默认值）：

令牌	颜色	用途
background	#F0EDF8	画布
ink	#0B0B0D	主要文本和图标描边
inkMuted	#3A3A4A	次要文本
inkDim	#6B6B7E	第三级文本
accent	#7A5BDC	薰衣草色，用于连接线和标题强调条
accentDeep	#5A3DB8	更深的薰衣草色，仅用于按下状态
hairline	#CCCAE0	细线边框

深色调色板会反转这些颜色。可按场景通过 palette: { accent: "#E74C3C", ... } 覆盖。

各轨道字段参考

以下各轨道类型会列出其接受的字段，以及上述通用字段。

title-overlay

字段	类型	描述
text	string	标题文本。

位置固定在画面顶部。没有 position 字段。

list-reveal

字段	类型	描述
position	{ x, y }	列表块的中心。
rows	Row[] (1-5)	列表行。
rows[].text	string	行标签。
rows[].iconName	string?	可选的 Tabler 图标名称。
rows[].revealAtFrame	int	此行出现的帧（相对于 startFrame）。

flow

字段	类型	描述
position	{ x, y }	流程块的中心。
nodes	Node[] (2-5)	序列。
nodes[].iconName	string	Tabler 图标。
nodes[].label	string	图标下方的标签。
direction	"horizontal"	v1 中仅支持水平方向。
revealCadenceFrames	int	相邻节点之间的帧数。默认值为 35。

comparison

字段	类型	描述
position	{ x, y }	对比块的中心。
left、right	Side	各自为：{ iconName, label, subLabel? }。
divider.label	string	中心文本。默认值为 "vs"。
divider.showLine	boolean	是否绘制垂直线。默认值为 true。
revealCadenceFrames	int	左侧、右侧和分隔符依次显示之间的帧数。默认值为 25。

hub

字段	类型	描述
position	{ x, y }	中心节点的位置。
center.iconName、center.label	string	中心节点。
satellites	Satellite[] (2-4)	各自为：{ iconName, label }。
revealCadenceFrames	int	中心节点与各卫星节点依次显示之间的帧数。默认值为 22。

布局会根据数量自动生成。2 个卫星节点分别位于顶部和底部。3 个排列成朝上的三角形。4 个位于四个基本方位。

icon

字段	类型	默认值	说明
name	string	必填	Tabler 图标名称。
position	{ x, y }	必填	画布上的位置。
sizePx	int	160	图标尺寸。
color	string	（主题 ink）	CSS 颜色。
strokeWidth	number	2	描边宽度。

text

字段	类型	默认值	说明
text	string	必填	文本。支持 \n。
position	{ x, y }	必填	画布上的位置。
fontSizePx	int	56	字体大小。
color	string	（主题 ink）	CSS 颜色。
fontWeight	400 | 500 | 600 | 700 | 800	600	字重。
fontFamily	string	（工具包的 Aeonik 字体栈）	CSS 字体栈。
align	"left" | "center" | "right"	"center"	对齐方式。
maxWidthPx	int	不限	换行宽度。

lottie

字段	类型	默认值	说明
source	string	必填	URL 或相对于 public/ 的路径。
position	{ x, y }	必填	位置。
sizePx	int	400	宽度和高度（正方形）。
loop	boolean	false	循环播放动画。
playbackRate	number	1	播放速度倍率。

backgroundImage

字段	类型	默认值	说明
source	string	必填	URL、data: 或 public/ 路径。
opacity	number	1	0..1。
fit	"cover" | "contain"	"cover"	CSS object-fit。
tint	string?	无	绘制在图像上的 CSS 颜色。
tintOpacity	number	0	色调图层的不透明度。

图层依次叠放：背景颜色、图像、色调，然后是轨道。

限制

• 时长为 4 到 6 秒。会进行验证。
• 画面比例为 9:16，分辨率为 1080×1920。默认值。
• 帧率为 30 fps。
• 仅支持 Tabler 图标和线条风格的 Lottie。
• 主题使用 Wednesday Solutions 调色板。可在 src/scene/theme.ts 中编辑。

输出格式

背景	编码格式	容器	用途
任意 CSS 颜色	H.264	.mp4	剪辑到你的短视频中的全画幅补充镜头。
"transparent"	ProRes 4444	.mov	与带 alpha 通道的面对镜头讲述视频合成。

项目结构

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

扩展

如需添加新的轨道类型（例如 quote）：

1. 在 src/scene/types.ts 中添加 QuoteTrackSchema，将其纳入 TrackSchema，并导出该类型。
2. 构建 src/components/Quote.tsx。使用 Remotion 的 useCurrentFrame() 和 ../motion/primitives 中的 trackStyle。从 usePalette() 读取颜色，并从 src/scene/theme.ts 中的 FONT_FAMILY 读取字体。
3. 在 src/scene/Scene.tsx 中注册该分支。
4. 更新 mcp/server.ts 中的架构提示，以便 Agent 知道存在这种新类型。

无需更改渲染器和 MCP 工具处理程序。可以复制 Flow.tsx 或 Hub.tsx，作为编排组件的起点。

---

费用

每次渲染的费用为零。仅使用本地 CPU 和磁盘。个人和小团队可免费使用。如果要用于商业发布，请查看每个依赖项的许可证。

致谢

• Remotion 是基于 React 的视频渲染引擎。
• Tabler Icons 是图标库。
• LottieFiles 是 Lottie 动画市场。
• Model Context Protocol 是用于将工具包开放给 Claude Code 的标准。

支持项目

VideoOverlayKit 免费且采用 MIT 许可。如果这个工具包为你节省了时间或渲染预算，最简单的回馈方式就是在 GitHub 上赞助该项目。赞助资金将用于开发新组件、改进默认设置和修复 bug，让这些改进能比我晚上独自开发更快交付。

Wednesday Solutions（wednesday.is）是这个设计系统背后的工作室。如果你需要定制开发、符合品牌形象的主题，或为受监管行业交付 AI 功能提供生产支持，可以通过这种方式联系团队。

---

由 Wednesday Solutions 用 ♥ 制作

许可证

MIT。

问题与贡献

请在 github.com/alichherawalla/video-overlay-kit 提交问题。src/scene/types.ts 中的 schema 是约定。添加新的轨道类型时，请先提出规范的结构，然后再开发组件。