REMOTION 動態設計 — 實作技能
1. 編碼前審查
- 閱讀
CLAUDE.md、MASTER_PROMPT.md及架構文件。 - 確認實際使用的 Remotion/React/TypeScript 版本與套件管理器。
- 找到現有的進入點與合成註冊表。
- 遵循儲存庫慣例;除非必要,否則不要隨意更換依賴項。
- 使用
beyond-video的輸出、腳本、分鏡圖與樣式指南作為生產規格。 - 在依賴記憶之前,請先對照已安裝版本的 Remotion 原始碼(例如參考克隆中的
packages/core/src)驗證你要使用的 API。
2. 合成設定檔
預設值:
- width: 1080
- height: 1920
- fps: 60
- aspect: 9:16
- duration: 以影格為單位的正整數
每個合成都需要一個唯一 ID 和明確的中繼資料。沒有正當理由,請勿在不同圖層中存放不同的 FPS 值。
<Composition> 接受 id、fps、width、height、durationInFrames、defaultProps,以及選擇性的 calculateMetadata(可根據 props 動態計算持續時間/中繼資料)和 schema。durationInFrames 必須為正數。
3. 時間軸工程
- 將持續時間和起始影格集中存放在中央資料/設定檔中。
- 使用一致的影格間隔約定;建議使用
[start, end)。 - 場景的
durationInFrames必須為正數。 - 確保合成的總持續時間涵蓋所有場景加上結尾/收束部分。
- 驗證是否有重疊或間隙;只有在需要轉場/合成時才允許有重疊。
- 不要依賴浮點數來定義最終影格邊界。
4. 確定性動畫 — 時間/影格 API (Remotion 4.x)
時間來源:
useCurrentFrame()— 當前的影格,從 0 開始索引。僅能在合成元件內部使用;在合成外部使用會拋出錯誤。useVideoConfig()— 回傳{width, height, fps, durationInFrames, id, defaultProps, defaultVideoImageFormat, ...};在合成外部使用會拋出錯誤。
內插與彈簧:
interpolate(input, inputRange, outputRange, options?)— 支援 number、string、boolean 和 array 輸出的多載版本。選項:easing、extrapolateLeft/extrapolateRight('extend' | 'identity' | 'clamp' | 'wrap')、output、outputType、posterize。當動畫不能超出範圍時,請使用 clamp 外推模式。spring({frame, fps, config?, from=0, to=1, durationInFrames?, durationRestThreshold?, delay=0, reverse=false})。SpringConfig:damping(預設 10)、mass(1)、stiffness(100)、overshootClamping(false)。damping <= 0會使動畫永不穩定(導致無限循環錯誤)。measureSpring({fps, config?, threshold=0.005})— 彈簧穩定所需的影格數;threshold=0會回傳Infinity。
規則:
- 動畫必須是影格和 props 的函數。
- 對粒子/噪點/隨機數值進行播種。
- 避免將
setInterval、setTimeout、requestAnimationFrame、Date.now()以及自執行的 CSS keyframes 作為影片動畫的主要來源。 - 不要在合成渲染期間擷取網路資料。
- 不要包含來自不穩定網址或需要登入的網址的音訊/視訊。
delayRender(label?, options?)會保持渲染狀態,直到呼叫continueRender(handle)為止(例如用於非同步資源);其超時時間由 CLI--timeout設定。
5. Sequence、Series 及局部 vs 全域影格
這是最常出錯的規則 — 曾經有過一個真實的 bug,因為某個元件在 Series.Sequence 內部計算了全域影格:
- 在
<Sequence>內部,useCurrentFrame()回傳的是相對於該 Sequence 起始點的影格:(frame - (cumulatedFrom + relativeFrom)) * playbackRate。Sequence 內部的元件看不到全域影格。 <Sequence>的 props:from?、name?、durationInFrames?(必須為正數;使用loop時為必填)、layout('absolute-fill'|'none')、premountFor、loop以及裁切相關 props(僅在layout="absolute-fill"時有效)。<Series.Sequence>僅能在<Series>內部使用;在<Series>外部使用Series.Sequence會拋出「此元件必須位於<Series />元件內部。」的錯誤。- 兩種有效的路由模式 — 選擇一種並保持一致性:
- 全域影格路由器(用於影片專案):一個路由器元件使用全域的
useCurrentFrame()並根據[start, end)範圍來選擇段落;段落元件從全域影格進行計算。 - Series:每個
Series.Sequence包含一個段落;段落元件從局部影格進行計算(Sequence 起始處為 0)。
- 全域影格路由器(用於影片專案):一個路由器元件使用全域的
- 除非有明確理由,否則不要在一個合成中混合使用兩種模式。
6. 場景/元件結構
- 一個場景只有一個敘事/視覺責任。
- 場景的 props 使用 TypeScript 定義。
- 可重複使用的元件應解決一個明確的視覺任務。
- 避免單一檔案包含整個影片。
- 將內容設定、渲染器、樣式代碼和資源引用分開。
- 為可選資源設計備用方案;切勿隱藏遺失的關鍵資源。
7. 媒體元件與資源
<Img src>— 若圖片載入失敗且未提供onError,會取消渲染(cancelRender)。對於關鍵資源,務必提供onError,或確保資源在渲染前已存在。staticFile(path)— 對應public/目錄中的檔案;用於所有本地資源(圖片、音訊、影片)。<Audio>— 請參閱sound-design以了解如何將提示表對應到 props(trimBefore/After— 舊別名為startFrom/endAt—volume、playbackRate)。提示在時間軸上的位置由<Sequence from>設定;修剪 props 僅決定播放檔案中的哪個部分。<Audio>沒有mutedprop;靜音是一個 CLI 標誌(--muted)。<Video>/<OffthreadVideo>和<Still>遵循相同的影格規則;媒體持續時間必須根據影格來排程,而不是檔案的元數據。
8. 2D 動畫
視需要使用 SVG/形狀/CSS/點陣圖。注意錨點、變形原點、反鋸齒、圖層分層、裁切以及安全區域。所有變形都必須以影格為驅動。
9. 像素與火柴人支援
像素藝術:
- 鎖定邏輯畫布與像素縮放比例;
- 縮放精靈時使用最近鄰插值;
- 必要時將位置吸附到網格;
- 鎖定調色板與精靈尺寸;
- 避免模糊與次像素閃爍。
火柴人:
- 保持比例與支點一致;
- 當專案規模允許時,使用姿勢/骨架庫;
- 為輪廓與手勢製作動畫以便閱讀;
- 使表情/姿勢與故事節奏同步。
關於走路循環、跟隨動作與待機動畫,請參閱 character-animation。
10. 3D 動畫
- 僅在能帶來創意價值時才添加 3D 元素。
- 檢查
three、@react-three/fiber、@remotion/three的版本及其文件。 - 對於 Remotion ThreeCanvas 整合,請遵循所安裝 API 版本的以影格為驅動的方法;不要假設即時的 R3F 模式會自動具有確定性。
- 使用影格來驅動攝影機、變形、材質、光照與粒子。
- 考慮渲染器/無頭模式的相容性、紋理大小、幾何體與計算成本。
- 當有助於提高可讀性和可維護性時,將 3D 圖層與 2D 排版/疊加層分開。
- 有關詳細的 3D 場景導演技巧,請參閱
3d-scene-director。
11. 排版與轉場
- 優先考慮層級結構與可讀性。
- 切勿讓轉場覆蓋重要文字。
- 每個轉場連接兩個段落;不要添加沒有功能的效果。
- 透過樣式指南保持動畫曲線與強度的一致性。
- 使文字持續時間符合閱讀需求。
12. 實作結尾
根據 beyond-video 工作表實作結尾 Logo 與 Call to Action。Logo 必須來自官方資源或經認可的佔位符。文案、時機、主題與合成必須感覺是為當前影片量身打造的。
13. 交接前 QA
檢查合成 ID、中繼資料、影格範圍、匯入、型別、靜態資源、字型、樣式一致性、安全區域、結尾與資源授權。執行可用的 lint/typecheck/測試。不要渲染 MP4。不要提交/推送。
輸出格式
- 合成註冊表:ID、1080×1920、60 FPS、durationInFrames、場景列表 + 影格範圍。
- 使用的 API:API 名稱 + 相關簽名 + 驗證位置(已安裝的 Remotion 版本)。
- 影格路由模式:全域或 Series — 選擇一種,並在整個合成中保持一致。
- 資源註冊表:檔案、
staticFile、關鍵資源的備用方案/onError。 - QA 檢查清單 + typecheck/lint 結果。
迷你範例
全域影格路由器(影片專案模式):
const frame = useCurrentFrame();
const beat = BEATS.find((b) => frame >= b.start && frame < b.end);
return (
<AbsoluteFill>
{beat?.id === 'S01-B01' && <Hook />}
{beat?.id === 'S01-B02' && <Problem />}
</AbsoluteFill>
);
使用測量持續時間的彈簧:
const settle = measureSpring({fps, config: {damping: 12}});
const progress = spring({frame, fps, config: {damping: 12}});
失敗模式
Series.Sequence內部的元件計算了全域影格 → 錯誤的段落,場景顯示在錯誤的時間點。修正:從局部影格計算,或切換到全域影格路由器。- 在沒有
<Series>的情況下使用Series.Sequence→ 渲染時拋出錯誤。將其包裹在<Series>中,或直接使用<Sequence>(而非Series.Sequence)。 spring的damping <= 0→ 動畫永不穩定。保持damping > 0。- 缺少圖片且沒有
onError→ 渲染被取消。添加onError或確保資源在渲染前存在。 - 在合成外部使用
useCurrentFrame()/useVideoConfig()→ 拋出錯誤。僅在合成元件內部呼叫它們。