remotion-to-hyperframes

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 按需跳转模型的模式，防止有损处理剩余的 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 合成导出回 Remotion（或其他任何框架）不属于支持的工作流——转换方向仅限 Remotion → HyperFrames。请明确说明这一点。
• 非 Remotion 源。 After Effects 项目（.aep）、Framer Motion / 纯 React / CSS 动画，或其他工具的源代码，都不属于 Remotion 合成——没有 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、自定义钩子。
• 提示（转换时附注说明）：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 --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 中经验证的阈值表）。如果差异检查未通过，运行 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 通过	不适用