Communitygithub.com

Remotion到HyperFrames移植器

将现有的Remotion(React)合成源代码单向移植到HyperFrames HTML。仅在用户明确要求移植/转换/迁移/翻译Remotion源码时使用——单向、仅限Remotion。

Remotion到HyperFrames移植器 是什么?

该技能专为将现有Remotion(React)视频合成方案移植到HyperFrames(HTML + GSAP)而设计。它提供了从Remotion API到HyperFrames等价物的机械映射,覆盖了约80%的常见模式。技能包含分层测试语料库(T1-T4层级,共4个测试用例),通过SSIM指标对翻译质量进行定量评估,并设定了严格的阈值以验证视觉保真度。 工作流程由五个步骤组成:首先对Remotion源码进行静态检查,检测无法干净翻译的模式(如状态管理、异步计算等),若发现阻塞项则停止并推荐运行时互操作方案;其次根据源码中使用的特定API加载对应的参考文档进行翻译规划;第三步生成HyperFrames HTML结构;第四步通过渲染对比进行SSIM差异验证;最后在TRANSLATION_NOTES.md中记录翻译缺口。 该技能明确不支持反向翻译(从HyperFrames移植回Remotion)、非Remotion来源(如After Effects、Framer Motion、纯React/CSS动画)翻译,也不处理基于React状态机的动画逻辑。对于任何不确定性,应回退到`/hyperframes`通用创作流程。该技能可在Claude Code、Cursor、Codex等AI代理平台上使用。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/remotion-to-hyperframes

在你喜欢的 AI 中提问

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

文档

首先,保持本技能新鲜——运行前向用户确认: 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、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 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})。每个Remotion useCurrentFrame()推导都成为该时间轴上场景偏移内的补间。

  • 每个场景文件中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.9740.95
T2多场景 + spring + 音频 + 图像0.9850.95
T3数据驱动、自定义子组件、计数0.9530.90
T4逃生舱(8个lint用例)8/8 passn/a

Individual skills in this repo

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

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

1999AZZAR/designer-mcp

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

1999AZZAR/designer-mcp

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

1999AZZAR/designer-mcp

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). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

1999AZZAR/designer-mcp

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

1999AZZAR/designer-mcp

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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`.

1999AZZAR/designer-mcp

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

1999AZZAR/designer-mcp

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

1999AZZAR/designer-mcp

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

1999AZZAR/designer-mcp

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

1999AZZAR/designer-mcp

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

1999AZZAR/designer-mcp

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

1999AZZAR/designer-mcp

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

1999AZZAR/designer-mcp

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). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

相关技能