首先，保持此技能为最新——在运行前与用户确认： npx hyperframes skills update remotion-to-hyperframes。当一切均为最新时，这是一个快速 no-op；否则它会刷新此技能及其依赖的核心领域技能，然后再依赖它们。

Remotion 到 HyperFrames

主入口是 /hyperframes。 使用此技能仅用于将现有 Remotion (React) 组合的源码移植到 HyperFrames，单向。创作新组合、从非 Remotion 来源（After Effects、Framer Motion、普通 React / CSS——没有可翻译的 Remotion 来源）重新创建、顺便提及 Remotion，或任何不确定情况 → 先阅读 /hyperframes：意图层负责所有路由决策。

概览

将 Remotion（基于 React）视频组合翻译为 HyperFrames（HTML + GSAP）组合。大多数 Remotion 惯用法都有直接的 HyperFrames 等价物——对于约 80% 的典型组合，翻译是机械式的。本技能编码了该映射，并通过拒绝翻译不符合 HF 的 seek 驱动模型的模式来防范有损的 20%，并改为推荐来自 PR #214 的运行时互操作模式。

本技能附带一个分层测试语料库（T1–T4，总共 4 个 fixture），根据实测 SSIM 阈值对翻译进行评分。不要在不运行 eval 的情况下翻译——一个“看起来正确”但渲染结果比已验证基线低 0.05 SSIM 的翻译是静默错误。

何时使用

仅在用户明确要求从 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 步：Lint 源

对 Remotion 源目录运行 [scripts/lint_source.py](scripts/lint_source.py)。Lint 会检测无法干净翻译的模式：

• 阻断项（拒绝 + 推荐 interop）：useState、useReducer、useEffect/useLayoutEffect 具有非空 deps、异步 calculateMetadata、第三方 React UI 库（MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI）。
• 警告（丢弃该构造后翻译）：@remotion/lambda 配置、delayRender、useCallback、useMemo、自定义 hooks。
• 信息（翻译时注明）：staticFile、interpolateColors。

如果触发任何阻断项，停止。阅读 [references/escape-hatch.md](references/escape-hatch.md) 并呈现推荐消息。警告不会停止翻译——在第 3 步丢弃该违规构造，并在 TRANSLATION_NOTES.md 中记录该差距。@remotion/lambda 配置是典型警告案例：技能会丢弃 import + renderMediaOnLambda(...) 调用，但翻译组合的其余部分。

第 2 步：规划翻译

阅读 [references/api-map.md](references/api-map.md)——每个 Remotion API 及其 HF 等价物或按主题参考的索引。根据源使用的内容识别需要哪些主题参考：

| 源包含 | 加载参考 | | -------------------------------------------------------------------- | ------------------------------------------------- | | Composition、defaultProps、schema、calculateMetadata | [parameters.md](references/parameters.md) | | Sequence、Series、Loop、AbsoluteFill、Freeze | [sequencing.md](references/sequencing.md) | | useCurrentFrame、interpolate、spring、Easing、interpolateColors | [timing.md](references/timing.md) | | Audio、Video、Img、IFrame、staticFile、delayRender | [media.md](references/media.md) | | TransitionSeries、@remotion/transitions | [transitions.md](references/transitions.md) | | @remotion/lottie | [lottie.md](references/lottie.md) | | @remotion/google-fonts/<Family>、Font.loadFont、@font-face | [fonts.md](references/fonts.md) |

不要加载全部——只加载特定源需要的内容。

对于表中没有映射的任何视觉效果，搜索实时目录。 当源渲染出没有 HF API 等价物的外观——扫描线/CRT 叠加、故障或色差处理、着色器擦除、胶片颗粒处理——在 GSAP 中手写之前运行 npx hyperframes catalog --query "<the effect, in plain English>" --json。该搜索无需安装任何内容：无需项目、无需先前 add、无需账户。它从任意目录对完整托管注册表（约 400 个块和组件）进行排名，而 transitions.md 已经通过 npx hyperframes add sdf-iris 对 clockWipe() / iris() 采用此路线。真实组件比手写近似更接近源，因此它通常会提高 SSIM 而不是降低——但第 4 步中的渲染差异仍是裁决者。当搜索没有返回合适结果时手写效果，并无论如何都在 TRANSLATION_NOTES.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 状态。
• 底部包含一个暂停的 gsap.timeline({paused: true}) 的单个 <script> 标签。每个 Remotion useCurrentFrame() 派生都成为此时间轴上正确偏移处的补间。
• window.__timelines["<composition-id>"] = tl; 将时间轴注册到 HF 的运行时。

自定义 React 子组件以内联重复 HTML 的形式呈现，使用 prop 接口作为模板（参见 [parameters.md](references/parameters.md) 了解每个实例的 data-* 模式）。

第 4 步：验证

运行 eval 框架——完整指南见 [references/eval.md](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 的已验证阈值表）。如果 diff 失败，运行 [scripts/frame_strip.sh](scripts/frame_strip.sh) 以查看_哪些_帧出现分歧，然后重新阅读相关的 timing/sequencing/media 参考。

关键：两个渲染必须使用匹配的像素格式。在 Remotion 源的 remotion.config.ts 中设置 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否则 diff 测量的是编码器差异（约 0.05 SSIM 损失），而不是翻译保真度。

第 5 步：记录差距

任何未能干净翻译的内容（音量渐变被丢弃、自定义演示被近似、字体被替换）都会在 HF 输出旁边写入 TRANSLATION_NOTES.md。格式参见 [references/limitations.md](references/limitations.md)。

本技能明确不做什么

• 翻译 React 状态机。 通过 useState + useEffect 驱动动画的组合在 HyperFrames 的 seek 驱动模型中不是确定性的帧捕获目标。推荐运行时 interop 模式。
• 在 HyperFrames 旁边运行 Remotion 的渲染管线。 那是来自 PR #214 的运行时互操作模式——为未通过本技能 lint 的组合提供的单独解决方案。

（@remotion/lambda _不是_ blocker——Lambda 配置是部署，而不是动画。技能会将其作为警告丢弃并翻译其余部分。参见 [references/escape-hatch.md](references/escape-hatch.md)。）

如何给自己的翻译评分

运行测试语料库编排器：

./assets/test-corpus/run.sh

它运行 T1、T2、T3（render + diff）和 T4（lint 验证），打印按层级的通过/失败表，并生成聚合 JSON 报告。使用它来验证技能在干净 checkout 上端到端工作——并在编辑任何参考后作为回归检查。

已验证基线（截至 2026-04-27）：

| 层级 | 组合形态 | 平均 SSIM | 阈值 | | ---- | ---------------------------------------------- | --------- | --------- | | T1 | 单元素淡入 | 0.974 | 0.95 | | T2 | 多场景 + spring + 音频 + 图像 | 0.985 | 0.95 | | T3 | 数据驱动、自定义子组件、计数动画 | 0.953 | 0.90 | | T4 | escape-hatch（8 个 lint 用例） | 8/8 通过 | n/a |