Communitygithub.com

remotion-motion-design

使用 Remotion 設計與實作合成、時間軸、場景系統、2D/3D 動畫、排版、轉場及可重複使用的元件。

remotion-motion-design 是什麼?

這份技能指南旨在協助開發者使用 Remotion 建立高品質、可重複使用的動態設計系統。它涵蓋了從前期規劃、合成設定到時間軸管理與動畫實作的完整流程。技能的核心在於強調「以影格為驅動」的確定性動畫原則,避免使用不穩定的時間或非同步 API。它詳細說明了如何使用 `useCurrentFrame()` 獲取當前影格、`useVideoConfig()` 讀取合成配置,並透過 `interpolate()` 和 `spring()` 等工具函式創建流暢的動畫。同時,它也指出了常見的錯誤,例如在 `Series.Sequence` 內部誤用全域影格,或使用無效的彈簧參數導致動畫卡死。支援 2D 與 3D 動畫,並包含像素風格與火柴人角色動畫的輔助說明。整體而言,此技能為開發者提供了一套嚴謹且可預測的工作流程,以產出符合影片製作標準的元件。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/achmdfzn/motionforge-atelier/tree/main/.claude/skills/remotion-motion-design

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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> 沒有 muted prop;靜音是一個 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() → 拋出錯誤。僅在合成元件內部呼叫它們。

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

相關技能