Communitygithub.com

libz-renlab-ai/TeamBrain

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

TeamBrain 是什麼?

此技能專門用於將基於 React 的 Remotion 影片組合機械化地轉換為基於 HTML 和 GSAP 的 HyperFrames 組合。它內建了一個分層測試語料庫(T1-T4),並透過 SSIM 閾值來評分翻譯品質,確保翻譯結果不僅「看起來正確」,還需達到像素級別的精確度。技能包含一個源碼檢查步驟,能自動檢測並阻止翻譯那些無法在 HyperFrames 的 seek-driven 模型中乾淨轉換的模式(如 useState、useEffect),並在遇到阻斷器時推薦運行時互通模式作為替代方案。工作流程涵蓋從源碼檢查、翻譯規劃、生成 HyperFrames 組合(包括 data-* 屬性和 GSAP timeline)、到最終的驗證和生成 TRANSLATION_NOTES.md 文件的完整過程。此技能支援 Claude Code 等平台,主要用於有明確遷移需求的場景,而非建立全新的 HyperFrames 組合。

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

在你喜歡的 AI 中提問

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

說明文件

Remotion 轉 HyperFrames

概述

將 Remotion(基於 React)影片組合轉換為 HyperFrames(HTML + GSAP)組合。大多數 Remotion 慣用語在 HyperFrames 中都有直接對應——對於約 80% 的典型組合,其翻譯是機械式的。此技能編碼了這些對應關係,並透過拒絕翻譯不符合 HF 基於 seek 的模型的模式,來防禦有損耗的 20%,建議改用來自 PR #214 的運行時互通模式。

該技能附帶一個分層測試語料庫(T1–T4,總共 4 個測試案例),根據測量的 SSIM 閾值來評分翻譯。在沒有執行評估的情況下不要進行翻譯——一個「看起來正確」但 SSIM 比驗證基準低 0.05 的翻譯是靜默錯誤的。

工作流程

步驟 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、自訂 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-*。
  • 一個扁平清單,包含帶有 data-start / data-duration / data-track-index 的場景 div。
  • 用於佈局的內聯 <style>;CSS 設定每個動畫屬性的 from 狀態。
  • 底部的一個 <script> 標籤,包含一個暫停的 gsap.timeline({paused: true})。每個 Remotion useCurrentFrame() 推導都成為這個 timeline 上在正確偏移量的補間動畫。
  • window.__timelines["<composition-id>"] = tl; 將 timeline 註冊到 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

閾值:低於原始碼複雜度等級的 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 的模型中的確定性影格捕獲目標。建議使用運行時互通模式。
  • 與 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多場景 + spring + 音訊 + 圖片0.9850.95
T3資料驅動、自訂子組件、計數器0.9530.90
T4逃逸艙口(8 個檢查案例)8/8 通過不適用

Individual skills in this repo

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

libz-renlab-ai/TeamBrain

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.

libz-renlab-ai/TeamBrain

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.

libz-renlab-ai/TeamBrain

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 CLI commands (init, lint, preview, render, transcribe, tts) see the hyperframes-cli skill.

libz-renlab-ai/TeamBrain

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.

libz-renlab-ai/TeamBrain

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

相關技能