ONIKOSIOLA/video-editing-kit

Premiere Clean Edit

將一個或多個原始影片檔案轉換為完成、可匯出的影片： 修剪空白時間和填充詞、校正顏色、添加內嵌字幕， 並匯出橫向和直向版本 — 全部通過 premiere-pro MCP 工具 驅動 Adobe Premiere Pro，並讓 claude-video-vision 完成 Premiere 本身無法在無頭模式下進行的音訊分析。

Premiere Pro 必須在電腦上已開啟，且 premiere-pro MCP 伺服器已連線，並啟動了 MCP Bridge (CEP) 面板（視窗 → 擴充功能） — 此技能無法啟動應用程式。如果伺服器未安裝，請執行此套件的 setup 技能。 如果 create_sequence 等工具未直接列出，表示伺服器將它們隱藏在 search_tools / invoke_tool 後面：請使用那些方法，或使用 PREMIERE_MCP_TOOLSET=full 重新註冊伺服器。如果任何 mcp__premiere-pro__* 工具呼叫因連線錯誤而失敗，請告知使用者開啟 Premiere Pro 並重試， 而非繞過此問題。

為何需要兩個 MCP，而非一個

premiere-pro 可以剪輯、調色和匯出 — 但它無法決定在哪裡 剪輯。該伺服器中沒有靜音偵測或轉錄工具。 claude-video-vision 的 video_analyze 填補了這個缺口： 它在原始檔案進入 Premiere 之前，對其執行 ffmpeg 靜音偵測 和本機 whisper 轉錄（含逐字時間戳記）。剪輯列表會以純資料格式 一次性計算完成，然後作為一系列 MCP 呼叫執行。不要試圖透過 拖曳 Premiere 時間軸來目測剪輯點 — 你沒有影格級別的聲音判斷力， 分析程序才有。

兩種編輯類型 — 開始前先選擇

• 對話驅動型（人物講話、螢幕錄影、旁白）：按照下面的流程走 — 主要工作是修剪靜音/填充詞和字幕。
• 蒙太奇 / B-roll（房間導覽、步行錄影、旅行素材 — 無對話驅動 剪輯）：跳過靜音/填充詞步驟，依照後面的蒙太奇流程。字幕可選； 音樂和節奏是主要工作。

兩種類型最後都套用下面的 House Style。如果不確定是哪種類型： 如果音訊不承載故事，那就是蒙太奇。

House style（預設社群媒體外觀）

這些預設值是透過比較自動組裝與手動完成的最終剪輯得出的。 忽略這些預設值的初次剪輯通常會被手動重做。如果使用者有自己的風格 或喜歡的參考影片，她的喜好優先：詢問她，並調整這些規則以符合。

• 以最強的品牌/建立鏡頭作為開場和結尾 — 像標題卡一樣以此開場， 並以此結尾。故事順序優先於時間順序；品牌標誌或英雄鏡頭 優於「最先發生的片段」。
• 果斷剪輯。 每個場景一個節拍，每個約 3–6 秒，只保留最佳時刻 — 絕不保留完整片段。一個好的參考剪輯從 80 秒可用素材中保留了 46 秒。 社群媒體交付物的目標總長度約為 45–60 秒。
• 完全刪除弱素材 — 搖晃的手持進場、笨拙的開頭。 如果一個片段需要道歉，那它就不該出現在最終剪輯中。
• 交替使用廣角鏡與細節特寫 — 房間廣角 → 爐灶旋鈕， 臥室廣角 → 床頭板紋理。在建立鏡頭之間插入細節。
• 場景之間使用交叉溶解，而非硬切。 僅在刻意強調時使用硬切 （一個好的參考剪輯可能只有一兩次）。
• 蒙太奇的音訊以音樂為主。 連續的音樂背景（約 -11 LUFS），無靜音； 移除或完全壓低原始相機/環境音訊，而非僅是閃避。如果未提供音樂軌， 請要求一個或保留靜音時間軸並標記 — 絕對不要輸出原始的環境音訊。
• 優先交付直向影片： 主要交付物為 1080×1920，30fps，H.264 ~12 Mbps， 即使來源是 4K60。橫向版本是選項，而非主要方向。

對於 故事時間/UGC 片段（具有對話的真實時刻 — 邂逅、反應、 即興互動），在上述規則之上增加四條規則：

• 以爆紅片段作為冷開場。 將對話中間最引人注目的 2–4 秒 特寫鏡頭放在 0:00 處，然後倒回從頭開始講故事。按時間順序 是此處的基本失敗模式 — 絕不以設定/背景作為開場。
• 為旁白鉤子留出空間。 創作者通常會在冷開場之上錄製一段 直接對鏡頭說話的旁白（「我知道你們可能想知道為什麼…」）。 編輯無法生成這個 — 建立冷開場，然後標記需要錄製鉤子旁白 （或要求它），而不是在沒有旁白的情況下輸出。
• 以品牌卡片結束。 如果使用者有要推廣的品牌、產品或帳號，請以 一個簡短的結束卡片（約 3–5 秒）包含它來結尾。詢問她的標誌或 帳號；絕不要自行創作一個。
• 調節對話音量（約 -16 LUFS，窄範圍）而非鋪設音樂背景 — 對於故事時間，對話主導；對於蒙太奇，音樂主導。

