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、calculateMetadata | parameters.md |
Sequence、Series、Loop、AbsoluteFill、Freeze | sequencing.md |
useCurrentFrame、interpolate、spring、Easing、interpolateColors | timing.md |
Audio、Video、Img、IFrame、staticFile、delayRender | media.md |
TransitionSeries、@remotion/transitions | transitions.md |
@remotion/lottie | lottie.md |
@remotion/google-fonts/<Family>、Font.loadFont、@font-face | fonts.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})。每個 RemotionuseCurrentFrame()推導都成為這個 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.974 | 0.95 |
| T2 | 多場景 + spring + 音訊 + 圖片 | 0.985 | 0.95 |
| T3 | 資料驅動、自訂子組件、計數器 | 0.953 | 0.90 |
| T4 | 逃逸艙口(8 個檢查案例) | 8/8 通過 | 不適用 |