remotion-best-practices

Overview

What is the remotion-best-practices skill?

remotion-best-practices 技能是一組精選的指南與規範，專門用來搭配 Remotion（以 React 為基礎的影片製作框架）建立影片。它將動畫、音訊、字幕、FFmpeg 使用方式、素材資產、3D 場景等各種領域的設計模式，整理成聚焦明確的規則檔，放在 rules/ 底下。

與其從零到處拼湊範例，這個技能提供具主見的建議，教你如何組織 Remotion 程式碼，讓畫面渲染穩定、能擴充到大型專案，並在長期維護上保持乾淨清晰。

Who is this skill for?

如果你符合以下任一情境，適合安裝這個技能：

• 使用 Remotion 與 React 製作行銷、產品介紹或社群影片
• 需要以程式自動產生影片（例如資料驅動或範本式內容）
• 處理大量音訊內容，如 podcast、audiogram 或音樂視覺化
• 想要清楚的字幕、字幕檔與 SRT 流程範例
• 要在 Remotion 合成中加入 3D 或 Three.js 內容

這個技能特別適合前端工程師、會寫程式的動態設計師，以及希望統一 Remotion 專案寫法的團隊。

What problems does it solve?

Remotion best-practices 技能幫你處理實際 Remotion 專案中常遇到的問題，例如：

• 以「frame 為基準驅動所有動畫」，讓渲染穩定且結果可重現
• 透過 public/ 資料夾與 staticFile() 正確匯入與引用 圖片、影片、音訊與字型
• 建立 乾淨的影片 composition，具有一致的時間軸、轉場與參數設定
• 處理 音訊（多軌疊加、裁切、延遲、音量、播放速度、loop、音效）
• 產生 音訊視覺化（頻譜長條、波形、低頻反應特效等）
• 操作 字幕與 captions，包含 SRT 匯入與轉錄流程
• 使用 FFmpeg 進行裁切、截取影格、偵測靜音等作業
• 透過 @remotion/three 整合 3D、Three.js 與 React Three Fiber
• 在渲染前動態計算 composition metadata（長度、尺寸、props）
• 在渲染前使用 Mediabunny 驗證媒體相容性

只要你的專案超出簡單示範等級，這些規則都提供在實戰與正式上線環境中驗證過的設計模式。

When is this skill a good fit?

在以下情況特別適合使用 remotion-best-practices 技能：

• 專案已使用 Remotion，或正在評估以 Remotion 產生影片
• 想要在動畫、素材、音訊、字幕與 3D 上，有一致且清楚的規範
• 需要以程式碼層級的範例為主，而不是只有高層文件說明

這個技能不會取代 Remotion 官方文件，也不是學習 React 的完整教學。它預設你已熟悉 React 基礎，並且至少大致看過 Remotion 文件。

How to Use

1. Installation and setup

Install the skill into your agent environment

使用 skill manager，從 upstream repository 加入 Remotion best-practices 技能：

npx skills add https://github.com/remotion-dev/skills --skill remotion

安裝後，remotion-best-practices 的知識就會提供給你的 agent，在協助你處理 Remotion 專案時可引用這些規則檔。

Review the core documentation files

安裝完成後，先打開以下檔案：

• SKILL.md – 整體說明、適用情境與重要規則檔連結
• rules/animations.md – 如何用 useCurrentFrame() 與 useVideoConfig() 驅動動畫
• rules/assets.md – 正確匯入圖片、影片、音訊與字型的方式
• rules/audio.md – 處理音訊、裁切、延遲與多軌疊加
• rules/audio-visualization.md – 音訊資料、波形與頻譜視覺化
• rules/3d.md – 透過 @remotion/three 使用 Three.js 與 React Three Fiber 建立 3D 場景

這些規則構成大多數 Remotion 影片剪輯工作流程的基礎。

2. Core concepts and best practices

Drive all animations by frame

請參考 rules/animations.md，裡面說明 Remotion 動畫的核心原則：

• 使用 useCurrentFrame() 讀取目前 frame
• 使用 useVideoConfig() 取得 fps
• 以秒為單位計算動畫時間，再換算成 frame（seconds * fps）
• 使用 interpolate() 等 helper，把 frame 映射到位置、不透明度或其他屬性
• 避免使用 CSS transitions、CSS animations 與 Tailwind 的動畫類別，它們在 Remotion 中無法穩定渲染

這種以 frame 為中心的方式，能確保不論播放速度或環境如何，輸出結果都一致。

Manage assets via public/ and staticFile()

rules/assets.md 說明如何處理媒體素材：

