Communitygithub.com

Remotion 转 HyperFrames

仅当用户明确要求将现有的 Remotion (React) 视频合成项目移植/转换/迁移/翻译为 HyperFrames HTML 时使用。禁止用于其他场景。

Remotion 转 HyperFrames 是什么?

此技能旨在将现有的 Remotion (React) 视频合成项目机械地翻译为 HyperFrames (HTML + GSAP) 格式。它处理了大约 80% 的典型合成,并内置了一套规则来拒绝翻译不适合 HyperFrames 基于帧查找模型的模式(例如 useState、useEffect 和异步 calculateMetadata),同时推荐运行时互操作模式。该技能附带一个T1-T4分级测试语料库,通过 SSIM 指标量化翻译保真度,在生成翻译后必须运行评估以验证质量。此转换是单向的,仅支持 Remotion 作为源,不支持反向导出或其他非 Remotion 源(如 After Effects、Framer Motion、原生 React/CSS 动画)的翻译。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1345AbhishekKumar/starter-supabase/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 基于帧查找模型的模式,同时推荐使用 PR #214 中的运行时互操作模式,来防范那有损的 20%。

该技能附带一个分级测试语料库(T1–T4,共 4 个固定测试用例),可根据测量的 SSIM 阈值对翻译进行评分。未经运行评估请不要进行翻译——一个看起来正确但渲染结果比验证基线低 0.05 SSIM 的翻译是静默错误的。

何时使用

仅当用户明确要求从 Remotion 迁移时才使用此技能。 触发短语示例:

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

在以下情况下请勿使用此技能:

  • (a) 用户正在创作一个新的 HyperFrames 合成,即使他们正在对比测试一个类似的 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 合成。

工作流

第一步:检查源码

在 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 并展示推荐消息。警告项不会阻止翻译——在第三步中删除违规构造并在 TRANSLATION_NOTES.md 中记录差异。@remotion/lambda 配置是典型的警告案例:技能会删除导入和 renderMediaOnLambda(...) 调用,但会翻译合成的其余部分。

第二步:规划翻译

阅读 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

不要全部加载——只加载特定源码所需的部分。

第三步:生成 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 设置所有动画属性的 from 状态。
  • 底部的一个 <script> 标签,包含一个暂停的 gsap.timeline({paused: true})。每个 Remotion useCurrentFrame() 派生值都成为此时间线上正确偏移处的补间动画。
  • window.__timelines["<composition-id>"] = tl; 将时间线注册到 HF 运行时。

自定义 React 子组件内联为重复的 HTML,使用 prop 接口作为模板(参见 parameters.md 了解每个实例的 data-* 模式)。

第四步:验证

运行评估框架——完整指南见 references/eval.md。快速路径:

# 渲染 Remotion 基线(在固定测试用例中执行 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 损失),而非翻译保真度。

第五步:记录差异

任何未能干净翻译的内容(删除的音量渐变、近似的自定义演示文稿、替换的字体)都将在 HF 输出旁边生成一个 TRANSLATION_NOTES.md。格式参见 references/limitations.md。

此技能明确不做什么

  • 翻译 React 状态机。 通过 useState + useEffect 驱动动画的合成在 HyperFrames 的基于帧查找模型中不是确定性帧捕获目标。推荐使用运行时互操作模式。
  • 与 HyperFrames 同时运行 Remotion 的渲染管线。 这是 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.9740.95
T2多场景 + spring + 音频 + 图像0.9850.95
T3数据驱动、自定义子组件、计数动画0.9530.90
T4逃逸舱(8 个 lint 用例)8/8 通过不适用

Individual skills in this repo

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

1345AbhishekKumar/starter-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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-supabase

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.

相关技能