remotion-to-hyperframes
熱門將現有的 Remotion (React) 合成作品移植到 HyperFrames HTML。僅在使用者明確要求移植/轉換/遷移/翻譯 Remotion 原始碼時使用。請勿使用於：(a) 創作新的 HyperFrames 合成作品；(b) 僅順帶提及 Remotion；(c) 僅作為參考分享 Remotion 程式碼；(d) 未明確要求遷移的「與我的 Remotion 影片相同」——視為全新建置。有疑問 → `/general-video`。單向、僅限 Remotion：無反向匯出 (HyperFrames→Remotion 或任何框架)，無非 Remotion 來源 (After Effects、Framer Motion、純 React/CSS) → 超出範圍，請透過 `/general-video` 重新建立。標記不支援的模式 (useState、useEffect、async calculateMetadata、第三方 React 函式庫、`@remotion/lambda`) 並建議使用執行時期互通模式而非有損翻譯。不確定是否要移植還是重新建置，或僅順帶提及 Remotion？→ /hyperframes。
將現有的 Remotion (React) 合成作品移植到 HyperFrames HTML。僅在使用者明確要求移植/轉換/遷移/翻譯 Remotion 原始碼時使用。請勿使用於：(a) 創作新的 HyperFrames 合成作品；(b) 僅順帶提及 Remotion；(c) 僅作為參考分享 Remotion 程式碼；(d) 未明確要求遷移的「與我的 Remotion 影片相同」——視為全新建置。有疑問 → `/general-video`。單向、僅限 Remotion：無反向匯出 (HyperFrames→Remotion 或任何框架)，無非 Remotion 來源 (After Effects、Framer Motion、純 React/CSS) → 超出範圍，請透過 `/general-video` 重新建立。標記不支援的模式 (useState、useEffect、async calculateMetadata、第三方 React 函式庫、`@remotion/lambda`) 並建議使用執行時期互通模式而非有損翻譯。不確定是否要移植還是重新建置，或僅順帶提及 Remotion？→ /hyperframes。
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 閾值對翻譯進行評分。未執行評估前請勿進行翻譯——一個「看起來正確」但渲染結果比驗證基準低 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 設定是典型的警告案例：此技能會移除匯入和 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，以及每個純量屬性的data-*。 - 一個扁平場景 div 列表，帶有
data-start/data-duration/data-track-index。 - 內聯
<style>用於佈局；CSS 設定每個動畫屬性的from狀態。 - 底部一個
<script>標籤，包含一個暫停的gsap.timeline({paused: true})。每個 RemotionuseCurrentFrame()的衍生都會成為此時間軸上正確偏移量的補間動畫。 window.__timelines["<composition-id>"] = tl;將時間軸註冊到 HF 的執行時期。
自訂 React 子元件會內聯為重複的 HTML，使用 prop 介面作為範本 (請參閱 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 --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 通過 | 不適用 |
