cli-anything-shotcut は何をしますか？
動画編集のためのステートフルなコマンドラインインターフェース。MLT XML形式に基づき、AIエージェントやパワーユーザーがGUIなしでShotcutプロジェクトを作成・編集できます。
インストール
このCLIはcli-anything-shotcutパッケージの一部としてインストールされます：
pip install cli-anything-shotcut
前提条件：
- Python 3.10+
melt（MLT CLI）— レンダリングと再生に必要ffmpeg/ffprobe— メディアプローブに必要- システムに
shotcutがインストールされていること
使い方
基本的なコマンド
# ヘルプの表示
cli-anything-shotcut --help
# インタラクティブREPLモードの開始
cli-anything-shotcut
# 新しいプロジェクトの作成
cli-anything-shotcut project new -o project.json
# JSON出力で実行（エージェント向け）
cli-anything-shotcut --json project info -p project.json
REPLモード
サブコマンドなしで呼び出すと、アンドゥ/リドゥ機能を備えたインタラクティブなREPLセッションが開始されます：
cli-anything-shotcut
# またはプロジェクトを指定：
cli-anything-shotcut --project my_project.mlt
REPLコマンド
ワークフロー： 常に最初に media import で clip_id を取得し、次に add-clip でタイムラインに配置します。
プロジェクト＆セッション：
new [profile]— 新規プロジェクト作成（デフォルト：hd1080p30）open <path>—.mltファイルを開くsave [path]— プロジェクトを保存info— プロジェクト情報を表示xml— 生のMLT XMLを表示status— セッション状態を表示undo/redo— 操作履歴を移動
メディア（2段階モデル）：
media import <file> [--caption name]— ファイルをプロジェクトビンにインポート、clip_id（例：clip0）を返すmedia— インポートしたメディアをすべて一覧表示probe <file>— メディアファイルを解析
タイムライン：
add-track <video|audio> [name]— トラックを追加tracks— すべてのトラックを一覧表示show— タイムラインの概要を表示add-clip <clip_id> <track> [in] [out] [--at time]— インポートしたクリップをトラックに配置clips <track>— トラック上のクリップを一覧表示remove-clip <track> <clip>— クリップを削除trim <track> <clip> [--in tc] [--out tc]— クリップをトリミングsplit <track> <clip> <at>— 指定のタイムコードでクリップを分割
フィルター：
list-filters [video|audio]— 利用可能なフィルターを参照filter-info <name>— フィルターの詳細を表示add-filter <name> [--track n] [--clip n] [key=val ...]— クリップ、トラック、または全体にフィルターを追加filters [--track n] [--clip n]— アクティブなフィルターを一覧表示remove-filter <idx> [--track n] [--clip n]— インデックスでフィルターを削除set-filter <idx> <param> <value> [--track n] [--clip n]— フィルターパラメータを設定volume-envelope [--track n] [--clip n] TIME=LEVEL ...— キーフレーム付き音量エンベロープ（例：00:00:00.000=1.0 00:00:03.000=0.35）duck [--track n] [--clip n] START..END ...— ダッキングエンベロープ（例：00:00:06.000..00:00:09.000）
エクスポート：
presets— エクスポートプリセットを一覧表示render <output> [--preset name]— ビデオファイルにレンダリング
コマンドグループ
プロジェクト
プロジェクト管理：新規作成、開く、保存、情報。
| コマンド | 説明 |
|---|---|
new | 新しい空のプロジェクトを作成 |
open | 既存の.mltプロジェクトファイルを開く |
save | 現在のプロジェクトを保存 |
info | プロジェクトの詳細情報を表示 |
profiles | 利用可能なビデオプロファイルを一覧表示 |
xml | 現在のプロジェクトの生のMLT XMLを表示 |
タイムライン
タイムライン操作：トラック、クリップ、トリミング。
| コマンド | 説明 |
|---|---|
show | タイムラインの概要を表示 |
tracks | すべてのトラックを一覧表示 |
add-track | タイムラインに新しいトラックを追加 |
remove-track | インデックスでトラックを削除 |
add-clip | clip_idでインポートしたクリップをトラックに追加；絶対配置には --at をサポート |
remove-clip | トラックからクリップを削除 |
move-clip | クリップをトラック間または位置間で移動 |
trim | クリップのイン/アウトポイントをトリミング |
split | 指定のタイムコードでクリップを2つに分割 |
clips | トラック上のすべてのクリップを一覧表示 |
add-blank | トラックに空白ギャップを追加 |
set-name | トラックの表示名を設定 |
mute | トラックをミュートまたはミュート解除 |
hide | ビデオトラックを非表示または表示 |
フィルターグループ
フィルター操作：追加、削除、エフェクト設定。
| コマンド | 説明 |
|---|---|
list-available | 利用可能なフィルターをすべて一覧表示 |
info | フィルターとそのパラメータの詳細を表示 |
add | クリップ、トラック、または全体にフィルターを追加 |
remove | インデックスでフィルターを削除 |
set | フィルターのパラメータを設定 |
list | ターゲット上のアクティブなフィルターを一覧表示 |
volume-envelope | トラックまたはクリップにキーフレーム付き音量エンベロープを作成または置換 |
duck | 1つ以上の時間ウィンドウで実用的なダッキングエンベロープを構築 |
メディア
メディア操作：プローブ、一覧表示、ファイル確認。
| コマンド | 説明 |
|---|---|
import | メディアファイルをプロジェクトビンにインポート |
probe | メディアファイルのプロパティを解析 |
list | 現在のプロジェクト内のすべてのメディアクリップを一覧表示 |
check | すべてのメディアファイルの存在を確認 |
thumbnail | ビデオファイルからサムネイルを生成 |
エクスポート
エクスポート/レンダリング操作。
| コマンド | 説明 |
|---|---|
presets | 利用可能なエクスポートプリセットを一覧表示 |
preset-info | エクスポートプリセットの詳細を表示 |
render | プロジェクトをビデオファイルにレンダリング |
トランジショングループ
トランジション操作：ディゾルブ、ワイプ、その他のトランジション。
| コマンド | 説明 |
|---|---|
list-available | 利用可能なトランジションタイプをすべて一覧表示 |
info | トランジションタイプの詳細を表示 |
add | 2つのトラック間にトランジションを追加 |
remove | インデックスでトランジションを削除 |
set | トランジションのパラメータを設定 |
list | タイムライン上のすべてのトランジションを一覧表示 |
合成グループ
合成：ブレンドモード、PIP、不透明度。
| コマンド | 説明 |
|---|---|
blend-modes | 利用可能なブレンドモードをすべて一覧表示 |
set-blend | トラックのブレンドモードを設定 |
get-blend | トラックの現在のブレンドモードを取得 |
set-opacity | トラックの不透明度を設定（0.0〜1.0） |
pip | クリップのピクチャーインピクチャー位置を設定 |
セッション
セッション管理：状態、アンドゥ、リドゥ。
| コマンド | 説明 |
|---|---|
status | 現在のセッション状態を表示 |
undo | 最後の操作を元に戻す |
redo | 最後に元に戻した操作をやり直す |
save | セッション状態をディスクに保存 |
list | 保存されたセッションをすべて一覧表示 |
プレビュー
反復編集レビューのためのプレビューバンドルとライブプレビューセッション。
| コマンド | 説明 |
|---|---|
preview recipes | プレビューレシピを一覧表示 |
preview capture | 低解像度のプレビューバンドルをレンダリング |
preview latest | 最新の既存バンドルを返す |
preview live start | ライブプレビューセッションを開始し、最初のバンドルを公開 |
preview live push | 新しいバンドルをライブセッションに公開 |
preview live status | レンダリングせずに現在のライブセッション状態を照会 |
preview live stop | アーティファクトを削除せずにライブセッションを停止 |
典型的な quick バンドルの内容：
preview.mp4- いくつかのサンプルフレーム
- 中間点
hero.png - プロジェクト情報を含む
summary.json
ポーリングモードもサポート：
cli-anything-shotcut --json --project edit.mlt preview live start --recipe quick --mode poll --source-poll-ms 500
preview live status --json にはセッション参照とコンパクトな trajectory_summary が含まれるため、エージェントは最新の数回の公開を低コストで把握できます。
ビューワーコマンド：
cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session
例
新しいプロジェクトの作成
新しいShotcutプロジェクトファイルを作成します。
cli-anything-shotcut project new -o myproject.json
# またはプログラムでの使用のためにJSON出力
cli-anything-shotcut --json project new -o myproject.json
インタラクティブREPLセッション
アンドゥ/リドゥ機能を備えたインタラクティブセッションを開始します。
cli-anything-shotcut
# コマンドを対話的に入力
# 'help' で利用可能なコマンドを表示
# 'undo' と 'redo' で履歴を移動
プロジェクトのエクスポート
プロジェクトを最終出力形式にエクスポートします。
cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite
決定論的なタイムライン再構築
再構築時には、追加専用のクリップ挿入よりも絶対配置を推奨します：
cli-anything-shotcut --project myproject.mlt media import intro.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip0 \
--track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000
cli-anything-shotcut --project myproject.mlt media import broll.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip1 \
--track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000
--atは、目的の時間が空のスペースにある場合に自動的に空白を挿入します。- CLIは既存のクリップとの重なりを拒否します。
- 後で絶対配置があいまいにならないよう、明示的な
--inと--outの値を推奨します。
オーディオオートメーション
cli-anything-shotcut --project myproject.mlt filter volume-envelope \
--track 2 \
--point 00:00:00.000=1.0 \
--point 00:00:03.000=0.35 \
--point 00:00:05.000=1.0
cli-anything-shotcut --project myproject.mlt filter duck \
--track 2 \
--window 00:00:06.000..00:00:09.000 \
--window 00:00:15.000..00:00:18.000 \
--normal 1.0 --duck 0.25
CLIは以下のセッション状態を保持します：
- アンドゥ/リドゥ：最大50レベルの履歴
- プロジェクトの永続化：プロジェクト状態をJSONとして保存/読み込み
- セッション追跡：変更内容を追跡
出力形式
すべてのコマンドはデュアル出力モードをサポート：
- 人間可読（デフォルト）：表、色付き、整形済みテキスト
- 機械可読（
--jsonフラグ）：エージェントが消費するための構造化JSON
# 人間向け出力
cli-anything-shotcut project info -p project.json
# エージェント向けJSON出力
cli-anything-shotcut --json project info -p project.json
AIエージェント向け
このCLIをプログラム的に使用する場合：
- 解析可能な出力のために常に
--jsonフラグを使用 - リターンコードを確認 - 0は成功、0以外はエラー
- エラー時はstderrを解析してエラーメッセージを取得
- すべてのファイル操作には絶対パスを使用
- エクスポート操作後に出力の存在を確認
- 既知の編集を再現する際は
timeline add-clip --atを優先 - キーフレーム付き音量またはダッキング変更の後は最終レンダリングを確認
preview captureまたはpreview live ...を使用して、ペーシング、カット、フィルター効果を視覚的に検証- 返されたアーティファクトパス（
hero.pngやpreview.mp4など）を読み取る；JSONペイロードはディスク上のファイルを参照します - 完全な
trajectory.jsonを読む前にpreview live status --jsonを使用 - 既存のバンドルやライブセッションの検査/オープンには
cli-hub previews ...のみを使用
詳細情報
- 完全なドキュメント：パッケージ内のREADME.mdを参照
- テストカバレッジ：パッケージ内のTEST.mdを参照
- 方法論：cli-anything-plugin内のHARNESS.mdを参照
バージョン
1.0.0