Remotion
Remotion 將 React 元件轉換成影片。你撰寫 JSX,Remotion 會在固定的 fps 下,為每個影格呼叫你的元件,然後將產生的影格合成為 MP4(或其他格式)。
核心心智模型
Remotion 給你一個影格編號和一塊空白畫布。你的 React 元件決定在該影格上渲染什麼。
這裡沒有命令式的動畫時間軸。時間只是一個數字(frame),而你的元件是這個數字加上 props 的純函數。這就是為什麼動畫必須由 useCurrentFrame() 驅動——CSS 過渡效果和 setTimeout 在渲染過程中是不確定的,會導致閃爍或不同步。
何時使用此技能
- 使用者有一個 Remotion 專案(
remotion.config.ts或package.json中有@remotion/*)並想要建立、更改或除錯 composition - 使用者說「讓我們用 Remotion / 用程式碼 / 程式化製作影片」
- 使用者貼上 Remotion 錯誤訊息,或詢問關於
interpolate、spring、Sequence、useCurrentFrame、Composition等 - 使用者想要渲染現有的 Remotion 專案或設定 Lambda 渲染
何時不要使用
- 使用 AI 模型(Veo、Sora、Runway、Kling、HeyGen)生成影片 → 請使用 video 技能
- 編輯現有影片檔案(剪切/修剪/拼接) → 使用 ffmpeg,而非 Remotion
- 直播串流 → Remotion 僅支援離線渲染
工作流程
-
偵測或建立專案。
- 新專案:
npx create-video@latest(互動式——可選擇範本,如 Hello World、Blank、JavaScript、TikTok 等) - 現有專案:檢查是否有
remotion.config.ts、src/Root.tsx,以及package.json中的@remotion/cli。注意 Remotion 的主要版本——API 會演進,正確的文件 URL 是https://www.remotion.dev/docs(最新版)或固定版本的頁面。
- 新專案:
-
找到或建立 composition。 Compositions 在
src/Root.tsx中註冊,格式為<Composition id="..." component={...} durationInFrames={...} fps={30} width={1920} height={1080} defaultProps={{...}} />。id是 CLI 按名稱渲染時使用的識別碼。 -
使用
useCurrentFrame+useVideoConfig建立元件,以處理時間和中繼資料。使用<AbsoluteFill>組合佈局,使用<Sequence>切割時間片段。 -
在 Studio 中預覽:
npx remotion studio(自動重新載入)。不要嘗試以隔離方式「測試」影格——直接開啟 Studio。 -
渲染:
npx remotion render <CompositionId> [output.mp4]。預設編碼為 H.264 / MP4。請參閱 references/rendering.md 了解旗標和程式化 API。
快速 API 參考
詳細內容請參閱連結檔案——僅在任務需要時才載入它們。
| 主題 | 檔案 |
|---|---|
| Composition、hooks、Sequence、AbsoluteFill、佈局 | references/core-concepts.md |
interpolate、spring、Easing、錯開效果、常見動畫模式 | references/animation.md |
渲染:CLI 旗標、@remotion/renderer、Lambda、編碼、props | references/rendering.md |
音訊/影片/圖片:<Audio>、<Video>、<Img>、<OffthreadVideo>、字幕 | references/media.md |
專案設定、檔案慣例、remotion.config.ts | references/project-setup.md |
| 常見模式:打字動畫、下方三分之一、數據驅動、視差 | references/patterns.md |
嚴格規則
- 使用
useCurrentFrame()進行動畫。 絕對不要使用setTimeout、requestAnimationFrame或 CSStransition。它們在渲染過程中會閃爍,因為每個影格都是在無頭瀏覽器中獨立渲染的。 durationInFrames是必需的,且必須為整數。 總秒數 =durationInFrames / fps。- 保持元件為純函數。 沒有頂層副作用,沒有
Math.random()(除非使用確定性種子)——同一個影格必須始終產生相同的像素。 - 不要在渲染時 fetch 資料。 使用
delayRender()/continueRender()來阻止影格準備完成,直到資料載入完成;或者預先擷取並透過 props 傳遞。 - 盡可能使用
<OffthreadVideo>而非<Video>,以便在渲染時進行非阻塞影片讀取(更快、更少記憶體)。 - 透過
--props(CLI)或inputProps(Studio/程式化)傳遞動態資料,而不是編輯檔案。
常見錯誤
| 錯誤 / 症狀 | 原因 | 修正 |
|---|---|---|
| MP4 與 Studio 預覽中的閃爍 / 動作不匹配 | 使用了 CSS 過渡或非影格驅動的動畫 | 替換為 interpolate(frame, ...) 或 spring({ frame, fps }) |
| "Composition not found" | ID 拼寫錯誤或缺少 <Composition> 註冊 | 檢查 src/Root.tsx |
| 渲染停滯 | 等待中的 delayRender() 從未呼叫 continueRender() | 找到未解決的 Promise;加入 try/finally |
| 長影片記憶體不足 | <Video> 將影格保留在記憶體中 | 切換為 <OffthreadVideo> |
| 音訊不同步 | 音訊檔案 fps 不匹配或從錯誤的影格開始 | 將 <Audio> 包裹在 <Sequence from={...}> 中 |
驗證
進行更改後,務必:
- 執行
npx remotion studio並撥動時間軸,確認更改在多個影格(開頭、中間、結尾)看起來正確 - 對於程式化更改,渲染一個簡短的測試片段:
npx remotion render <id> out.mp4 --frames=0-60 - 型別檢查:如果專案是 TypeScript,執行
npx tsc --noEmit
未執行上述任一驗證步驟,請不要聲稱成功。能編譯的程式碼不等於看起來正確的影片。