使用 ffmpeg 剪輯影片
你是一位編輯者，工作對象是逐字稿與濾波圖，而非滑鼠與時間軸。這條產線是確定性的：一切以文字編輯，並透過一條指令重新建構。
素材 → 附帶字級時間的逐字稿 → EDL（剪輯清單） → ffmpeg → 完成影片
↑ ↑
faster-whisper 手動編輯 — 這就是剪輯
核心原則：影片從不以像素為單位分析 — 剪輯由計時文字驅動。 語音決定結構；畫面為其服務。
一卷還是多卷？
請先決定這點 — 它將徹底改變後續流程。
- 一兩卷 → 按下方步驟順序，以對話形式進行。
- 三卷或以上 → 切換至批次管線：references/batch-pipeline.md。每個階段對整個專案執行一次，並依輸入雜湊值快取。以對話方式處理十卷，大約會消耗十倍的情境，且毫無益處。
工作順序
務必依序執行步驟，絕不跳過。每個步驟的輸出是下一步的輸入。
- 檢查環境。 若缺少 ffmpeg / faster-whisper / Chrome → 請參閱 references/setup.md。在乾淨的機器上約需十分鐘。
- 取得來源。 若使用者提供的是網址而非檔案，請先使用
download.py擷取。 - 檢查來源 — ffprobe、場景偵測、連絡表。透過 Read 親眼檢視影格。 切勿僅憑文字盲目剪輯。
- 轉錄成附帶字級時間的逐字稿，並校對結果。即使是清晰的音訊，語音辨識仍可能出錯。沒有本地模型？
transcribe_cloud.py可從 Groq/OpenAI 取得相同輸出。 - 與使用者達成概念共識，若對方尚未指定：格式、圖形內容、目標平台。只問一個問題，而非一份問卷。
- 建立 EDL — 剪去停頓，絕不剪斷想法。
- 建立
base，然後逐格驗證剪輯點。 - 產生字幕與疊加層，建構
final。 - 執行驗收清單，並使用 SendUserFile 交付檔案。
每個步驟的完整指令 — references/pipeline.md。
這條管線能做與不能做的事
能：語義剪輯、去除停頓、剪輯處放大、調色（包含 .cube LUT）、字級字幕、透過 HTML/CSS 實現任意複雜的資訊圖表、穩定、社交平台音量正規化、批次處理。若已安裝 Remotion 外掛，還能從 React 渲染動畫圖形 — 詳見 references/remotion.md。
完全不能 — 若使用者要求，請直接告知：物件追蹤（將字幕固定於移動的手部）與遮罩調色。這些仍需要 Premiere / DaVinci / After Effects。
單獨無法，但安裝 FableCut 後可： 影格精確的創意剪輯、關鍵影格動畫、轉場、速度變化、去背、跟隨音樂節拍剪輯。FableCut 是 agent 透過 MCP 驅動的瀏覽器時間軸 — 詳見 references/fablecut.md。它沒有語音辨識，匯出時需人工點擊，因此語音驅動的結構與無人值守的批次仍在這條管線中處理。
現成工具
assets/tools/ 存放了十二個可用腳本 — 將其複製到專案中，不要重寫：
| 腳本 | 功能 |
|---|---|
download.py | 從網址擷取來源素材（yt-dlp）— 若已有本地檔案則可跳過 |
transcribe.py | faster-whisper → 附帶字級時間的 transcript.json + .srt |
transcribe_cloud.py | 相同輸出，透過 Groq/OpenAI Whisper API — 不需下載模型，但需要 API 金鑰 |
pauses.py | 列出語音中的停頓 — EDL 的基礎 |
dump_words.py | 每個字及其索引與信心度 — 用於校對 |
make_ass.py | 字級 ASS 字幕，重新對應至剪輯後時間軸 |
render_overlays.py | HTML/CSS → 無頭 Chrome → 1080×1920 含透明度的 PNG |
build.py | 組合：base（剪輯 + 調色）、final（疊加層 + 字幕 + 音訊） |
build_vo.py | 同上，但針對 獨立的旁白音軌 — 影片來自多個來源，對齊音訊 |
batch_vo.py | 在一次模型載入中轉錄所有旁白 |
mute_subs.py | 當全螢幕卡片顯示時，隱藏字幕 |
pipeline.py | 批次驅動程式 — 對每卷執行每個階段，並有快取 |
assets/templates/ 存放了起始用的 edl.json、overlays.json 和 corrections.json。
請按以下方式佈局專案：
<素材所在資料夾>/
├── IMG_XXXX.MOV
└── edit/
├── tools/ ← 複製的腳本
├── work/ ← 中間檔案，永不交付
├── overlays/ ← 渲染後的 PNG
├── out/ ← 完成影片
├── edl.json overlays.json corrections.json subs.ass
參考檔案
按需載入，不要一次全部載入：
- references/setup.md — 在乾淨機器上安裝（Windows/macOS），驗證 ffmpeg 版本
- references/pipeline.md — 逐步工作流程、剪輯規則、指令
- references/storyboard.md — 影片格式、面板類型、如何為對嘴人物設計分鏡
- references/design-system.md — 調色盤、字體尺度、安全區域、疊加技術
- references/batch-pipeline.md — 將多卷視為階段執行，以及情境實際用在哪裡
- references/remotion.md — 動畫圖形層級：何時 React 渲染的疊加層值得其成本
- references/fablecut.md — 時間軸層級：何時將剪輯移交給 FableCut，以及兩條管線如何對接
- references/ffmpeg-cookbook.md — 調色、效果、轉場、音訊、編碼
- references/troubleshooting.md — 在首次執行 ffmpeg 前閱讀此文；十七種失敗情況，每種花費一小時
決定影片成敗的規則
這些是從實際建構中學到的，而非文件。
- 檢視影格。 逐字稿無法告訴你說話者在那一刻是否站起來或整理頭髮。這些正是剪輯會失敗的地方。
- 卡片放在臉部上方，絕不遮住臉。 初次嘗試總是將面板放在畫面中央，遮住眼睛。說話者的眼神是影片贏得信任的一半關鍵。
- 在語句結尾剪輯，而非按碼錶。 每隔「N 秒」剪一刀，會把想法切成兩半。
- 每個停頓保留 0.2–0.3 秒。 若將停頓完全消除，聽起來會像口吃。
- 絕不觸碰戲劇性停頓 — 在問題之後、結論之前。此時沉默正在發揮作用。
- 在不同段落間交替使用
zoom。 這樣剪輯看起來像是角度變化，而非錯誤。 - 至少留一段完全不使用圖形。 觀眾需要喘息空間；連續不斷的卡片令人疲憊。
- 校對字幕。 辨識錯誤一旦嵌入畫面就無法挽回。
- 透過目視驗證，而非憑信心。 擷取靜止影格，用
hstack堆疊，透過 Read 檢視結果。 - 未執行 pipeline.md 中的驗收清單，絕不交付。
- 絕不讓工具回寫至設定檔。 腳本若將自身輸出附加到 EDL 中，會使檔案大小加倍，後續每次編輯都會將整個內容帶入情境。產生的資料應存放在
work/中。 - 親自閱讀逐字稿的第一行與最後一行。 Whisper 會在靜音處幻覺出編造的文字 — 經典案例是俄語音訊上出現偽造的字幕製作人員名單 — 且可能帶有看似正常的信心分數。兩個轉錄腳本會自動過濾明顯案例，但過濾器並非萬無一失。參閱 troubleshooting.md #17。
編排
此任務包含多個步驟 — 使用 TaskCreate 為各個階段（逐字稿、EDL、調色、圖形、組合）建立任務，並保持其狀態更新。長時間運作（模型下載、base 渲染）請在背景執行，並利用時間處理不依賴它們的工作：模型下載時，設計疊加層並在靜止影格上測試調色。
使用 SendUserFile 交付完成影片，並附上簡短說明關於哪些內容已變更。