filmcraft

FilmCraft

ユーザーが意図するプロジェクトとシーケンスを使って、構造化された自動化インターフェースから FilmCraft を操作します。

プロトコルのリファレンス

呼び出しを構築する前に、references/control-protocol.md の関連セクションを読んでください。これは 2026-10-08 にダウンロードされた、変更されていない上流のスナップショットです。

ソース：FilmCraft control protocol。上流の MIT ライセンスは references/LICENSE-MIT に含まれています。

関連する項目として、リファレンス内で Desktop control channel、Selection or explicit targets、Moving clips、Trim mode、Replace With Clip、Audio mixing、Essential Sound、Colour、Keyboard shortcuts、MCP を検索してください。相対リンクは https://github.com/storytold/filmcraft/blob/main/docs/ を基準に解決されます。MCP の引数スキーマ、CLI の永続化、エクスポートの進捗とキャンセルについては、上流のエージェント向けドキュメント、Part 1 を参照してください。保存、復旧、再リンク、プロキシのコマンドが必要な場合は、project-files.md を参照してください。インストール済みの動作が異なる場合は、パラメーターを推測せず、インストール済みのコマンドレジストリとツールスキーマを確認してください。

セッションを選ぶ

利用可能な FilmCraft ツールと実行ファイルを確認し、適切な既存セッションを再利用してください。ユーザーが開いているプロジェクトにはデスクトップブリッジが必要です。ヘッドレスセッションは別個のプロセス内プロジェクトであり、ライブウィンドウを編集できません。ファイルベースの無人作業では、ヘッドレス MCP または CLI を使用してください。

デスクトップ制御とブリッジの例（実行ファイルのパスとポートを適宜変更してください）：

filmcraft --control 9876
filmcraft-cli mcp --bridge 127.0.0.1:9876

ヘッドレス MCP：

filmcraft-cli mcp --project /absolute/path/project.fcproj

--project または --demo を指定せずにヘッドレス MCP を起動すると、空のプロジェクトで開始します。UI ツールにはブリッジモードが必要です。このスキルを作成または使用しても、FilmCraft のインストールや MCP サーバーの登録は行われません。利用できない場合は、不足している実行ファイルまたは接続を報告してください。

デスクトップの TCP チャネルはループバックのみで、認証されません。使用中のみ有効にしてください。UTF-8 の JSON オブジェクトを 1 行ずつ送信し、文字列の method、任意の params、重複しないリクエスト ID を指定してください。応答を読み取り、ok を確認してください。これは生の TCP であり、HTTP ではありません。無効なリクエスト、4 MiB を超える行、または過剰な接続によって接続が閉じられる場合があります。エラー後は、以降の呼び出しの前に再接続してください。接続が閉じられたというだけの理由で、結果が不明な変更操作を再実行しないでください。

確認と編集

MCP の doc_inspect または project_inspect と sequence_inspect を使って、プロジェクト項目、アクティブなシーケンス、トラック、クリップ、再生ヘッド、選択範囲、エフェクトを特定します。デスクトップコントロールでは、engine.commands から確認コマンドを見つけます。ui.inspect で UI の状態を確認します。

MCP の command_list またはデスクトップの engine.commands を使って、コマンド ID、パラメーターの説明、現在の有効状態を確認します。MCP の command_run {id, params} またはデスクトップの engine.execute {command, params} で実行します。タスクを正確に表現できる場合は、説明されている明示的な clips / clip または items / item の対象指定を優先します。コマンドレジストリには選択状態に基づく有効状態が表示されます。無効と表示されたコマンドでも、明示的な対象を指定すれば受け付けられる場合がありますが、ほかの前提条件は引き続き適用されます。

時間は整数のティックで指定します。1 秒あたり 254,016,000,000 ティックです。使用できる場合は、説明されている seconds、frame、または timecode の代替指定を使います。ティック値の time フィールドに秒を指定してはいけません。フレーム数を解釈する前に、シーケンスのフレームレートを確認します。実際のトラック ID、または V1 や A2 などの既存の名前を使用します。存在しないトラックを指定するとエラーになります。

クリップを移動する前に、リンクされた相手、ロックされたトラック、移動先の重なりを確認します。timeline.move は移動先の素材を上書きする場合があり、insert を使うと挿入できます。既定では、リンクされた相手も同じオフセットで移動します。指定したクリップだけを移動する場合に限り、linked: false を使用します。返された moved ID と、オーディオの同期やシーケンスの負の時間からのずれも含めて、移動後のタイミングを確認します。

置き換え編集では、short と sourceInClamped の結果を確認します。置き換えに成功しても、利用可能なメディアを超えて最後のフレームが保持されたり、保持されたソースの In がクランプされたりする場合があります。ダイナミックトリム操作では、説明されている秒単位のクロックを指定し、続行する前にトリム操作を完了またはキャンセルします。ミキサーのオートメーション、ダッキング、LUT、HDR の作業については、オーディオまたはカラーのセクションを確認します。関係のないシーケンス設定は維持します。

ダイアログやジェスチャーでは、ui.elements を確認し、返された安定した要素 ID を優先して使用します。説明されているダイアログおよびビューのフィールドには ui.set を使用し、タイムライン上の位置指定には ui.timeline.locate / ui.timeline.hit を使用します。レイアウトを変更した後は、状態を再確認します。ui.type はフォーカス中のフィールドを対象とします。ユーザーのキーボードフォーカスを明示的に変更するのは ui.focus だけです。タスクでアクティブ化が必要な場合に呼び出します。

保存、エクスポート、検証

ファイルを開く、保存する、またはエクスポートする前に、インストール済みのファイルコマンドとそのパラメーターを確認してください。必要に応じて編集可能なプロジェクトを .fcproj として保存し、指定された出力先と形式を守ってください。単発の CLI 編集を永続化するには、--project と --save、または --save-as <path> が必要です。メモリ上の編集を、保存済みプロジェクトとして報告しないでください。

既知のコマンドシーケンスには、失敗後も続行する意図がある場合を除き、stop_on_error: true を指定してバッチを使用してください。各ステップの結果を確認し、バッチが失敗した場合は、その後の作業を判断する前に、プロジェクトの状態を確認してください。

file.exportMedia では、wait: true を指定すると完了まで待機します。指定しない場合は、返されたジョブ ID を保持し、完了または失敗するまで jobs.list をポーリングしてください。必要に応じて、対象のジョブを jobs.cancel でキャンセルしてください。待機中のエクスポートを MCP でキャンセルすると、部分的な出力は削除されます。進捗確認とキャンセルに対応していることを、利用する前に確認してください。タイムアウトまたは返信の消失後は、再試行する前にプロジェクトとジョブの状態、および出力を確認してください。安全に再試行できると確認できない場合は、作業を中止して、結果が不確定であることを報告してください。

シーケンスの状態を確認し、代表的なレンダリングフレームまたはスクリーンショットを調べてください。MCP の render_frame／render_preview は、ヘッドレスでレンダリングするか、ブリッジモードでプログラムモニターをキャプチャしますが、再生ヘッドや選択状態は変更しません。デスクトップのスクリーンショットは、フレームが表示されない場合、10 秒後に失敗することがあります。キャプチャの失敗と編集の失敗を区別してください。オーディオを編集した場合は、可能であれば、再生またはエクスポートしたオーディオサンプルも確認してください。保存先のパス、エクスポートの完了、およびメディアの欠落、ソース範囲のクランプ、未完了のジョブなどの重要な警告を報告してください。