remotion-to-hyperframes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Remotion to HyperFrames

Remotion 转 HyperFrames

Confirm the route before you build. Use this only to port an existing Remotion (React) composition's source into HyperFrames. Authoring a new composition (even one inspired by a Remotion video) → the creation workflows /
/general-video
. Out of scope (one-way, Remotion-only): no reverse export (HyperFrames → Remotion or any framework), and a non-Remotion source (After Effects, Framer Motion, plain React / CSS) has no Remotion source to translate → re-create via
/general-video
. Unsure, or only a passing Remotion mention? Read
/hyperframes
first.

构建前请确认使用场景。本技能仅用于将现有Remotion（React）合成源码迁移至HyperFrames。创建新合成（即使是受Remotion视频启发的合成）请使用常规创建流程或
/general-video
。不在服务范围内（仅支持单向Remotion迁移）：不支持反向导出（HyperFrames→Remotion或其他框架），非Remotion源文件（After Effects、Framer Motion、纯React/CSS）无Remotion源码可转换——需通过
/general-video
重新创建。不确定使用场景或仅顺带提及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.

将基于React的Remotion视频合成转换为HyperFrames（HTML + GSAP）合成。大多数Remotion惯用写法都有对应的HyperFrames等效实现——约80%的常规合成可通过机械方式完成转换。本技能内置了映射规则，对于不符合HF的seek驱动模型的模式会拒绝转换，转而推荐PR #214中的运行时互操作模式，以此避免20%的有损转换情况。

本技能附带分层测试语料库（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.

NOT SUPPORTED (decline — this is not what this skill does):

The reverse direction. Exporting a HyperFrames composition back out to Remotion (or to any other framework) is not a workflow — the translation is Remotion → HyperFrames only. Say so plainly.
Non-Remotion sources. An After Effects project (
```
.aep
```
), a Framer Motion / plain-React / CSS animation, or any other tool's source is not a Remotion composition — there is no Remotion source to translate. Re-create it natively via
```
/general-video
```
, or decline if HyperFrames can't represent it.

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

/general-video

(the general HyperFrames authoring flow) instead.

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

"将我的Remotion项目迁移至HyperFrames"
"将这段Remotion代码转换为HyperFrames"
"从Remotion迁移"
"翻译这段Remotion合成代码"
"将这段代码重写为HyperFrames HTML"

请勿在以下场景使用本技能：

(a) 用户正在创建新的HyperFrames合成，即使他们已有类似的Remotion视频或正在进行A/B测试。
(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创建流程）。

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-*
```
。
包含
```
data-start
```
/
```
data-duration
```
/
```
data-track-index
```
的场景div扁平列表。
用于布局的内联
```
<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 --skill=remotion-to-hyperframes --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驱动模型的确定性帧捕获目标。推荐使用运行时互操作模式。
同时运行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