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 中的運行時交互模式,來防止那 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:檢查源碼
對 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 配置是典型的警告案例:技能會刪除 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 的扁平列表,帶有
data-start/data-duration/data-track-index屬性。 - 用於佈局的內聯
<style>;CSS 設定每個動畫屬性的初始狀態。 - 在底部的一個
<script>標籤,包含一個暫停的gsap.timeline({paused: true})。每個 RemotionuseCurrentFrame()的衍生值都會在此時間軸上以正確的偏移量成為一個補間動畫。 window.__timelines["<composition-id>"] = tl;將時間軸註冊到 HF 運行時。
自訂 React 子組件使用 prop 介面作為模板,內聯為重複的 HTML(請參閱 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 --skill=remotion-to-hyperframes --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 按幀驅動模型中的確定性幀捕獲目標。建議使用運行時交互模式。 - 與 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 通過 | 不適用 |