Communitygithub.com

editar-video

以專業級水準編輯真實影片,使用本機 ffmpeg 進行色彩校正(正規化→平衡→場景匹配→調色)、飽和度、對比度、BT.709 合法層級、膚色、iPhone HLG 轉 SDR、裁剪、J/L Cut、圖層、文字、字幕、.cube LUT、縮放/穩定、響度,並為 Reels/TikTok 輸出。依靠測量(每個場景的示波器和數值)來判斷色彩,而不是「看起來」如何,並提供包含數值的前後對照表。

editar-video 是什麼?

這項技能讓 AI 代理能使用本機 ffmpeg 執行專業級影片編輯與色彩校正,專為需要客觀、可重複的色彩工作流程的開發者與影像工作者設計。它支援 macOS 與 Linux,並透過 Python 指令稿實作。其核心原則是「色彩靠測量來判斷」——每個色彩調整都附有觸發該調整的測量數值(如波形、向量示波器、直方圖),以及調整後的結果。技能涵蓋完整的編輯管線:從影片分析(顯示範圍與警告)、色彩校正(正規化、平衡、場景匹配、創意調色、套用 LUT),到裁剪(硬切、J Cut、L Cut)、圖層疊加、文字/字幕、運動效果(縮放、平移、穩定),以及針對 Reels/TikTok 的最終輸出與響度控制。它還包含一個「檢查點」系統,在關鍵階段(診斷、預覽、最終渲染)要求使用者確認,確保在繼續進行前解決任何問題。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/arthurmkt/arthur-portfolio-mkt/tree/main/design/editar-video

在你喜歡的 AI 中提問

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

說明文件

基於測量的影片編輯

**原則:**色彩靠測量來判斷。我所提出的每一個色彩調整,都會附上觸發該調整的數值(示波器、百分位數、膚色角度)以及調整後的數值。此技能中的每一條規則都有出處;沒有出處的規則會標示為 [無出處],絕不會當作規則使用。

**聲明限制:**我看的是影格和數值,而不是觀看正在播放的影片。**節奏、剪輯的感覺和調色風格,完全由提出要求的人來判斷。**在交付時,我會明確要求對方在手機上觀看。

**需求:**ffmpeg 與 ffprobe(在 8.1.2 版測試,搭配 libvidstab 用於 R61)、Python 3.10 以上版本,以及 numpy 和 Pillow(pip install numpy pillow)。

檔案

檔案用途
scripts/escopos.py場景診斷:示波器圖表(波形、RGB 並列、附膚色線的向量示波器、直方圖)+ 帶有警告與出處的 diagnostico.md/json
scripts/comparar.py每個場景的修正前後對比:圖表、1080p 解析度 split_cenaN.png 圖片、數值表格以及已解決/新增的警告
scripts/graduar.py套用校正計劃(JSON),按照訊號順序,以 16 位元 RGB 處理;--previa 參數會生成修正前後的靜止影格
scripts/gerar_lut.py將已批准的校正轉換為 .cube 檔案(33/65 點),供 Premiere/Resolve/CapCut 使用,並透過 PSNR 驗證
scripts/montar.py根據清單(JSON)組合片段,支援硬切、J Cut 與 L Cut
scripts/receitas.py38 個附有出處的 ffmpeg 配方;testar clipe.mp4 會執行全部;md 會產生 referencias/receitas-ffmpeg.md
referencias/cor-fluxo.md訊號順序、對比度、曲線、飽和度、16 位元精度
referencias/niveis-e-escopos.mdBT.709、EBU R103 v3.0、如何讀取每種示波器、指令稿如何測量
referencias/pele.md膚色線、色度範圍、症狀→原因→修正
referencias/hdr-hlg.mdiPhone HLG 轉 SDR、BT.2408 層級、基於測量的轉換鏈
referencias/corte.mdMurch(六法則、閃爍)、動作剪輯、J/L Cut、音訊銜接、同步
referencias/plataformas.mdMeta 與 TikTok:格式、安全區域、持續時間、官方規範與非官方建議
referencias/receitas-ffmpeg.md按類別(輸入、診斷、色彩、調色、剪輯、圖層、運動、後製、音訊、輸出)分組的 38 個配方

工作目錄:每個專案一個資料夾(例如:editar-video/<專案>/<片段>/):原始素材、計劃、預覽、圖表和最終輸出都放在一起。

在以下命令中,~/.claude/skills/editar-video 是技能安裝的路徑。如果安裝在其他位置,請自行調整。


步驟 0 — 輸入(無檢查點)

python ~/.claude/skills/editar-video/scripts/receitas.py mostrar R01   # 然後對檔案執行

在開始任何操作之前,根據 ffprobe 的數值來決定:

  • color_transfer=arib-std-b67 (HLG) 或 smpte2084 (PQ) → 先轉換為 SDR(referencias/hdr-hlg.md,R03)。切勿僅更改標籤。
  • r_frame_rate ≠ avg_frame_rate → 可變幀率:在剪輯前先執行 R02(Meta 要求固定幀率,請參考 Ads Guide)。
  • color_range=pc → 在轉換前(R04)先確認內容是否真的是 0–255。signalstats 會忽略範圍標籤。
  • AI 生成檔案、螢幕錄影:通常沒有標籤或屬於全範圍。在假設之前先進行測量。

步驟 1 — 基於測量的診斷(檢查點 1)

python ~/.claude/skills/editar-video/scripts/escopos.py bruto.mp4 -o diag            # SDR
python ~/.claude/skills/editar-video/scripts/escopos.py bruto.mp4 -o diag --sdr      # HLG:在色調映射後測量
python ~/.claude/skills/editar-video/scripts/escopos.py bruto.mp4 --pele 0.35,0.15,0.3,0.25   # 臉部區域

