capcut-edit

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>\
• Windows（JianYing / 剪映）：%LOCALAPPDATA%\JianyingPro\User Data\Projects\com.lveditor.draft\<project>\

基本原則 — 決定論的なスクリプト

複数の capcut 呼び出し、算術処理、または分岐を伴うレシピは、すべて scripts/ 内のパラメーター化されたシェルスクリプトとして提供します。Claude は入力を指定してスクリプトを呼び出し、スクリプトが固定の手順を実行します。スクリプトにできるレシピは、必ずスクリプトにしてください。references/ に手順を文章で記述してはいけません。

references/workflows.md には、どのスクリプトを呼び出すか、その理由を記載します。再構成可能な一連の手順は記載しません。

段階的な開示

まず全体像を把握し、必要な部分を詳しく確認します。プロジェクトの JSON 全体を出力してはいけません。

capcut info <project> -H           # overview
capcut doctor -H                   # installed media/transcription capabilities
capcut diagnose <project> -H       # canonical files, divergence, editor safety
capcut tracks <project> -H         # all tracks
capcut materials <project> -H      # material summary
capcut segments <project> -H       # segments with timing
capcut segment <project> <id>      # one item, full detail

出力モード

• 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。

一括処理はトランザクションです。操作が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 の計算、アルファキーフレームはレンダリングされないためアニメーション素材を使うこと、など。
• 列挙値の確認 — 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 エントリーポイントを自動的に解決するため、capcut-cli のチェックアウト外にインストールされている場合も、このスキルを使用できます。優先順位は $CAPCUT_CLI（dist/index.js またはランチャーへの明示的なパス）、リポジトリのビルド、インストール済みの node_modules/capcut-cli、PATH 上の capcut-cli／capcut の順です。.js エントリは node で実行されます。PATH から取得したランチャー、またはランチャーを指す $CAPCUT_CLI は直接実行されます。anim.sh はプラットフォームごとに CapCut のエフェクトキャッシュディレクトリを解決します。$CAPCUT_EFFECT_CACHE で上書きできます。

不変条件

• 編集前に 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> を実行します。仕様は refs、変換、デコレーター、テンプレート、字幕、キーフレーム、フェードに対応しています。
• カラオケ：capcut caption <project> --audio <path> --whisper-engine <openai|whisper-cpp|faster-whisper> --karaoke。
• プロキシ：capcut render <project> --all-video-tracks --burn-captions。FFmpeg の機能フラグを確認するため、先に doctor を実行してください。
• 自動化：capcut serve --workers N --retries N --timeout MS。ジョブに安定した id フィールドを指定し、ランナーがプロジェクトごとに書き込みを直列化するようにしてください。
• エージェントのスキーマ：CLI v0.28.0 以降では、capcut describe --compact を実行してコマンドを確認し、続いて capcut describe --command <name> で完全な契約を取得してください（複数の名前について繰り返します）。プレーンな capcut describe はレジストリ全体を返し、旧バージョンでも動作します。これらの契約を信頼できる情報源として使用し、ヘルプテキストをスクレイピングしたり、フラグを推測して作ったりしないでください。