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 逐帧驱动模型的模式，以及推荐来自 PR #214 的运行时互操作模式，来防范有损的 20%。

该技能附带一个分层测试语料库（T1–T4，共 4 个测试用例），根据测量的 SSIM 阈值对翻译进行评分。不运行评估就不要翻译——一个“看起来正确”但 SSIM 比验证基线低 0.05 的翻译是静默错误的。

何时使用

仅当用户明确要求从 Remotion 迁移时使用此技能。 触发短语示例：

• "将我的 Remotion 项目移植到 HyperFrames"
• "将此 Remotion 代码转换为 HyperFrames"
• "从 Remotion 迁移"
• "翻译此 Remotion 合成"
• "将其重写为 HyperFrames HTML"

在以下情况下不要使用此技能：

• (a) 用户正在创作新的 HyperFrames 合成，即使他们有或正在 A/B 测试类似的 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 合成。

工作流

步骤 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 设置每个动画属性的 from 状态。
• 底部一个 <script> 标签，包含一个暂停的 gsap.timeline({paused: true})。每个 Remotion useCurrentFrame() 推导都成为此时间线上正确偏移处的补间。
• 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 查看哪些帧出现差异，然后重新阅读相关的 timing/sequencing/media 参考。

关键：两个渲染必须使用匹配的像素格式。在 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	多场景 + spring + 音频 + 图像	0.985	0.95
T3	数据驱动、自定义子组件、计数动画	0.953	0.90
T4	逃生舱（8 个检查用例）	8/8 通过	不适用