capcut-cli — CapCut/剪映で編集出荷

capcut-edit

バージョン認識可能なストアを介してCapCut / JianYingの下書きを編集するためのCLIです。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呼び出し、算術演算、または分岐を含むレシピは、パラメータ化されたシェルスクリプトとして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>      # 1つのアイテム、詳細情報

出力モード

• JSON（デフォルト）：jqにパイプするか、スクリプトに渡します。
• -H：人間が読みやすいテーブル。
• -q：静か、終了コードのみ — スクリプト内の書き込みコマンド用。

バッチ書き込み

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

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

バッチはトランザクション型です。1つの操作が失敗すると、何も書き込まれません。ユーザーが部分的なコミットを明示的に受け入れる場合にのみ--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の計算、アルファキーフレームはレンダリングされないのでアニメーションマテリアルを使用する、など。
• Enum探索 — 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を介したスケール+パンキーフレーム（モーションプロパティはレンダリングされます。アルファはレンダリングされません — 代わりに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>。スペックは、参照、変換、デコレータ、テンプレート、キャプション、キーフレーム、フェードをサポートします。
• カラオケ：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が信頼できる情報源です。ヘルプテキストをスクレイピングしたり、フラグを発明したりしないでください。