• 將所有靜態媒體（圖片、字型、音訊、影片）放在 public/ 資料夾
• 使用 staticFile("my-file.ext") 參照 public/ 內的檔案
• 將 staticFile() 搭配 Remotion 元件使用，例如 <Img>、<Video>、<Audio>
• 若檔案已託管在網路上，可直接使用遠端 URL

這樣的做法可以避免路徑錯誤、自動處理 URL 編碼，並適用於不同的部署環境。

Build robust audio and sound design

rules/audio.md 針對音訊工作流程提供細節：

• 使用 @remotion/media 中的 <Audio> 匯入音訊
• 以 frame 為單位，透過 trimBefore 與 trimAfter 裁切音訊片段
• 使用 <Sequence> 包裝，延遲音訊或與畫面同步
• 疊加多個 <Audio> 元件，處理音樂、旁白與音效

若需要音訊驅動的視覺效果，搭配 rules/audio-visualization.md：

• 安裝 @remotion/media-utils
• 使用 useWindowedAudioData() 讀取一段時間窗的音訊樣本
• 使用 visualizeAudio() 產生頻率資料，繪製頻譜長條

這讓你能輕鬆製作 audiogram、節奏反應標題與音樂視覺化效果。

Handle captions and subtitles

頂層的 SKILL.md 會引導你到字幕相關的規則：

• rules/subtitles.md – 字幕使用模式
• rules/display-captions.md – 在畫面上渲染字幕
• rules/import-srt-captions.md – 匯入 SRT 字幕檔
• rules/transcribe-captions.md – 以轉錄為主的字幕流程

在以下需求時特別好用：

• 製作社群平台上的燒錄字幕（burned-in subtitles）
• 管理不同語言的字幕軌
• 建立自動或半自動的字幕生成流程

Use FFmpeg for advanced video operations

rules/ffmpeg.md 說明何時搭配 FFmpeg 與 Remotion 使用，例如：

• 精準裁切或串接來源影片
• 偵測音訊中的靜音
• 擷取影格或產生 GIF

Remotion 專注在渲染與合成畫面，而 FFmpeg 負責對原始媒體檔進行重度處理。兩者搭配常是正式環境影片流程中最有效率的組合。

Bring in 3D with Three.js and React Three Fiber

如果你想在 Remotion 影片中加入 3D 場景，請先閱讀 rules/3d.md：

• 依建議指令安裝 @remotion/three 套件：npx remotion add @remotion/three（或使用你慣用的套件管理工具）
• 使用 <ThreeCanvas> 包住 3D 內容，並從 useVideoConfig() 傳入 width 與 height
• 設定基本燈光（例如 ambientLight 與 directionalLight）
• 使用 useCurrentFrame() 驅動 3D 動畫，而非 @react-three/fiber 的 useFrame()

如此可以確保 3D 畫面逐格渲染正確，不會出現閃爍或音畫不同步。

3. Dynamic compositions and metadata

Calculate duration and dimensions dynamically

rules/calculate-metadata.md 展示如何在 <Composition> 上使用 calculateMetadata：

• 根據外部資料（例如輸入影片長度）動態調整 durationInFrames
• 讓 composition 尺寸對齊輸入影片或其他動態值
• 在渲染開始前先轉換 props

搭配 rules/get-video-duration.md 與 rules/get-video-dimensions.md 等 helper，你可以：

• 讓 composition 自動依上傳內容調整尺寸
• 確保片頭片尾長度與媒體內容精準對齊

這在處理使用者產生內容或範本式影片系統時特別實用。

4. Media validation and compatibility

Check if a video can be decoded

rules/can-decode.md 介紹如何用 Mediabunny 進行相容性檢查：

• 使用 npx remotion add mediabunny 安裝 Mediabunny
• 使用提供的 canDecode() helper 檢查 URL 來源影片是否可被瀏覽器解碼
• 對於上傳的 Blob 來源，則使用 canDecodeBlob() 變體

這在建立上傳流程時很有用，可以在啟動昂貴的渲染程序前先驗證媒體。

5. Additional focused rules

除了核心主題外，rules/ 底下還有許多可按需查閱的專門指南：

• rules/compositions.md – 如何設計與管理 Remotion compositions
• rules/timing.md、rules/sequencing.md、rules/transitions.md、rules/text-animations.md – 精細掌控動態與時間節奏
• rules/fonts.md、rules/measuring-text.md、rules/measuring-dom-nodes.md – 排版與版面精準控制
• rules/gifs.md、rules/images.md、rules/videos.md、rules/transparent-videos.md、rules/trimming.md、rules/extract-frames.md – 操作各種媒體格式與流程
• rules/maps.md、rules/charts.md、rules/lottie.md、rules/light-leaks.md – 特定領域的視覺設計模式
• rules/voiceover.md、rules/sfx.md – 旁白與音效的實作流程
• rules/tailwind.md – 在保持 Remotion 相容性的前提下使用 Tailwind（排除不允許的動畫類別）

