LBEILC / Multiplane

# Multiplane
English · 简体中文
给 AI agent 用的本地无头 HTML 视频渲染器。**镜头就是普通网页**：页面实现 `render(t)`，画面只由时间 `t` 决定；Multiplane 用无头 Chromium 逐帧截图，做超采样、运动模糊、胶片颗粒等后期，用 FFmpeg 合成视频，并能检查镜头是否确定。
> 当前版本 `0.3.8`（最新版本见 Releases 页面）。完整测试在 Windows、macOS、Linux 三个平台的 CI 上全部通过；Windows 另在真机上验证过。1.0 之前接口仍可能调整。
名字来自迪士尼的多层摄影台（multiplane camera）：一层层平面画稿放在不同深度、逐帧拍摄、带真实景深。对应这里的多层网页画面、三维卡片层和累积景深。
## 特点
- **不用学新框架**。镜头是 HTML、CSS 和一段 JavaScript，agent 最擅长写的东西。
- **渲染前检查**。`lint` 不开浏览器、不到一秒，指出墙钟时间、随机数、CSS 动画、网络资源等会破坏确定性的写法，定位到文件、行、列；渲染命令启动前会自动先跑。
- **可验证**。`verify` 会乱序、重载页面、单进程和多进程分别渲染同一批帧，逐像素比较；不一致时给出出问题的时刻、区域和差异图。
- **运动模糊不跨硬切**。每帧在快门时间内多次采样、按线性光混合；镜头声明的硬切时刻 `cuts` 两侧的画面不会糊在一起。
- **三维层与累积景深**（可选，`multiplane/three`）：图片卡片进三维空间，多次采样累积出真实的焦外虚化，与运动模糊配合。
- **机器可读**。所有命令支持 `--json`，输出带稳定错误码的事件流；每次运行有独立的作业目录，可查询进度、可取消。
- **也能出静帧**。`stills` 按指定时刻输出 PNG，和视频走同一套超采样、运动模糊、景深和透明通道。可以用来抽帧检查，也可以直接出封面、海报、配图这类高质量静帧。
- **确定性**。渲染器自身不引入墙钟时间和未设种子的随机数；同一输入在同一环境下逐像素一致，并由测试保证。
## 效果
**运动模糊**：左边不开运动模糊；中间固定 8 个采样，快速转动的轮辐变成一条条分开的残影；右边按移动距离自动加采样，连成顺滑的拖尾。下排是局部放大。
**硬切不糊在一起**：切点后的第一帧。左边没有声明硬切，运动模糊把切点前一个画面的颜色和圆形混了进来；右边在镜头里声明了 `cuts`，切得干净。
**三维景深**：同一组卡片，焦点分别在前景和背景。焦外虚化是多次采样累积出来的，不是按深度图做的后期模糊，所以前景边缘不会溢出、背景也不会渗进前景的轮廓。下排是前景卡片的局部放大。
## 快速开始
需要 Node.js 24 或更新版本，以及支持 libx264 的 FFmpeg。
 [code] 
示例在安装好的包里，所以用 `--root` 把资源根指向包目录；出于安全，渲染时不会提供 `node_modules` 下的文件。
新版 npm 默认不运行依赖包的安装脚本，所以第二条命令用来下载 Playwright 使用的 Chromium。如果是克隆了本仓库，在仓库里运行 `npm install`，直接渲染 `examples/animation.html` 即可。
把使用说明 skill 交给你的 agent：运行 `npx multiplane skill install --host all`（Claude Code 装到 `~/.claude/skills/multiplane`，Codex 装到 `~/.agents/skills/multiplane`），或者让桌面软件来安装。装好后新开一个 agent 会话。
在克隆的仓库里，`npm install` 会自己下载这个 Chromium（已安装则复用）。离线环境可设 `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` 跳过，之后再运行 `npx playwright install chromium`。Linux 上 Chromium 还需要系统库：运行一次 `npx playwright install-deps chromium`（缺的时候 `doctor` 会提示）。
### FFmpeg
Multiplane 不随包分发 FFmpeg。需要自己安装一个支持 libx264 的：
| 系统 | 一种获取方式 |
|---|---|
| Windows | 从 FFmpeg 官方下载页 获取构建 |
| macOS | `brew install ffmpeg` |
| Linux | 发行版的软件包，例如 `sudo apt-get install ffmpeg` |
FFmpeg 的许可取决于你安装的构建。然后用以下任一方式告诉 Multiplane（按优先级）：
1. 命令行参数 `--ffmpeg `；
2. 环境变量 `MULTIPLANE_FFMPEG`；
3. 用户配置文件里的 `ffmpeg`（见下文“用户配置”）；
4. 放进系统 PATH。
想一次设好、所有项目都生效，运行 `npx multiplane config set ffmpeg `，它会顺便检查这个文件能不能用。
默认用软件编码 `x264`；有 NVIDIA 显卡时可用 `--encoder nvenc-h264` 或 `--encoder nvenc-hevc`。`doctor` 会检查 FFmpeg 能否运行、是否支持所需编码器。
## 写一个镜头
 [code] 
约定只有三条：
- 画面都画在 `#stage` 里，用固定的 CSS 宽高声明画幅；
- `render(t)` 是同步函数，同一个 `t` 永远画出同样的画面；
- 字体、图片等素材用本地文件，在 `setup()` / `ready` 里加载完。
完整约定、哪些写法会破坏确定性、三维层用法，见 agent 使用说明 `skills/multiplane/SKILL.md`。它同时是给 agent 加载的 skill。
## 命令
| 命令 | 用途 |
|---|---|
| `multiplane lint ` | 静态代码检查，不开浏览器 |
| `multiplane render ` | 渲染成 MP4 |
| `multiplane stills ` | 按时刻输出静帧（PNG）并生成联系表；可用于检查，也可直接出高质量静帧 |
| `multiplane verify ` | 确定性检查 |
| `multiplane inspect ` | 不渲染，输出镜头的时长、帧数、舞台尺寸、硬切和 `meta` |
| `multiplane serve` | 在 127.0.0.1 上提供镜头，写镜头时用浏览器打开 |
| `multiplane benchmark` | 在本机实测不同进程数的渲染速度，之后渲染自动用最快的进程数 |
| `multiplane doctor` | 检查 Node