概述
本技能用于把基于 React 的 Remotion 视频合成翻译为 HyperFrames(HTML + GSAP)合成。多数 Remotion 惯用法都有对应的 HyperFrames 等价写法,典型合成中约 80% 的翻译是机械性的;对于不适合 HyperFrames 寻帧驱动模型的模式,技能会拒绝翻译,并建议采用 PR #214 中的运行时互操作方案。
技能附带分层测试语料(T1–T4,共 4 个夹具),按实测 SSIM 阈值给翻译打分。未运行评估不要进行翻译——一个“看起来正确”但 SSIM 比验证基线低 0.05 的翻译属于隐性错误。
适用时机
仅在用户明确要求从 Remotion 迁移时使用,例如:
- “把我的 Remotion 项目移植到 HyperFrames”
- “把这段 Remotion 代码转换成 HyperFrames”
- “从 Remotion 迁移”
- “翻译这个 Remotion 合成”
- “把它重写为 HyperFrames HTML”
以下情况不要使用:
- 用户正在编写新的 HyperFrames 合成,即使有相似的 Remotion 视频或正在做 A/B 测试。
- 用户只是顺带提到 Remotion,并未要求迁移。
- 用户提供 Remotion 代码作为参考资料,而非要求翻译。
- 用户要求“做出和我的 Remotion 一样的视频”但未明确要求迁移源码——应视为全新 HyperFrames 构建。
不支持的情形(应明确拒绝):
- 反向方向:把 HyperFrames 合成导出回 Remotion 或其他框架不是本技能的工作流,翻译仅限 Remotion → HyperFrames。
- 非 Remotion 来源:After Effects 工程(.aep)、Framer Motion、纯 React/CSS 动画等没有 Remotion 源码可翻译,应通过 /general-video 原生重建,或在 HyperFrames 无法表达时拒绝。
存疑时,默认使用 /general-video(通用 HyperFrames 编写流程)原生编写 HyperFrames 合成。
工作流程
第 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、自定义 hooks。
- 信息项(翻译并注明):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})。每个 Remotion useCurrentFrame() 推导都变成该时间线上正确偏移处的补间。
- window.__timelines["<composition-id>"] = tl; 向 HF 运行时注册时间线。
- 自定义 React 子组件以内联重复 HTML 形式呈现,以 prop 接口为模板(参见 parameters.md 的按实例 data-* 模式)。
第 4 步:验证
运行评估工具——完整指南见 references/eval.md。快速路径:
Render Remotion baseline (after npm install in the fixture)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
Render HF translation
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
SSIM diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
阈值:约比源码复杂度等级 p05 低 0.02(见 eval.md 的验证阈值表)。若 diff 失败,运行 scripts/frame_strip.sh 查看哪些帧出现偏差,然后重读相关的 timing/sequencing/media 参考。
关键:两次渲染必须使用匹配的像素格式。在 Remotion 源码的 remotion.config.ts 中设置 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否则 diff 测的是编码器差异(约 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(渲染 + diff)和 T4(lint 验证),打印分层通过/失败表,并输出聚合 JSON 报告。用于在干净检出上端到端验证技能是否工作,以及编辑任何参考后的回归检查。
验证基线(截至 2026-04-27):
T1 单元素淡入,平均 SSIM 0.974,阈值 0.95; T2 多场景 + spring + 音频 + 图片,平均 SSIM 0.985,阈值 0.95; T3 数据驱动、自定义子组件、计数增长,平均 SSIM 0.953,阈值 0.90; T4 逃生通道(8 个 lint 用例),8/8 通过,无阈值。