你可以依專案功能需求，選擇性參考這些規則。

6. Workflow tips for using this skill

With an AI agent

如果你使用的 AI 助理已安裝這個技能，可以這樣善用：

• 在需要更深入範例時，請它開啟特定規則檔（例如 rules/audio.md）
• 讓它產生符合規則的程式碼片段（不用 CSS transitions、所有動畫透過 useCurrentFrame()、正確使用 staticFile() 等）
• 將這個技能視為檢查清單，在 review 或重構 Remotion 程式碼時對照使用

In a team setting

對團隊而言，可以這樣將此技能標準化：

• 在內部文件中分享相關 rules/*.md 檔案連結
• 把技能中的建議整理進團隊內部的程式碼規範
• 在新成員加入 Remotion 專案時，將其作為參考教材與入門指引

FAQ

Is this skill the same as the Remotion framework?

不是。Remotion 是用 React 建立影片的底層框架，而 remotion-best-practices 技能是一組建立在 Remotion 之上的最佳實務與規則檔，專門用來指引你如何組織程式碼、處理媒體並避開常見陷阱。

Do I need to know React to benefit from this skill?

需要。Remotion 生態系以 React 為核心，規則檔中的範例也預設你了解 components、props 與 hooks。這個技能聚焦在 Remotion 特有 的議題，而不是從零教你學 React。

How do I install the Remotion best-practices skill?

在你的 agent 或 skills 環境中執行以下指令安裝：

npx skills add https://github.com/remotion-dev/skills --skill remotion

接著開啟 SKILL.md 與 rules/ 資料夾，瀏覽可用主題。

Can I use this skill without a Remotion project yet?

你可以在尚未建立專案前先閱讀內容與範例，但實際價值會在你已有 Remotion workspace 時更明顯。許多規則會提到 @remotion/media、@remotion/media-utils、@remotion/three 或 Mediabunny 等套件，你會希望把它們直接裝進自己的專案中使用。

Does this skill cover 3D content with Three.js?

有。rules/3d.md 專門介紹如何在 Remotion 中使用 Three.js 與 React Three Fiber 搭配 @remotion/three 製作 3D 內容，包含如何安裝套件、以 <ThreeCanvas> 包住內容，以及如何用 useCurrentFrame() 驅動動畫。

Where do I find guidance on audio visualizations and audiograms?

請參考 rules/audio-visualization.md。裡面示範如何安裝 @remotion/media-utils、使用 useWindowedAudioData() 取得音訊資料，再透過 visualizeAudio() 轉換成頻譜與波形，用來建立 audiogram 等視覺效果。

What if I need to work with captions and subtitles?

請從 SKILL.md 開始，它會指向：

• rules/subtitles.md：一般字幕設計模式
• rules/display-captions.md：如何在畫面上顯示字幕
• rules/import-srt-captions.md：匯入 SRT 檔案
• rules/transcribe-captions.md：以轉錄為主的字幕流程

這些指南涵蓋 Remotion 影片中大部分常見的字幕需求。

When should I use FFmpeg instead of pure Remotion code?

當你需要對原始媒體檔進行操作時，例如精準裁切、串接、靜音偵測或擷取影格時，建議使用 FFmpeg。Remotion 擅長以 React 組合與渲染場景，而 rules/ffmpeg.md 會說明如何以及何時在 Remotion pipeline 中整合 FFmpeg。

Can this skill help me avoid performance and rendering issues?

可以。許多規則就是為了避免常見問題而設計，例如：

• 3D 場景使用 useFrame() 而非 useCurrentFrame() 導致畫面閃爍
• 依賴 CSS transitions 的動畫在渲染時無法呈現
• 素材路徑錯誤或 URL 編碼不正確
• 媒體在渲染過程中失敗，因為實際無法解碼

遵循 rules/animations.md、rules/assets.md、rules/3d.md 與 rules/can-decode.md 中的建議，可以讓你的 Remotion 專案更穩定可靠。

How do I explore all available rule files?

安裝完成後，在你的環境中打開 rules/ 目錄。重要檔案包括：

• rules/3d.md
• rules/animations.md
• rules/assets.md
• rules/audio-visualization.md
• rules/audio.md
• rules/ffmpeg.md
• rules/compositions.md
• rules/timing.md
• rules/subtitles.md
• rules/voiceover.md

你可以透過 Files 分頁或編輯器瀏覽其餘檔案，了解更多像是圖表、地圖、GIF 與 Tailwind 等進階主題。