Remotion 转 HyperFrames 是做什么的?
在执行构建之前,请先确认路线。 此技能仅用于将现有的 Remotion (React) 合成源码移植到 HyperFrames。创作一个新的合成(即使是受 Remotion 视频启发)→ 请使用创作工作流
/general-video。超出范围(单向,仅限 Remotion):不支持反向导出(HyperFrames → Remotion 或任何框架),并且一个非 Remotion 源(After Effects、Framer Motion、原生 React/CSS)没有可翻译的 Remotion 源码 → 请通过/general-video重新创建。不确定,或仅仅是提了一下 Remotion?请先阅读/hyperframes。
概述
将 Remotion(基于 React)视频合成翻译为 HyperFrames(HTML + GSAP)合成。大多数 Remotion 惯用法都有直接的 HyperFrames 等价物——对于约 80% 的典型合成,翻译是机械性的。此技能编码了这种映射关系,并通过拒绝翻译不适合 HF 基于帧查找模型的模式,同时推荐使用 PR #214 中的运行时互操作模式,来防范那有损的 20%。
该技能附带一个分级测试语料库(T1–T4,共 4 个固定测试用例),可根据测量的 SSIM 阈值对翻译进行评分。未经运行评估请不要进行翻译——一个看起来正确但渲染结果比验证基线低 0.05 SSIM 的翻译是静默错误的。
何时使用
仅当用户明确要求从 Remotion 迁移时才使用此技能。 触发短语示例:
- "将我的 Remotion 项目移植到 HyperFrames"
- "将这段 Remotion 代码转换为 HyperFrames"
- "从 Remotion 迁移"
- "翻译这个 Remotion 合成"
- "将其重写为 HyperFrames HTML"
在以下情况下请勿使用此技能:
- (a) 用户正在创作一个新的 HyperFrames 合成,即使他们正在对比测试一个类似的 Remotion 视频。
- (b) 用户顺带提到了 Remotion,但并未请求迁移。
- (c) 用户分享 Remotion 代码作为参考资料,而非请求翻译。
- (d) 用户要求“与我的 Remotion 视频相同”但未明确要求迁移源码——将其视为一个全新的 HyperFrames 构建。
不支持(请拒绝——这不在本技能范围内):
- 反向方向。 将 HyperFrames 合成导出回 到 Remotion(或任何其他框架)并不是一个工作流——翻译方向只能是 Remotion → HyperFrames。直接说明。
- 非 Remotion 源。 After Effects 项目(
.aep)、Framer Motion / 原生 React / CSS 动画或任何其他工具的源码都不是 Remotion 合成——没有 Remotion 源码可翻译。通过/general-video原生重新创建,或者如果 HyperFrames 无法表示则拒绝。
如有疑问,默认使用 /general-video(通用的 HyperFrames 创作流程)创作原生 HyperFrames 合成。
工作流
第一步:检查源码
在 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 并展示推荐消息。警告项不会阻止翻译——在第三步中删除违规构造并在 TRANSLATION_NOTES.md 中记录差异。@remotion/lambda 配置是典型的警告案例:技能会删除导入和 renderMediaOnLambda(...) 调用,但会翻译合成的其余部分。
第二步:规划翻译
阅读 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 |
不要全部加载——只加载特定源码所需的部分。
第三步:生成 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 设置所有动画属性的from状态。 - 底部的一个
<script>标签,包含一个暂停的gsap.timeline({paused: true})。每个 RemotionuseCurrentFrame()派生值都成为此时间线上正确偏移处的补间动画。 window.__timelines["<composition-id>"] = tl;将时间线注册到 HF 运行时。
自定义 React 子组件内联为重复的 HTML,使用 prop 接口作为模板(参见 parameters.md 了解每个实例的 data-* 模式)。
第四步:验证
运行评估框架——完整指南见 references/eval.md。快速路径:
# 渲染 Remotion 基线(在固定测试用例中执行 npm install 后)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# 渲染 HF 翻译
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --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 损失),而非翻译保真度。
第五步:记录差异
任何未能干净翻译的内容(删除的音量渐变、近似的自定义演示文稿、替换的字体)都将在 HF 输出旁边生成一个 TRANSLATION_NOTES.md。格式参见 references/limitations.md。
此技能明确不做什么
- 翻译 React 状态机。 通过
useState+useEffect驱动动画的合成在 HyperFrames 的基于帧查找模型中不是确定性帧捕获目标。推荐使用运行时互操作模式。 - 与 HyperFrames 同时运行 Remotion 的渲染管线。 这是 PR #214 中的运行时互操作模式——一个针对无法通过该技能 lint 检查的合成的独立解决方案。
(@remotion/lambda _不是_阻止项——Lambda 配置属于部署,而非动画。技能会将其作为警告项删除并翻译其余部分。参见 references/escape-hatch.md。)
如何评价你自己的翻译
运行测试语料库编排器:
./assets/test-corpus/run.sh
它将运行 T1、T2、T3(渲染+差异比较)和 T4(lint 验证),打印每个层级的通过/失败表,并输出一个聚合的 JSON 报告。使用此工具验证技能在全新检出上是否端到端正常工作——并作为编辑任何参考资料后的回归检查。
已验证基线(截至 2026-04-27):
| 层级 | 合成形状 | 平均 SSIM | 阈值 |
|---|---|---|---|
| T1 | 单元素淡入 | 0.974 | 0.95 |
| T2 | 多场景 + spring + 音频 + 图像 | 0.985 | 0.95 |
| T3 | 数据驱动、自定义子组件、计数动画 | 0.953 | 0.90 |
| T4 | 逃逸舱(8 个 lint 用例) | 8/8 通过 | 不适用 |