Remotion 完整教學

「用 React 寫影片」這個流派的標竿與最成熟的實作，把 component composition (元件合成) / state / hook 全部搬進 video timeline (影片時間軸)，再用 Rust-based compositor (合成器) + Lambda / Cloud Run 解掉大型 production (生產) 的渲染瓶頸。

1. 專案定位

一句話：Remotion = React + Video。用寫網頁的方式寫影片，但渲染端有自己的 native binary、自己的 lambda serverless 方案、自己的 player web component，已經是 5 年穩定迭代的生態系。

1.1 為什麼選 Remotion

• 完整的 web 技術棧：CSS / Canvas / SVG / WebGL / Three.js / Lottie / Rive 都能塞進 frame。
• 可程式化：interpolate / spring / useCurrentFrame 等 hook 讓動畫可被計算、被測試、被 diff。
• React 生態系全套可用：state、context、composition、Fast Refresh。
• 分散式渲染成熟：@remotion/lambda 是業界少數工程化完善的 serverless video render。
• MCP server 已內建：@remotion/mcp 讓 AI agent 直接接管 Remotion 專案。

1.2 適用 / 不適用情境

2. 安裝指南

2.1 最快路徑

1# 一鍵 scaffold（會問互動式問題、產出 starter project）
2npx create-video@latest

2.2 手動加裝到既有 React 專案

1npm install remotion @remotion/cli @remotion/player
2# 或 bun add remotion @remotion/cli @remotion/player

2.3 從原始碼 build（contributor 路徑）

 1# 1. clone
 2git clone https://github.com/remotion-dev/remotion.git
 3cd remotion
 4
 5# 2. 安裝（必用 bun v1.3.3+）
 6bun install
 7
 8# 3. build 全部 package（用 Turborepo）
 9bunx turbo run make
10
11# 4. 跑測試（lint + test）
12bunx turbo run lint test
13
14# 5. 啟 dev testbed
15cd packages/example && bun run dev   # http://localhost:3000
16
17# 6. （選用）啟 docs site
18cd packages/docs && bun run start

2.4 系統需求

• Node.js >= 18（建議 20+）
• Bun v1.3.3+（contributor 用；終端使用者可不裝）
• FFmpeg（renderer 內建抓取 binary，通常自動裝）
• Rust toolchain（僅 contributor 動 packages/compositor 時需要）
• Go >= 1.23（僅動 @remotion/lambda-go 時需要）

2.5 安裝流程圖

flowchart TD
    A[使用者] --> B{你是?}
    B -->|新專案| C[npx create-video@latest]
    B -->|既有 React app| D[npm install remotion @remotion/cli]
    B -->|要貢獻原始碼| E[git clone + bun install + bunx turbo run make]
    C --> F[src/Composition.tsx]
    D --> F
    E --> G[packages/example/]
    F --> H[npx remotion studio]
    G --> H
    H --> I[browser preview]
    I --> J[npx remotion render]
    J --> K[output.mp4]

3. 核心架構解析

3.1 四層架構

Remotion 是 React composition → bundler → renderer → encoder 四段式：

1. Composition Layer：使用者寫 <Composition id="my-video" component={MyVideo} durationInFrames={150} fps={30} ... />，元件用 useCurrentFrame() 取當前 frame 編號。
2. Bundler：@remotion/bundler 把 React 專案 bundle 成可在 headless Chrome 內執行的 URL。
3. Renderer：@remotion/renderer 開 headless Chrome，給每個 frame 設 setFrame(n) → 等 React 重渲 → 截圖。
4. Compositor：Rust binary（packages/compositor）負責高速合成 + 編碼成 MP4 / WebM。

3.2 Component 互動圖

flowchart LR
    A[src/Root.tsx 註冊 Composition] --> B[@remotion/bundler]
    B --> C[Webpack bundle]
    C --> D[@remotion/renderer]
    D --> E[Headless Chrome setFrame loop]
    E --> F[React re-render]
    F --> G[PNG screenshot]
    G --> H[@remotion/compositor Rust binary]
    H --> I[FFmpeg encode]
    I --> J[output.mp4]
    K[@remotion/player browser embed] -.preview.-> A
    L[@remotion/cli studio] -.dev UI.-> A
    M[@remotion/lambda] -.distributed.-> D
    N[@remotion/mcp] -.AI agent.-> A

