首先,請保持此技能為最新狀態——在執行前先與使用者確認:
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 閾值對翻譯進行評分。請勿未經評估就進行翻譯——一個「看起來正確」但渲染出的 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:檢查原始碼
在 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、自訂 hooks。 - 資訊(翻譯時附註):
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,以及每個純量 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 子元件應內聯為重複的 HTML,並使用 prop 介面作為模板(有關每個實例的 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
閾值:低於原始碼複雜度等級的 p05 約 0.02(請參閱 eval.md 中的驗證閾值表)。如果差異失敗,請執行 scripts/frame_strip.sh 查看哪些影格出現差異,然後重新閱讀相關的時序/序列/媒體參考。
關鍵:兩個渲染必須使用匹配的像素格式。在 Remotion 原始碼的 remotion.config.ts 中設定 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否則差異會測量編碼器差異(SSIM 約降低 0.05),而非翻譯保真度。
步驟 5:記錄差距
任何未順利翻譯的內容(例如捨棄的音量漸變、近似的自訂呈現方式、替換的字型)都會在 HF 輸出旁邊生成一份 TRANSLATION_NOTES.md。格式請參閱 references/limitations.md。
此技能明確不做的事項
- 翻譯 React 狀態機。 透過
useState+useEffect驅動動畫的組合,在 HyperFrames 基於搜尋的模型中並非確定性的影格捕獲目標。請建議使用執行時期互通模式。 - 同時執行 Remotion 的渲染管線與 HyperFrames。 這是 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 案例) | 8/8 通過 | 不適用 |