Remotion CLI
此工具為 remotion,來自 @remotion/cli。所有指令皆透過 npx remotion <command> 執行,且每個指令都會先打包專案,因此型別錯誤或錯誤的引入會顯現為打包失敗,而非渲染失敗。
npx remotion --help 與 npx remotion <command> --help 是標誌的權威來源。 標誌在不同版本間會變動;請閱讀幫助輸出,而非信任任何清單(包括本清單)。以下內容為開發循環與失敗模式,並非標誌參考。
開發循環
| 階段 | 指令 | 原因 |
|---|---|---|
| 建立專案 Scaffold | npx create-video@latest --blank | 產生匹配的 package.json、remotion.config.ts、tsconfig |
| 型別檢查 | npx tsc --noEmit | 成本最低的關卡;在渲染前捕捉 schema/prop 漂移 |
| 列出組合 | npx remotion compositions | 確認即將渲染的 id 確實存在 |
| 探測畫面 | npx remotion still <id> out/probe.png --frame=<n> | 花費數秒而非數分鐘;迭代的主力工具 |
| 審閱 | npx remotion studio | 交給使用者;他們自行拖動時間軸並編輯 props |
| 渲染 | npx remotion render <id> out/video.mp4 | 僅在使用者核准後進行 |
| 遠端部署 | npx remotion bundle → npx remotion lambda render <url> <id> | 分散式渲染;需要已部署的 AWS 基礎設施 |
在渲染前先探測靜態畫面
一個 45 秒 1080p 組合的完整渲染耗時數分鐘。靜態畫面僅需數秒,且能回答大部分問題:文字是否在畫面內、資源是否載入、顏色是否正確。請探測每個場景的中間點,檢視所有圖片,然後再進行渲染。
npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180
切勿僅因打包成功就回報組合可正常運作。請查看像素。
Studio 是審閱工具,而非除錯器
npx remotion studio 提供含有時間軸、由 Zod schema 驅動的 props 編輯器以及精確畫面跳轉的服務。將其交給使用者進行審閱。對於你自己的驗證,偏好使用 still 探測:它們可腳本化,且你可以直接查看輸出,無需要求使用者描述所見。
傳遞 props
--props 接受 JSON 字串或 JSON 檔案路徑,並覆蓋 defaultProps:
npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'
若 props 不符組合的 Zod schema,則渲染會大聲失敗。這正是宣告 schema 的目的,因此請保持其準確。
批次渲染
沒有批次子指令。請在 shell 中對 id 或 prop 載荷進行迴圈:
for id in $(npx remotion compositions --quiet); do
npx remotion render "$id" "out/$id.mp4"
done
對於同一組合的多個資料集渲染,建議在 Node 腳本中使用 @remotion/renderer 的 renderMedia():它只打包一次,而非每次渲染都打包,這項差異主導了實際時間。
渲染效能
--concurrency=<n>設定並行工作數。預設為 CPU 核心數一半(上限 8);最大值為核心數,請求更多工作會導致錯誤,而非自動限制。在記憶體緊張的機器上,降低此值可解決看似渲染器錯誤的崩潰。--jpeg(取代預設的 PNG 畫面格式)在組合無需保留透明度時可大幅加速。npx remotion benchmark測量實際渲染,因此可用於證明變更並行數或編解碼器的效果,而非猜測。npx remotion gpu報告瀏覽器實際會加速的項目。在把緩慢渲染歸咎於著色器或大量濾鏡之前,值得先檢查此項。
診斷失敗
| 症狀 | 可能原因 |
|---|---|
| 打包失敗 | 型別錯誤或錯誤的引入。執行 npx tsc --noEmit 以取得相同錯誤的可讀版本。 |
| "No composition with id …" | Root.tsx 中的 id 與你傳遞的不同。npx remotion compositions 可解決此問題。 |
| 渲染卡住,然後超時 | delayRender() 沒有對應的 continueRender()。每個延遲控制代碼都必須被釋放。 |
| 每一幀看起來都像第 0 幀 | CSS 動畫/轉場,或使用了 requestAnimationFrame。渲染器不會推進瀏覽器時鐘。 |
| 動畫在幀之間閃爍或跳動 | 未使用種子 seed 的 Math.random()。請改用 random(seed)。 |
| 向前拖動時間軸時動作正常,跳轉時卻出錯 | 狀態驅動的動畫。請改用 useCurrentFrame() 來推導。 |
| 僅在 Lambda 或打包渲染中出現資源 404 | 使用了硬編碼路徑而非 staticFile()。 |
| 版本錯誤令人困惑 | Remotion 套件版本不一致。npx remotion versions 會報告不一致之處。 |
| 渲染中途記憶體不足 | 並行數過高,不符合機器規格。請降低 --concurrency。 |
回報失敗時,請提供實際錯誤輸出。請勿轉述堆疊追蹤。
已退役 HyperFrames CLI 功能去向
舊的 hyperframes CLI 包含了 Remotion CLI 所沒有的編寫、媒體與 QA 指令。以下所有內容皆非 Remotion 指令,請勿嘗試執行:
| 退役指令 | 該功能現在的位置 |
|---|---|
init | npx create-video@latest --blank,然後 /hyperframes-core → references/project-structure.md |
lint、check、layout、validate | npx tsc --noEmit 加上 still 探測。那些閘門強制的 data-* 合約已不存在。 |
snapshot、compare、grade-compare | npx remotion still 在選定的畫面;自行使用工具比對 PNG 差異。 |
preview、play、present | npx remotion studio |
add、catalog | /hyperframes-registry |
capture | /product-launch-video(網站捕捉)及 /media-use |
tts、transcribe、remove-background | /media-use |
beats、keyframes | /hyperframes-creative(節拍規劃)、/hyperframes-keyframes |
cloud、publish | npx remotion bundle + remotion lambda / remotion cloudrun,或自行託管 |
skills、docs、upgrade、doctor | 這些技能已收錄在此 repo 中;npx remotion upgrade 與 npx remotion versions |
如有任何工作流程技能或參考檔案仍指示你執行 npx hyperframes <anything>,則該指示已過時。請從上表執行對應的 Remotion 動作,並在你的摘要中說明遇到過時指標,以便修正。