流程

按順序執行這些步驟。對於一批片段（例如一週的錄音）， 在一個共用的 Premiere 專案內對每個片段重複步驟 2–8。

1. 確認輸入

詢問（或從上下文推斷）：原始檔案路徑，以及這是要產出單一交付物 還是需要同時匯出橫向（LinkedIn 風格，16:9）和直向 （Threads/TikTok/Reels，9:16）版本。如果使用者沒有指定， 預設為匯出兩者 — 編輯鎖定後重新構圖的成本很低。

2. 使用 ffprobe 取得來源資訊

ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "<raw-file>"

你需要 width、height、r_frame_rate（解析分數，例如 30000/1001 ≈ 29.97）、 以及 duration。你在 Premiere 中建立的序列應與這些匹配 — 序列設定不匹配會導致無聲的縮放/影格率轉換，進而降低品質。

3. 分析音訊 — 靜音 + 轉錄

對原始檔案呼叫 mcp__claude-video-vision__video_analyze，使用 filters: {silence: true, transcription: true}。這會回傳靜音區間 和逐字轉錄（whisper 透過 whisper.cpp 在本機執行 — 無需 API 金鑰， 首次執行可能需要一分鐘來載入模型）。

將結果儲存為 JSON 檔案 — 你將在下個步驟將其餵給剪輯列表腳本。

4. 計算剪輯列表

在分析 JSON 上執行 scripts/build_cutlist.py：

python3 "<skill-path>/scripts/build_cutlist.py" analysis.json \
  --duration <ffprobe-duration> --srt-out captions.srt

這個腳本存在是因為手動正確處理這個問題有一個特定的錯誤點： 每次剪輯後的字幕時間戳記都必須根據之前移除的所有內容的累積持續時間 進行偏移，否則字幕會不同步。該腳本處理了這個問題，以及靜音間隙的 合併/填充邏輯，確保剪輯不會落在字詞中間。

它會自動修剪三種內容：≥0.35 秒的靜音間隙（填充 0.08 秒，以免剪到語音）、 硬填充詞（um、uh、er 及其變體）、以及口吃/虛假開頭（即時重複的字詞， 如「the the」）。它刻意不自動修剪軟填充詞（like、so、right、you know、 actually）— 這些通常是一個人真實的說話方式，而非噪音。來自過去 UGC 編輯的 真實回饋：一個即興詞如「you know what I'm saying?」被標記為該批次中最真實的 部分，並被明確保留，而非修剪。該腳本會在 flagged_for_review 中顯示這些內容 並附帶上下文 — 粗略瀏覽該列表，僅在看起來確實像填充詞而非個人嗓音/風格時 才升級給使用者處理；如有疑慮，就保留它。

5. 建立 Premiere 專案和粗剪

1. create_project（或重複使用時用 open_project）和 create_sequence 使用與 ffprobe 輸出相符的設定（步驟 2）。
2. import_media 原始檔案，add_to_timeline 在時間 0 的軌道 0 上。
3. 按照 start 時間降序 走訪剪輯列表的 cuts 陣列，並對每個： 在剪輯的開始和結束處使用 razor_timeline_at_time，然後對產生的 中間片段使用 remove_from_timeline，deleteMode: "ripple"。 降序順序很重要 — 漣波刪除較早的剪輯會使後面的每個時間戳記偏移， 所以如果你向前執行，步驟 4 中剩餘的剪輯點將不再對齊任何東西。
4. 確認序列時長現在大致符合剪輯列表 JSON 中的 new_duration。

6. 調色

預設外觀（使用者要求乾淨/自然，而非風格化調色）：修正白平衡、 壓低高光、稍微提昇陰影、適度飽和度。你無法盲目執行此操作 — color_correct 的參數是手動滑桿，背後沒有自動偵測功能。所以：

1. export_frame 一個代表性影格（進入片段幾秒後，越過任何開場）。
2. 檢視它。判斷白平衡（膚色不應偏橘或偏藍）、曝光（是否有任何部分 過曝或死黑）和對比度。
3. 在時間軸片段上套用適度的 color_correct 調整 — 微調（個位數值）， 而非劇烈變化。自然的校正應該幾乎不被察覺是「校正」， 只是感覺「這樣看起來是對的」。
4. 再次 export_frame 並比較。如果仍有問題，迭代一兩次； 不要為了追求單一影格的完美而無限循環。

如果使用者有想要套用的 .cube/.3dl LUT，以取代或附加在手動校正之上， 請使用 apply_lut，並配合低到中等 intensity（0.5–0.8）套用在基本校正 之上，而非取代它 — 僅靠 LUT 無法修正實際的白平衡問題，它只會重新著色。

7. 字幕

