Remotion 影片 — 編碼實際影格
你是編碼器與渲染器。 你接收資產 — 錄音、旁白、B-roll 素材、逐字稿 — 以及 React 程式碼,並產出一個實際檔案:out/video.mp4。你的同儕負責撰寫文字與計劃;你是唯一產生像素的人。這裡的嚴謹原則是可重現的影格:相同輸入、相同確定性輸出,並透過 ffprobe 可讀的渲染進行驗證。
你擁有 Remotion 專案架構、<Composition> / <Sequence> / <TransitionSeries> 圖表、字幕處理管線(Whisper.cpp → toCaptions → createTikTokStyleCaptions)、靜音移除流程,以及帶有 codec 和並行度旗標的 npx remotion render 呼叫。
一個決定:影格還是文字?
如果要求是產出一個檔案,你來對了地方。如果要求是產出文字或計劃,在寫任何 .tsx 之前先轉交出去。
| 要求項目 | 轉交給 | 原因 |
|---|---|---|
| 產出 MP4/MOV、轉場、燒錄字幕、渲染 | 這裡 | 這些是像素與影格 |
| 編寫腳本、鉤子、節奏、螢幕字幕文字、剪輯決策表 | ../video-shorts/SKILL.md | 那些是文字;剪輯的決策,而非剪輯的執行 |
將音訊處理至 LUFS 目標、產出章節 + RSS <item> | ../podcast/SKILL.md | 音訊處理與 feed,而非影片編碼 |
| 結構化課程/影片的敘事弧線與流程 | ../course-storytelling/SKILL.md | 敘事架構,而非渲染 |
| 設計縮圖圖片 | ../youtube-thumbnails/SKILL.md | 靜態圖片,而非影片 |
一條線的界限:video-shorts 決定剪輯點並撰寫字幕文字;你在程式碼中執行剪輯,並將字幕燒錄到影格中。
建立專案
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npm run dev # 在瀏覽器中開啟 Remotion Studio
Remotion 目前的穩定版本是 4.0.471;它需要 Node 16+(或 Bun 1.0.3+),且本地渲染目標為 macOS 15 (Sequoia)+。自 2026 年 1 月 起,Remotion 附帶 Agent Skills — npx skills add remotion-dev/skills 會將 Remotion-aware 的指引整合到 Claude Code 中。請在 Remotion 專案內執行此指令,當你想要框架自身的技能與此技能一同載入時。
先在 <Composition> 上固定 fps 與尺寸,且之後永遠不要更改。 原因:每個持續時間都以影格為單位計算,而 frames = seconds * fps。在寫好持續時間後更改 fps,每個時間點都會無聲地偏移。 垂直短片為 1080×1920 @ 30;橫向為 1920×1080 @ 30。
組合圖表
// src/Root.tsx
import { Composition } from "remotion";
import { MyVideo } from "./MyVideo";
export const RemotionRoot: React.FC = () => {
return (
<Composition
id="MyVideo" // 你傳給 `remotion render` 的 id
component={MyVideo}
durationInFrames={300} // 30fps 下 10 秒
fps={30}
width={1080}
height={1920}
/>
);
};
// src/MyVideo.tsx
import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
export const MyVideo: React.FC = () => {
const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ frame, fps, config: { damping: 200 } });
return (
<AbsoluteFill style={{ backgroundColor: "black" }}>
<Sequence from={0} durationInFrames={90}>
<AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* 場景 1 */}</AbsoluteFill>
</Sequence>
<Sequence from={90} durationInFrames={210}>{/* 場景 2 */}</Sequence>
</AbsoluteFill>
);
};
僅透過 useCurrentFrame() 搭配 interpolate() 和 spring() 來製作動畫。切勿在 composition 內讀取牆上時鐘時間 (Date.now()) 或呼叫未設種子的 Math.random()。 原因:渲染是並行且可依影格位址的 — 每個影格獨立計算,因此任何非影格的輸入在重新渲染時都會產生不同的像素,破壞了「相同輸入、相同輸出」的保證。 如果需要隨機性,請使用 Remotion 的 random(seed)。
轉場
使用 @remotion/transitions(自 v4.0.53 起可用)。<TransitionSeries> 交錯放置 .Sequence(一個片段,附帶 durationInFrames)和 .Transition(一個 presentation 加上一個 timing)。轉場的持續時間會從總時間中扣除,因此相鄰的序列會在轉場期間重疊。
import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
import { slide } from "@remotion/transitions/slide";
import { fade } from "@remotion/transitions/fade";
import { Easing } from "remotion";
<TransitionSeries>
<TransitionSeries.Sequence durationInFrames={90}>{/* 場景 A */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={slide({ direction: "from-left" })}
timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
/>
<TransitionSeries.Sequence durationInFrames={120}>{/* 場景 B */}</TransitionSeries.Sequence>
<TransitionSeries.Transition
presentation={fade()}
timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
/>
<TransitionSeries.Sequence durationInFrames={90}>{/* 場景 C */}</TransitionSeries.Sequence>
</TransitionSeries>
每個 presentation 都是一個子匯入(@remotion/transitions/slide、/fade、/wipe、/flip、/clockWipe、/none)。
| Presentation | 感覺 / 使用時機 |
|---|---|
slide | 場景將下一個推入;節拍之間的方向性動量 |
fade | 柔和交叉淡出;平靜、中性的場景變化 |
wipe | 硬邊緣掃過;充滿活力,「下一個主題」 |
flip | 3D 卡片翻轉;俏皮,適用於揭示 |
clockWipe | 徑向掃描;倒數計時,「時間流逝」 |
none | 無動畫的硬切,但仍作為 TransitionSeries 節點 |
linearTiming 用於可預測、影格精確的剪輯;springTiming 用於有機的動態效果。 原因:線性在持續時間上是確定性的,因此你可以精確地預算影格;彈簧會超調並穩定下來,看起來很自然,但需要 durationRestThreshold 讓渲染知道何時完成。
動畫燒錄字幕
原生 @remotion/captions 套件於 v4.0.216 版本推出(與棄用舊版 convertToCaptions() 輔助函式為同一版本)。管線在 Node 伺服器上執行一次,然後 composition 讀取字幕:
- 轉錄。
@remotion/install-whisper-cpp下載 Whisper.cpp 和一個模型(medium.en約 1.5 GB)並在 Node 伺服器上將音訊轉錄為 Whisper JSON。 - 轉換。
@remotion/install-whisper-cpp的toCaptions()將該 JSON 轉換為帶有每個 token 時間戳的Caption[]。(convertToCaptions()是舊版別名 — 從 v4.0.216 起已棄用;請使用toCaptions()。) - 分段為頁面。
@remotion/captions的createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })將 token 分組為同時出現的「頁面」。
combineTokensWithinMilliseconds 的值是頁面大小的調整鈕。 原因:低值(約 200ms)將每個單字放在自己的頁面上 → 產生逐字彈出動畫;高值(約 1200ms)將一個短語打包在一頁中。 低 ms = TikTok 逐字能量;高 ms = 可讀短語。根據格式而非預設值來選擇。
完整的 Whisper.cpp 安裝、轉錄伺服器,以及 token 高亮字幕渲染器元件(含安全區樣式)收錄在 references/captions-pipeline.md 中 — 在建立字幕層之前請先閱讀它。
自動靜音移除
靜音處理是在來源音訊/影片進入 Remotion 之前執行的,而非在 composition 內部。原因:Remotion 渲染你提供的影格;修剪靜音是資產的上游編輯,先執行此操作意味著每個下游影格編號都已經反映了修剪後的時間軸。
使用 auto-editor(一個 Python + ffmpeg 引擎)進行初步處理,根據音訊音量裁剪空白段落:
auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
--margin在每個保留區域周圍添加邊距,以避免剪輯切到語音。--edit audio:threshold=4%設定音量下限,低於該值的區域視為「靜音」。--export premiere會輸出 EDL/XML 而非檔案,以便重新匯入 NLE。
pip 分發已過時/停止維護 — 請透過官方二進位檔或 pipx 安裝,不要用 pip install。 原因:PyPI 套件版本落後,可能與文件中的標誌不符。 當 auto-editor 不可用時,低階的備選方案是 ffmpeg 的 silencedetect / silenceremove 濾鏡。兩者及其完整的旗標矩陣,都收錄在 references/render-and-pipeline.md 中。
B-roll 疊加
透過在 <AbsoluteFill> 內部使用 <OffthreadVideo>(或 <Img>)並以 <Sequence from> 控制顯示時機,將疊加層置於主影片之上:
import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
const fps = 30;
const broll = { start: 4.0, duration: 3.0 }; // 秒
<AbsoluteFill>
<OffthreadVideo src={staticFile("main.mp4")} /> {/* 基礎層 */}
<Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
<AbsoluteFill style={{ /* 例如:畫中畫的內縮 */ }}>
<OffthreadVideo src={staticFile("broll.mp4")} /> {/* 疊加層 */}
</AbsoluteFill>
</Sequence>
</AbsoluteFill>
將每個時間碼轉換為影格數,使用 Math.round(seconds * fps),在邊界處執行一次。 原因:一個在 4.0 秒的 B-roll 提示,在 30fps 下是影格 120,但在 60fps 下是影格 240 — 在資料中保留秒數,並乘以來自 useVideoConfig() 的 fps,這樣更改 fps 就不會使疊加層不同步。 在渲染期間使用 <OffthreadVideo>(而非 DOM <video> 或 <Video>)以獲得影格精確的解碼。
渲染
# 先測試區域:1-2 秒,低成本驗證管線
npx remotion render MyVideo out/test.mp4 --frames=0-45
# 然後完整渲染
npx remotion render MyVideo out/video.mp4
省略 composition id 會顯示互動式選取器。透過 @remotion/cli/config 在 remotion.config.ts 中進行設定,或在 CLI 上傳遞旗標(旗標優先):
// remotion.config.ts
import { Config } from "@remotion/cli/config";
Config.setConcurrency(8);
Config.setCodec("h264");
| Codec | 用途 | 旗標 |
|---|---|---|
h264 | 網頁/YouTube 的預設值;廣泛相容性 | (預設) |
h265 | 檔案更小,相同品質;播放支援較少 | --codec=h265 |
prores | 編輯級母帶,檔案大,可重新匯入 NLE | --codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png |
vp8 / gif | 網頁 Alpha 或循環預覽 | --codec=vp8 / --codec=gif |
務必在完整渲染之前,先渲染一個 1-2 秒的區域(--frames=0-45)。 原因:對數分鐘長的 composition 進行完整渲染需要實際的時間和 CPU;區域測試可以在幾秒內發現損壞的字幕層或遺失的資產。 關於無頭/CI 渲染、確定性輸出規則,以及完整的 codec/品質矩陣,請參閱 references/render-and-pipeline.md。
反模式
| 不良實踐 | 為何會出錯 | 良好實踐 |
|---|---|---|
| 在 JSX 中硬編碼以秒為單位的持續時間 | Remotion 以影格為單位思考;fps 一變,秒數就不同步 | 在資料中儲存秒數,邊界處 Math.round(seconds * fps) |
在 composition 中使用 Date.now() / 未設種子的 Math.random() | 影格並行渲染且在重新渲染時 → 非確定性像素 | 一切依賴 useCurrentFrame();使用 random(seed) |
在寫入持續時間後更改 fps | 每個下游影格計數會無聲地偏移 | 先在 <Composition> 上固定 fps + 尺寸,然後保持不變 |
| 每次執行都重新下載 Whisper 模型 | 約 1.5 GB 的 medium.en 重複下載並阻塞管線 | 下載一次,快取模型路徑,重複使用 |
| 將 1.5 GB 的 Whisper 模型提交到 git | 膨脹儲存庫;模型是建置資產 | 在 .gitignore 中加入模型目錄;在設定/CI 中獲取 |
| 為了測試一個變更而渲染完整影片 | 浪費數分鐘的渲染時間來發現一個損壞的圖層 | 先 --frames=0-45 區域測試,再完整渲染 |
| 在此處撰寫字幕文案或鉤子 | 那是腳本,不是編碼 | 轉交給 ../video-shorts/SKILL.md;你只負責燒錄 |
在渲染中使用一般的 <video> / <Video> 作為 B-roll | 非影格精確;會在渲染時撕裂或跳幀 | 使用 <OffthreadVideo> 以獲得影格精確的解碼 |
| 在 composition 內部執行靜音移除 | 修剪靜音是上游資產編輯 | 在來源檔案上使用 auto-editor,然後才進 Remotion |
驗證與參考資料
bash scripts/verify.sh <project-dir>— 檢查 Remotion 專案格式是否正確並可渲染。如果 Node + ffmpeg 存在,它會執行npx remotion compositions確認 composition id 存在,對臨時 MP4 進行短區域渲染,並使用ffprobe確認存在具有預期尺寸/fps 的影片串流。如果兩者都不存在,它會回退到靜態檢查:至少存在一個 composition.tsx,且渲染腳本引用了一個真實的 composition id 和一個輸出路徑。預設為唯讀;若目標為空/乾淨則退出 0。references/captions-pipeline.md— 完整的 Whisper.cpp 安裝 + 轉錄伺服器、toCaptions、token 高亮字幕渲染器元件,以及字幕樣式/安全區備註。references/render-and-pipeline.md—auto-editor+ ffmpeg 靜音指令、完整的渲染旗標矩陣、無頭/CI 渲染、codec 表格,以及ffprobe驗證。