Communitygithub.com

notque/vexjoy-agent

影片剪輯管線:使用 FFmpeg 和 Remotion 剪輯素材、組合片段。

vexjoy-agent 是什麼?

此技能實現了一個六層影片剪輯管線,將 AI 的判斷任務(如決定保留或剪掉哪些片段、選擇精華)與 FFmpeg 和 Remotion 的確定性機械執行分開。它支援 Bash、FFmpeg、Remotion、TypeScript、Python 和外部 AI 服務(如 ElevenLabs 和 fal.ai)。工作流程從素材盤點開始,接著透過 AI 分析生成編輯決策列表(EDL),然後使用 FFmpeg 批次剪輯並串接片段。必要時,可以使用 Remotion 加入程式化疊加層(如標題、字幕),並使用 AI 生成填補素材缺口(如配音、背景音樂)。最後,管線會產出一個粗剪版本,並附上手抄筆記,將需要人類品味判斷的作業(如調色、音樂混音)交給人類完成。此技能適合開發者和 AI 代理,用於自動化結構化影片製作,特別是在需要精確重現和明確閘控的場景。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

影片剪輯技能

概述

此技能實作了一個六層管線,由 AI 處理判斷任務(保留什麼、剪掉什麼、選擇精華),而 FFmpeg/Remotion 則以確定性方式執行機械操作。

層級名稱機制主要工具
1擷取盤點原始素材Bash + Glob
2AI 結構逐字稿到 EDLLLM 判斷
3FFMPEG 剪輯EDL 到片段檔案FFmpeg(確定性)
4REMOTION 合成片段到 TSX 合成Remotion + TypeScript
5AI 生成以生成素材填補缺口ElevenLabs / fal.ai(條件式)
6最終修飾人類品味層人類 + 非線性編輯器

深入參考

訊號載入位置內容
各階段的 Shell 指令、閘控檢查references/phase-commands.md第 1-6 階段的完整指令區塊
FFmpeg 配方:剪輯、串接、代理、偵測references/ffmpeg-commands.md時間戳提取、批次剪輯、音訊正規化、場景/靜音偵測
Remotion 合成架構references/remotion-scaffold.mdTSX 合成範本、渲染指令、重複使用模式
圖片轉影片管線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>' 並選擇可用的語言。

相關技能