remotion-to-framevideo

Remotion 转 FrameVideo

概述

将 Remotion（基于 React）视频合成转换为 FrameVideo（HTML + GSAP）合成。大多数 Remotion 惯用模式在 FrameVideo 中都有直接对应项——对于约 80% 的典型合成，转换过程是机械式的。本技能编码了这种映射，并通过拒绝转换不适用于 HF 按需定位模型的模式，避免丢失其余 20% 的内容；对于这些模式，建议改用 PR #214 中的运行时互操作方案。

本技能附带一个分级测试语料库（T1–T4，共 4 个测试样例），根据实测 SSIM 阈值对转换结果进行评分。请勿在未运行评估的情况下进行转换——转换结果可能“看起来没问题”，但 SSIM 比已验证基线低 0.05，这种错误很容易被忽略。

适用场景

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

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

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

• (a) 用户正在编写新的 FrameVideo 合成，即使他们有一个类似的 Remotion 视频，或正在对其进行 A/B 测试。
• (b) 用户只是顺带提到 Remotion，并未要求迁移。
• (c) 用户分享 Remotion 代码是作为参考资料，而非要求转换。
• (d) 用户要求“制作与我的 Remotion 视频相同的视频”，但未明确要求迁移源代码——应将其视为全新的 FrameVideo 构建。

如有疑问，请改用 framevideo 技能编写原生 FrameVideo 合成。

工作流

步骤 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 ../fv-src && npx framevideo render --output ../fv.mp4

# SSIM diff
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./fv.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 状态机。 通过 useState + useEffect 驱动动画的组合，在 FrameVideo 基于 seek 驱动的模型中并非确定性帧捕获目标。建议使用运行时互操作模式。
• 不让 Remotion 的渲染管线与 FrameVideo 同时运行。 这是 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 通过	不适用