Remotion 到 HyperFrames 迁移指南
概述
将 Remotion(基于 React)视频合成转换为 HyperFrames(HTML + GSAP)合成。大多数 Remotion 惯用法在 HyperFrames 中都有直接对应——对于约 80% 的典型合成来说,翻译是机械化的。该技能编码了映射关系,并通过拒绝翻译不适合 HyperFrames 基于帧驱动模型的不当模式,以及推荐来自 PR #214 的运行时间互操作模式,来防范那有损的 20%。
该技能附带一个分层的测试语料库(T1–T4,共4个测试用例),用于根据测量的 SSIM 阈值来评分翻译。不要在未运行评估的情况下进行翻译——一个“看起来不错”但 SSIM 比已验证基线低 0.05 的翻译在技术上是错误的。
工作流程
步骤 1:检查源码
在 Remotion 源码目录上运行 scripts/lint_source.py。该检查器会检测无法干净翻译的模式:
- 阻塞项(拒绝并推荐互操作):
useState、useReducer、带有非空依赖项的useEffect/useLayoutEffect、异步calculateMetadata、第三方 React UI 库(MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI)。 - 警告项(删除构造后翻译):
@remotion/lambda配置、delayRender、useCallback、useMemo、自定义钩子。 - 信息项(翻译时附加注释):
staticFile、interpolateColors。
如果有任何阻塞项触发,则停止。阅读 references/escape-hatch.md 并显示推荐信息。警告不会阻止翻译——在步骤 3 中删除有问题的构造,并在 TRANSLATION_NOTES.md 中记录差距。@remotion/lambda 配置是典型的警告情况:技能会删除导入和 renderMediaOnLambda(...) 调用,但会翻译合成的其余部分。
步骤 2:规划翻译
阅读 references/api-map.md——这是每个 Remotion API 及其 HF 对应项或按主题参考的索引。根据源码使用的内容,确定需要加载哪些主题参考:
| 源码包含的内容 | 加载参考文件 |
|---|---|
Composition、defaultProps、schema、calculateMetadata | parameters.md |
Sequence、Series、Loop、AbsoluteFill、Freeze | sequencing.md |
useCurrentFrame、interpolate、spring、Easing、interpolateColors | timing.md |
Audio、Video、Img、IFrame、staticFile、delayRender | media.md |
TransitionSeries、@remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>、Font.loadFont、@font-face | fonts.md |
不要全部加载——只加载特定源码需要的内容。
步骤 3:生成 HF 合成
输出 index.html,包含:
- 根
<div id="stage">,带有合成的data-composition-id、data-start="0"、data-duration(以秒为单位)、data-fps、data-width、data-height,以及每个标量 prop 的一个data-*。 - 场景 div 的扁平列表,其中包含
data-start/data-duration/data-track-index。 - 内联
<style>用于布局;CSS 设置每个动画属性的初始状态。 - 底部的一个单一
<script>标签,包含一个暂停的gsap.timeline({paused: true})。每个 RemotionuseCurrentFrame()推导都成为该时间线上在正确偏移量处的补间。 window.__timelines["<composition-id>"] = tl;将时间线注册到 HF 的运行时。
自定义 React 子组件会内联为重复的 HTML,使用 prop 接口作为模板(参见 parameters.md 了解按实例的 data-* 模式)。
步骤 4:验证
运行评估工具——references/eval.md 提供完整指南。快速路径:
# 渲染 Remotion 基线(在夹具中运行 npm install 后)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# 渲染 HF 翻译
cd ../hf-src && npx hyperframes render --output ../hf.mp4
# SSIM 差异对比
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
阈值:比源码复杂度等级的 p05 低约 0.02(参见 eval.md 的已验证阈值表)。如果差异失败,运行 scripts/frame_strip.sh 查看哪些帧出现差异,然后重新阅读相关的时序/排序/媒体参考。
关键:两个渲染必须使用匹配的像素格式。在 Remotion 源码的 remotion.config.ts 中设置 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否则差异会测量编码器差异(约 0.05 SSIM 损失),而不是翻译保真度。
步骤 5:记录差距
任何未能干净翻译的内容(如音量渐变丢失、自定义演示近似、字体替换)都会在 HF 输出旁生成一个 TRANSLATION_NOTES.md。格式参见 references/limitations.md。
本技能明确不做的事情
- 翻译 React 状态机。 使用
useState+useEffect驱动动画的合成在 HyperFrames 的基于帧驱动模型中不是确定性的帧捕获目标。推荐运行时间互操作模式。 - 在 HyperFrames 旁边运行 Remotion 的渲染管道。 那是来自 PR #214 的运行时间互操作模式——一个针对未通过本技能检查的合成的单独解决方案。
(@remotion/lambda 不是阻塞项——Lambda 配置是部署,不是动画。本技能会将其作为警告项删除并翻译其余部分。参见 references/escape-hatch.md。)
如何评估你自己的翻译
运行测试语料库编排器:
./assets/test-corpus/run.sh
它会运行 T1、T2、T3(渲染 + 差异对比)和 T4(检查验证),打印按层级划分的通过/失败表,并输出一个聚合的 JSON 报告。使用此功能来验证技能在干净检出上是否端到端工作——并在编辑任何参考后作为回归检查。
已验证基线(截至 2026-04-27):
| 层级 | 合成形状 | 平均 SSIM | 阈值 |
|---|---|---|---|
| T1 | 单元素淡入 | 0.974 | 0.95 |
| T2 | 多场景 + 弹簧动画 + 音频 + 图片 | 0.985 | 0.95 |
| T3 | 数据驱动、自定义子组件、计数动画 | 0.953 | 0.90 |
| T4 | 逃逸口(8 个检查用例) | 8/8 通过 | n/a |