Remotion 轉 HyperFrames 是做什麼的?
總覽
將 Remotion (React 基礎) 影片合成內容轉換為 HyperFrames (HTML + GSAP) 合成內容。大多數 Remotion 慣用語法都有直接的 HyperFrames 等效方式——對於約 80% 的典型合成內容,這項轉換是機械性的。此技能包含了轉換映射,並透過拒絕轉換不符合 HF 搜尋驅動模型的模式,來防範那 20% 的高損耗情況,同時建議改採 PR #214 中的執行時期互操作模式。
此技能附帶一個分層測試語料庫(T1–T4,共 4 個測試實例),用於根據測量的 SSIM 閾值來評分轉換結果。請務必執行評估後再進行轉換——一個「看起來正確」但比驗證基準線低 0.05 SSIM 的轉換結果,實際上是有問題的。
使用時機
僅在使用者明確要求從 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:檢查原始碼
在 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 設定是典型的警告案例:此技能會移除該 import 及 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-*。 - 一個場景 div 的扁平列表,每個 div 帶有
data-start/data-duration/data-track-index。 - 用於版面配置的內聯
<style>;CSS 設定每個動畫屬性的起始狀態 (from)。 - 頁面底部的單一
<script>標籤,包含一個暫停的gsap.timeline({paused: true})。每個 Remotion 的useCurrentFrame()推導都會變成在此時間軸上適當偏移的 tween 動畫。 window.__timelines["<composition-id>"] = tl;將時間軸註冊到 HF 的執行時期。
自訂的 React 子元件會內聯為重複的 HTML,使用 prop 介面作為範本(有關每個實例的 data-* 模式,請參閱 parameters.md)。
步驟 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 的搜尋驅動模型中並非確定性的影格擷取目標。請建議採用執行時期互操作模式。 - 同時執行 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.974 | 0.95 |
| T2 | 多場景 + spring 彈性動畫 + 音訊 + 圖片 | 0.985 | 0.95 |
| T3 | 資料驅動、自訂子元件、計數動畫 | 0.953 | 0.90 |
| T4 | 逃脫通道(8 個 lint 案例) | 8/8 通過 | n/a |