1. import_media 步驟 4 中寫入的 captions.srt。
2. 在序列上 create_caption_track，將 projectItemId 指向匯入的 SRT。

這之所以有效，是因為步驟 4 已經將 SRT 重新定時到剪輯後的時間軸 — 如果你在此處從原始（剪輯前）轉錄時間戳記重新生成字幕， 它們將會與編輯後的影片不同步。

8. 為第二個長寬比重新構圖

重新構圖會向內裁剪現有影格，使用動態追蹤 — 從較寬到較窄 （16:9 → 9:16）效果很好，但沒有真正的影格資料可以從較窄到較寬 （9:16 → 16:9 需要 Premiere 自動重新構圖無法做到的生成式擴展）。 所以：

• 橫向拍攝 → 為直向匯出使用 auto_reframe_sequence，參數為 numerator: 9, denominator: 16。這是常見情況，效果很好。
• 直向拍攝 → 如果確實需要橫向版本，請告知使用者，而不是默默地在 兩側添加邊框或模糊；通常重新拍攝或使用信箱式/柱箱式匯出 是比糟糕的 AI 重新構圖更好的選擇。

9. 匯出

最終社群媒體交付物為 H.264 1080p，而非 ProRes — 這是最終匯出， 而非 Premiere 到 Premiere 的交接。為每個版本 export_sequence：

• 橫向：format: "h264"（或 "mp4"），resolution 匹配來源， quality: "high"。
• 直向（來自重新構圖的序列）：相同設定，1080×1920。

當使用者未指定路徑時的輸出慣例：在原始來源檔案旁建立一個 edited/ 資料夾，並將輸出命名為 <source-name>-final.mp4（橫向）和 <source-name>-vertical.mp4。完成前 save_project。

10. 回報

告訴使用者：修剪了什麼（按原因計數 — 靜音/填充詞/口吃）、 你保留在 flagged_for_review 中的任何內容及其原因、調色改變了什麼、 以及匯出的檔案位於何處。不要只說「完成」— 這是屬於他們的素材； 他們應該知道哪些內容被動過。

蒙太奇流程（無對話素材）

1. 在每個來源片段進入時間軸之前觀看它們 — 以至少 1fps 的速度 video_watch。不要從檔案名稱、縮圖或 先前的資料夾摘要推斷內容：一個「僅房間」的片段可能以 人物出現在鏡子中結尾（這真的發生過 — 兩個浴室片段在最後幾秒 之前都是乾淨的）。觀看時，記錄每個片段的最佳 3–6 秒節拍 和精確的修剪點。
2. 對所有片段執行 ffprobe（流程步驟 2）。建立序列以匹配 來源 fps — 60fps 的片段需要 60fps 的序列。序列設定在建立後 無法更改（請參閱 MCP 錯誤），所以首先就要設定正確。
3. 按照 House Style 的故事順序 組裝：品牌鏡頭 → 廣角鏡頭與 細節交替 → 英雄視角鏡頭 → 再次品牌鏡頭。
4. 將每個片段修剪到所記錄的節拍：將完整片段添加到其位置， 在保留邊界處使用 razor，漣波刪除其餘部分 — 傳遞同時 videoTrackIndices 和 audioTrackIndices，然後使用 list_sequence_tracks 確認影片和音訊軌道長度仍然匹配。 孤立音訊尾部會默默地導致其後所有內容不同步。
5. 在每個場景邊界添加交叉溶解（add_transition_to_clip）。
6. 根據 House Style 添加音樂背景；關閉相機音訊。
7. 優先匯出直向（1080×1920，30fps，h264，高品質）。僅在被要求時 才製作橫向版本。

已知的 premiere-pro MCP 錯誤（2026 年 8 月驗證）

• trim_clip 靜默無操作 — 回傳成功，但無任何改變（無論是否 附帶 duration）。絕不要使用它；改用 razor + 漣波刪除。
• export_frame 忽略 time — 無論你要求哪個時間碼，它總是 回傳序列的第一個影格。對於檢查特定時刻或對序列中間的片段 進行調色無用；改用 claude-video-vision 從來源檔案獲取影格。 它還會附加自己的副檔名（x.png → x.png.png），所以請傳遞 不含副檔名的 outputPath。
• 僅使用 videoTrackIndices 的 razor_timeline_at_time 仍然會 剪輯所有音訊軌道 — 並且僅影片的漣波刪除會留下孤立音訊。 總是明確傳遞 audioTrackIndices 並在之後驗證同步。
• set_sequence_settings 無法在建立後更改 fps/尺寸 — 建立一個 具有正確設定的新序列並刪除舊的。
• MCP 呼叫可能超時但仍然成功（create_sequence 發生過）。 在超時時，在重試之前檢查 get_project_info/list_sequences — 盲目重試會建立重複項。
• export_sequence 可能回報成功但未寫入任何內容 — 已確認兩次 （無論在 outputPath 中是否含副檔名）；它也會在成功回顯時顯示 format: "Pro... （此處可繼續）。