mk-video-editing

mk-video-editing 是做什麼的？

將提供的素材剪輯成可觀看且風格一致的成品：正確的詞語按正確的順序排列，能良好構圖拍攝主體的攝影機，一致的畫面，乾淨且音量均衡的聲音，以及雅緻的標題。結構來自於素材本身以及其中的對話內容。

此技能的功能

需求	工具	成本	參考文件
逐字稿、填充詞/假開頭/停頓檢測	edit:transcribe (mlx-whisper), speech:flow	免費，本地端	footage-editing.md
穩定影像、追蹤演講者、重構4K寬景（推近、推進、平移）、HDR→SDR、去閃爍、色彩匹配、溶解、跳接剪輯	edit:analyze, edit:track, EDL + medit (edit:render)	免費，本地端	footage-editing.md
對話清理、混音、閃避、響度	speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure	免費，本地端	footage-editing.md
旁白	voice:tts (透過Fal的ElevenLabs)	付費，已核准	credentials.md
標題、下三分之一、結尾卡（ProRes 4444 Alpha）	mgraphics JSON場景, graphics:render, scripts/tools/graphics/examples/ 中的範本	免費，本地端	graphics README
背景音樂	EDL music (已閃避), music:score (透過Fal的ElevenLabs Music), audio:analyze 用於節拍對齊	僅產生時付費	finishing.md
標題/轉場音效	SoundSynth (synth: 颼颼聲、上升音、撞擊音、滴答聲…), sfx:gen/sfx:mix 或 EDL sounds	免費（Stable Audio prompt: 付費）	finishing.md
畫面特效（閃爍、淡入/出、衝擊、發光、鏡頭、條紋…）	mvfx 提示表, vfx:stills/vfx:render	免費，本地端	finishing.md
交付編碼	media:twitter, media:youtube, media:faststart	免費，本地端	tasks.md
獨立工作的平行子代理	work:next/work:accept/work:log/work:watch	免費	tasks.md

每個任務及其引數和選項皆在 tasks.md 中。測試設定檔在 testing.md。

執行契約

為 macOS 14+ 上的 Claude Code 設計，需使用 Apple Silicon（Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, uv 用於本地 Whisper）。當任務因缺少工具而失敗時，請先執行 doctor；setup 會建置 Swift 工具。Ruby 是唯一的執行進入層：執行 ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'task[args]'。任務會委派給驅動原生 Swift 工具 medit (scripts/tools/edit)、mgraphics (scripts/tools/graphics) 和 mvfx (scripts/tools/vfx) 的 Ruby 服務（lib/media/edit.rb、speech.rb、guard.rb，…）。當缺少某項功能時，請新增一個 Ruby 方法和一個輕量任務。一個專案會執行其自己的 lib/ 和 tools/ 副本：修改技能後，將變更的檔案 rsync 到專案中。

記憶體安全（強制）

4K/HDR 硬體解碼會將影格保留在 VTDecoderXPCService 中，位於作業本身的記憶體空間之外。在沒有交換檔案的 16 GB 機器上，耗盡記憶體會凍結電腦，而不是變慢。因此：

• 一次只執行一個重量級任務（medit analyze/render/stills, mgraphics encodes, Demucs, 大型 ffmpeg encodes）。切勿同時平行或在背景執行數個任務；如有需要，在一個背景命令中依序串連它們。除非 RAM ≥ 32 GB，否則 JOBS 保持為 1。
• 每個 medit/mgraphics/mvfx 渲染呼叫都會經過 Media::Guard（在 Ruby 服務中自動執行）：它每 0.3 秒取樣一次作業 + 解碼器記憶體使用量和核心可用百分比，並在超過 MEDIT_MAX_FOOTPRINT_MB（預設 3500）或低於 MEDIT_MIN_FREE_PCT（預設 30）時發送 SIGKILL。當可用記憶體已經很低時，它會拒絕啟動。所有三個渲染器預設 JOBS=1；平行區塊需要明確設定 JOBS。
• 對於任何新的解碼/渲染程式碼路徑，請先在短範圍且設定嚴格限制的情況下進行驗證（TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/path/log），檢查日誌是否平穩，然後再執行完整長度。
• 在 Swift 媒體迴圈中，將每個 copyNextSampleBuffer 和 Core Image 渲染包裹在 autoreleasepool 中（非同步程式碼永遠不會排空預設池：影格會以約 1.5 GB/s 的速度洩漏）。

