渲染

使用 CLI 将你的 Hyperframes 合成渲染为 MP4、MOV 或 WebM。渲染流水线是逐帧且基于寻址的——参见确定性渲染了解底层原理。

快速开始

验证你的环境

运行诊断命令检查所需依赖：

npx hyperframes doctor

预期输出：

✓ Node.js    v22.x
✓ FFmpeg      7.x
✓ FFprobe     7.x
✓ Chrome      (bundled)
✓ Docker      available

预览你的合成

渲染前，在浏览器中预览合成以验证其外观正确：

npx hyperframes preview

渲染为 MP4

在项目目录中运行渲染命令：

npx hyperframes render --output output.mp4

预期输出：

⠋ Rendering composition "root" (30fps, standard quality)
✓ Captured 240 frames in 8.2s
✓ Encoded to output.mp4 (8.0s, 1920x1080, 4.2MB)

渲染模式

本地模式

本地模式（默认）

使用 Puppeteer（捆绑 Chromium）和你系统的 FFmpeg。开发期间迭代速度快。

**需要：**你系统上安装了 FFmpeg。如果 FFmpeg 未找到，请参见故障排除。

npx hyperframes render --output output.mp4

优点：

• 启动快，无容器开销
• 默认可使用系统 GPU 进行 Chrome/WebGL 捕获
• 可使用系统 GPU 进行硬件加速编码（配合 --gpu）
• 最适合迭代开发

缺点：

• 由于字体和 Chrome 版本差异，不同平台输出可能不同
• 不适合需要可重现性的 CI/CD 流水线

Docker 模式

Docker 模式

确定性输出，使用精确的 Chrome 版本和字体集。用于生产渲染和 CI 流水线。

**需要：**Docker 已安装并运行。

npx hyperframes render --docker --output output.mp4

优点：

• 每个平台输出相同——相同的 Chrome、相同的字体、相同的 FFmpeg
• 生产中使用的同一流水线
• 适合 CI/CD 和自动化工作流

缺点：

• 由于容器初始化启动较慢
• 浏览器捕获使用确定性软件 GL 路径
• GPU 编码需要 Docker 主机 GPU 直通，在 Docker Desktop 上不跨平台

ℹ️ Note

Docker 模式使用 chrome-headless-shell 配合 BeginFrame 控制实现帧精确的确定性捕获。

何时使用哪种模式

选项

质量和编码

--quality 标志选择一个预设，控制 H.264 CRF（恒定速率因子）和编码器速度：

如需更精细的控制，使用 --crf 或 --video-bitrate 覆盖预设：

# Near-lossless quality (CRF 15 = very high quality, large file)
npx hyperframes render --crf 15 --output pristine.mp4

# Target a specific bitrate (useful for size-constrained delivery)
npx hyperframes render --video-bitrate 10M --output controlled.mp4

提示：默认 standard 预设（CRF 18）在 1080p 下视觉无损——大多数人无法将其与源区分开。使用 --quality draft 进行更快迭代，或在文件大小不是问题时使用 --quality high / --crf 10。

GPU 加速

Hyperframes 有两个独立的 GPU 加速面：

• --gpu 在可用时使用 FFmpeg 中的硬件视频编码器。支持的后端包括 macOS 上的 VideoToolbox、NVIDIA 系统上的 NVENC、Windows 上的 AMD AMF、Linux 上的 VAAPI 以及受支持的 Windows/Linux 主机上的 Intel QSV。
• 浏览器 GPU 使用主机 GPU 进行本地 Chrome/WebGL 捕获。本地渲染时自动启用，Docker 中禁用。使用 --no-browser-gpu 退出。

# Add hardware FFmpeg encoding to the default local browser-GPU render
npx hyperframes render --gpu --output encoded-fast.mp4

# Opt out of hardware Chrome/WebGL capture
npx hyperframes render --no-browser-gpu --output software-browser.mp4

# Use browser GPU plus hardware FFmpeg encoding
npx hyperframes render --gpu --output gpu.mp4

浏览器 GPU 捕获仅限本地模式。它映射到平台原生 Chrome GPU 后端：macOS 上的 Metal、Windows 上的 D3D11 和 Linux 上的 EGL。当跨机器精确可重现性比本地渲染速度更重要时，使用 --no-browser-gpu 或 Docker 模式。

工作进程

每个渲染工作进程启动一个独立的 Chrome 浏览器进程来并行捕获帧。更多工作进程可以加速渲染，但每个消耗约 256 MB RAM 和大量 CPU。

默认行为

默认情况下，Hyperframes 使用 CPU 核心数的一半，上限为 4：

这是刻意保守的。每个工作进程生成自己的 Chrome 进程，因此每个工作进程的开销很大。较少的工作进程避免与 FFmpeg 编码和其他应用程序的资源竞争。

选择工作进程数

# Explicit worker count
npx hyperframes render --workers 1 --output output.mp4

# Let Hyperframes pick based on your CPU
npx hyperframes render --workers auto --output output.mp4

# Maximum parallelism (use with caution on laptops)
npx hyperframes render --workers 8 --output output.mp4

💡 Tip

从默认值开始。如果渲染感觉慢且你的系统有余量（检查活动监视器 / htop），尝试增加 --workers。如果看到高内存压力或风扇噪音，减少它。

何时使用 1 个工作进程

