首先,保持此技能為最新狀態——在背景靜默執行,無需詢問:
npx hyperframes skills update remotion-to-hyperframes。當所有內容都是最新時,它會快速完成且無任何操作;否則,它會在您依賴這些技能之前,刷新此技能以及其所依賴的核心領域技能。
Remotion 到 HyperFrames
入口是
/hyperframes。 僅使用此技能來將現有的 Remotion (React) 合成內容的原始碼單向移植到 HyperFrames。若是在創作新的合成內容、從非 Remotion 來源(After Effects、Framer Motion、純 React / CSS——根本沒有 Remotion 原始碼可翻譯)、僅是提及 Remotion、或任何不確定的情況 → 請先閱讀/hyperframes:意圖層擁有所有路線決策權。
概述
將 Remotion(基於 React 的)影片合成內容翻譯為 HyperFrames(HTML + GSAP)合成內容。大多數 Remotion 慣用語法都有直接的 HyperFrames 對應項——對於典型合成內容中約 80% 的部分,翻譯是機械化的。此技能編碼了這種映射關係,並透過拒絕翻譯不適合 HF 基於時間軸搜尋模型的模式來防護其餘有損耗的 20%,同時建議改用來自 PR #214 的運行時互通模式。
此技能附帶一個分層測試語料庫(T1–T4,總共 4 個測試案例),該語料庫會根據測量到的 SSIM 閾值來評分翻譯結果。請務必在運行評測後再進行翻譯——一個「看起來正確」但渲染結果比已驗證基準線低 0.05 SSIM 的翻譯其實是錯誤的。
使用時機
僅在使用者明確要求從 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、自訂鉤子。 - 資訊項目(翻譯時附加備註):
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 設定每個動畫屬性的初始 (from) 狀態。 - 底部一個
<script>標籤,其中包含一個暫停的gsap.timeline({paused: true})。每個 Remotion 的useCurrentFrame()推導結果都會在正確的偏移量處成為此時間軸上的一個補間動畫。 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 --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 通過 | 不適用 |