Communitygithub.com

Remotion 到 HyperFrames 迁移

将现有的 Remotion(React)视频合成项目迁移到 HyperFrames(HTML + GSAP)格式。仅当用户明确要求移植/转换/迁移/翻译 Remotion 源代码时使用。

Remotion 到 HyperFrames 迁移 是什么?

这是一个专门用于将 Remotion(基于 React)视频合成翻译为 HyperFrames(HTML + GSAP)合成的人工智能代理技能。该技能采用机械式映射,约 80% 的典型 Remotion 合成可以直接转换,其余 20% 涉及局限性模式(如 React 状态管理、async `calculateMetadata`、第三方 React UI 库等),需要推荐运行时互操作方案而非直接翻译。它集成了分层测试语料库(T1-T4,共 4 个固定测试用例),通过计算的 SSIM 阈值评估翻译质量,并明确禁止反向导出(HyperFrames 到其他框架)以及处理非 Remotion 来源(如 After Effects、Framer Motion 等)。该技能遵循五个步骤的工作流:源代码检查(通过 `lint_source.py` 检测无法翻译的模式)、翻译规划(根据 API 映射加载对应的参考文档)、生成 HyperFrames 合成(输出格式化的 `index.html`)、通过 SSIM 差异验证翻译质量,以及记录翻译差距。它受限于 HyperFrames 的 seek-driven 模型,不支持翻译 React 状态机,也不支持运行 Remotion 的渲染管道。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-nextjs/tree/HEAD/.agents/skills/remotion-to-hyperframes

在你喜欢的 AI 中提问

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

文档

Remotion 到 HyperFrames

在开始构建之前请确认路线。 仅用于将现有 Remotion(React)合成源移植到 HyperFrames。新建 合成(即使灵感来自 Remotion 视频)→ 使用创建流程 / /general-video。超出范围(单向,仅限 Remotion):不支持反向导出(HyperFrames → Remotion 或任何框架),且 非 Remotion 来源(After Effects、Framer Motion、纯 React / CSS)没有可翻译的 Remotion 源代码 → 通过 /general-video 重新创建。不确定,或者只是顺便提及 Remotion?先阅读 /hyperframes。

概述

将 Remotion(基于 React)视频合成翻译为 HyperFrames(HTML + GSAP)合成。大多数 Remotion 习惯用法在 HyperFrames 中都有直接对应项——对于约 80% 的典型合成,翻译是机械性的。此技能编码了映射关系,并通过拒绝翻译不适合 HF seek-driven 模型的模式,转而推荐来自 PR #214 的运行时互操作模式,来防止有损的 20%。

该技能附带一个 分层测试语料库(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。该检查器可检测无法干净翻译的模式:

  • 阻塞项(拒绝并建议互操作):useState、useReducer、带非空依赖项的 useEffect/useLayoutEffect、async 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 对应项或按主题引用的索引。根据源使用的 API 确定需要加载的主题引用:

源包含的内容加载的参考文档
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,以及每个标量属性一个 data-*。
  • 场景 div 的扁平列表,每个带有 data-start / data-duration / data-track-index。
  • 内联 <style> 用于布局;CSS 设置每个动画属性的 from 状态。
  • 底部的一个 <script> 标签,包含一条暂停的 gsap.timeline({paused: true})。每个 Remotion useCurrentFrame() 推导都变成此时间线上偏移正确的补间动画。
  • window.__timelines["<composition-id>"] = tl; 将时间线注册到 HF 运行时。

自定义 React 子组件作为重复的 HTML 内联,使用属性接口作为模板(关于每个实例的 data-* 模式,请参阅 parameters.md)。

步骤 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 查看哪些帧出现了差异,然后重新阅读相关的 timing/sequencing/media 参考文档。

关键:两个渲染必须使用匹配的像素格式。在 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-driven 模型中不是确定性的帧捕获目标。建议使用运行时互操作模式。
  • 与 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 13 individual skills — each has its own dedicated page.

1345AbhishekKumar/starter-nextjs

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

1345AbhishekKumar/starter-nextjs

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

1345AbhishekKumar/starter-nextjs

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). HyperFrames-native: single paused timeline, seek-safe, deterministic.

1345AbhishekKumar/starter-nextjs

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

1345AbhishekKumar/starter-nextjs

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

1345AbhishekKumar/starter-nextjs

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

1345AbhishekKumar/starter-nextjs

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

1345AbhishekKumar/starter-nextjs

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, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1345AbhishekKumar/starter-nextjs

Use when the user wants a short, design-led motion graphic where motion is the message: kinetic typography, stat or number count-up, chart/data-viz hit, logo sting, brand lockup, lower-third, callout, social overlay, animated headline/tweet/news item, motion poster, or quick captured-page highlight. Usually under 10s and up to ~30s, with no narration arc, voice-over, or live-action subject. Can render to MP4 or transparent overlay. Not for longer, multi-scene, narrated, or brand-reel pieces (use general-video), narrated website videos (website-to-video), topic explainers (faceless-explainer), product promos (product-launch-video), PR videos (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a quick motion-first piece or a longer / narrated treatment, see /hyperframes.

1345AbhishekKumar/starter-nextjs

Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it.

1345AbhishekKumar/starter-nextjs

turn a product or marketing URL, pasted script, or brief into a product launch video, including SaaS promos, feature reveals, app launches, company promos, and product marketing videos. Use this skill when the user wants to market, launch, promote, or reveal a product. Do not use it for general non-launch website tours, non-product topic explainers, GitHub pull requests, captioning existing footage, or short unnarrated motion graphics. If the intent is unclear, route through /hyperframes first. This is the new shot-sequence architecture: every visual frame is authored as a time-coded shot sequence picked from a menu of golden blueprints, so frames develop over their full duration instead of freezing after entrance.

1345AbhishekKumar/starter-nextjs

turn a GitHub pull request (a PR URL like github.com/<owner>/<repo>/pull/<N>, an <owner>/<repo>#<N> ref, or 'this PR' in a checked-out repo) into a code-change explainer video, up to ~3 min (sweet spot 30-90s) — changelog, feature reveal, fix, or refactor walkthrough, rendered from the diff / commits / files. The input is a CODE CHANGE read via the gh CLI; there is no website capture. Use this skill for a GitHub PR. Do not use it for a product launch/promo (use /product-launch-video), a tour of a real website (use /website-to-video), a topic explainer with no PR (use /faceless-explainer), captions on existing footage (use /embedded-captions), or a short unnarrated motion graphic (use /motion-graphics). If the intent is unclear, route through /hyperframes first.

1345AbhishekKumar/starter-nextjs

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相关技能