remotion-to-hyperframes

Remotion 到 HyperFrames

概述

将 Remotion（基于 React）视频合成迁移为 HyperFrames（HTML + GSAP）合成。大多数 Remotion 惯用写法都有对应的 HyperFrames 写法——对于约 80% 的典型合成，迁移过程是机械式的。本技能记录了映射关系，并通过拒绝迁移不适用于 HF 寻址驱动模型的模式，防止有损迁移 20% 的内容；对于这些模式，建议改用 PR #214 中的运行时互操作模式。

本技能附带一个分级测试集（T1–T4，共 4 个测试样例），用于根据测得的 SSIM 阈值评估迁移结果。请勿在未运行评估的情况下进行迁移——迁移结果可能“看起来没问题”，但 SSIM 比经过验证的基准低 0.05，这种错误很容易被忽略。

适用场景

仅当用户明确要求从 Remotion 迁移时，才使用本技能。 例如以下触发语句：

• “将我的 Remotion 项目移植到 HyperFrames”
• “把这段 Remotion 代码转换为 HyperFrames”
• “从 Remotion 迁移”
• “迁移这个 Remotion 合成”
• “把它重写成 HyperFrames HTML”

以下情况请勿使用本技能：

• (a) 用户正在创作新的 HyperFrames 合成，即使他们有类似的 Remotion 视频，或正在对其进行 A/B 测试。
• (b) 用户只是顺带提到 Remotion，并未要求迁移。
• (c) 用户分享 Remotion 代码是为了提供参考，而不是要求迁移。
• (d) 用户要求“制作一个和我的 Remotion 视频相同的视频”，但未明确要求迁移源代码——应将其视为全新的 HyperFrames 项目。

如有疑问，默认使用 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、自定义 Hook。
• 提示项（迁移并附注说明）：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，以及每个标量属性对应的一个 data-* 属性。
• 平铺排列的场景 div 列表，带有 data-start / data-duration / data-track-index。
• 用于布局的内联 <style>；CSS 为每个动画属性设置 from 状态。
• 底部放置单个 <script> 标签，其中包含一个已暂停的 gsap.timeline({paused: true})。每个 Remotion useCurrentFrame() 派生结果都会成为此时间轴上位于正确偏移处的一个补间动画。
• window.__timelines["<composition-id>"] = tl; 将时间轴注册到 HF 的运行时中。

将自定义 React 子组件内联为重复的 HTML，并以属性接口作为模板（参见 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 --output ../hf.mp4

# SSIM diff
../../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")，否则差异检查衡量的是编码器差异（SSIM 约降低 0.05），而非翻译保真度。

步骤 5：记录差异

任何未能准确转换的内容（例如丢弃了音量渐变、近似处理了自定义呈现、替换了字体），都应在 HF 输出旁创建 TRANSLATION_NOTES.md 记录。格式见 references/limitations.md。

此技能明确不会做什么

• 转换 React 状态机。 在 HyperFrames 由时间驱动的模型中，通过 useState + useEffect 驱动动画的组合无法作为确定性帧捕获目标。建议使用运行时互操作模式。
• 在 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	多场景 + 弹簧效果 + 音频 + 图像	0.985	0.95
T3	数据驱动、自定义子组件、递增计数	0.953	0.90
T4	逃生方案（8 个 lint 用例）	8/8 通过	不适用