外掛安裝： 在執行設定或更新命令之前，請遵循外掛執行規則。若此技能位於 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 基於幀搜尋模型的模式，以及推薦使用 PR #214 的執行時期互通模式，來防止那 20% 可能有損耗的情況。
此技能附帶一個 分級測試語料庫（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、自訂 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 |
不要全部載入 — 僅載入特定原始碼所需的參考。
針對表格未對應的任何視覺效果，搜尋即時目錄。 當原始碼使用了 HF API 中無對應項的視覺效果時 — 例如掃描線/CRT 疊層、故障或色差效果、著色器轉場、底片顆粒效果 — 請先執行 npx hyperframes catalog --query "<效果名稱，以白話英文描述>" --json，然後再手動用 GSAP 撰寫。此搜尋無需安裝任何東西：不需要專案、不需要事先 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，以及每個純量 prop 對應一個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})。每一個 RemotionuseCurrentFrame()的衍生都成為該場景時間軸上於場景內偏移量處的補間動畫。 - 每個場景檔案中的
window.__timelines["<scene-id>"] = tl;，以及根元素自身的window.__timelines["<composition-id>"]（可能為空）。
自訂 React 子元件使用 prop 介面作為模板內聯為重複的 HTML（請參閱 parameters.md 以了解每個實例的 data-* 模式）。
步驟 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
閾值：低於原始碼複雜度等級的 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 通過 | 不適用 |