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: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、自訂鉤子。 - 資訊 (附上註記進行翻譯):
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>標籤。每個 RemotionuseCurrentFrame()推導都變成這個時間軸上一個位於正確偏移量的補間動畫。 window.__timelines["<composition-id>"] = tl;將時間軸註冊到 HF 的執行時期。
自訂 React 子組件使用 prop 介面作為模板,內聯為重複的 HTML (有關每個實例的 data-* 模式,請參閱 parameters.md)。
步驟 4:驗證
執行評測框架 — 完整指南請參閱 references/eval.md。快速路徑:
# 渲染 Remotion 基準 (在固定測試案例中執行 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
閾值:低於原始碼複雜度等級的第 5 個百分位數約 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 的執行時期互通模式 — 一個針對未通過此技能 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 案例) | 全部通過 | 不適用 |