插件安装: 在执行设置或刷新命令之前,如果此技能位于 HyperFrames 插件内部,请遵循插件执行规则。独立安装则保留下面的更新说明。
首先,保持此技能最新——在运行前与用户确认:
npx hyperframes skills update remotion-to-hyperframes。如果一切最新,则快速无操作;否则,它会在你依赖此技能以及其依赖的核心领域技能之前刷新它们。
Remotion 到 HyperFrames
入口是
/hyperframes。 仅在将现有的 Remotion (React) 合成源码移植到 HyperFrames 时使用此技能,单向。创作 新 合成、从非 Remotion 源(After Effects、Framer Motion、纯 React / CSS——没有 Remotion 源码可翻译)重新创建、或任何不确定的情况 → 请先阅读/hyperframes:意图层负责所有路由决策。
概述
将 Remotion (基于 React) 视频合成转换为 HyperFrames (HTML + GSAP) 合成。大多数 Remotion 惯用法都有直接的 HyperFrames 等价物——对于约 80% 的典型合成,翻译是机械性的。此技能编码了映射关系,并通过拒绝翻译不适合 HF 基于 seek 模型的模式来防止那有损耗的 20%,并推荐使用 PR #214 中的运行时互操作模式。
该技能附带一个分层测试语料库(T1–T4,共 4 个测试用例),用于根据测量的 SSIM 阈值对翻译进行评分。不要在没有运行评估的情况下进行翻译——一个“看起来正确”但渲染结果比验证基线低 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 无法表示,则拒绝。
如有疑问,请返回 /hyperframes;其意图层会选择路由。
工作流程
步骤 1:Lint 源代码
在 Remotion 源目录上运行 scripts/lint_source.py。Lint 会检测无法干净翻译的模式:
- 阻塞项(拒绝并推荐互操作):
useState、useReducer、具有非空依赖项的useEffect/useLayoutEffect、异步calculateMetadata、第三方 React UI 库(MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI)。 - 警告项(翻译但移除该构造):
@remotion/lambda配置、delayRender、useCallback、useMemo、自定义 hooks。 - 信息项(翻译并附注):
staticFile、interpolateColors。
如果触发了任何阻塞项,停止。阅读 references/escape-hatch.md 并展示推荐消息。警告项不会停止翻译——在步骤 3 中移除违规构造并在 TRANSLATION_NOTES.md 中记录差距。@remotion/lambda 配置是典型的警告案例:该技能会移除 import + 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 |
不要全部加载——只加载特定源需要的内容。
在实时目录中搜索表格未映射的任何视觉效果。 当源绘制了一种没有 HF API 等价物的外观——扫描线/CRT 叠加、故障或色差通道、着色器擦除、胶片颗粒处理——在手写 GSAP 之前,运行 npx hyperframes catalog --query "<以纯英语描述的视觉效果>" --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-composition-src="compositions/<scene>.html"和data-start/data-duration/data-track-index。根元素不包含嵌套布局。 - 每个场景一个
compositions/<scene>.html(一个<template>子合成):其用于布局的内联<style>(CSS 设置每个动画属性的from状态)、其标记,以及一个在场景本地时间内的暂停的gsap.timeline({paused: true})。每个 RemotionuseCurrentFrame()推导转换为该时间线上场景内偏移处的补间。 - 在每个场景文件中设置
window.__timelines["<scene-id>"] = tl;,并为根元素自身的(可能为空)时间线设置window.__timelines["<composition-id>"]。
自定义 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 中的运行时互操作模式——一个针对无法通过此技能 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 | 多场景 + spring + 音频 + 图像 | 0.985 | 0.95 |
| T3 | 数据驱动、自定义子组件、计数 | 0.953 | 0.90 |
| T4 | 降级方案(8 个 lint 案例) | 8/8 通过 | 不适用 |