測量穩定狀態：每個 4K HLG 來源的分析 ≈ 1.0 GB（作業 + 解碼器）；包含溶解的渲染會開啟兩個來源。

1. 初始導入

只詢問缺少的資訊：素材路徑、剪輯類型（演講片段、回顧…）、標題/工作人員文字、目標長度、旁白需求。使用媒體進行初始化（符號連結，絕不複製或修改）：

ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/project --media /abs/clip1.MOV --media /abs/clip2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project setup

探測每個來源（ffprobe：尺寸、fps、時長、HDR 傳輸）。提取音訊（audio/raw/*.wav，48 kHz）並在本地端進行轉錄：edit:transcribe[analysis/transcripts,source/...]（mlx-whisper large-v3-turbo，含字詞時間；免費）。閱讀每個轉錄稿，並將每個片段所說的內容及其時間戳記寫入 docs/BRIEF.md。透過網路搜尋用於標題的事件事實並記錄來源。

2. 分析（依序執行）

REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[source/A.MOV,analysis/A.json]'   # 一次一個
mv 'edit:track[analysis/A.json,analysis/A.track.json]'      # 當過早找不到演講者時使用 SEED=x,y；SPACE=frame 用於穩定：0
mv 'edit:stats[analysis/A.json,from,to]'

• REGION 將穩定化（相位相關）限制於靜態場景（舞台、螢幕），排除觀眾。
• DETECT_REGION 將舞台區域裁切以進行 Vision 人物檢測，解析度約提升 2 倍——這對遠距離的演講者至關重要（檢測率從 2% 提高到 40–90% 的取樣）。
• 軌跡是「世界鎖定」的（已移除穩定化）、連續性選取，並透過 max_aspect 丟棄寬廣的前景盒子（頭部）。
• 手機素材（iPhone 等）在相機中已進行穩定化：使用 stabilize: 0 和 SPACE=frame 軌跡來渲染。 我們的穩定器可能會將移動中的投影片內容誤認為相機運動，並加入突然的水平跳動。檢查：計算分析中 |Δshift| > 8 px 的影格數；iPhone 4K 上殘留的抖動測量約為 0.9 px RMS，不值得校正。

語音流暢度（填充詞、假開頭、重複、不自然的停頓）

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # 提示 Whisper 寫出 um/uh
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # 閱讀 analysis/flow/A.txt

檢測器會以聲學方式（能量 + 發聲，非 Whisper 字詞時間）測量停頓，對其進行分類（句子/逗號/短語），並標記填充詞、未轉錄的哼聲、重複和可能的假開頭，每個都附有建議的 cut。根據意義對每個項目做出決定，然後在生成器中使用 Media::Cuts 應用剪輯（步驟 4）。透過閱讀 .txt 檔案來查找自我修正和未完成的句子（"in order to be—"，在掌聲前未完成的最後一句話）；檢測器僅提出候選項目。

• 全影格的色彩統計資料通常受投影螢幕主導；請匹配演講者區域（軌跡周圍的區塊）的曝光度，並在靜止畫面上判斷白平衡。

3. 計畫與批准

撰寫 docs/PLAN.md：選取表格（來源、以句子邊界為進/出點、內容、連接方式：溶解/跳接）、標題、旁白文字、運鏡語言、畫面與音訊處理方式。在對話中總結；使用 NOTE='...' plan:approve 記錄批准（在付費呼叫前也需要，例如透過 voice:tts 的 ElevenLabs 旁白；請參閱 credentials.md — 在插件工作階段中，付費任務會透過 mk-video-editing MCP 伺服器執行）。

4. 使用生成器腳本建置 EDL

撰寫 edit/build_edl.rb（完整的 EDL 架構和實際範例請參閱 footage-editing.md）。定義一個鏡位詞彙表（WIDE 縮放≈1.2–1.4，MWIDE 適應≈0.4，MED 適應≈0.56，PUNCH 適應≈0.72，上限由 max_zoom 3.6 設定），並以來源秒數（取自轉錄稿）撰寫運鏡節拍：6–12 秒的慢速推近、在強調台詞處的剪接推進、在主題/投影片變化時剪接到寬景、在每個跳接時重新構圖。每個片段：safe 區域（排除干擾前景）、deflicker、grade 匹配；一個共用的 look。覆疊圖層是 ProRes 4444 alpha 標題（請參閱下方的標題章節）。

使用 lib/media/cuts.rb 移除選取內部的詞語和停頓：Media::Cuts.pause_cuts（自動縮短不自然的停頓）、Media::Cuts.segments（將選取分割成跳接片段，將邊界對齊到詞語之間最安靜的點，以對比構圖開啟每個片段，保持每個縮放持續時間 ≥ 4.5 秒）、Media::Cuts.text（記錄每個剪輯移除的內容到 edit/cuts.txt）。在靜默中開始和結束每個選取，並遠離相機操作（檢查邊緣附近的移動速度）。footage-editing.md 中有實際範例。

5. 音訊

speech:clean[audio/raw/A.wav,audio/clean/A.wav]（PRESET=room：低頻切除、FFT 降噪、中頻切除、臨場感、去噝聲、溫和擴展器、電平器；ISOLATE=1 用於本地 Demucs 人聲分離）。當要求時，使用 voice:tts 添加旁白（MODEL=v4 用於 Eleven v4）。僅在簡報要求時添加背景音樂：提供的音軌或 music:score，作為 EDL music 放置（請參閱 finishing.md）。然後執行 speech:mix[edit/edl.json,audio/mix.wav]。它會混合片段音訊，在溶解處加入交叉淡入淡出（audio_xfade: 0.15 在 0.6 秒溶解前保留最後一個詞語）、旁白下的 audio_duck、sounds 以及帶側鏈閃避的 music，然後套用兩遍 loudnorm 規範化至 −16 LUFS / −1.5 dBTP。

6. 審查、渲染、交付

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...] — 每個靜止畫面加上包含裁切（紅色）、主體（綠色）和安全區域（黃色）的完整來源影格。檢查構圖、頭部空間、前景干擾、各剪輯間的曝光/白平衡連續性。
• edit:sheet 連絡表；edit:preview[edl,out.mp4,from,to] 半解析度的修改範圍草稿。
• edit:render[edit/edl.json,output/final.mp4]（JOBS=1）。切勿覆寫已交付的母版。
• 在渲染影片前進行 QA：speech:mix，然後對混合音軌執行 edit:transcribe，並閱讀每個片段 at 時間點前後的詞語（成本低；可捕捉到被剪斷的詞語和單字閃現）。渲染完成後，重新轉錄最終版本；將版本和問題記錄在 docs/REVIEW.md。

交付影片、計畫/簡報/審查文件，以及關於選擇和已知問題的簡短摘要。在變更工具組後執行 testing.md 中的 RSpec 設定檔，並在渲染器變更後於 tools/graphics 中執行 swift test。

標題

從 scripts/tools/graphics/examples/ 中的範本開始：opening_title.json、lower_third.json 和 end_card.json（1920×1080，AvenirNext，一種重點色）。將它們複製到 edit/titles/，更改文字和時間，或者當有多個標題時，從 edit/make_titles.rb 生成它們。透過網路檢查名稱、角色和事件事實。

1. 使用 ONLY= 在一個鏡頭的影格上（PLATE=）渲染靜止畫面，檢查易讀性、安全邊距和重點色。
2. 使用 CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,frames,1920,1080,fps] 以剪輯的 fps 進行渲染。
3. 將其作為 EDL overlays 項目放置，在開場卡下方使用攝影機 dim/blur 使底版變暗或模糊。

場景格式（節點、軌跡、緩動、發光、字型）在 graphics README 中。渲染器變更後，在 scripts/tools/graphics 中執行 swift test，並逐位元組比較新舊標題渲染結果。

後製（可選）

背景音樂、音效和畫面特效是可選的處理環節，在 finishing.md 中描述：

• 背景音樂在渲染前放入 speech:mix；
• SFX（sfx.yml）和 VFX（cues.yml）在渲染後的母版上執行，並始終寫入新檔案。

當簡報要求預告片或回顧片的感覺時使用它們。乾淨的談話剪輯很少需要這些。

平行作業

對於長時間的剪輯，將獨立的工作（標題、旁白台詞、各區段的審查靜止畫面、QA 轉錄稿）分割到 config/production.json 中，並設定它們的 depends。透過 work:next 將它們交給子代理，讓它們透過 work:log 回報，並在審查後接受每個工作（work:accept）。子代理可以平行編寫場景、腳本和文件。重量級媒體作業（medit, mgraphics/mvfx 編碼, Demucs）仍一次只執行一個（基於上述記憶體安全考量）。