0xS4N4TG/kinetograph · 上手攻略

• 仓库：0xS4N4TG/kinetograph
• 链接：https://github.com/0xS4N4TG/kinetograph
• 分类：agent / 程序化视频渲染引擎（TypeScript + Rust）
• 作者：spark
• 更新：2026-10-28

一、它是什么

Kinetograph 是一个程序化视频渲染引擎，作者 Sanat Gupta（0xS4N4TG）的定位原话是「A blazingly fast programmatic video engine, made for agents」——为 AI agent 而生的视频引擎。

它的核心思路是：你（或你的 agent）用 TypeScript 写视频，Node 跑代码，一个 Rust GPU 合成器逐帧画出像素。视频用 Remotion 的 API 写（remotion / @remotion/* 的 import 会被映射到 Kinetograph 自己的实现），支持 CSS、SVG、Canvas 2D、WebGL shader 和 Web Audio。

关键技术主张有两条，都很硬：

1. 渲染路径里没有 Chrome。README 明确说「No Chrome anywhere in rendering, including canvas and WebGL: every CSS, SVG and canvas feature is ported natively」，Chrome for Testing 只在测试里当参照物用。Node 托管引擎以获得完整 Web API 与 npm 生态，引擎本身是原生 addon，像素永不跨回 JavaScript。
2. 架构是三层：TS 项目层（Remotion API / CSS / SVG / Canvas 2D / WebGL / Web Audio）→ Node 层（esbuild 打包、确定性 shim、React reconciler、浏览器 shim、场景发射）→ Rust 层（kinetograph-dom 负责 DOM/CSS 布局与绘制；kinetograph-core 是基于 wgpu 的合成器，用 Skia 画矢量与文字、WGSL 做特效、naga 转译 GLSL、scene3d 处理 glTF/PBR、ThorVG 跑 Lottie、2.5D 相机、运动模糊、图层缓存；media 模块走 FFmpeg 解码编码）。

版本状态：Beta，v0.2.0（2026-10-27 发布）。作者自己写明「It works and renders real projects, but APIs can still change between versions and some features are missing」。许可为 PolyForm Small Business License 1.0.0——个人、非营利组织、员工少于 100 人且 2019 年营收低于 100 万美元的公司免费，更大的公司需商业授权。

二、它解决什么问题

问题一：Remotion 渲染慢且依赖浏览器。 Remotion 用 Chromium 无头渲染逐帧截图再经 FFmpeg 编码，大规模批量渲染时浏览器成为吞吐瓶颈。Kinetograph 把渲染整条链路换成原生 GPU 合成，README 给出的数字是：官方发布影片是 1,184 帧 1080p 含音频，在一台笔记本上 26 秒渲完；Showcase 示例 928 帧 1920×1080 用 13 秒；Canvas 2D 示例 60 帧 860×420 只要 0.6 秒。官方注明这些时间是 Apple M4 上 kinetograph render --concurrency 4 三次运行的中位数。

问题二：agent 看不见视频。 Kinetograph 的设计直接围绕 agent 的感官边界：它给 agent 一个 MCP server，把每个 CLI 命令变成工具，其中 still、strip（等距抽帧的接触印像表，每帧带帧号和时间标签）、onion（多帧叠加显示运动路径）会把 PNG 作为图像返回给 agent，agent 就能"看"到自己的输出。同时提供一个 skill 教 agent 一个闭环：write → look → check → render。

问题三：写视频和做动画是两套技能栈。 因为兼容 Remotion API，现有 Remotion 项目可以原样跑；同时也支持 HyperFrames 项目（写 HTML）和纯 JSON 场景格式。

三、快速安装

路径一：直接用 npm 包（最省事）

需要 Node 22 或更高版本。packages/cli/package.json 的 engines 字段为 "node": ">=22"，根 package.json 同样声明 "node": ">=22"。

npm install kinetograph
# 或全局
npm install -g kinetograph

CLI 的 bin 名是 kinetograph（"bin": { "kinetograph": "dist/cli.js" }）。

路径二：从源码构建（推荐用于开发/调优）

仓库是 npm workspaces 单体仓，工作区包括 crates/node、crates/skia/node、packages/scene、packages/compat、packages/react、packages/core、packages/audio、packages/cli、packages/plugins/{gsap,p5-brush,motion,anime}、packages/studio。

git clone https://github.com/0xS4N4TG/kinetograph.git
cd kinetograph

npm ci
npm run build                                       # TS 各包 + debug 版原生 addon
npm run build:release -w @kinetographdev/native       # 计时用的 release 版 addon

从源码构建的额外要求（README 的 Build from source 段）：

• rustup 工具链（stable，edition 2024）
• wgpu 支持的 GPU（macOS 上是 Metal），不需要显示器
• render 命令要链接 FFmpeg，因此构建需要 FFmpeg 开发库和 pkg-config

# macOS
brew install ffmpeg pkgconf

# 若没有 pkg-config，改用 FFMPEG_DIR 指向 FFmpeg 前缀
export FFMPEG_DIR=$(brew --prefix ffmpeg)

cargo build --release
./target/release/kinetograph render examples/papercut-card.json -o out/card.mp4

路径三：给 agent 装 MCP server 与 skill

# Claude Code：注册 MCP server（项目级；--scope user 则全局）
claude mcp add kinetograph -- npx -y kinetograph mcp

# Codex CLI
codex mcp add kinetograph -- npx -y kinetograph mcp
# 或在 ~/.codex/config.toml 写：
#   [mcp_servers.kinetograph]
#   command = "npx"
#   args = ["-y", "kinetograph", "mcp"]

# Cursor：写进 .cursor/mcp.json
#   { "mcpServers": { "kinetograph": { "type": "stdio",
#     "command": "npx", "args": ["-y", "kinetograph", "mcp"] } } }

# 安装两个 skill：kinetograph（写-看-查-渲 闭环）和 kinetograph-migrate（Remotion 迁移）
npx skills add 0xS4N4TG/kinetograph

skill 也可以从已装的 npm 包里手动复制：

mkdir -p ~/.claude/skills
cp -R node_modules/kinetograph/skills/kinetograph \
      node_modules/kinetograph/skills/kinetograph-migrate \
      ~/.claude/skills/

四、核心用法

4.1 最小项目

项目入口文件要调用 registerRoot，然后注册 Composition：

import { registerRoot, Composition } from 'remotion';
import { AbsoluteFill, useCurrentFrame, interpolate } from 'remotion';

const Title = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 15, 30], [0, 1, 0]);
  return (
    <AbsoluteFill style={{ background: '#111', opacity }}>
      <h1 style={{ color: '#fff', fontSize: 120 }}>Hello</h1>
    </AbsoluteFill>
  );
};

export const RemotionRoot = () => (
  <Composition id="Title" component={Title} durationInFrames={90} fps={30} />
);

registerRoot(RemotionRoot);

import 路径规则：项目照常 import from 'remotion' 和 '@remotion/*'，CLI 会把它们映射到 @kinetographdev/core；Kinetograph 自己的原生元素和特效则从 @kinetographdev/core 引入。

4.2 CLI 命令

# 渲染单帧为 PNG
npx kinetograph still examples/rajz-cards/index.tsx 60 -o out/rajz-60.png

# 生成抽帧接触表（适合 agent 或人快速检查）
npx kinetograph strip examples/rajz-cards/index.tsx -n 12 -o out/rajz-strip.png

# 渲染视频
npx kinetograph render examples/rajz-cards/index.tsx -o out/rajz-cards.mp4

# 检查某一帧的场景图（层、边界、解析后的样式），JSON 输出
npx kinetograph inspect examples/rajz-cards/index.tsx --frame 60 --json

所有命令都支持 --json。另外还有 lint（文字溢出框/画布、层出界、文字重叠、缺字体、缺资源、类型错误，以及引擎画不出来的 Remotion 内容）、check（跑 tsc --noEmit 抓「渲染时不报错的类型错」）、doctor（报告项目里引擎画不出的东西及出现在哪些帧）、snapshot（与 __snapshots__/ 里已批准的 PNG 对比）、audio_analyze（LUFS 响度、真峰值、削波、静音）、bench（各阶段每帧毫秒数）、effects（列出特效及其参数）、compositions（列出项目的 composition）、track（Blender 式运动跟踪）、fetch-deps（预下载项目外部依赖）。

4.3 MCP 工具表（agent 视角）

npx kinetograph mcp 起 stdio MCP server，每个 CLI 命令对应一个工具（studio 除外，它会一直运行）。命令名带空格的用下划线。错误以 { "error": { "code", "message" } } 返回。

still / strip / onion 的 output 可选（省略时写临时 PNG 并返回）；render 必须给 output。

4.4 Studio 编辑器

kinetograph studio src/index.tsx

打开本地编辑器，预览帧由引擎本身绘制，所以所见即所得。功能：

• 时间轴：每个 shot 和音频片段一行；重复组件折叠成一行，点条即跳转；"Show details" 展开所有层。
• 可读层名：每层以其组件与文本命名，并标出源文件和行号。
• 指哪改哪（point and ask）：在预览里点某一层或框选多层，然后告诉你的 coding agent 要改什么；agent 会拿到选区、源码位置和该区域的图片。agent 通过 ACP（Agent Client Protocol）通信，预设支持 Claude Code、Codex 和 Gemini（README 注明目前只测过 Claude Code），并且在 agent 编辑文件前会先征求同意。
• 检视与渲染：props、场景树、每层解析后的字段与渲染结果都在同一窗口。

4.5 离线依赖与锁文件

render / still / doctor / studio 等命令会在第 0 帧之前下载项目需要的外部资源然后离线绘制。HyperFrames 项目会拉 CDN 脚本、数据、媒体、图片和字体；Remotion 项目会拉 <Img>、<Video> 和 CSS url() 指向的 https 资源。--offline 则完全不下载。

下载的文件会由入口旁的 kinetograph.lock.json 锁定（URL → SHA-256 与大小），首次下载时写入；后续运行会比对缓存，不匹配就停下并报出 URL，fetch-deps --update 接受新字节。缓存写入是原子的（先写哈希最后写文件），所以并行 worker 首次渲染不会读到半个文件。

4.6 测试

npm test                              # CPU 测试
KINETOGRAPH_GPU_TESTS=1 npm test      # GPU 测试

五、典型适用场景

场景 1：Agent 驱动的批量视频生成。 这是项目第一定位。agent 通过 MCP 拿到 strip/still 的 PNG 图像反馈，靠「写 → 看 → 查 → 渲」闭环迭代。官方给的触发式提示词示例极短：「make a 5 second title card for X, check it with strip and lint, and render it to out/title.mp4」。论文级项目可参考 papercut-explainer（作者自己的 Remotion 库 + agent skills 做的剪纸科普短片系列）。

场景 2：把已有 Remotion 项目搬过来。 用 kinetograph-migrate skill：跑 doctor，按参考文件逐条修 3D、工具链和不支持内容，再用 --strict 渲染。

场景 3：高吞吐程序化视频（数据可视化、批量模板视频）。 无浏览器的渲染路径在这里价值最大。

场景 4：写 HTML 视频（HyperFrames 路线）。 支持 import maps、ES modules、动态 import()、CSS 变量等。

场景 5：需要精确控制的动效与后期。 0.2.0 新增 GSAP 及免费插件（SplitText、MotionPath、DrawSVG、TextPlugin、Flip）、<Video datamosh>（用视频自身运动矢量把一个镜头拖进下一个）、WebGPU、HyperFrames 项目、x264/x265 全平台编码（自带 FFmpeg）、SVG 图片与符号/emoji 字体回退。效果目录（effects）里已有 23 个场景特效，另有 colorGrade 场景特效支持 blur / pixelate / halftone / ascii / dither / bloom / CRT curvature / digital glitch 等 64 个控制项。

六、坑与注意

坑 1：版本是 Beta，API 会变。 现象：README 明写「Beta, version 0.2.0 ... APIs can still change between versions and some features are missing」。影响：写进生产管线的脚本随时可能因 API 变更而崩。修复：锁版本（kinetograph@0.2.0），升级前先读 CHANGELOG.md（0.2.0 发布于 2026-10-27，同时有大量 Unreleased 条目，说明变动极快）。

坑 2：许可证不是 MIT，商业化有硬门槛。 现象：PolyForm Small Business License 1.0.0——个人/非营利/员工 <100 人且 2019 年营收 <100 万美元免费，更大的公司需商业授权（见 COMMERCIAL.md）。影响：公司里超过 100 人的团队直接商用会违约。修复：先读 LICENSE.md 与 COMMERCIAL.md 确认门槛，超限走商业授权。

坑 3：字体是最大的隐形坑，中文尤其。 现象：known-issues 明写「Fallback fonts cover symbols, not scripts」——字符缺字时回退到 Noto Sans Symbols 2、Noto Sans Math、Noto Emoji，CJK、阿拉伯语、天城文等没有内置字体，会被画成方框并被报告（错误信息形如 font-family，"no glyph for U+4E2D ..."）；emoji 是单色的。影响：中文视频会整片变豆腐块。修复：在项目里显式注册含所需字形的字体（Kinetograph 侧可参考 @remotion/google-fonts/JetBrainsMono 的注册方式）。另注意：monospace 默认回退到比例字体（内置 JetBrains Mono Regular，92 KB，SIL OFL 1.1）——但 known-issues 的 "Libraries" 一节又写着「monospace text falls back to a proportional face」，这两处口径不完全一致，以实际渲染为准，别信单一来源。

坑 4：IFrame 完全不支持。 现象：known-issues 的 "Not planned" 明确列 IFrame 不绘制，「because a real webpage needs a browser」，且会被报告为不支持内容。影响：任何依赖 iframe 嵌入真实网页的方案在 Kinetograph 下走不通。修复：改用 HyperFrames 的 HTML 路线，或先做静态快照。

坑 5：WebGPU 有真实功能缺口。 现象：known-issues 记录 WebGPU 页面在所有机器上 maxVertexBuffers 都报 8；色彩/模板 renderbuffer、深度纹理和模板测试仍未实现；Three.js 完全不绘制（加载 Three.js 的页面每帧都被报告）。影响：依赖 Three.js 的 3D 场景、依赖深度测试的 WebGL 效果会有画面差异或直接丢失。修复：长渲染前必须跑 doctor；项目若用 HTML 元素或 CSS，建议 doctor + --strict 双保险。

坑 6：@remotion/webcodecs 整块不可用。 现象：known-issues 写明 @remotion/webcodecs 的 convertMedia 和 @remotion/media-parser 的 box tree 与 sample 回调会抛 UnsupportedApiError；onVideoFrame 给的不是 WebCodecs 的 VideoFrame（只有 width/height/timestamp/close()）。影响：自己写编解码的 Remotion 代码迁移过来会直接抛错。修复：普通 <Video> / <Audio> 不受影响；自定义编解码路径需重写为 <Video> + onVideoFrame 组合。

坑 7：确定性 shim 会改变运行时语义。 现象：架构图里 Node 层有 determinism shim——Date、Math.random、定时器、rAF 全部由帧号驱动；每个 effect 帧都会重跑 setup/apply/cleanup，setup 保留的状态不跨帧；async 的 apply/onInit/onPaint 会阻塞该帧直到 promise 落定，但依赖定时器的 promise 需要真实时间，而渲染的虚拟时钟不推进。影响：写「一次性初始化」或依赖真实时间的动画逻辑会静默出错。修复：把状态放在帧外显式传递，不要依赖 setup 的副作用残留；避免在 effect 里用 setTimeout。

坑 8：Canvas 逐帧清空，语义和浏览器不同。 现象：CHANGELOG 0.2.0 修复项写明「A <canvas> a frame draws on, on the React path, starts that frame empty」——useEffect(..., []) 只画一次的 canvas 仍会保留像素，但 React 路径下画过的 canvas 会保留。影响：still 45（或从中途启动的 render worker）与完整渲染的第 45 帧画面不同，肉眼对比会误判 bug。修复：需要跨帧持久的画面要放到别处（如图片层或 DOM），别依赖 canvas 自身残留。

坑 9：构建依赖偏重，容易卡在 FFmpeg。 现象：Rust 构建需要 edition 2024 的 stable rustup、wgpu 支持的 GPU、FFmpeg 开发库和 pkg-config；pkg-config 缺失时要改设 FFMPEG_DIR。影响：新手在 macOS/Linux 上第一次构建大概率卡住。修复：先 brew install ffmpeg pkgconf；没 GPU 的机器可用 KINETOGRAPH_SKIA_CPU=1 强制 CPU 渲染（render/still 会打印 renderer: Skia CPU (no GPU found)），但会失去 GPU 速度优势。

坑 10：0.2.0 的 FFmpeg 是双轨且许可证不同。 现象：平台包 @kinetographdev/native-<platform> 现在在 bin/ 里带一份独立的 GPL ffmpeg（x264、x265、libvpx），addon 本身只链接 LGPL ffmpeg，但 addon 会把缺失的编码器作为子进程调用。站点有专门的 /docs/ffmpeg-license/ 页。影响：如果你的产品需要分发时符合 GPL/LGPL 义务，必须读这一页——这是本项目最容易踩的法律坑。修复：商用前先过 /docs/ffmpeg-license/；必要时用 KINETOGRAPH_FFMPEG 指向自带的 ffmpeg。

坑 11：视频播放色彩管理与 Chrome 不同。 现象：known-issues 记录「A video whose colour space is not named is converted as a video layer is, which differs from Chrome's colour management」；变量字体的 advance width 在 Chrome 里差约 13%（Recursive + weight-wave），导致 measureText 拟合的行会换行；WebGL 渐变预乘 alpha 行为、foreignObject 内 <div> 的支持都在 0.2.0 才补齐。影响：与 Remotion/浏览器渲染结果逐像素对比会有差异。修复：不要用像素级比对代替视觉验收；变宽字体要重测排版。

坑 12：项目极其年轻。 现象：仓库 2026-10-23 创建，2026-10-27 就发布 0.2.0；写作时点 190 star / 15 fork / 10 open issues，最近提交 2026-10-27。影响：文档与实现不同步的概率高（本篇写作时 web_search 返回的搜索缓存里 README 还写着「version 0.1.0」，而实拉是 0.2.0）。修复：一切以仓库当前 CHANGELOG.md 与 main 分支为准，别信第三方博客或搜索缓存里的版本号。

七、与同类对比

差异化要点：Kinetograph 是三者中唯一把「渲染路径里没有浏览器」当架构目标、并把「agent 能看见输出」当一等公民（MCP 返回图像）的。它的代价是生态极小（4 天大、190 star），且长尾 CSS/DOM 兼容性仍需逐条查 known-issues；Remotion 的生态成熟度是数量级差距。

八、一句话推荐结论

推荐试用，但只适合愿意跟进 beta 变更、且已在 Remotion 上有积累的团队——它的无浏览器渲染路径和 MCP 图像反馈确实解决真问题；但在项目成熟度（4 天）、字体覆盖（中文需自备）、Remotion API 长尾兼容（webcodecs 整块不可用、IFrame 不支持）和 PolyForm 商业门槛这四点澄清前，不建议直接押生产。

附：核对与不确定说明

• 已核实（直接 fetch）：README 全文（raw.githubusercontent.com，main 分支）、packages/cli/package.json（version 0.2.0、bin 名、engines ≥22、依赖版本）、根 package.json（workspaces 列表、engines ≥22）、CHANGELOG.md（0.2.0 与 Unreleased 段全文）、站点文档 packages/site/content/docs/guides/agents.mdx（MCP 工具表、客户端配置、skill 安装、闭环）与 packages/site/content/docs/known-issues.mdx（未支持/部分支持清单）、GitHub API 仓库元数据、release tag（v0.2.0，2026-10-27）。
• 版本标注：v0.2.0，发布于 2026-10-27。CHANGELOG 顶部仍有大量 "Unreleased" 条目（motion tracking、onVideoFrame、GSAP、HyperFrames 模块导入、WebGL 深度测试等），意味着 main 分支领先于 0.2.0 发布版。
• 不确定项：① 性能数字（26 秒 / 1,184 帧等）为作者自报，均为 Apple M4 + --concurrency 4 三次中位数，未在其他硬件复现；papercut 系列的三个数字明确说明取的是「三次中最快一次」，与其它示例的中位数口径不同，不能横向比较；② monospace 字体回退在 CHANGELOG（内置 JetBrains Mono 92 KB）与 known-issues（回退到比例字体）两处口径冲突，已在坑 3 中标注，以实测为准；③ npm install kinetograph 是否已在公共 npm 上按 0.2.0 发布未实测（publishConfig.access: public 与 bin 字段表明会发，但未查 npm registry）；④ 素材 overlay 包（"Text Animation Overlays"、"Custom Transitions: Film Burns"）不在仓库内，正式发布需另行授权；⑤ KINETOGRAPH_SKIA_CPU=1 强制 CPU 的具体性能代价未量化；⑥ 未 clone 仓库、未实际渲染任何示例。