當此技能被啟用時,請務必以 :clapper: 表情符號作為您的第一個回應開頭。
Remotion 影片
Remotion 是一個使用 React 以程式化方式建立影片的框架。不同於基於時間軸的編輯器,您可以將組合(Compositions)寫成 React 元件,其中每一幀都是當前影格編號的函數。這賦予了您 TypeScript、npm 套件和基於元件的架構的全部能力來建構影片——從動畫解說、社群媒體短片到數據驅動的視覺化和大規模個人化影片。
本技能涵蓋專案設定、組合結構、使用 interpolate 和 spring 的影格動畫、場景排序、素材管理、音訊整合、使用 Zod 架構的參數化影片,以及透過 CLI 或程式化 API 輸出為 MP4/WebM。
何時使用此技能
當使用者有以下需求時觸發此技能:
- 想要使用 React/TypeScript 以程式化方式建立影片
- 詢問關於 Remotion 組合、useCurrentFrame 或 useVideoConfig
- 需要為文字、元素或場景轉場添加動畫
- 想要從程式碼輸出影片為 MP4、WebM 或 GIF
- 詢問關於 spring 動畫、interpolate 或基於影格的時間控制
- 需要從頭設定一個新的 Remotion 專案
- 想要將音訊、圖片或字型加入 Remotion 影片
- 詢問關於參數化/數據驅動的影片生成
- 需要設定 Remotion Studio 來預覽組合
在以下情況請不要觸發此技能:
- 與影片創作無關的一般 React 問題——請使用 React 技能
- 使用傳統時間軸工具(Premiere、DaVinci、FFmpeg CLI)進行影片編輯
- 網頁的 CSS 動畫——請使用動畫/動態設計技能
- 在網頁應用程式中進行影片播放或串流——請使用媒體播放器技能
關鍵原則
-
每一幀都是一個純函數 - Remotion 元件透過
useCurrentFrame()接收當前影格,並且必須為該影格產生確定性的輸出。不能有副作用,不能有無隨機種子的隨機性,不能依賴於真實時間。相同的影格編號必須始終產生相同的視覺輸出。 -
組合是影片的基本單元 - 每個
<Composition>定義了一個具有明確尺寸(寬度、高度)、影格率(fps)和持續時間(durationInFrames)的影片。將組合視為專案中的「頁面」——每個影片變體或場景一個,可以獨立輸出。 -
對所有內容使用 interpolate -
interpolate()函數將影格號碼映射到任何數值(透明度、位置、縮放、顏色通道)。結合extrapolateRight: 'clamp',它是所有動畫的主力工具。當需要基於物理的緩動時,請使用spring()。 -
使用 Sequence 進行時間偏移 - 使用
<Sequence from={frame}>來延遲子元件的開始時間,以及使用<Series>來一個接一個地播放子元件。永遠不要使用 setTimeout 或手動影格計算來進行排序——宣告式的基本元件可以在預覽和輸出中正確處理。 -
素材是靜態的,數據是動態的 - 將圖片、字型和音訊檔案放入
public/資料夾,並使用staticFile()來引用它們。對於動態數據(API 回應、資料庫記錄),使用delayRender()/continueRender()來暫停輸出直到數據載入完成。
核心概念
組合結構
每個 Remotion 專案都有一個註冊組合的根檔案:
import { Composition } from 'remotion';
import { MyVideo } from './MyVideo';
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo"
component={MyVideo}
durationInFrames={150}
fps={30}
width={1920}
height={1080}
/>
);
};
基於影格的時間控制
Remotion 中的所有時間都以影格而非秒為單位表示。若要轉換:
- 秒數轉影格:
seconds * fps - 影格轉秒數:
frame / fps
在 30 fps 下,一個 5 秒的影片是 150 影格。影格 0 是第一個影格。
動畫模型
Remotion 提供了兩個核心動畫基本單元:
| 基本單元 | 使用案例 | 範例 |
|---|---|---|
interpolate() | 從影格到數值的線性/鉗位映射 | 淡入、滑入、縮放 |
spring() | 基於物理的動畫,包含阻尼/質量 | 彈跳進場、自然運動 |
兩者都回傳一個數值,您可以將其應用到樣式(透明度、變形等)。
常見任務
1. 設定新的 Remotion 專案
npx create-video@latest
這會建立一個包含 TypeScript、範例組合和已設定的 Remotion Studio 的專案。專案結構如下:
my-video/
src/
Root.tsx # 註冊所有組合
MyComp.tsx # 您的第一個組合元件
public/ # 靜態素材(圖片、字型、音訊)
remotion.config.ts # Remotion 設定
package.json
使用以下指令啟動預覽工作室:
npx remotion studio
2. 使用 useCurrentFrame 建立基本組合
import { AbsoluteFill, useCurrentFrame, useVideoConfig, interpolate } from 'remotion';
export const FadeInText: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 30], [20, 0], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#0f0f0f',
}}
>
<h1
style={{
fontSize: 80,
color: 'white',
opacity,
transform: `translateY(${translateY}px)`,
}}
>
Hello Remotion
</h1>
</AbsoluteFill>
);
};
3. 逐字動畫文字
將文字拆分為單字,並使用 <Sequence> 錯開每個單字的出現時間:
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate } from 'remotion';
const AnimatedWord: React.FC<{ children: string }> = ({ children }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 15], [0, 1], {
extrapolateRight: 'clamp',
});
const translateY = interpolate(frame, [0, 15], [10, 0], {
extrapolateRight: 'clamp',
});
return (
<span
style={{
display: 'inline-block',
opacity,
transform: `translateY(${translateY}px)`,
marginRight: 12,
}}
>
{children}
</span>
);
};
export const WordByWord: React.FC<{ text: string }> = ({ text }) => {
const words = text.split(' ');
return (
<AbsoluteFill
style={{
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#1a1a2e',
flexWrap: 'wrap',
padding: 100,
}}
>
{words.map((word, i) => (
<Sequence key={i} from={i * 8}>
<AnimatedWord>{word}</AnimatedWord>
</Sequence>
))}
</AbsoluteFill>
);
};
4. 使用 spring 的元素動畫
使用 spring() 來建立感覺自然的基於物理的動畫:
import { AbsoluteFill, useCurrentFrame, useVideoConfig, spring } from 'remotion';
export const SpringCard: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const scale = spring({
frame,
fps,
config: { damping: 200, stiffness: 100, mass: 0.5 },
});
const slideUp = spring({
frame: frame - 10,
fps,
config: { damping: 12, stiffness: 100 },
});
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center', backgroundColor: '#0d1117' }}>
<div
style={{
width: 400,
height: 250,
backgroundColor: '#161b22',
borderRadius: 16,
transform: `scale(${scale}) translateY(${(1 - slideUp) * 50}px)`,
}}
>
<p style={{ color: 'white', fontSize: 32 }}>Spring Animation</p>
</div>
</AbsoluteFill>
);
};
5. 使用 Sequence 和 Series 進行場景轉場
使用 <Sequence> 進行重疊場景,使用 <Series> 進行順序播放:
import { AbsoluteFill, Sequence, Series, useCurrentFrame, interpolate } from 'remotion';
const Scene: React.FC<{ color: string; title: string }> = ({ color, title }) => {
const frame = useCurrentFrame();
const opacity = interpolate(frame, [0, 20], [0, 1], {
extrapolateRight: 'clamp',
});
return (
<AbsoluteFill style={{ backgroundColor: color, justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ color: 'white', fontSize: 72, opacity }}>{title}</h1>
</AbsoluteFill>
);
};
export const MultiScene: React.FC = () => {
return (
<AbsoluteFill>
<Series>
<Series.Sequence durationInFrames={60}>
<Scene color="#e63946" title="Scene One" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#457b9d" title="Scene Two" />
</Series.Sequence>
<Series.Sequence durationInFrames={60}>
<Scene color="#2a9d8f" title="Scene Three" />
</Series.Sequence>
</Series>
</AbsoluteFill>
);
};
6. 素材處理(圖片、字型、staticFile)
使用 staticFile() 從 public/ 資料夾引用靜態素材:
import { AbsoluteFill, Img, staticFile } from 'remotion';
export const AssetDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<Img
src={staticFile('logo.png')}
style={{ width: 300, height: 300 }}
/>
</AbsoluteFill>
);
};
使用 @remotion/google-fonts 或 CSS @font-face 載入自訂字型:
import { loadFont } from '@remotion/google-fonts/Inter';
const { fontFamily } = loadFont();
export const FontDemo: React.FC = () => {
return (
<AbsoluteFill style={{ justifyContent: 'center', alignItems: 'center' }}>
<h1 style={{ fontFamily, fontSize: 64, color: 'white' }}>
Custom Font
</h1>
</AbsoluteFill>
);
};
7. 音訊整合
以音量控制和時間設定加入音訊:
import { AbsoluteFill, Audio, Sequence, staticFile, interpolate } from 'remotion';
export const WithAudio: React.FC = () => {
return (
<AbsoluteFill style={{ backgroundColor: '#000' }}>
<Audio
src={staticFile('background-music.mp3')}
volume={(f) =>
interpolate(f, [0, 30, 120, 150], [0, 0.8, 0.8, 0], {
extrapolateLeft: 'clamp',
extrapolateRight: 'clamp',
})
}
/>
<Sequence from={15}>
<Audio src={staticFile('whoosh.mp3')} volume={0.5} />
</Sequence>
</AbsoluteFill>
);
};
8. 輸出影片
從命令列輸出為 MP4:
# 輸出預設組合
npx remotion render src/index.ts MyVideo out/video.mp4
# 輸出為 4K 解析度
npx remotion render src/index.ts MyVideo out/video.mp4 --width 3840 --height 2160
# 輸出為 WebM
npx remotion render src/index.ts MyVideo out/video.webm --codec vp8
# 輸出特定影格範圍
npx remotion render src/index.ts MyVideo out/video.mp4 --frames 0-90
# 使用自訂 props 輸出
npx remotion render src/index.ts MyVideo out/video.mp4 --props '{"title": "Hello"}'
關於程式化輸出,請參閱 references/rendering-guide.md。
反模式 / 常見錯誤
| 錯誤 | 為什麼是錯的 | 應該怎麼做 |
|---|---|---|
在沒有種子的情況下使用 Math.random() | 在輸出過程中每幀產生不同的輸出 | 使用確定性種子或 Remotion 的 random() |
使用 setTimeout / setInterval | 破壞基於影格的輸出——計時器不會每幀前進 | 對所有時間控制使用 useCurrentFrame() 和影格計算 |
缺少 extrapolateRight: 'clamp' | 數值在後續影格中超出目標範圍 | 始終在 interpolate() 中加入 { extrapolateRight: 'clamp' } |
| 在影格計算中硬編碼 fps | 當組合 fps 改變時會出錯 | 使用 useVideoConfig().fps 來推導時間 |
對輸出內容使用 <Video> | 由於搜尋開銷,輸出效能較慢 | 使用 <OffthreadVideo> 以獲得更好的輸出效能 |
忘記對非同步數據使用 delayRender() | 在數據載入前輸出,顯示空白/損壞的影格 | 立即呼叫 delayRender(),準備好時呼叫 continueRender() |
| 使用非確定性值的內聯樣式 | 在預覽和輸出之間閃爍或不一致 | 僅從影格編號推導所有樣式值 |
| 巨大的單一組合 | 難以維護,且無法獨立輸出場景 | 拆分為多個組合或對場景使用 Series |
注意事項
-
extrapolateRight 預設為 'extend' - 如果您寫了
interpolate(frame, [0, 30], [0, 1])而沒有鉗位,數值會在影格 30 之後持續增加(例如,影格 60 會得到透明度 2)。除非您故意想要外推,否則請始終傳入{ extrapolateRight: 'clamp' }。 -
spring() 從其上下文的影格 0 開始 - 在
<Sequence from={60}>內部使用spring()時,傳遞給 spring 的影格會在父層的影格 60 處重設為 0。如果您傳遞父層的原始影格,動畫將會已經完成。請在 Sequence 子元件內部使用useCurrentFrame(),而不是來自父層的影格。 -
staticFile() 路徑相對於 public/ - 呼叫
staticFile('images/logo.png')會尋找public/images/logo.png。使用絕對路徑或public/之外的路徑會在預覽中靜默失敗,並在輸出時報錯。請確保所有素材都在public/目錄中。 -
delayRender 有 30 秒的超時時間 - 如果您的非同步操作(API 呼叫、字型載入)花費超過 30 秒,輸出將會中止。對於慢速操作,請使用
delayRender('Loading data', { timeoutInMilliseconds: 60000 })增加超時時間。 -
組合尺寸必須是偶數 - 影片編解碼器(H.264、VP8)需要偶數的寬度和高度。如果您傳入奇數尺寸,Remotion 將會拋出錯誤。