3.3 一個最小 composition

 1// src/MyVideo.tsx
 2import { AbsoluteFill, interpolate, useCurrentFrame } from "remotion";
 3
 4export const MyVideo: React.FC = () => {
 5  const frame = useCurrentFrame();
 6  const opacity = interpolate(frame, [0, 30], [0, 1], {
 7    extrapolateRight: "clamp",
 8  });
 9  return (
10    <AbsoluteFill style={{ backgroundColor: "#0a0a0a", color: "white" }}>
11      <h1 style={{ opacity, fontSize: 120 }}>Hello Remotion</h1>
12    </AbsoluteFill>
13  );
14};
15
16// src/Root.tsx
17import { Composition } from "remotion";
18import { MyVideo } from "./MyVideo";
19
20export const RemotionRoot: React.FC = () => (
21  <Composition
22    id="HelloRemotion"
23    component={MyVideo}
24    durationInFrames={150}
25    fps={30}
26    width={1920}
27    height={1080}
28  />
29);

關鍵 hook：useCurrentFrame() / useVideoConfig() / interpolate() / spring() / random() / delayRender() / continueRender()。

3.4 ~126 個 package 分類速覽

graph TB
    A[Remotion Monorepo] --> B[核心]
    A --> C[分散式渲染]
    A --> D[內容工具]
    A --> E[視覺特效]
    A --> F[開發者工具]
    B --> B1[remotion / cli / renderer / bundler / compositor]
    C --> C1[lambda / cloudrun / serverless / lambda-go/php/python/ruby]
    D --> D1[player / captions / openai-whisper / elevenlabs / fonts / lottie / rive / gif]
    E --> E1[effects / motion-blur / noise / light-leaks / animation-utils / shapes / transitions]
    F --> F1[mcp / create-video / eslint-config / babel-loader / docs / discord-poster]

4. CLI 與工具腳本詳細用法

4.1 CLI 子命令（npx remotion）

4.2 常用環境變數

4.3 開發指令（contributor 用）

1bun install                              # 安裝
2bunx turbo run make                      # build all
3bunx turbo run lint test                 # lint + test all
4bunx turbo run make --filter='@remotion/player'   # 只 build 單一 package
5bun run stylecheck                       # CI 風格檢查
6bun pre-commit.ts                        # pre-commit hook (oxfmt)

5. 應用場景

6. 資安掃描報告

工具：人工審查 + grep 對 packages/core / packages/cli / packages/renderer 抽樣。

6.1 結果總表

6.2 詳細說明

🟡 License 法務風險

Remotion 的最大「資安」議題其實是 法律合規：

• 個人 / ≤3 人公司 / 非營利 → 免費（含商業用途）
• 超過 3 人公司或營利組織 → 必須購買 Company License（remotion.pro/license）

在企業導入時請務必先做 license compliance 評估；若觸發 Company License 條件而未購買，是合約 / 著作權法層級的風險，不是技術 bug。

🟡 Lambda IAM 寬鬆

@remotion/lambda 部署時預設給的 IAM policy 為了功能完整可能偏寬。生產環境應：

