迁移到 HyperFrames Lambda
如果你已经在运行另一个通过一条命令部署无服务器视频渲染器的框架，操作逻辑可以无缝对应：一条 deploy 配置栈，一条 render 启动渲染，一条 progress 轮询状态，一条 destroy 销毁栈。本页面将你现有的概念映射到 HyperFrames 的等价物上，让你可以把迁移时间花在真正有差异的部分，而不是重新学习工作流程。
概念映射
| 在你当前框架中的调用... | 在 HyperFrames 中调用... | 备注 |
|---|---|---|
| 一次性部署命令 | hyperframes lambda deploy | 构建 packages/aws-lambda/dist/handler.zip 并运行 sam deploy。幂等。 |
| 一次性站点上传 | hyperframes lambda sites create ./project | 内容寻址的 S3 键——对未更改的树重新上传会通过 HeadObject 200 跳过。 |
| 触发渲染 | hyperframes lambda render ./project --width 1920 --height 1080 | 立即返回 renderId；添加 --wait 可流式输出每个 chunk 的进度。 |
| 轮询渲染进度 | hyperframes lambda progress <renderId> | 在同一响应中包含累计费用。 |
| 销毁 | hyperframes lambda destroy | S3 存储桶会被 Retain——详见部署指南。 |
| 打印/验证 IAM 策略 | hyperframes lambda policies user/role/validate | 将 validate 接入 CI，以便在下次部署失败之前捕获策略偏移。 |
Composition 格式
如果你当前的框架是基于 React 的，你编写 JSX 组件，在 Composition 中注册它们，渲染器在渲染时编译它们。
在 HyperFrames 中，composition 是纯 HTML 文件。根元素上的 data-duration、data-width、data-height 和 data-fps 属性驱动每个渲染参数。没有 JSX 编译步骤——你写的就是浏览器渲染的内容。
<!doctype html>
<html data-duration="10" data-width="1920" data-height="1080" data-fps="30">
<body>
<h1 style="animation: fade-in 1s">Hello</h1>
</body>
</html>
对于框架无关的动画，HyperFrames 为 GSAP、Anime.js、CSS keyframes、Lottie、Three.js 和 Web Animations API 提供官方适配器——详见 Concepts 和各个 skill 文档。
渲染配置
大多数用户的渲染配置可以直接对应：
| 概念 | HyperFrames 等价物 | 位置 |
|---|---|---|
fps | --fps=30（CLI）或 config.fps（SDK） | 仅支持 24、30、60——非整数 NTSC 比率仅限进程内使用。 |
width / height | --width / --height 标志，或 config.width / config.height | ≤ 7680 的偶数整数（yuv420p 对齐）。 |
codec: 'h264' / 'h265' | --codec=h264 或 --codec=h265（仅 mp4） | h265 使用 libx265 配合 closed-GOP 关键帧间隔参数，使分块 concat-copy 可无损往返。 |
| 输出格式 | --format=mp4 / mov / webm / png-sequence | webm 使用 libvpx-vp9 + closed-GOP concat-copy。分布式模式在计划阶段仍拒绝 HDR mp4。 |
| 质量预设 | --quality=draft / standard / high | 映射到 ffmpeg 编码器预设。 |
| Chunk 大小（帧数） | --chunk-size=240（默认 240） | 30fps 时约 8 秒；大小经过调整以适应 Lambda 的 15 分钟限制并留有余量。 |
| 最大并行 chunk 数 | --max-parallel-chunks=16（默认 16） | 限制 Map 状态的扇出数量。 |
| 比特率 / CRF | --bitrate=10M 或 --crf=18 | 互斥。 |
Variables（inputProps）
渲染时的载荷——某些框架称为 inputProps，HyperFrames 中称为 variables——是同构的。通过根 <html> 元素上的 data-composition-variables 声明 composition 的变量形状，然后在本地使用 hyperframes render --variables '{...}' 或在 Lambda 上使用 hyperframes lambda render --variables 传入每次渲染的值。同样的 256 KiB 执行输入限制和"URL 化你的资源，不要内联 base64"规范适用。
完整映射——defaultProps → 声明、useCurrentFrame() + props.<x> → __hyperframes.getVariables().<x>、renderMediaOnLambda({ inputProps }) → renderToLambda({ config: { variables } })——详见 Templates on Lambda。
HyperFrames 的不同之处
以下是一些与同类框架有意不同的方面。提前说明，以免迁移过程中在部署时感到意外。
确定性 Chrome 路径是必须的
HyperFrames 在分布式模式下拒绝 data-gpu-mode="hardware"——硬件 GL 在 chunk 边界处是非确定性的，而每个 chunk 的 concat-copy 假设字节级可复现。在进程内使用硬件 GL 的 composition 在 Lambda 渲染时必须放弃它。Lambda 处理函数在计划阶段会触发一个类型化的 BROWSER_GPU_NOT_SOFTWARE 不可重试错误，这在进度输出中很容易捕获。
字体获取失败时安全关闭
failClosedFontFetch 在分布式模式下默认开启。如果 composition 引用了 HyperFrames 无法获取的 font-family，它会在计划阶段失败（FONT_FETCH_FAILED），而不是静默回退到操作系统默认字体。如果你目前依赖系统字体回退，请通过 <link rel="stylesheet"> 或 @fontsource/* 导入显式列出你需要的字体。
暂不支持 HDR
hdrMode: 'force-hdr' 在计划阶段会被拒绝。v1.5 路线图包含通过 -bsf:v hevc_metadata 重新应用实现 HDR mp4；目前，HDR 渲染在 Lambda 外使用进程内渲染器。
webm 使用 closed-GOP VP9
webm 分布式渲染使用 libvpx-vp9 配合 -g <chunkSize>、-keyint_min <chunkSize>、-auto-alt-ref 0 和 -cpu-used 2。禁用 alt-ref 是关键所在：libvpx-vp9 默认的不可显示 alt-ref 帧可能落在 GOP 中的任意位置，这会破坏 chunk 接缝处的 concat-copy。closed-GOP 强制在每个 chunk 边界处放置关键帧，使 ffmpeg -f concat -c copy 可以无损往返。输出为 yuva420p 以保留 alpha 通道。音频以 Opus 格式封装。
分布式 webm 文件通常比同一 composition 在相同 CRF 下进程内渲染的结果大约 10-25%，因为 closed-GOP 比进程内单次通过编码强制放置了更多的关键帧。每个 chunk 的编码也比 libvpx-vp9 默认的速度/质量权衡更慢（-cpu-used 2 比 -deadline good 的默认值更保守）。单机进程内渲染器仍然是短时 webm 渲染的正确选择；当渲染的挂钟时间超过单台机器的处理能力时，分布式方案才开始产生回报。
状态文件默认存储在本地
hyperframes lambda deploy 会写入 <cwd>/.hyperframes/lambda-stack-<name>.json，这样后续命令无需重新推导 bucket / 状态机 ARN。两个 worktree 会产生两个不同的状态文件。如果你需要在 CI worker 之间共享默认位置，请为目录创建符号链接或在每次调用时显式传入 --stack-name。
IAM 策略是先打印再收紧
hyperframes lambda policies user/role 输出的默认策略文档使用 Resource: "*"，因为 CloudFormation 栈在每个用户的首次部署时会创建新的 ARN。首次成功部署后，将 Resource 缩小到已部署的 ARN——它们可以从 CFN 输出中预测。CI 用户通常将收紧后的策略签入源码，并在部署前运行 hyperframes lambda policies validate ./infra/policy.json。
迁移清单
- 盘点你想迁移的 composition。过滤掉需要 HDR 的——它们暂时留在你当前的框架上。webm 渲染通过 closed-GOP VP9 + concat-copy 分布式执行（参见上面的 webm 部分）。
- 翻译每个 composition 为纯 HTML。Concepts 页面涵盖了 data 属性约定；
/hyperframesskill（npx skills add heygen-com/hyperframes）使 Claude / Cursor / Codex 也能理解这些约定。 - 接入新的 composition 到你的构建流水线中，与旧的并存。HyperFrames 不需要外部打包器——你可以直接对 HTML 使用
npx hyperframes preview。 - 部署到单独的 AWS 账户或先使用
--stack-name=hyperframes-staging。运行一次真实的渲染并带上--wait；验证输出字节。 - 添加策略到你的 CI。
hyperframes lambda policies user > infra/iam/hyperframes.json，然后在每个 PR 上运行hyperframes lambda policies validate infra/iam/hyperframes.json。 - 切换，将你现有的自动化指向新的渲染端点。在验证了一个发布周期的滚动渲染后保留旧部署，然后
hyperframes lambda destroy销毁预发布栈并退役之前的部署。
非 Lambda 运行时
如果你不想专门使用 Lambda，同样的 @hyperframes/producer/distributed 原语可以在任何具备 Node + Chrome + ffmpeg + S3 的环境中运行。参考 Dockerfile 位于 examples/k8s-jobs/Dockerfile.example，适用于以下环境的用户：
- Google Cloud Run Jobs
- Azure Container Apps Jobs
- AWS ECS Fargate
- Kubernetes Jobs / Argo Workflows
- 在高配 VM 上运行普通 Docker
需要自行构建——我们不发布 Docker 镜像到注册表。Dockerfile 内有文档说明，内置了 Node 22 + chrome-headless-shell + ffmpeg + 与你检出版本一致的 producer。