effectcraft

EffectCraft

構造化された自動化インターフェースを使用して、ユーザーが意図するプロジェクトとセッションで EffectCraft を操作します。

参考資料

デスクトップ呼び出しを構成する前に、references/control-protocol.md の該当セクションをお読みください。これは、2026-11-02 に上流の制御プロトコルからダウンロードされた未変更のスナップショットです。上流の MIT ライセンスは references/LICENSE-MIT に含まれています。

Engine、UI state、Input、Locating things、または Screenshots を資料内で検索してください。相対ドキュメントリンクは https://github.com/storytold/effectcraft/blob/main/docs/ を基準に解決されます。

MCP ツールのスキーマ、CLI の構文、スクリプト作成、トラッキング、ロトスコープ、エクスポートのワークフローについては、必要に応じて上流のエージェントガイドを参照してください。動作が異なる場合は、インストール済みアプリケーションからスキーマを確認してください。他の ArtCraft アプリケーションのパラメーターを再利用したり、After Effects との完全な互換性を想定したりしないでください。

セッションを選択する

利用可能な EffectCraft ツール、インストール済みの実行ファイル、既存のセッションを確認します。対象のセッションに接続する MCP 接続が利用できる場合は、それを優先してください。

• 実行中のデスクトッププロジェクトでは、その制御チャネルまたは effectcraft-cli mcp --bridge 9877 を使用します。必要なデスクトップセッションは effectcraft --control 9877 または EFFECTCRAFT_CONTROL_PORT=9877 で開始できます。環境に合わせて実行ファイルのパスとポートを調整してください。
• 独立した作業では、effectcraft-cli mcp --project /absolute/path/project.ecproj でヘッドレスセッションを開きます。effectcraft-cli mcp はコンテンツなしで起動し、--demo はデモコンテンツを読み込みます。ヘッドレスレンダリングはデフォルトで CPU を使用します。--gpu は別の GPU コンポジターを要求し、使用可能なアダプターがない場合は失敗します。
• 1 回限りの CLI 呼び出しでは、別個のヘッドレスエンジンが使用され、デフォルトでデモプロジェクトが読み込まれます。対象のプロジェクトまたは --empty を指定し、編集を保存するには --save または --save-as を使用してください。実行中のアプリで操作する場合は、CLI 呼び出しで --bridge 9877 を指定できます。

適切なセッションを再利用してください。デスクトップアプリに編集内容が反映されることを期待して、別のヘッドレスプロジェクトを開かないでください。実行ファイルまたは接続を利用できない場合は、その旨を報告してください。このスキルは EffectCraft のインストールや MCP サーバーの設定を行いません。

コマンドとトランスポートを確認する

デスクトップチャネルは 127.0.0.1 上の生 TCP であり、HTTP や MCP JSON-RPC ではありません。文字列の method、省略可能な params、互いに異なるリクエスト ID を含む UTF-8 JSON オブジェクトを、1 行に 1 つ送信します。リクエストごとに 1 つ返信を読み取り、ID を照合し、依存する操作の前に ok を確認してください。

{"id":1,"method":"ui.inspect","params":{}}
{"id":2,"method":"engine.execute","params":{"command":"project.summary"}}
{"id":3,"method":"engine.execute","params":{"command":"command.describe","params":{"command":"comp.new"}}}

接続は持続し、返信は順序どおりに返されます。リクエストは UI フレーム間に実行され、タイムアウトは 60 秒です。無効なリクエスト行、無効な UTF-8、または 4 MiB を超える行があると、接続が閉じられます。接続は最大 16 件まで処理されます。ポートには認証がないため、必要な間だけ有効にしてください。タイムアウトまたは変更操作への返信が失われた場合は、再実行する前に状態を確認してください。結果を安全に特定できない場合は、操作を止め、不確実な状況を報告してください。

ID、スキーマ、有効状態、無効化の理由を確認するには、engine.commands またはエンジンコマンド command.list と command.describe を使用してください。engine.execute {command, params} で編集を実行します。これはダイアログを開かずにエンジンコマンドを実行します。ui.menu.invoke {id, params} はメニューのクリックと同様に動作し、params が空の場合はダイアログが開くことがあります。

MCP では、list_commands、describe_command、execute_command {command, params} のほか、get_comp、get_layer、set_property などのヘルパーツールを使用します。実際に接続されているツールのスキーマを使用してください。MCP ヘルパーとデスクトップメソッドでは、名前とパラメーターの大文字・小文字の形式が異なります。CLI の確認には、effectcraft-cli commands または effectcraft-cli exec --list --schemas --json を使用してください。

コンポジションの確認と編集

編集前に、プロジェクト項目、アクティブなコンポジション、選択範囲、時間、変更状態、バックグラウンドジョブを確認してください。デスクトップのクエリでは、engine.execute を通じて project.summary、comp.info、editor.state、app.capabilities、jobs.list を利用できます。MCP では get_state、get_project、get_comp を利用できます。

