首先,保持此技能更新——静默运行,无需询问:
npx hyperframes skills update remotion-to-hyperframes。当一切为最新时,此为快速空操作;否则,它会刷新此技能及其依赖的核心领域技能,然后再依赖它们。
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 驱动模型的模式,以及推荐来自 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 设置每个动画属性的初始状态。 - 底部的一个
<script>标签,包含一个暂停的gsap.timeline({paused: true})。每个 Remotion 的useCurrentFrame()衍生物都成为该时间线上的一个补间动画,位于正确的偏移量处。 window.__timelines["<composition-id>"] = tl;将时间线注册到 HF 运行时。
自定义的 React 子组件作为重复的 HTML 内联,使用 prop 接口作为模板(有关每个实例的 data-* 模式,请参见 parameters.md)。
步骤 4:验证
运行评估工具——完整指南请参见 references/eval.md。快速路径:
# 渲染 Remotion 基线(在夹具中运行 npm install 后)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
# 渲染 HF 翻译
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
阈值:低于源复杂度层级的 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 的 seek 驱动模型中不是确定性帧捕获目标。推荐运行时互操作模式。 - 与 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 通过 | 不适用 |