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）composition 的源代码移植到 HyperFrames 时，才使用此 skill。创作新 composition（即使只是受某个 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 视频 composition 转换为基于 HyperFrames（HTML + GSAP）的 composition。大多数 Remotion 惯用写法都有直接的 HyperFrames 对应项——对于约 80% 的典型 composition，转换是机械式的。此 skill 编码了这些映射关系，并通过拒绝转换不符合 HF 基于 seek 的模型的模式，防止剩余 20% 出现有损转换，同时推荐 PR #214 中提出的运行时互操作方案。

该 skill 附带分级测试语料库（T1–T4，共 4 个 fixture），依据实测 SSIM 阈值对转换结果进行评分。不要在没有运行 eval 的情况下进行转换——一个“看起来正确”但渲染 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 迁移时，才使用此 skill。 触发短语示例：

“把我的 Remotion 项目移植到 HyperFrames”
“把这些 Remotion 代码转换为 HyperFrames”
“从 Remotion 迁移”
“转换这个 Remotion comp”
“重写为 HyperFrames HTML”

不要在以下情况下使用此 skill：

(a) 用户正在创作新的 HyperFrames composition，即使他们拥有或正在 A/B 测试类似的 Remotion 视频。
(b) 用户只是顺带提及 Remotion，并没有要求迁移。
(c) 用户只是分享 Remotion 代码作为参考材料，而不是要求进行转换。
(d) 用户只要求“与我的 Remotion 视频相同”，却没有明确要求迁移源代码——此时应视为全新的 HyperFrames 构建。

不支持（拒绝——这不是此 skill 的用途）：

反向方向。 将 HyperFrames composition 导出回 Remotion（或任何其他框架）不属于工作流范围——转换仅支持 Remotion → HyperFrames。请直接说明这一点。
非 Remotion 来源。 After Effects 项目（
```
.aep
```
）、Framer Motion／普通 React／CSS 动画或任何其他工具的源代码都不是 Remotion composition，因此没有可供转换的 Remotion 源代码。请通过
```
/general-video
```
原生重新创建；如果 HyperFrames 无法表现它，则拒绝处理。

如有疑问，默认使用

/general-video

（通用 HyperFrames 创作流程）创作原生 HyperFrames composition。

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

。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

配置是典型的警告案例：skill 会移除 import 和

renderMediaOnLambda(...)

调用，但会转换 composition 的其余部分。

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 composition

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">
```
，带有 composition 的
```
data-composition-id
```
、
```
data-start="0"
```
、
```
data-duration
```
（单位为秒）、
```
data-fps
```
、
```
data-width
```
、
```
data-height
```
，以及每个标量 prop 对应的一个
```
data-*
```
属性。
扁平的 scene div 列表，每个元素带有
```
data-start
```
／
```
data-duration
```
／
```
data-track-index
```
。
用于布局的内联
```
<style>
```
；CSS 设置每个动画属性的
```
from
```
状态。
底部唯一的
```
<script>
```
标签，其中包含一个暂停的
```
gsap.timeline({paused: true})
```
。每个由 Remotion
```
useCurrentFrame()
```
推导出的值，都会变成该 timeline 上位于正确偏移位置的 tween。

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

，用于向 HF runtime 注册 timeline。

将自定义 React 子组件以 prop 接口为模板，以重复 HTML 的形式内联（有关每实例

data-*

模式，请参阅

parameters.md

）。

Step 4: Validate

第 4 步：验证

Run the eval harness —

references/eval.md

for the full guide. Quick path:

bash

undefined

运行 eval 测试工具——完整指南请参阅

references/eval.md

。快速路径：

bash

undefined

Render Remotion baseline (after npm install in the fixture)

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

Render HF translation

cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4

SSIM diff

../../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) 查看_哪些_帧出现偏差，然后重新阅读相关的 timing／sequencing／media 参考文档。

**关键事项**：两次渲染必须使用匹配的像素格式。在 Remotion 源代码的 `remotion.config.ts` 中设置 `Config.setVideoImageFormat("png")` 和 `Config.setColorSpace("bt709")`——否则，差异测试衡量的是编码器差异（SSIM 约下降 0.05），而不是转换保真度。

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

此 skill 明确不做什么

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
```
驱动动画的 composition，在 HyperFrames 基于 seek 的模型中不是确定性的逐帧捕获目标。推荐使用运行时互操作方案。
并行运行 Remotion 渲染管线与 HyperFrames。 这属于 PR #214 的运行时互操作方案——是针对未通过此 skill 的 lint 检查的 composition 提供的独立解决方案。

（

@remotion/lambda

_不是_阻断项——Lambda 配置属于部署，而非动画。skill 会将其作为警告移除，同时转换其余部分。请参阅

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（lint 验证），打印各层级的通过／失败表，并输出汇总 JSON 报告。使用它可以在干净检出上验证 skill 是否端到端正常工作，也可以在编辑任何参考文档后将其用作回归检查。

已验证基线（截至 2026-04-27）：

层级	Composition 结构	平均 SSIM	阈值
T1	单元素淡入	0.974	0.95
T2	多场景 + spring + 音频 + 图像	0.985	0.95
T3	数据驱动、自定义子组件、数值递增	0.953	0.90
T4	escape-hatch（8 个 lint 用例）	8/8 通过	不适用