透過 FCPXML 編輯 Final Cut Pro
在動手之前
在進行任何 edit 動作之前，務必先執行 inspect 再執行 diagnose。時間軸的結構從檔名中無法看出，基於錯誤假設進行的編輯很難復原。
- 使用
inspect的analyze_timeline動作來了解時間軸的形狀、時長與解析度。 - 使用
diagnose的validate_timeline動作來檢查間隙、閃爍幀與重複片段。 - 實際「看到」時間軸後再進行任何修改：讀取
preview://<path>資源。它會產生一個自包含的 HTML 時間軸，包含各自車道上的連接片段，讓你能看到 B-roll 和音訊層，而不只是主要故事線。
七個群組
| 群組 | 用途 |
|---|---|
inspect | 唯讀式理解。總是從這裡開始。 |
diagnose | 發現問題：間隙、閃爍幀、靜音、重複片段、節拍。 |
edit | 變更片段：插入、刪除、修剪、分割、重新排序、重定時、移除靜音。 |
mark | 標記與章節，包括 SRT/VTT 和節拍匯入。 |
generate | 建立新結構：粗剪、蒙太奇、A/B 卷、模板，以及從影片使用剪輯清單匯入 import_edl_json。 |
transcript | 本機轉錄，然後根據「說了什麼」進行編輯或清理。transcript_pack 將所有拍攝內容放在一個頁面上 — 在規劃對話編輯之前先閱讀它。每個動作都接受 backend: "elevenlabs" 來啟用語者標籤和音訊事件；這會將媒體上傳到 ElevenLabs，需要 ELEVENLABS_API_KEY — 預設的 local 則不會離開本機。 |
deliver | 匯出到其他 NLE、重新格式化、重新連結、推送到 FCP。 |
preview | 「看到」編輯效果：代理轉譯、聯絡表，以及從來源媒體讀取的底片+波形圖。 |
watch | 關閉循環：注意操作者的 Cmd-E 匯出，並與上一次的匯出差異比較。 |
index | 分析快取。index_status 顯示其產生的時間；index_build 預先處理時間軸中的所有來源；index_clear 清除快取。沒有任何東西依賴它。 |
scenes | 從像素偵測鏡頭邊界。detect_scenes 列出片段在來源和時間軸時間的剪輯點（當透過 [scenes] 安裝時使用 PySceneDetect，否則使用 ffmpeg 較粗略的場景濾鏡）；scenes_to_markers 在每個剪輯點放置標記；scenes_split 在該處分割片段。結果會快取在索引中。 |
organize | 大量媒體庫記錄與分類帳。organize_auto 從快取的標題和逐字稿為每個片段建議關鍵字（apply=true 會寫入它們）。透過 clip_name 萬用字元、keyword 及/或 role 選擇片段，然後使用 organize_keywords（新增/移除/取代）、organize_rate（喜好/拒絕/清除）或 organize_roles — 每個動作都會寫入一份 _organized 副本。history 列出檔案資料夾中所有記錄的操作；undo 將最後 n 個輸出移動到日誌的 undone/ 資料夾（絕不刪除，如果檔案自那之後已變更則拒絕執行）。 |
find | 「哪個部分是…」的路由器。find_shots 根據說了什麼（逐字稿）、記錄了什麼（名稱、關鍵字、筆記、標記、音訊事件），以及（在使用 [find] 擴充並下載本機模型的情況下）影格內容來對時刻進行排名 — 第一行說明哪些層級回應以及哪些層級無法回應的原因。find_index 預先處理場景和標題，並報告哪些片段沒有逐字稿（絕不轉錄，絕不上線）。find_to_timeline 將結果組合成一個 _found 精選序列，並附有多樣性評分。 |
每個呼叫都採用 {"action": "...", "args": {...}} 格式。如果你傳遞的動作不屬於該群組，錯誤訊息會列出有效的動作 — 請閱讀該訊息，而不是猜測。
會讓你吃虧的 FCPXML 事實
- 時間是有理數，絕非浮點數。
3600/2400s就是 1.5 秒。絕不要對時間碼進行浮點數運算，也不要自己進行四捨五入。 offset是時間軸位置。start是來源入點。 它們是不同的數字，混淆它們會悄悄地偏移編輯。- 媒體庫片段和時間軸片段是不同的元素。
<asset-clip>存在於媒體庫中，<clip>存在於時間軸上。 - 標記是片段的子元素，而不是同層級元素。
<spine>是主要故事線。 連接片段透過車道掛在主要故事線片段上：正數在上方（影片），負數在下方（音訊）。.fcpxmld套件是目錄，包含Info.fcpxml及附帶資料。儲存時必須保留附帶資料，否則物件追蹤和電影級資料將會遺失。- 片段名稱重複很常見。 在工具同時提供兩種方式時，優先使用基於元素的操作而非名稱查詢。
移除靜音：選擇正確的方法
有兩個偵測然後修正的配對，它們不能互換。兩者都遵循此伺服器中其他偵測/修正配對的相同分割原則：偵測器位於 diagnose，修正器位於 edit。
detect_media_silence(diagnose) →remove_media_silence(edit) 使用 ffmpeg 讀取實際來源音訊。準確、較慢，需要安裝 ffmpeg。detect_silence_candidates(diagnose) →remove_silence_candidates(edit) 僅使用時間軸啟發式演算法。快速、不需要 ffmpeg，但它是推測的。
在正確性至關重要的情況下使用媒體版本。請說明你使用了哪一種。
通常較佳的工作順序
inspect→diagnose→ 讀取preview://資源。- 如果編輯是以對話為主，使用
transcript的transcript_pack動作 — 所有對話集中在一個頁面，這樣可以根據實際的用詞而非片段名稱來制定計畫。 - 使用
generate進行組合，edit進行精修，mark加入章節。 - 在你認為編輯完成之前，對你修改過的範圍使用
preview的preview_check動作。這一步能使編輯不再盲目。preview://資源和preview_timeline都是從 XML 繪製的 — 它們顯示的是「寫入」的內容，因此無法分辨一個修正過的剪輯點和一個有問題的剪輯點。preview_check則會讀取媒體。不要將兩者混用，也不要因為工具呼叫回報成功就跳過這一步。 deliver，可以是匯出或是push_to_fcp推送到正在執行的應用程式。- 每會話一次使用
watch的watch_start動作，然後在操作者匯出後使用watch_pull。Final Cut Pro 沒有程式化匯出功能 — Apple 從未提供過 — 因此只有在操作者按下 Cmd-E 時，這個循環才會關閉。請清楚地說明這一點，而不是默默地等待。
請勿
- 請勿在未進行診斷檢查的情況下進行編輯。閃爍幀和間隙會不斷累積。
- 請勿假設 ffmpeg 或 Whisper 已安裝。兩者都會優雅地降級，並回傳空結果而不是錯誤，因此請檢查回應。
- 請勿閱讀
preview_render摘要中「UNVERIFIED」之後的內容。這表示無法讀回轉譯檔案的時長，因此無法確認該轉譯的任何內容。 - 請勿忽略「Substituted:」行。代理轉譯會將轉場顯示為硬剪輯，因此你在時間軸中看到的 dissolve 並不是你正在查看的內容。
- 除非已呼叫
push_to_fcp並回報成功，否則請勿聲稱編輯已進入 Final Cut Pro。寫入 .fcpxml 檔案並不等同於匯入它。 - 請勿僅憑工具自身的成功訊息就相信時間軸看起來正確。請讀取
preview://並查看。