• 短合成（低于 2 秒 / 60 帧）——并行开销超过收益
• 低内存机器（4 GB 或更少）
• 渲染与其他重进程（视频编辑、大型构建）同时运行

何时增加工作进程

• 在具有 8+ 核心和 16+ GB RAM 的机器上的长合成（30+ 秒）
• 专用渲染机器或 CI 运行器
• 在配置良好的主机上的 Docker 模式

并发渲染

当多个渲染请求同时到达生产者服务器时（常见于 AI 代理），每个渲染生成自己的 Chrome 工作进程集。过多的并发渲染可能耗尽 CPU 并导致失败。

生产者服务器使用请求级信号量来排队渲染。同时只有 maxConcurrentRenders 个渲染执行——额外请求在 FIFO 队列中等待直到有空位。

配置

# CLI flag
npx hyperframes render --max-concurrent-renders 2 --output output.mp4

# Environment variable (for the producer server)
PRODUCER_MAX_CONCURRENT_RENDERS=2

默认为 2 个并发渲染，在 8 核机器上运行良好，每个渲染使用 2-3 个工作进程。

队列状态

生产者服务器暴露一个 GET /render/queue 端点返回当前状态：

{
"maxConcurrentRenders": 2,
"activeRenders": 1,
"queuedRenders": 3
}

AI 代理可以轮询此端点来决定是否提交渲染或等待。

SSE 队列事件

使用流式端点（POST /render/stream）时，排队请求在渲染开始前收到 queued 事件：

{"type": "queued", "requestId": "...", "position": 2}

这使代理可以向用户报告"排队中"而不是看起来卡住了。

选择并发限制

💡 Tip

不确定时使用 1。渲染会排队并顺序执行，但每个都获得完整的 CPU 并尽快完成。这比 3 个渲染争夺 CPU 都慢慢完成——或失败——要好。

透明视频

Hyperframes 支持渲染透明背景——用于覆盖层、底部字幕条、订阅卡片以及你想在视频编辑器中合成到其他素材上方的任何元素。

推荐格式：MOV（ProRes 4444）

npx hyperframes render --format mov --output overlay.mov

MOV 配合 ProRes 4444 是透明视频的行业标准。它在所有主流视频编辑器中工作：

• CapCut
• Final Cut Pro
• Adobe Premiere Pro
• DaVinci Resolve
• After Effects

⚠️ Warning

ProRes MOV 文件较大（短片段通常 5-40 MB），因为 ProRes 是为编辑优化的高质量中间编解码器，而非交付格式。这是预期的——Remotion 和专业流水线也做同样的权衡。

格式比较

ℹ️ Note

WebM VP9 alpha 技术上支持但所有主流视频编辑器都忽略 alpha 通道并将透明区域渲染为黑色。只有基于 Chromium 的浏览器（Chrome、Arc、Brave、Edge）正确解码 VP9 alpha。Safari 不支持。编辑器工作流使用 MOV，WebM 仅用于基于浏览器的播放。

PNG 序列（无编码）

npx hyperframes render --format png-sequence --output frames/

--format png-sequence 完全跳过编码器。捕获的 RGBA 帧被复制到 <output>/frame_NNNNNN.png（零填充），如果合成有音频，还会写入 audio.aac 伴生文件。当你需要无损帧时使用此选项——用于在 After Effects / Nuke / Fusion 中合成，或作为自定义编码流水线的输入。--output 被视为目录，如果不存在则创建。

工作原理

当你使用 --format mov、--format webm 或 --format png-sequence 渲染时，Hyperframes：

1. 将每帧捕获为带 alpha 通道的 PNG（而非 MP4 的 JPEG）
2. 通过 Emulation.setDefaultBackgroundColorOverride 将 Chrome 页面背景设为透明
3. 使用支持 alpha 的编解码器编码（MOV 使用 ProRes 4444，WebM 使用 VP9）；png-sequence 跳过编码直接写入捕获的帧

你的合成 HTML 不应在 html 或 body 上设置 background——保持未设置以便透明背景透出。

编写透明合成

<style>
/* Do NOT set background on html/body — leave them transparent */
* { margin: 0; padding: 0; box-sizing: border-box; }

[data-composition-id="my-overlay"] {
position: relative;
width: 1920px;
height: 1080px;
overflow: hidden;
/* No background here either */
}
</style>

只有可见元素（卡片、文本、图片）会出现在最终视频中。其他一切都是透明的。

验证透明度

• **在浏览器中：**打开 MOV 文件——它不会播放（ProRes 不是浏览器编解码器）。改为渲染一个 WebM 副本并在 Chrome 中打开棋盘格背景页面查看。
• **在视频编辑器中：**导入 MOV 文件并将其放在其他素材上方的轨道上。透明区域应显示下方的素材。
• **在线工具：**使用 rotato.app/tools/transparent-video 验证你的 MOV 或 WebM 具有有效的透明度。

提示

💡 Tip

开发期间使用 draft 质量以获得快速预览。最终输出切换到 standard 或 high。

• 使用 npx hyperframes benchmark 查找系统的最优设置
• Docker 模式较慢但保证跨平台相同输出
• 对于帧数较多的合成，--gpu 可以显著加速本地编码

下一步

• 确定性渲染 了解确定性保证
• HDR 渲染 从 HDR 视频和图片源渲染 HDR10 MP4
• CLI 参考 完整的 CLI 命令和标志列表
• 故障排除 修复常见渲染问题