1. 限制 S3 bucket 路徑（用 Resource: arn:aws:s3:::mybucket/* 而非 *）
2. 限制 Lambda invocation source（用 source ARN condition）
3. 開 CloudTrail 監控 unusual invocation pattern

🟢 API key 環境變數

OPENAI_API_KEY / ELEVENLABS_API_KEY 均走 process.env.*，不會落地。bunfig.toml 內已設 .env.bundle 隔離。

🟢 Compositor binary 來源

packages/compositor/ 用 Rust 編譯，產出多平台 binary（darwin-arm64 / darwin-x64 / linux-arm64-gnu/musl / linux-x64-gnu/musl / win32-x64-msvc）並透過 npm package 分發。供應鏈攻擊面集中在 npm，建議使用 npm audit + lockfile commit。

6.3 部署建議

7. FAQ

Q1. Remotion 跟 HyperFrames 有什麼不同？

A: 詳見 hyperframes 教學 §1.3 的比較表。核心：Remotion = React/JSX，bundler 必須；HF = plain HTML，無 build。Remotion 生態系大、HF 上手快。

Q2. 為什麼 useCurrentFrame() 在 React 重渲時還能保持 deterministic？

A: 因為 Remotion 渲染端是 frame-by-frame setFrame loop：給定 frame 編號 → 透過 React context 注入 → render 出該 frame → 截圖。每 frame 是獨立 evaluation，無 wall-clock 干擾。

Q3. 我要做 AI 個人化影片，怎麼起步？

A: npx create-video@latest → 選 Hello World template → 把 props 設成你的個人化資料 → 用 npx remotion render --props='{"name":"Alice"}' 渲染。

Q4. Lambda 是不是很貴？

A: 視渲染解析度與長度。AWS Lambda 計費按 GB-秒；4K 30s 影片約 $0.05–0.20 美金。詳算機在 https://www.remotion.dev/lambda 提供。

Q5. 可以用 Tailwind 嗎？

A: 可以。packages/enable-tailwind 提供整合。注意 PurgeCSS 規則要 include node_modules/remotion/**。

Q6. 如何把現有影片素材塞進 composition？

A: 用 <Video src="..." />、<Audio src="..." />、<OffthreadVideo>（適合長影片）；@remotion/media-parser 可分析格式 / 時長。

Q7. 為什麼 commit 規範要 [package-name]: msg 格式？

A: 因為 Remotion 是 monorepo，每個 package 獨立版號；commit prefix 用於 changelog 自動分類。

8. 進階技巧

8.1 用 spring 取代 interpolate

 1import { spring, useCurrentFrame, useVideoConfig } from "remotion";
 2
 3const frame = useCurrentFrame();
 4const { fps } = useVideoConfig();
 5const scale = spring({
 6  frame,
 7  fps,
 8  from: 0,
 9  to: 1,
10  config: { damping: 12, mass: 0.5 },
11});

spring() 比 interpolate() 自然，適用 UI 元素彈跳、文字進場。

8.2 並行多 composition 渲染（CI 場景）

1# 從 compositions 命令列舉，並行 render
2npx remotion compositions --json | jq -r '.[].id' | \
3  xargs -I {} -P 4 npx remotion render {} --output ./out/{}.mp4

8.3 Lambda 渲染最佳化

1# 一次部署、長期重用
2npx remotion lambda functions deploy --memory 3009 --disk 10240 --timeout 600
3
4# 渲染（帶 reuse 旗標）
5npx remotion lambda render <serve-url> <comp-id> --concurrency-per-lambda 1

8.4 MCP 整合 Claude / Cursor

1# 在 Claude Code / Cursor 設定 MCP
2npx -y @remotion/mcp

Agent 即可直接讀 / 寫 src/Composition.tsx，並透過 render 工具產出影片。

8.5 用 @remotion/media-parser 預載資料

1const parsed = await parseMedia({ src: "./input.mp4", fields: { durationInSeconds: true } });
2// 動態決定 durationInFrames = Math.ceil(parsed.durationInSeconds * fps)

9. 整合進其他工作流

10. 重點摘要 Checklist

• Remotion 用 React 寫影片，需 bundler。
• 核心 hook：useCurrentFrame / useVideoConfig / interpolate / spring。
• <Composition> 註冊在 Root.tsx，是渲染入口。
• 開發必用 bun，build 用 Turborepo。
• Compositor 是 Rust binary，多平台分發。
• License 限制：>3 人公司或營利組織需購 Company License。
• 分散式：@remotion/lambda 與 @remotion/cloudrun 已生產化。
• MCP server：@remotion/mcp 讓 AI agent 直接操作 composition。
• 包含 ~126 個 package，按需安裝即可。
• Remotion 5.0 將調整 license（PR #3750），導入前留意。

11. 進一步閱讀

• 官方文件: https://remotion.dev/docs
• API Reference: https://remotion.dev/api
• License 完整條文: https://github.com/remotion-dev/remotion/blob/main/LICENSE.md
• 購買 Company License: https://remotion.pro/license
• Showcase: https://remotion.dev/showcase
• Discord: https://remotion.dev/discord
• Jonny Burger（作者）twitter: https://twitter.com/JNYBGR
• AGENTS.md（contributor 與 AI agent 開發指引）
• CONTRIBUTING.md