影片剪輯技能
概述
此技能實作了一個六層管線,由 AI 處理判斷任務(保留什麼、剪掉什麼、選擇精華),而 FFmpeg/Remotion 則以確定性方式執行機械操作。
| 層級 | 名稱 | 機制 | 主要工具 |
|---|---|---|---|
| 1 | 擷取 | 盤點原始素材 | Bash + Glob |
| 2 | AI 結構 | 逐字稿到 EDL | LLM 判斷 |
| 3 | FFMPEG 剪輯 | EDL 到片段檔案 | FFmpeg(確定性) |
| 4 | REMOTION 合成 | 片段到 TSX 合成 | Remotion + TypeScript |
| 5 | AI 生成 | 以生成素材填補缺口 | ElevenLabs / fal.ai(條件式) |
| 6 | 最終修飾 | 人類品味層 | 人類 + 非線性編輯器 |
深入參考
| 訊號 | 載入位置 | 內容 |
|---|---|---|
| 各階段的 Shell 指令、閘控檢查 | references/phase-commands.md | 第 1-6 階段的完整指令區塊 |
| FFmpeg 配方:剪輯、串接、代理、偵測 | references/ffmpeg-commands.md | 時間戳提取、批次剪輯、音訊正規化、場景/靜音偵測 |
| Remotion 合成架構 | references/remotion-scaffold.md | TSX 合成範本、渲染指令、重複使用模式 |
| 圖片轉影片管線 | references/image-to-video.md | 驗證、準備、編碼、驗證工作流程 |
| 用於視覺化的 FFmpeg 濾鏡圖 | references/ffmpeg-filters.md | 縮放/填補、聲波圖、頻譜圖、疊加、完整濾鏡圖 |
指示
飛行前檢查(在第 1 階段前執行)
必要條件(缺少時阻擋):ffmpeg(所有階段)、node(Remotion / npx)。
建議條件(缺少時警告):remotion(僅第 4 階段需要)。
which ffmpeg >/dev/null 2>&1 || { echo "ERROR: ffmpeg not found. Install: brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "ERROR: node not found. Install: https://nodejs.org or via nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "WARNING: remotion CLI not found. Phase 4 unavailable. Install: npm install @remotion/cli"
第 1 階段:擷取
目標:盤點所有原始素材,並在處理前確認檔案存在於磁碟上。
限制:原始檔案為唯讀。所有 FFmpeg 指令僅寫入新檔案。切勿覆寫原始素材。
步驟:定位原始檔案(find),使用 ffprobe 檢查每個檔案,為超過 10 分鐘的檔案產生代理(參見 references/ffmpeg-commands.md -> Proxy Generation),建立工作目錄(segments/、assembled/)。完整指令區塊:references/phase-commands.md -> Phase 1。
閘控:原始檔案已在磁碟上確認。檔案清單已寫入 source-inventory.txt。僅在閘控通過時才繼續。
第 2 階段:AI 結構
目標:分析內容並產生書面 EDL(cuts.txt),以驅動所有下游剪輯。
限制:cuts.txt 是契約。EDL 檔案是下游階段的唯一真實來源。請勿手動編輯 FFmpeg 指令——應從 EDL 產生。
限制:在手動撰寫 EDL 之前,先執行 FFmpeg 場景/靜音偵測。偵測輸出提供判斷依據,而非取代判斷。
步驟:使用 whisper/AssemblyAI 轉錄、執行場景/靜音偵測、套用判斷(哪些推進敘事、哪些是填充內容、目標時長)、以 EDL 格式 START_TIME,END_TIME,LABEL 撰寫 cuts.txt、檢查重疊與總時長。完整指令區塊與 EDL 格式範例:references/phase-commands.md -> Phase 2。
閘控:transcript.txt 存在。cuts.txt 已寫入磁碟。僅在兩個檔案都存在時才繼續。
第 3 階段:FFMPEG 剪輯
目標:確定性執行 EDL——為 cuts.txt 中的每個區段執行一次 FFmpeg 剪輯。
限制:使用迴圈從 EDL 批次剪輯。請勿為每個剪輯建立個別的 FFmpeg 指令。這可確保可重現性,並能以清單形式進行審查。
限制:一律從 cuts.txt 的順序產生 concat-list.txt,而非從 shell glob。Shell glob(segments/*.mp4)按字母順序排序,而非 EDL 順序。
步驟:使用 while 迴圈從 EDL 批次剪輯(libx264/aac、-avoid_negative_ts make_zero)、驗證區段、依 EDL 順序產生 concat-list.txt、使用 -f concat -safe 0 -c copy 串接。完整指令區塊:references/phase-commands.md -> Phase 3。另請參閱 references/ffmpeg-commands.md -> Batch Cutting。
閘控:所有區段檔案都存在。assembled/rough-cut.mp4 已寫入磁碟。僅在閘控通過時才繼續。
第 4 階段:REMOTION 合成
目標:將區段包裝成 Remotion TSX 合成,以實現程式化疊加層、標題或轉場。
使用時機:僅在 rough-cut.mp4 需要程式化元素(動畫標題、下方三分之一處、字幕軌、品牌疊加層)時使用。如果 rough-cut.mp4 已足夠,則跳至第 6 階段。
限制:第 4 層需要 TypeScript/React。將 TSX 工作交給 typescript-frontend-engineer;之後返回 python-general-engineer 進行第 5 階段及後續。
步驟:初始化 Remotion(首次使用 npm create video@latest;否則使用 npm install @remotion/cli @remotion/player remotion)、搭建合成(參見 references/remotion-scaffold.md)、使用 npx remotion render 渲染。完整指令區塊:references/phase-commands.md -> Phase 4。
閘控:assembled/remotion-output.mp4 存在。僅在閘控通過時才繼續。
第 5 階段:AI 生成
目標:僅在必要時,使用生成素材填補原始材料的實際缺口。
限制:在生成任何內容之前,檢查現有素材是否涵蓋該缺口。僅生成不存在的內容。
決策樹:繞過缺口進行剪輯 → 更新 cuts.txt 並重新執行第 3 階段;配音 → ElevenLabs(需要授權);音樂 → fal.ai(交給 fal-ai-media);B-roll → fal.ai(交給 fal-ai-media)。ElevenLabs Python 輔助工具、授權模式及儲存至磁碟流程:references/phase-commands.md -> Phase 5。
閘控:所有必要的生成素材在繼續前已儲存至 assets/ 目錄。
第 6 階段:最終修飾
目標:產出組合後的輸出,並將品味層工作交給人類。
限制:第 6 層是人類的領域。此技能負責組合;人類負責完成。下列事項需要人類判斷,不應以程式化方式嘗試:
- 調色與片段間的色彩匹配
- 音樂時機與音量降低
- 字幕樣式、字型、定位
- 轉場時機與樣式
- 最終音訊混音電平
交接範本(handoff-notes.txt,包含來源清單、EDL、粗剪路徑、待辦人類事項清單):references/phase-commands.md -> Phase 6。
閘控:assembled/rough-cut.mp4(或 assembled/remotion-output.mp4)存在。handoff-notes.txt 已寫入磁碟。
影片逐字稿提取
將影片的逐字稿提取為可讀的段落。優先使用上傳者提供的字幕;否則使用自動產生的字幕。
# 路徑 1:上傳者字幕(準確)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# 路徑 2:自動產生(當路徑 1 未寫入檔案時的回退方案)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# 將 VTT 清理為段落
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <work-dir>/<id>.en.vtt
選項:--timestamps 用於 [mm:ss] 標記,--keep-brackets 用於提示標籤,-o FILE 用於檔案輸出。其他語言:變更 --sub-langs。列出可用字幕:yt-dlp --list-subs '<URL>'。
錯誤處理
| 錯誤 | 原因 | 解決方案 |
|---|---|---|
| 原始檔案出現「無此檔案或目錄」 | cuts.txt 中的路徑與檔名不符 | 執行 cat source-inventory.txt。為包含空格的路徑加上引號。 |
| FFmpeg「無效選項」或編碼器錯誤 | 編碼器不可用或旗標語法錯誤 | `ffmpeg -codecs |
| Remotion「找不到合成」 | 合成 ID 不符 | 檢查 src/index.ts 中的註冊 ID。在渲染指令中精確匹配。 |
| 區段串接順序錯誤 | Shell glob 按字母順序排序,而非 EDL 順序 | 根據 cuts.txt 的順序產生 concat-list.txt,而非根據 glob。 |
| ElevenLabs 401 | 未設定 ELEVENLABS_API_KEY | 在第 5 階段前執行 export ELEVENLABS_API_KEY=your_key。 |
| 從逐字稿提取中未取得 .vtt 檔案 | 影片在要求的語言中沒有字幕 | 執行 yt-dlp --list-subs '<URL>' 並選擇可用的語言。 |