Communitygithub.com

Remotion 到 HyperFrames 迁移技能

将现有的 Remotion(基于 React)视频合成转换为 HyperFrames HTML 合成。仅当用户明确要求迁移、转换或重写 Remotion 合成为 HyperFrames 时使用。

Remotion 到 HyperFrames 迁移技能 是什么?

该技能提供了一种机械化的翻译流程,用于将基于 React 的 Remotion 视频合成转换为基于 HTML 和 GSAP 的 HyperFrames 合成。它适用于大约 80% 的典型 Remotion 组合,但通过代码检查阻止那些无法干净翻译的模式(如使用 React 状态管理或异步 calculateMetadata),并为这些复杂情况推荐运行时互操作模式。该技能需要一个结构化的五步工作流程:通过 lint_source.py 检查源码,通过 api-map.md 规划翻译,生成带有 GSAP 时间线的 index.html,通过 SSIM 阈值进行验证,并记录任何翻译差距在 TRANSLATION_NOTES.md 中。它包含一个分层测试语料库(T1-T4),通过测量 SSIM 评分来确保翻译保真度,并自动处理 Remotion 的 useCurrentFrame、Sequence 和 interpolate 等常用 API 的等效映射。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/libz-renlab-ai/TeamBrain/tree/HEAD/.agents/skills/remotion-to-hyperframes

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Remotion 到 HyperFrames 迁移指南

概述

将 Remotion(基于 React)视频合成转换为 HyperFrames(HTML + GSAP)合成。大多数 Remotion 惯用法在 HyperFrames 中都有直接对应——对于约 80% 的典型合成来说,翻译是机械化的。该技能编码了映射关系,并通过拒绝翻译不适合 HyperFrames 基于帧驱动模型的不当模式,以及推荐来自 PR #214 的运行时间互操作模式,来防范那有损的 20%。

该技能附带一个分层的测试语料库(T1–T4,共4个测试用例),用于根据测量的 SSIM 阈值来评分翻译。不要在未运行评估的情况下进行翻译——一个“看起来不错”但 SSIM 比已验证基线低 0.05 的翻译在技术上是错误的。

工作流程

步骤 1:检查源码

在 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(...) 调用,但会翻译合成的其余部分。

步骤 2:规划翻译

阅读 references/api-map.md——这是每个 Remotion API 及其 HF 对应项或按主题参考的索引。根据源码使用的内容,确定需要加载哪些主题参考:

源码包含的内容加载参考文件
Composition、defaultProps、schema、calculateMetadataparameters.md
Sequence、Series、Loop、AbsoluteFill、Freezesequencing.md
useCurrentFrame、interpolate、spring、Easing、interpolateColorstiming.md
Audio、Video、Img、IFrame、staticFile、delayRendermedia.md
TransitionSeries、@remotion/transitionstransitions.md
@remotion/lottielottie.md
@remotion/google-fonts/<Family>、Font.loadFont、@font-facefonts.md

不要全部加载——只加载特定源码需要的内容。

步骤 3:生成 HF 合成

输出 index.html,包含:

  • 根 <div id="stage">,带有合成的 data-composition-id、data-start="0"、data-duration(以秒为单位)、data-fps、data-width、data-height,以及每个标量 prop 的一个 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,使用 prop 接口作为模板(参见 parameters.md 了解按实例的 data-* 模式)。

步骤 4:验证

运行评估工具——references/eval.md 提供完整指南。快速路径:

# 渲染 Remotion 基线(在夹具中运行 npm install 后)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# 渲染 HF 翻译
cd ../hf-src && npx hyperframes render --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 的基于帧驱动模型中不是确定性的帧捕获目标。推荐运行时间互操作模式。
  • 在 HyperFrames 旁边运行 Remotion 的渲染管道。 那是来自 PR #214 的运行时间互操作模式——一个针对未通过本技能检查的合成的单独解决方案。

(@remotion/lambda 不是阻塞项——Lambda 配置是部署,不是动画。本技能会将其作为警告项删除并翻译其余部分。参见 references/escape-hatch.md。)

如何评估你自己的翻译

运行测试语料库编排器:

./assets/test-corpus/run.sh

它会运行 T1、T2、T3(渲染 + 差异对比)和 T4(检查验证),打印按层级划分的通过/失败表,并输出一个聚合的 JSON 报告。使用此功能来验证技能在干净检出上是否端到端工作——并在编辑任何参考后作为回归检查。

已验证基线(截至 2026-04-27):

层级合成形状平均 SSIM阈值
T1单元素淡入0.9740.95
T2多场景 + 弹簧动画 + 音频 + 图片0.9850.95
T3数据驱动、自定义子组件、计数动画0.9530.90
T4逃逸口(8 个检查用例)8/8 通过n/a

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

libz-renlab-ai/TeamBrain

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

libz-renlab-ai/TeamBrain

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

libz-renlab-ai/TeamBrain

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

libz-renlab-ai/TeamBrain

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

libz-renlab-ai/TeamBrain

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

相关技能