remotion-to-hyperframes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Remotion to HyperFrames

Remotion 转 HyperFrames

Overview

概述

Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model and recommending the runtime interop pattern from PR #214 instead.

The skill ships with a tiered test corpus (T1–T4, 4 fixtures total) that grades translations against measured SSIM thresholds. Don't translate without running the eval — a translation that "looks right" but renders 0.05 SSIM lower than the validated baseline is silently wrong.

将Remotion（基于React）视频合成转换为HyperFrames（HTML + GSAP）合成。大多数Remotion惯用写法都有直接对应的HyperFrames等效写法——对于约80%的典型合成，转换过程是机械性的。该技能内置了映射规则，并通过拒绝转换不符合HF的seek-driven（基于帧定位）模型的模式，来避免20%的有损转换情况，转而推荐PR #214中的运行时互用模式。

该技能附带一个分层测试语料库（T1–T4，共4个测试用例），会根据测量的SSIM阈值对转换结果进行评分。未运行评估请勿进行转换——看起来“正确”但渲染结果的SSIM比验证基线低0.05的转换实际上是错误的。

When to use

使用场景

Use this skill ONLY when the user explicitly asks to migrate from Remotion. Example trigger phrases:

"port my Remotion project to HyperFrames"
"convert this Remotion code to HyperFrames"
"migrate from Remotion"
"translate this Remotion comp"
"rewrite this as HyperFrames HTML"

Do NOT use this skill when:

(a) The user is authoring a new HyperFrames composition, even if they have or are A/B-testing a similar Remotion video.
(b) The user mentions Remotion in passing without asking for migration.
(c) The user shares Remotion code as reference material rather than asking for a translation.
(d) The user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build.

When in doubt, default to authoring a native HyperFrames composition with the

hyperframes

skill instead.

仅当用户明确要求从Remotion迁移时使用此技能。触发示例短语：

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

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

(a) 用户正在创建新的HyperFrames合成，即使他们已有类似的Remotion视频或正在进行A/B测试。
(b) 用户只是顺带提及Remotion，未要求迁移。
(c) 用户分享Remotion代码作为参考资料，而非要求转换。
(d) 用户要求“制作和我的Remotion视频一样的视频”但未明确要求迁移源代码——此时应视为从头构建HyperFrames。

如有疑问，默认使用

hyperframes

技能创建原生HyperFrames合成。

Workflow

工作流程

Step 1: Lint the source

步骤1：检查源代码

Run

scripts/lint_source.py

over the Remotion source directory. The lint detects patterns that can't translate cleanly:

Blockers (refuse + recommend interop):
```
useState
```
,
```
useReducer
```
,
```
useEffect
```
/
```
useLayoutEffect
```
with non-empty deps, async
```
calculateMetadata
```
, third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
Warnings (translate after dropping the construct):
```
@remotion/lambda
```
config,
```
delayRender
```
,
```
useCallback
```
,
```
useMemo
```
, custom hooks.
Info (translate with note):
```
staticFile
```
,
```
interpolateColors
```
.

If any blocker fires, stop. Read

references/escape-hatch.md

and surface the recommendation message. Warnings don't stop translation — drop the offending construct in step 3 and note the gap in

TRANSLATION_NOTES.md

@remotion/lambda

config is the canonical warning case: the skill drops the import +

renderMediaOnLambda(...)

calls but translates the rest of the composition.

在Remotion源代码目录上运行

scripts/lint_source.py

。该检查工具会检测无法干净转换的模式：

阻塞项（拒绝转换并推荐互用方案）：
```
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

配置是典型的警告案例：技能会移除导入和

renderMediaOnLambda(...)

调用，但转换合成的其余部分。

Step 2: Plan the translation

步骤2：规划转换方案

Read

references/api-map.md

— the index of every Remotion API and its HF equivalent or per-topic reference. Identify which topic references you'll need based on what the source uses:

Source contains	Load reference
`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`

Don't load all of them — load only what the specific source needs.

阅读

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`

无需加载所有文档——仅加载特定源代码所需的内容。

Step 3: Generate the HF composition

步骤3：生成HF合成代码

Emit

index.html

with:

Root

<div id="stage">

carrying the composition's

data-composition-id

data-start="0"

data-duration

(in seconds),

data-fps

data-width

data-height

, plus one

data-*

per scalar prop.

