Remotion 到 HyperFrames
先確認路線再開始。 僅當需要將現有的 Remotion (React) 組合原始碼移植到 HyperFrames 時,才使用此技能。如果是創作新的組合(即使其靈感來自 Remotion 影片)→ 請使用創作工作流程 /
/general-video。超出範圍(單向,僅限 Remotion):不支援反向匯出(HyperFrames → Remotion 或任何框架),且非 Remotion 來源(After Effects、Framer Motion、純 React / CSS)沒有可翻譯的 Remotion 原始碼 → 請透過/general-video重新建立。不確定,或只是順便提及 Remotion?請先閱讀/hyperframes。
概述
將 Remotion(基於 React)的影片組合翻譯成 HyperFrames(HTML + GSAP)組合。大多數 Remotion 慣用語法在 HyperFrames 中都有直接對應項——對於典型的組合,約 80% 的翻譯是機械式的。此技能編碼了這組映射關係,並透過拒絕翻譯不適合 HF 基於幀搜尋模型的模式,同時建議使用 PR #214 中的 Runtime Interop 模式,來防範那有損耗的 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 組合匯出回 到 Remotion(或任何其他框架)不是一個工作流程——翻譯僅限於 Remotion → HyperFrames。請明確告知。
- 非 Remotion 來源。 After Effects 專案(
.aep)、Framer Motion / 純 React / CSS 動畫或任何其他工具的原始碼都不是 Remotion 組合——沒有可翻譯的 Remotion 原始碼。請透過/general-video原生重新建立,或者如果 HyperFrames 無法表示,則拒絕。
若有疑慮,預設使用 /general-video(通用 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、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>列表,包含data-start/data-duration/data-track-index。 - 用於佈局的內聯
<style>;CSS 設定每個動畫屬性的from狀態。 - 底部一個包含單一暫停
gsap.timeline({paused: true})的<script>標籤。每個 Remotion 的useCurrentFrame()推導都會在此時間軸上的正確偏移處成為一個 tween。 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
閾值:約低於原始碼複雜度層級之 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 基於幀搜尋的模型中,不是確定性的幀捕獲目標。建議使用 Runtime Interop 模式。 - 與 HyperFrames 並行執行 Remotion 的渲染管線。 這是來自 PR #214 的 Runtime Interop 模式——一個針對無法通過此技能 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 通過 | 不適用 |