ffmpeg-pipeline 是做什麼的？
膠水技能。將生成的（或提供的）靜態圖片轉成帶旁白的動態 MP4，並處理代理經常遇到的繁瑣媒體工作。
需要 ffmpeg + ffprobe。提示模式需要 anon-image，--narration 需要 anon-audio；兩者都會自動偵測同層目錄下的套件，如果你改用 --images / --audio 則為選用。
指令
| 指令 | 功能 |
|---|---|
video | 靜態圖片（生成或來自 --images）→ MP4，含 zoompan 動態 + 交叉淡出，可選旁白與背景音樂 |
slideshow | 現有圖片 → MP4 |
mux | 將音軌附加到影片，自動循環/填補以符合長度 |
frames | 每隔 N 秒擷取靜態畫面 |
sheet | 聯絡表（N 張等距畫面，附時間戳） |
gif | 從任意片段裁切、調色盤最佳化的 GIF |
normalize | 將音訊音量正規化至 −16 LUFS |
speed | 改變音訊速度，不變音高（鏈式 atempo） |
info | 一行 ffprobe 摘要 |
probe | 依賴檢查 |
快速入門
# 單次呼叫完整管線：3 張生成畫面，每張 4 秒，附旁白
vidkit.py video "a lighthouse on a basalt cliff at dusk, cinematic" -o story.mp4 \
--shots 3 --seconds 4 --ratio 16:9 \
--narration "Somewhere on a cold coast, a lighthouse keeps its watch." \
--voice en-GB-RyanNeural
# 重複使用已有的圖片
vidkit.py video --images shots/ -o out.mp4 --seconds 3 --music bed.mp3
# 媒體手術
vidkit.py mux clip.mp4 voiceover.mp3 -o final.mp4
vidkit.py sheet final.mp4 -o preview.jpg --cols 4 --count 8
vidkit.py gif final.mp4 -o teaser.gif --start 1 --dur 2.5 --width 480
vidkit.py normalize voiceover.mp3 -o clean.mp3
vidkit.py info final.mp4
時間長度計算（讓你預測輸出結果）
使用 N 個片段，每個 S 秒，交叉淡出 0.8 秒：
持續時間 = N*S - (N-1)*0.8
3 × 4 秒 → 10.4 秒。如果旁白比畫面長，影片會循環播放以覆蓋它（-stream_loop）。如果旁白較短，音訊會以靜音填補，確保結尾不會遺失。兩種情況都已處理完畢 — 請勿自行加上 -shortest。
決策規則
- 比例：YouTube/網頁用
16:9，Shorts/Reels/TikTok 用9:16，動態消息與縮圖用1:1。所有影像都會縮放填滿後裁切，因此任何形狀的來源圖片都不會出現黑邊。 - 每張秒數：靜態圖片以 3–4 秒為佳；超過 6 秒的靜止畫面會感覺停滯。如果需要更長總時長，請增加畫面張數，而非增加每張秒數。
- 背景音樂：傳遞
--music後，音樂會以語音音量下的 12 % 混合。不要混合兩個大音量來源；請先正規化。 - GIF：保持寬度 ≤ 480 且持續時間 ≤ 3 秒，否則檔案會超過聊天限制。
失敗模式
| 症狀 | 原因 | 修正 |
|---|---|---|
missing dependency: ffmpeg | 未安裝 | apt install ffmpeg（或 brew install ffmpeg） |
ffmpeg failed: … Invalid argument 於 zoompan | 來源尺寸為奇數 | 濾鏡已縮放至 W*2；若你編輯過，請保持偶數值 |
| 輸出無聲音 | 旁白檔案遺失/空白 | 檢查路徑；--narration 可接受文字或音訊路徑 |
| 輸出比預期短很多 | 音訊比影片短且有人加了 -shortest | 移除它；vidkit.py 會自動填補 |
contact sheet needs Pillow | 缺少 Pillow | pip install pillow，或使用 frames 搭配你自己的工具 |
給代理的注意事項
- 除非使用者要求更高解析度，否則以 720p 渲染。速度快 4 倍，且在筆電螢幕上沒有人能分辨出差別。
- 最後一定要對成品執行
info，並將實際持續時間、解析度與檔案大小回報給使用者 — 這能捕捉到靜默失敗。 - 提供 MP4 路徑；不要將它嵌入。檔案本身就是成品。