ffmpeg-skill
指令碼位於此檔案旁的 scripts/ 目錄中;使用 python3 <skill-dir>/scripts/<name>.py 執行它們,交付範本位於 templates/。此檔案足以完成工作:下方表格會路由請求,而即將執行的腳本的 --help 是最便宜的完整標誌清單。參考檔案的成本與此檔案相同;僅在您有疑問時才開啟一個:references/scripts.md(所有 42 個腳本的每個標誌)、references/devices.md(iPhone HDR、GoPro、DJI、螢幕錄製、Zoom)、references/gotchas.md(末尾一行規則的詳細形式)。MCP:tools/list 預設僅顯示核心的 12 個;其他 30 個(根據此表格)可透過 tools/call 按名稱呼叫,由 contract --json 描述;設定 FFMPEG_SKILL_MCP_FULL=1 以取得全部 42 個。
每個腳本的共用標誌:--dry-run;--json(輸出路徑、輸出的探測、執行的命令);--json-brief(狀態/輸出/已驗證加上 summary;在撰寫步驟時優先使用);--fast(預覽品質);--progress;--timeout SECONDS(kind: timeout,預設 1800);--overwrite(步驟 7);--plan FILE(乾執行作為一個計畫,稍後由 render.py FILE 執行;如果輸入已變更則拒絕)。重新編碼工具也接受 --codec h264|hevc|av1|prores 和 --quality N:未設定時,SDR 使用 x264,HDR 使用 x265 Main10;prores 需要 -o NAME.mov,h264 拒絕 HDR(先執行 color.py --to-sdr)。
撰寫工具在 --dry-run 下不執行任何操作;測量工具(probe、check、sync、multicam、scenes、cropdetect、report、silence、loudness、stabilize)可能仍會執行 ffmpeg/ffprobe,但會略過工件/側邊檔案(--edl、--sheet、產生的 .ass);verify 會忽略此標誌。每個工具:contract --json dry_run。
工作流程(按此順序)
- 環境,僅在失敗時執行。 切勿以
doctor開始工作:故障的機器會以kind: missing_tool或命名遺失篩選器/編碼器的 ffmpeg 錯誤訊息失敗。在此類失敗後,或當被詢問機器能做什麼時,執行python3 <skill-dir>/scripts/_contract.py doctor(或npx ffmpeg-skill doctor):讀取ok/usable,報告遺失的能力。contract --json的工具模式是給規劃代理使用的,而非此工作流程。 - 探測您必須規劃的內容。 對您規劃所依據的每個輸入執行
probe.py——持續時間、fps、解析度、編解碼器、聲道、variable_frame_suspected——以及每當使用者詢問關於檔案時。在每次編輯前無需單獨探測:每個撰寫工具的--json已經攜帶其輸入和輸出的探測。根據真實數字規劃,切勿假設。 - 優先使用無損。 如果請求無需重新編碼即可滿足(在關鍵影格上進行簡單裁剪、重新封裝、僅變更音訊),則不要重新編碼。
cut.py和loudness.py預設會串流複製視訊;僅在需要影格精確裁剪時,才對cut.py使用--accurate。 - 使用
--dry-run --json規劃,然後執行。 對於計畫中的任何數字(那裡的尺寸可能是佔位符),請相信--json,而不是乾執行的摘要行。在長時間編碼前使用,以報告事實。--fast是預覽品質,--progress會在 stderr 上列印百分比/ETA。除非使用者要求取代,否則切勿將-o指向您在此工作中未建立的檔案;僅在這種情況下才傳遞--overwrite。 - 按合理順序鏈接。 一個沒有其他編輯的交付請求只是一個範本執行(
render.py --template NAME INPUT),而不是手動建立的鏈條。否則:色彩(HDR→SDR / LUT)→ 裁剪 → 合併 → 靜音 → 調整 → 字幕/疊加 → 同步 → 音訊 → 響度 → 匯出。在字幕之前進行影格變更,以便文字根據最終影格調整大小。盡可能少地重新編碼:中間檔案使用 CRF 18,export.py最後執行。三步或更多步驟:使用render.py搭配 project.json。 - 檢查可交付成果。 在報告之前,針對指定的目的地執行
check.py OUTPUT --platform X(範本執行已經執行此操作)。格式列(編解碼器、像素格式、大小、真實峰值、色彩標記、VFR)可以安全修正。判斷列會變更內容:持續時間(裁剪會損失素材)、長寬比(裁剪會損失邊緣)、fps(會丟失動作)、響度(不得增強環境音)——僅在請求隱含答案時才修正,否則陳述選擇及其成本。提及 WARN;不要追蹤它們。 - 驗證輸出。 從撰寫工具的
--json/--json-brief探測或probe.py確認持續時間、解析度、fps 和音訊符合請求,並報告這些數字(「final.mp4:59.98 秒,1080x1920,30 fps,AAC 立體聲」)。僅當腳本以退出碼 0 結束且輸出如預期探測時,步驟才算完成:非零退出、檔案缺失或為空、或與請求矛盾的探測,都屬於失敗,並應報告腳本的錯誤訊息。 - 保留使用者的原始檔案。 切勿覆蓋來源;在輸入旁或要求的位置寫入新檔案。現有的輸出路徑會被拒絕(
kind: input);--overwrite是說「是的,取代它」的唯一方式。 - 檢視圖片。 每當圖片變更時(字幕、疊加、圖形、裁剪/填補、調整大小、色彩、轉場、
join.py將剪輯縮放到第一個剪輯的影格、color.py --to-sdr)執行look.py OUTPUT --tiles 3x2(或--at T用於一個影格)並檢視 PNG(整個片段版面使用 4x3)。直到Look:指出該 PNG 的名稱為止——探測無法看到臉上的字幕。僅音訊:Look: not needed。需要查看的內容類似check.py在步驟 5 中的列:- 機械性(此技能自身的驗證和報告職責): 指定的文字/標誌位於指定位置,字幕在指定的時間戳出現,尺寸為偶數。來自
fit.py --fit pad的 Letterboxing 是該模式的正確結果,絕非需要標記的缺陷。 - 判斷(報告它,不要無聲通過或失敗): 主題或臉部是否被裁切、文字是否放在臉上、顏色是否看起來褪色、轉場是否到位。這些需要決定主題是什麼,由呼叫的代理決定——用一行話說出你看到的;他們來判斷。
若無視覺能力,請撰寫
Look: PATH (pixels not inspected; agent has no image view)——絕不要聲稱圖片已被檢查,當它沒有時,也不要因為不存在的功能而停滯。
- 機械性(此技能自身的驗證和報告職責): 指定的文字/標誌位於指定位置,字幕在指定的時間戳出現,尺寸為偶數。來自
在執行任何操作之前:要問什麼、要假設什麼
僅當答案會顯著改變輸出且請求未隱含答案時,才問一個簡短問題。當多個事項同時不明確時(例如模糊的「為社交媒體製作」,目的地、長寬比、長度和字幕都不清楚),不要一次問一個:提出一個包含您預設值的套裝方案,並讓使用者更改任何部分(「Reels:9:16 填補,60 秒,-14 LUFS,無字幕——可以嗎?」)。一個問題,一個答案,然後執行。切勿詢問 probe.py 可以告訴您的內容。
- 目的地決定長寬比、長度限制、響度和編解碼器;「給 Reels」一詞回答了所有四項並命名了一個範本。沒有目的地且僅是簡單裁剪/字幕:保持來源格式並說明。如果使用者說「匯出」、「發布」或「交付」,請詢問地點。
- 持續時間(例如「做 60 秒」)但沒有方法:對於 ≤1.5× 的變化使用加速,否則使用修剪,並說明是哪種。當內容是對話(修剪會失去話語)且變更很大時提問。
- 字幕但沒有文字來源:如果本地有 whisper 則使用
--transcribe,否則要求提供文字或時間檔案;切勿發明對話。 - 字型和品牌:如果使用者提到品牌、顏色或「我們字型」,請要求建立
brand.json一次,然後重複使用。 - CJK / 非拉丁文字:讓工具根據文字選擇字型(
--font會關閉此功能);僅漢字文字使用--lang ja|ko。doctor --json.fonts.scripts會說明此處能渲染什麼。方塊字(tofu)代表失敗的工作。 --fit crop的裁切位置:預設居中,但當請求或來源指定了偏離中心的主題(例如「將產品保持在右側」,有人在聯絡頁中明顯偏離中心)時,使用--crop-x/--crop-y(0=左/上,1=右/下)而不是猜測中心,或詢問要保留哪個邊緣。- 其他任何內容(轉場類型、字幕樣式):選擇常規預設值,說明您選擇了什麼,並在一行中提供替代方案。
此技能決定什麼、不決定什麼
此技能裁剪、合併、測量、同步、匯出和檢查檔案——它執行編輯,而不是決定編輯。以下屬於人類、呼叫的代理或其他技能:
- 哪個裁剪是對的,或可交付成果是否可批准——此技能測量和報告(
check.py的 PASS/WARN/FAIL,cut.py的持續時間誤差);使用者或製作代理決定是否出貨。 - 什麼使精彩片段有趣——
scenes.py --highlights通過一個測量的代理(音訊能量、持續時間)進行排名:結果是候選項,而不是定論。 - 縮圖或封面的構圖——一個設計決定,而非測量。
- 理解影片是關於什麼的——此處沒有視覺能力,只有
look.py的聯絡頁,供呼叫的代理觀看,而非供此技能解讀。 - 判斷什麼看起來好——「套用此 LUT」、「將曝光補償 +0.3 級」(
color.py)是機械性的;「將此場景調色為電影感」屬於一個決定參數的調色技能(color-grading-skill),然後再呼叫color.py。 - 字幕中的文字——提示文字會按原樣燒錄。對於畫面來說太長,意味著使用更小的尺寸、
--max-lines,或使用者自己的編輯;切勿重寫、縮短或改寫它,即使被要求「讓它適合」——這麼說,並提供使用較小尺寸的--max-lines 1。 - 選擇未給定的主題或區域——一旦知道邊界框,「裁剪到 x=200,y=0」是機械性的;「裁剪以將演講者保留在畫面內」需要決定演講者是什麼,這是呼叫的代理(透過
look.py聯絡頁)的判斷。
界線是:相同的輸入 + 相同的明確參數始終產生相同的可驗證輸出屬於此處;任何取決於品味、理解或看起來/聽起來好不好的東西,都屬於做出該判斷的人。
如果一個請求需要 42 個腳本中都沒有公開的 FFmpeg 功能,請說明並命名最接近的內建選項——永遠不要猜測在 scripts/*.py 之外的原始 ffmpeg/ffprobe 調用。這會繞過此技能所做的每個保證,因此當腳本的標誌無法涵蓋某些內容時,永遠不要將其作為備用方案。
請求 → 腳本
此表格和 doctor --json 的 tools 清單是現有內容的真實來源:僅命名您在其中之一看過的腳本(沒有 doctor.py、trim.py、subtitle.py)。
時間戳標誌(--start、--end、--at、--from、--duration、--offset,以及提示和章節檔案中的時間)接受秒數、mm:ss(.fff)、hh:mm:ss(.fff) 或帶有 @fps 的 SMPTE hh:mm:ss:ff(00:01:02:[email protected])——直接貼上 NLE 提示表即可;長度標誌(--min-silence、--margin、--fade)為純秒數。
| 使用者說 | 執行 |
|---|---|
| 「從 1:20 剪到 2:05」、「剪掉前 10 秒」 | cut.py input.mp4 --start 1:20 --end 2:05 |
| 「只保留這些部分」、「移除中間部分」 | cut.py input.mp4 --segments 0-1:00,1:30-2:00 |
| 「讓它正好 60 秒」 | fit.py input.mp4 --duration 60(加速)或 --method trim |
| 「剪這個並把它轉成 HEVC / AV1 / ProRes」(指定輸出編解碼器) | cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc(在任何重新編碼工具上使用 --codec/--quality;ProRes 需要 -o NAME.mov) |
| 「剪掉停頓」、「跳接」 | silence.py input.mp4 [--threshold -40 --min-silence 0.8] |
| 「剪掉呃和嗯」、「移除填充詞」 | silence.py input.mp4 --filler --words words.json(測量的單字時間;--transcribe 會產生它們) |
| 「不要剪在句子內部,只剪真正的停頓」 | silence.py input.mp4 --speech-aware——句子內部低於 --min-silence 的換氣會被保留,只剪掉句子邊界的停頓;與 --filler 組合成一個清單 |
| 「從這一個小時的影片中剪出一個 60 秒的精彩片段」 | scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments |
| 「跟著節拍剪」、「把它剪成配合音樂」 | scenes.py track.mp4 --beats --json > beats.json,然後 cut.py input.mp4 --segments ... --snap beats --snap-source beats.json(--snap-source 會攜帶測量的節奏網格) |
| 「這裡加速,那裡慢動作」(已知片段) | speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0 |
| 「停在這個影格」、「凍結最後一個影格」 | freeze.py clip.mp4 --hold 2 |
| 「流暢的慢動作」、「半速但流暢」 | fit.py input.mp4 --duration 2x --smooth interpolate(慢)或 --smooth blend |
| 「反轉這個剪輯」 | reverse.py input.mp4 |
| 「迴圈這個剪輯以填滿 30 秒」 | loop.py bg_loop.mp4 --duration 30 |
| 「把它變成直式 / 9:16 / 正方形」 | fit.py input.mp4 --aspect 9:16 --fit pad(或 --fit crop;--pad-fill blur 用於模糊邊條) |
| 「調整大小到指定高度/寬度」 | fit.py input.mp4 --height 1080(或 --width,或兩者都用於精確畫面) |
| 「裁剪到這個精確範圍」(已知 x/y/w/h) | crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920 |
| 「用模糊背景取代黑邊」 | fit.py input.mp4 --aspect 9:16 --fit blur(保留整個圖片,邊界為模糊、變暗的副本) |
| 「旋轉 90 度」、「鏡像」 | fit.py input.mp4 --rotate 90 / fit.py input.mp4 --flip h |
| 「地平線歪了」(已知度數) | straighten.py tilted.mp4 --degrees -2.5 |
| 「從這個 360 影片取得平面視圖」(已知 yaw/pitch/fov) | sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70 |
| 「這個舊影片是交錯的」 | deinterlace.py input.mp4 |
| 「畫面有顆粒/雜訊,清理一下」 | denoise.py input.mp4 --strength medium |
| 「模糊/馬賽克這個臉/車牌」(已知範圍) | redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate |
| 「穩定這個晃動的影片」 | stabilize.py input.mp4 |
| 「這個上有黑邊嗎?」 | cropdetect.py input.mp4 |
| 「iPhone Dolby Vision 片段看起來不對勁」 | color.py clip.mov --to-sdr 或 --strip-dovi(保留 HDR,移除 DV 層) |
| 「顏色看起來褪色 / iPhone HDR」 | color.py input.mp4 --to-sdr |
| 「套用這個顏色查詢表(LUT)」 | color.py input.mp4 --lut my_lut.cube |
| 「修正白平衡」 | color.py input.mp4 --white-balance 5600 |
| 「使其符合廣播安全色彩」 | color.py input.mp4 --legalize |
| 「加上一個 logo / 浮水印」(已知圖片) | overlay.py input.mp4 --image logo.png --position bottom-right --padding 20 |
| 「添加標題文字 'Hello World'」 | `overlay.py input.mp4 --text |