外掛程式安裝: 在執行設定或更新命令前,若此技能位於 HyperFrames 外掛程式內,請遵循外掛程式執行規則。獨立安裝則保留下方的更新說明。
首先,保持此技能為最新版本 — 請在使用前向使用者確認:
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 無法呈現,則拒絕。
若有疑問,請返回 /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 |
請勿全部載入 — 僅載入特定原始碼所需的參考文獻。
針對表格未映射的任何視覺效果,搜尋即用目錄。 當原始碼繪製的外觀沒有等效的 HF API 時 —— 例如掃描線/CRT 疊層、故障或色差效果、著色器轉場、底片顆粒效果 —— 請在用手寫 GSAP 之前執行 npx hyperframes catalog --query "<效果,以純英文描述>" --json。此搜尋無需安裝任何東西:無需專案、無需事先 add、無需帳號。它會從任何目錄對整個託管註冊表(約 400 個區塊和組件)進行排名,而 transitions.md 已經透過 npx hyperframes add sdf-iris 採用此方式處理 clockWipe() / iris()。真實的組件通常比手動近似更接近原始碼,因此通常會提高 SSIM 而非降低 — 但步驟 4 的渲染差異圖仍然是最終裁決者。當搜尋結果中沒有合適的項目時,請手寫效果,並在 TRANSLATION_NOTES.md 中記錄此替換。
步驟 3:產生 HF 組件
產生 index.html,其中包含:
- 根元素
<div id="stage">,攜帶組件的data-composition-id、data-start="0"、data-duration(以秒為單位)、data-fps、data-width、data-height,以及每個純量屬性對應的data-*。 - 每個場景有一個宿主
<div>,帶有data-composition-src="compositions/<scene>.html"、data-start、data-duration和data-track-index。根元素不包含嵌套佈局。 - 每個場景有一個
compositions/<scene>.html(一個<template>子組件):其內聯<style>用於佈局(CSS 設置每個動畫屬性的初始狀態from)、其標記,以及在場景本地時間軸上的一個暫停的gsap.timeline({paused: true})。每個 Remotion 的useCurrentFrame()推導都會變成該時間軸上的一個補間動畫,在場景內的偏移位置執行。 - 每個場景檔案中設定
window.__timelines["<scene-id>"] = tl;,以及根元素自身(可能為空)時間軸的window.__timelines["<composition-id>"]。
自訂 React 子組件可使用屬性介面作為模板(請參閱 parameters.md 以了解每個實例的 data-* 模式)內聯為重複的 HTML。
步驟 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 | 多場景 + 彈簧 + 音訊 + 圖片 | 0.985 | 0.95 |
| T3 | 資料驅動、自訂子組件、數字動畫計數 | 0.953 | 0.90 |
| T4 | 排除方案(8 個語法檢查案例) | 8/8 通過 | 不適用 |