Communitygithub.com

Remotion 到 HyperFrames 翻译技能

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

Remotion 到 HyperFrames 翻译技能 是什么?

该技能将基于 React 的 Remotion 视频合成翻译为 HyperFrames (HTML + GSAP) 合成。它编码了约 80% 的常规 Remotion 惯用法与其 HyperFrames 等价项之间的映射关系,并拒绝翻译不适合 HF 基于时间的驱动模型的模式(如 useState、useEffect 副作用、async calculateMetadata、第三方 React 组件库、@remotion/lambda),转而推荐运行时互操作方案。该技能包含一个分层测试语料库(T1-T4,共 4 个测试用例),用于根据测量的 SSIM 阈值评估翻译质量,并强制要求在翻译前运行评估。翻译失败的原因包括 React 状态机(无法在 HF 的 seek 驱动模型中确定性地渲染)以及与 Remotion 渲染管道的并行运行。

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

在你喜欢的 AI 中提问

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

文档

Remotion 到 HyperFrames

概述

将基于 React 的 Remotion 视频合成翻译为 HyperFrames (HTML + GSAP) 合成。大多数 Remotion 惯用法都有直接的 HyperFrames 等价项——对于约 80% 的常规合成,翻译是机械性的。此技能编码了映射关系,并通过拒绝翻译不适合 HF 基于时间点驱动模型的模式,以及推荐来自 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 技能编写原生 HyperFrames 合成。

工作流程

步骤 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、自定义 hooks。
  • 信息项(翻译并附上注释):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,以及每个标量属性对应的 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-* 模式)。

步骤 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 --output ../hf.mp4

# SSIM 差异对比
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

阈值:比源文件复杂性等级(参见 eval.md 中的验证阈值表)的 p05 低约 0.02。如果差异检查失败,运行 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-driven model)中不是确定性的帧捕获目标。建议使用运行时互操作模式。
  • 不并行运行 Remotion 的渲染管道和 HyperFrames。 那是来自 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 通过不适用

Individual skills in this repo

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

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

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.

delorenj/skills

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.

delorenj/skills

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 dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Generate speech using the self-hosted voxxy (vox) TTS service at https://vox.delo.sh. Use when the user asks to speak, say, narrate, synthesize speech, clone a voice, create a voice, add or register a voice, pipe TTS, or control voice qualities by description (e.g. "a young woman with a cheerful voice"). Handles HTTP API usage, voice profile management, description-based voice design, cloning, MCP registration, and integration patterns for new platforms.

delorenj/skills

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.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

相关技能