クエリで実際のコンポジション ID とレイヤー ID を取得してください。レイヤーは名前または #n（上から数えて 1 始まり）でも指定できますが、並べ替え後はインデックスが変わる場合があります。対応している場合はコンポジションを明示し、選択中のオブジェクトを操作するコマンドでは、選択範囲を意図どおりに設定してください。ロックされたレイヤーを誤ってロック解除したり編集したりしないでください。

layer.tree／MCP の get_layer でプロパティツリーを読み取り、返されたパスまたは UID を使用してください。prop.get／get_property で値を読み取ります。エフェクトを適用する前に、エフェクト ID とパラメーターを確認してください。返されるエフェクトとシェイプのパスから新しく作成されたインスタンスを特定できるため、同じ種類の別のエフェクトを誤って編集せずに済みます。

MCP の set_property では、time を指定しない場合は静的な値が設定され、time を指定するとキーフレームが作成され、expression を指定するとエクスプレッションが設定されます。時間の単位は秒です。キーフレームの時間にはレイヤー時間が使われます。これは、オフセットまたはストレッチされたレイヤーではコンポジション時間と異なります。補間方法と、該当する時間での値を確認してください。エクスプレッションの応答では value と evaluated が区別され、expressionError が報告されます。構文エラーがあると、エクスプレッションは保存されても無効のままになる場合があります。

関連する複数手順の編集では、スキーマを確認したうえで、MCP の batch または engine.batch の使用を検討してください。各ステップでは $N.key を使って前の結果を参照でき、バッチが失敗するとロールバックされます。手続き的な構築には、アプリケーションの After Effects 形式のオブジェクトモデルをサポートする run_script を使用できます。スクリプトのエラーと waiting の結果があれば確認してください。ScriptUI ダイアログが表示された場合は、スクリプトが終了する前に操作が必要です。アプリケーションのスクリプトに関するファイル／ネットワーク制限を遵守してください。

engine／MCP コマンドでプロジェクトを開く、置き換える、以前の状態に戻す、または閉じる操作をしても、保存の確認は表示されません。そのような切り替えの前に、変更状態を確認し、必要に応じてユーザーの作業を保存してください。未保存の作業を回避するために app.quit {force: true} を使用しないでください。

必要に応じて UI を操作する

ui.inspect と ui.elements {prefix?} を使って、描画されたウィジェットと安定した ID を確認してください。レイアウトを変更した後は、要素を再取得してください。座標とウィジェットの矩形は論理ウィンドウポイントです。ui.viewer.locate はコンポジションのピクセル座標をウィンドウポイントに変換し、ui.timeline.locate は指定した時間のレイヤー位置を特定します。推測した座標より、確認済みの ID を優先してください。ui.type はフォーカス中のフィールドに入力します。

ドキュメントに記載されたビューアー／タイムラインの状態には ui.set を使い、必要なパネルを表示するには ui.panel.show を使ってください。操作上必要な場合を除き、ui.focus でフォーカスを奪わないでください。UI ジェスチャーは合成入力の処理後に応答します。依存する編集を行う前に、その結果を確認してください。

保存、レンダリング、検証

編集可能な .ecproj は、エクスポートしたメディアとは別に保存します。MCP では save_project {path?} を使用します。選択したインターフェースに対応するエンジンの保存コマンドと CLI フラグを確認してください。保存結果と生成されたファイルを検証し、可能な場合は未保存の変更があるかどうかも確認します。

代表的な時刻のフレームを確認するには、render.frame（デスクトップ）または render_frame（MCP）を使用します。アニメーションの境界やトランジションも含めてください。デスクトップのフレームはビューアーのズームや解像度に依存しません。max_side: 0 を指定するとフルサイズになります。MCP の transparent: true は、確認用にアルファを保持します。パネルや UI の証拠には ui.screenshot を使用します。フレームのプレビューは、完成した動画のエクスポートではありません。

コマンドの検出と機能の確認により、レンダーキュー／エクスポートのスキーマとサポートされている形式を確認します。対象のコンポジション、出力先、時間範囲、寸法、アルファの要件を明示的に設定してください。対応している場合は renderQueue.render {wait: true} が完了するまで待つか、該当するジョブ／ステータスを完了までポーリングします。同様に、保存または適用する前に、トラッキングやロトのジョブのステータスを確認してください。プロジェクトを開いた後に背景映像の検証結果を確認し、結果に影響するメディアが見つからない場合は報告します。

エクスポートしたファイルが存在し、読み取り可能で、要求された形式と長さに一致することを検証します。必要に応じて、代表的なフレームとアルファを確認してください。Lottie またはタイムラインの相互運用に関する警告を確認し、ファイルが存在するだけで忠実に再現されていると判断しないでください。実際に保存／エクスポートしたパスと、未完了のジョブ、見つからないメディア、サポートされていない機能を報告します。