A flat list of scene divs with
```
data-start
```
/
```
data-duration
```
/
```
data-track-index
```
.
Inline
```
<style>
```
for layout; CSS sets the
```
from
```
state of every animated property.
A single
```
<script>
```
tag at the bottom containing one paused
```
gsap.timeline({paused: true})
```
. Every Remotion
```
useCurrentFrame()
```
derivation becomes a tween on this timeline at the right offset.

window.__timelines["<composition-id>"] = tl;

registers the timeline with HF's runtime.

Custom React subcomponents inline as repeated HTML using the prop interface as the template (see

parameters.md

for the per-instance

data-*

pattern).

输出

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设置每个动画属性的初始状态。
底部的单个
```
<script>
```
标签，包含一个暂停的
```
gsap.timeline({paused: true})
```
。每个Remotion的
```
useCurrentFrame()
```
推导都会成为此时间轴上对应偏移位置的补间动画。

window.__timelines["<composition-id>"] = tl;

将时间轴注册到HF的运行时中。

自定义React子组件会按照属性接口作为模板内联为重复的HTML（每个实例的

data-*

模式请参考

parameters.md

）。

Step 4: Validate

步骤4：验证

Run the eval harness —

references/eval.md

for the full guide. Quick path:

bash

undefined

运行评估工具——完整指南请参考

references/eval.md

。快速流程：

bash

undefined

Render Remotion baseline (after npm install in the fixture)

渲染Remotion基线（在测试用例目录中执行npm install后）

cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

Render HF translation

渲染HF转换结果

cd ../hf-src && npx hyperframes render --output ../hf.mp4

SSIM diff

SSIM差异对比

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff


Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.

**Critical**: both renders must use matching pixel format. Set `Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")` in the Remotion source's `remotion.config.ts` — otherwise the diff measures encoder differences (~0.05 SSIM hit), not translation fidelity.

../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff


阈值：比源代码复杂度层级的`p05`值低约0.02（请参考`eval.md`中的验证阈值表）。如果差异对比失败，运行[`scripts/frame_strip.sh`](scripts/frame_strip.sh)查看哪些帧出现差异，然后重新阅读相关的时序/合成/媒体参考文档。

**关键提示**：两次渲染必须使用匹配的像素格式。在Remotion源代码的`remotion.config.ts`中设置`Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")`——否则差异对比测量的是编码器差异（约0.05的SSIM损失），而非转换保真度。

Step 5: Document gaps

步骤5：记录差异

Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a

TRANSLATION_NOTES.md

written next to the HF output. See

references/limitations.md

for the format.

所有无法干净转换的内容（如丢失的音量渐变、近似的自定义呈现、替换的字体）都需要在HF输出旁编写

TRANSLATION_NOTES.md

。格式请参考

references/limitations.md

。

What this skill explicitly does NOT do

此技能明确不支持的操作

Translate React state machines. Compositions that drive animation via
```
useState
```
+
```
useEffect
```
are not deterministic frame-capture targets in HyperFrames' seek-driven model. Recommend the runtime interop pattern.
Run Remotion's render pipeline alongside HyperFrames. That's the runtime interop pattern from PR #214 — a separate solution for compositions that fail this skill's lint.

(

@remotion/lambda

is not a blocker — Lambda config is deployment, not animation. The skill drops it as a warning and translates the rest. See

references/escape-hatch.md

转换React状态机。通过
```
useState
```
+
```
useEffect
```
驱动动画的合成在HyperFrames的seek-driven模型中不是确定性的帧捕获目标。请推荐运行时互用模式。
同时运行Remotion和HyperFrames的渲染流水线。这是PR #214中的运行时互用模式——是针对未通过此技能检查的合成的单独解决方案。

（

@remotion/lambda

不属于阻塞项——Lambda配置是部署相关内容，与动画无关。技能会将其作为警告项移除，并转换其余部分。请参考

references/escape-hatch.md

。）

How to grade your own translation

如何自行评估转换结果

Run the test corpus orchestrator:

bash

./assets/test-corpus/run.sh

It runs T1, T2, T3 (render + diff) and T4 (lint validation), prints a per-tier pass/fail table, and emits an aggregate JSON report. Use this to verify the skill is working end-to-end on a clean checkout — and as a regression check after editing any reference.

Validated baseline (as of 2026-04-27):

Tier	Composition shape	Mean SSIM	Threshold
T1	single-element fade-in	0.974	0.95
T2	multi-scene + spring + audio + image	0.985	0.95
T3	data-driven, custom subcomponents, count-up	0.953	0.90
T4	escape-hatch (8 lint cases)	8/8 pass	n/a

运行测试语料库编排器：

bash

./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 通过	n/a