Communitygithub.com

Remotion 轉換至 HyperFrames

將現有的 Remotion(基於 React)影片組件轉換為 HyperFrames HTML 組件。僅在用戶明確要求移植、轉換、遷移、翻譯或改寫 Remotion 組件為 HyperFrames 時使用。

Remotion 轉換至 HyperFrames 是什麼?

此技能專門用於將以 React 為基礎的 Remotion 影片組件機械性轉譯為 HyperFrames(HTML + GSAP)組件,覆蓋約 80% 的典型場景。它內建分級測試語料庫(T1–T4),透過 SSIM 閾值驗證轉譯品質,確保視覺保真度。技能會先檢測原始碼中的阻塞模式(如 useState、useEffect 副作用、async calculateMetadata、第三方 React 元件庫、@remotion/lambda),若發現無法乾淨轉譯的結構,會立即停止並建議採用運行時互通(runtime interop)逃生艙方案,而非進行有損轉譯。支援的平台包括任何 HyperFrames 相容的環境(如 HeyGen)。翻譯流程包含 5 個步驟:原始碼 lint、根據 API 映射規劃、生成 index.html 搭配 GSAP 時間軸、透過渲染比對驗證,以及產出 TRANSLATION_NOTES.md 記錄落差。此技能不會翻譯 React 狀態機,也不會同時執行 Remotion 與 HyperFrames 渲染管線。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Remotion 轉換至 HyperFrames 是做什麼的?

概述

將 Remotion(基於 React)影片組件轉換為 HyperFrames(HTML + GSAP)組件。大多數 Remotion 慣用法都有對應的 HyperFrames 等效項——對於約 80% 的典型組件而言,轉譯是機械式的。此技能編碼了對應關係,並透過拒絕轉譯不符合 HF 基於影格搜尋模型(seek-driven model)的模式,來防範有損的 20%,同時建議改用 PR #214 中的運行時互通模式。

此技能附帶一個分級測試語料庫(T1–T4,共 4 個固定測試案例),可根據測量的 SSIM 閾值對轉譯進行評分。請務必執行評估後再轉譯——一個「看起來正確」但 SSIM 比驗證基準低 0.05 的轉譯是無聲的錯誤。

何時使用

僅當用戶明確要求從 Remotion 遷移時才使用此技能。 觸發短語範例:

  • "port my Remotion project to HyperFrames"
  • "convert this Remotion code to HyperFrames"
  • "migrate from Remotion"
  • "translate this Remotion comp"
  • "rewrite this as HyperFrames HTML"

在以下情況下請勿使用此技能:

  • (a) 用戶正在創作新的 HyperFrames 組件,即使他們已經有或正在 A/B 測試類似的 Remotion 影片。
  • (b) 用戶只是順帶提及 Remotion,但未要求遷移。
  • (c) 用戶分享 Remotion 程式碼作為參考資料,而非要求轉譯。
  • (d) 用戶要求「與我的 Remotion 影片相同」但並未明確要求遷移原始碼——應將其視為全新的 HyperFrames 構建。

如有疑問,請預設使用 hyperframes 技能來創作原生的 HyperFrames 組件。

工作流程

步驟 1:原始碼 Lint

對 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、自訂 Hook。
  • 資訊項(轉譯並附註):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 基於影格搜尋模型的確定性影格捕捉目標。建議改用運行時互通模式。
  • 同時執行 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多場景 + 彈簧動畫 + 音訊 + 圖片0.9850.95
T3資料驅動、自訂子組件、計數器0.9530.90
T4逃生艙(8 個 lint 案例)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.

相關技能