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的帧驱动模型的模式，转而推荐PR #214中的运行时互操作模式，以此避免那20%的有损转换情况。

本技能附带一个分层测试语料库（T1–T4，共4个测试用例），会基于测量的SSIM阈值对转换结果进行评分。未运行评估不要进行转换——看起来“正确”但SSIM比验证基线低0.05的转换其实是隐性错误的。

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
```
、自定义钩子。
提示项（转换并附带说明）：
```
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的帧驱动模型中不是确定性的帧捕获目标。请推荐使用运行时互操作模式。
同时运行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 通过	不适用