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% 的翻译是机械化的。本技能编码了映射关系,并通过拒绝翻译不适合 HyperFrames 基于帧的驱动模型(seek-driven model)的模式来防范那有损的 20%,并推荐使用 PR #214 中的运行时互操作模式作为替代。
该技能附带一个分层测试语料库(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 配置是典型的警告情况:本技能会删除 import + renderMediaOnLambda(...) 调用,但翻译合成的其余部分。
步骤 2:规划翻译
阅读 references/api-map.md —— 所有 Remotion API 及其 HyperFrames 等价物或按主题分类的参考索引。根据源码使用的内容确定需要加载哪些主题参考:
| 源码包含的内容 | 加载的参考 |
|---|---|
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:生成 HyperFrames 合成
生成 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})。每个 RemotionuseCurrentFrame()推导都成为该时间线上正确偏移处的渐变动画 (tween)。 window.__timelines["<composition-id>"] = tl;将时间线注册到 HyperFrames 运行时。
自定义 React 子组件作为重复的 HTML 内联,以 prop 接口为模板(参见 parameters.md 了解每个实例的 data-* 模式)。
步骤 4:验证
运行评估工具 —— 完整指南请参阅 references/eval.md。快速路径:
# 渲染 Remotion 基线(在 fixture 中运行 npm install 之后)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# 渲染 HyperFrames 翻译
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
阈值:低于源码复杂度层级第 5 百分位数 (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:记录差异
任何未干净翻译的内容(丢弃的音量渐变、近似的自定义演示、替换的字体)都会在 HyperFrames 输出旁边生成 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 | 多场景 + 弹簧动画 + 音频 + 图片 | 0.985 | 0.95 |
| T3 | 数据驱动、自定义子组件、计数动画 | 0.953 | 0.90 |
| T4 | 逃生门(8 个检查用例) | 8/8 通过 | 不适用 |