capcut-cli — 剪映/CapCut 可編輯出片

capcut-edit

用於透過版本感知儲存庫編輯 CapCut / 剪映草稿的命令列工具。v0.11 能偵測並同步 draft_content.json、draft_info.json、draft_meta_info.json 和 template-2.tmp 中的可讀時間軸。

專案位置

• macOS：~/Movies/CapCut/User Data/Projects/com.lveditor.draft/<project>/
• Windows：%LOCALAPPDATA%\CapCut\User Data\Projects\com.lveditor.draft\<project>\

核心原則 — 確定性腳本

任何涉及超過一次 capcut 呼叫、任何運算或任何分支的配方，都以參數化 shell 腳本的形式放在 scripts/ 中。Claude 會用輸入參數呼叫腳本；腳本執行固定的指令序列。如果某個配方可以寫成腳本，它就必須是腳本 —— 而不是 references/ 中的敘述。

references/workflows.md 僅記錄要呼叫哪個腳本以及為何呼叫，絕不包含可重構的指令序列。

漸進式資訊揭露

從概覽開始，逐步深入你需要的細節。絕對不要傾倒完整的專案 JSON。

capcut info <project> -H           # 概覽
capcut doctor -H                   # 已安裝的媒體 / 轉錄能力
capcut diagnose <project> -H       # 標準檔案、差異、編輯器安全性
capcut tracks <project> -H         # 所有軌道
capcut materials <project> -H      # 素材摘要
capcut segments <project> -H       # 包含時間的片段
capcut segment <project> <id>      # 單一項目，完整細節

輸出模式

• JSON（預設）：管線傳送給 jq，提供給腳本使用。
• -H：人類可讀的表格。
• -q：靜默模式，僅回傳結束代碼 —— 用於腳本中的寫入指令。

批次寫入

echo '{"cmd":"set-text","id":"a1b2c3","text":"Fixed"}
{"cmd":"volume","id":"d4e5f6","volume":0.5}' | capcut batch <project>

操作：set-text、shift、shift-all、speed、volume、opacity、trim。

批次是交易性的：一個操作失敗就不會寫入任何內容。只有在使用者明確接受部分提交時，才使用 --continue-on-error；即便如此，它仍會以非零狀態結束。

查閱位置

• references/api-reference.md — 所有指令、所有旗標、所有值格式（時間、百分比、角度）、ID 前綴規則、.bak 不變量。
• ../../docs/command-reference.md — 生成的指令合約 v2，包含型別化的位置參數/選項、可變性、前置條件、輸出格式與結束代碼。
• references/workflows.md — 配方 = 應執行哪個 scripts/X.sh 及原因。
• references/pitfalls.md — 先關閉專案、.bak、音訊的 clip=null、搭配 speed 的 source_timerange 運算、alpha 關鍵影格不會渲染請改用 animation 素材等。
• 列舉探索 — 呼叫 capcut enums --<category>（或加上 -H 顯示表格）來列出所有 CapCut 代碼。類別：--transitions、--masks、--image-intros、--image-outros、--image-combos、--text-intros、--text-outros、--text-loop-anims、--scene-effects、--character-effects、--audio-effects、--fonts。加上 --jianying 可切換命名空間。enums.json 套件透過 python3 scripts/extract-enums.py 一次性生成；執行階段不需 Python。
• scripts/ — 客戶端函式庫。目前有：
  • anim.sh — 套用任意 9 種 CapCut 入場/出場動畫；fade-in.sh 和 fade-out.sh 是它的簡易封裝。
  • ken-burns.sh — 透過 capcut keyframe --batch 實現縮放 + 平移關鍵影格（運動屬性會渲染；alpha 不會 — 請改用 anim.sh fade-in）。
  • long-to-short.sh — 裁切一個範圍，加上標題與 CTA 文字。
  • stamp-cta.sh — 套用已儲存的文字範本（請參閱 assets/examples/subscribe-cta.json）。
  • _test.sh — 對測試用固定資料執行所有封裝腳本；在此目錄有任何變更後執行。
• assets/examples/ — 供手動編輯的原始 JSON 片段。

不變量

• 在編輯前先關閉 CapCut 中的專案；編輯後再重新開啟。
• 每次寫入都會進行衝突檢查、原子化準備，並同步到每個可讀的時間軸目標。每個目標都會收到 .bak 和滾動式歷史快照。
• 除非使用者明確接受覆蓋磁碟上已變更的狀態或已開啟的編輯器，否則絕不傳遞 --force-write。
• 音訊片段的 clip 為 null（沒有不透明度/縮放）。
• capcut cut 會寫入 --out 指定的位置，絕不修改來源。
• ID：UUID 的前 6 個以上字元可作為前綴比對。
• 時間格式：1.5s、500ms、+0.5s、-1s、1:30、0:05.5、純數字代表秒。

v0.11 高價值路徑

• 完整草稿：capcut compile spec.json --check，然後 capcut compile spec.json --out <dir>。規格支援引用、變換、裝飾器、範本、字幕、關鍵影格和淡入淡出。
• 卡拉 OK：capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke。
• 代理渲染：capcut render <project> --all-video-tracks --burn-captions；先執行 doctor 以取得 FFmpeg 功能旗標。
• 自動化：capcut serve --workers N --retries N --timeout MS；為工作提供穩定的 id 欄位，讓執行器序列化每個專案的寫入。
• 代理綱要：capcut describe 是唯一真相來源。請勿解析說明文字或發明旗標。