cli-anything-shotcut

cli-anything-shotcut

MLT XML 形式に基づいて構築された、動画編集用のステートフルなコマンドラインインターフェースです。GUI を使わずに Shotcut プロジェクトを作成・編集する必要がある AI エージェントやパワーユーザー向けに設計されています。

インストール

この CLI は cli-anything-shotcut パッケージの一部としてインストールされます:

pip install cli-anything-shotcut

前提条件:

• Python 3.10+
• melt（MLT CLI）— レンダリングと再生に必要
• ffmpeg / ffprobe — メディアの解析に必要
• shotcut がシステムにインストールされている必要があります

使用方法

基本コマンド

# Show help
cli-anything-shotcut --help

# Start interactive REPL mode
cli-anything-shotcut

# Create a new project
cli-anything-shotcut project new -o project.json

# Run with JSON output (for agent consumption)
cli-anything-shotcut --json project info -p project.json

REPL モード

サブコマンドなしで起動すると、CLI は undo/redo をサポートする対話型 REPL セッションに入ります:

cli-anything-shotcut
# or with a project:
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、save、info。

コマンド	説明
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
# Or with JSON output for programmatic use
cli-anything-shotcut --json project new -o myproject.json

インタラクティブ REPL セッション

元に戻す/やり直しをサポートするインタラクティブセッションを開始します。

cli-anything-shotcut
# Enter commands interactively
# Use 'help' to see available commands
# Use 'undo' and 'redo' for history navigation

プロジェクトのエクスポート

プロジェクトを最終出力形式にエクスポートします。

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 として保存/読み込み
• セッションの追跡: 変更と改変を追跡

出力形式

すべてのコマンドは 2 つの出力モードをサポートします:

• 人間が読みやすい形式 (デフォルト): テーブル、色、整形されたテキスト
• 機械が読み取り可能な形式 (--json フラグ): エージェントが利用するための構造化 JSON

# Human output
cli-anything-shotcut project info -p project.json

# JSON output for agents
cli-anything-shotcut --json project info -p project.json

AI エージェント向け

この CLI をプログラムから使用する場合:

1. 常に --json フラグを使用する — 解析可能な出力のため
2. リターンコードを確認する — 成功時は 0、エラー時は非ゼロ
3. 失敗時は stderr を解析する — エラーメッセージを取得するため
4. すべてのファイル操作に絶対パスを使用する
5. エクスポート操作の後は出力が存在することを確認する
6. 既知の編集を再現する場合は timeline add-clip --at を優先する
7. キーフレーム付きの音量変更やダッキングの後は最終レンダリングを確認する
8. preview capture または preview live ... を使用して、ペーシング、カット、フィルター効果を視覚的に検証する
9. 返された成果物のパス (hero.png や preview.mp4 など) を読み取る — JSON ペイロードはディスク上のファイルを参照します
10. 完全な trajectory.json を読み取る前に preview live status --json を使用する
11. cli-hub previews ... は既存のバンドルまたはライブセッションを検査/開く場合にのみ使用する

詳細情報

• 完全なドキュメント: パッケージ内の README.md を参照してください
• テストカバレッジ: パッケージ内の TEST.md を参照してください
• 方法論: cli-anything-plugin 内の HARNESS.md を参照してください

バージョン

1.0.0