透過 VER → AMPLIAR → CONFIRMAR 的方法來閱讀圖表:先看影格,然後看每種示波器,最後看數值。展示:

  1. 圖表(folha_escopos.png)和每個場景的數值表;
  2. 經過測量的事實,每行一個,附帶規則與出處:「場景 2:高亮 R 98.6 / G 90.0 / B 80.2 → 高亮區域暖色調主導,如果牆壁是白色(Adobe,RGB 並列)」;
  3. 我無法透過測量得知的內容(例如:暖色調是否為刻意為之)。

自動膚色遮罩(Chai & Ngan)會偵測木紋、米色和橘色。如果臉部很小或有相同顏色的物體,請使用 --pele 參數指定臉部區域。

**檢查點 1:**提出要求的人需確認哪些是問題,哪些是意圖。我不會修正對方刻意保留的色調主導。

步驟 2 — 校正計劃與預覽(檢查點 2)

編寫 plano.json(格式請見 graduar.py 頂部)。每個操作都必須在 "porque" 欄位中說明測量原因。固定順序:符合規範 → 全域 → 場景(匹配) → 調色 → 後製 → 合法化(referencias/cor-fluxo.md,第 1 節)。

  • **正規化:**根據 baixas_RGB / altas_RGB 調整每個通道的黑/白點(niveis)。
  • **平衡:**先調整色溫,再調整綠色/洋紅色(temperatura,balanco)。
  • **場景匹配:**選擇參考場景(最開放或最接近所需調色的場景,Colorist Guide 20,第 2 課),然後將其他場景的平均 Y 值、高亮 RGB 和膚色調整至接近參考。
  • **調色:**僅在場景匹配後進行。風格化飽和度、創意 LUT。調色是品味問題:我提出建議,由對方決定。
python ~/.claude/skills/editar-video/scripts/graduar.py plano.json --mostrar   # 顯示濾鏡鏈
python ~/.claude/skills/editar-video/scripts/graduar.py plano.json --previa    # 每個場景中點的修正前後對比

**檢查點 2:**批准預覽。調整需包含場景與程度(「場景 3 減少暖色調,一半」)。我只修改被要求的內容。

步驟 3 — 渲染與基於測量的比較(檢查點 3)

python ~/.claude/skills/editar-video/scripts/graduar.py plano.json
python ~/.claude/skills/editar-video/scripts/comparar.py bruto.mp4 corrigido.mp4 -o comparacao --zoom-vs 2

交付 folha_antes_depois.png 圖片 + comparacao.md 檔案(修正前的數值 → 修正後的數值、已解決和新增的警告、場景間振幅)。如果出現新的警告,我會在展示前修正。

**檢查點 3:**提出要求的人觀看並批准修正後的影片。

步驟 4 — 剪輯、圖層、文字、運動(如有要求)

  • **剪輯:**JSON 格式的片段清單 → montar.py(硬切、J、L)。規則與出處請參考 referencias/corte.md。我會測量鏡頭長度和每分鐘剪輯次數;節奏由對方判斷。
  • **文字、字幕、標誌:**R50–R52,必須始終位於平台的安全區域內(referencias/plataformas.md)。文字來自封閉清單。字幕需配合講話內容,閱讀時間為每 3 個字 1 秒鐘,再加上 1 秒。
  • **影片上的運動效果:**帶有緩動的縮放/平移(R60)、穩定(R61)、速度(R62)。
  • 從零開始的 Motion Graphics(動態字體、動畫數字):使用 /motion 技能,並將影片以影格序列形式輸入。
  • 順序:圖形和字幕應在色彩校正和 HDR→SDR 轉換之後加入(ITU-R BT.2408-9 §9)。

步驟 5 — 審查與交付

在展示之前進行檢查清單:

  1. comparar.py 最終沒有出現層級/gamut 警告;使用 ffprobe 確認 BT.709 標籤。
  2. 解析度、固定幀率、持續時間、影格數,開頭/結尾無黑幀。
  3. 文字位於安全區域內;字幕與講話內容匹配。
  4. 已測量響度(R80)並告知。-14 LUFS 的目標值 [無官方出處];如果對方同意,我就使用。
  5. 編碼:R90(H.264,yuv420p,BT.709,+faststart)。
  6. 如果是 TikTok TopView 廣告(plataformas.md),前 3 秒無強烈閃光或純白畫面。
  7. 要求提出要求的人在手機上觀看:檢查節奏、感覺和膚色。

已批准的調色若需重複使用 → gerar_lut.py --plano plano.json -o <專案>_look.cube 和 --conferir 進行驗證。

程式碼規則(使用 ffmpeg 8.1.2 測量,2026 年 5 月 11 日)

  1. 色彩濾鏡必須在 format=gbrp16le 之後套用。8 位元格式來回轉換會損失平均 Y 值 1.1 碼;16 位元格式則能精確保留。
  2. 不要在 10 位元/HLG 流程中使用 eq:它會強制轉為 8 位元。
  3. 濾鏡中的路徑:file='/pasta/arquivo.cube'(使用單引號;路徑中包含 : 或空格時需要使用 \ 進行跳脫)。
  4. 輸出標籤:-colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv(並在 graduar.py 的濾鏡鏈結尾加上 setparams)。
  5. 僅在最後執行合法化(EBU R103 v3.0)。limiter 無法修正 RGB gamut;RGB16 階段會自行裁切。
  6. 重新編碼時,-ss 放在 -i 之前 = 精確裁剪;使用 -c copy 時,裁剪會落在關鍵影格上。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能