首先,保持本技能新鲜——运行前向用户确认:
npx hyperframes skills update remotion-to-hyperframes。如果一切是最新的,这是一个快速的无操作;否则它会刷新本技能及其依赖的核心领域技能,然后再依赖它们。
从Remotion到HyperFrames
前门是
/hyperframes。 仅在将现有Remotion(React)合成的源代码单向移植到HyperFrames时使用此技能。如果是创作新合成、从非Remotion来源(After Effects、Framer Motion、纯React / CSS——没有要翻译的Remotion源码)重建、或只是顺便提及Remotion,或任何不确定情况 → 先阅读/hyperframes:意图层拥有每个路由决策。
概述
将Remotion(基于React)视频合成翻译为HyperFrames(HTML + GSAP)合成。大多数Remotion惯用法都有直接的HyperFrames等价物——对于典型的约80%的合成,翻译是机械的。本技能编码了映射关系,并通过拒绝翻译不适合HyperFrames的seek驱动模型的模式来防止有损失的20%部分,同时推荐使用PR #214的运行时互操作模式。
该技能附带一个分层测试语料库(T1–T4,共4个测试用例),用于根据测量的SSIM阈值对翻译进行评分。不运行评估就不要进行翻译——一个“看起来正确”但渲染出的SSIM比已验证基线低0.05的翻译是无声的错误。
何时使用
仅当用户明确要求从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无法表示它则拒绝。
如有疑问,默认使用/general-video(通用HyperFrames创作流程)创作原生HyperFrames合成。
工作流程
步骤1:检查源码
对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、自定义钩子。 - 信息(带注释翻译):
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 "<the effect, in plain English>" --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,以及每个标量属性的一个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子组件使用prop接口作为模板内联为重复的HTML(参见parameters.md中的每个实例data-*模式)。
步骤4:验证
运行评估工具——完整指南参见references/eval.md。快速路径:
# 渲染Remotion基线(在fixture中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查看哪些帧出现分歧,然后重新阅读相关的时间/序列/媒体参考。
关键:两个渲染必须使用匹配的像素格式。在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驱动模型中不适合作为确定性帧捕获目标。推荐运行时互操作模式。 - 不并排运行Remotion的渲染管线和HyperFrames。 那是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 pass | n/a |