motion-canvas-agent

Motion Canvas Agent Plugin

HTTP 経由で、実行中の Motion Canvas エディターをプログラムから完全に制御します。任意のフレームにシークし、スクリーンショットを撮影し、シーングラフを調べ、解像度／fps／背景を変更して、レンダリングを開始できます。ブラウザーの自動操作は不要です。

アーキテクチャ

Agent (curl/script)  ──HTTP──▶  Vite Server (agent-plugin.ts)  ──HMR WS──▶  Browser (agent-client.ts)
                                      │                                           │
                                      ▼                                           ▼
                                screenshots/                               Player + Renderer
                                (PNG files)                                + ProjectMetadata

セットアップ

1. プラグインファイルをプロジェクトにコピーする

• assets/agent-plugin.ts → プロジェクトのルート
• assets/agent-client.ts → src/

2. vite.config.ts

import {defineConfig} from 'vite';
import motionCanvas from '@motion-canvas/vite-plugin';
import {agentPlugin} from './agent-plugin';

export default defineConfig({
  plugins: [
    motionCanvas(),
    agentPlugin({screenshotDir: './screenshots'}),
  ],
});

3. project.ts

import {makeProject} from '@motion-canvas/core';
import {agentClient} from './agent-client';

export default makeProject({
  plugins: [agentClient()],
  scenes: [...],
});

4. 起動してブラウザーを開く

npm start
# Open http://localhost:9000 in a browser

HTTP API リファレンス

ベース URL：http://localhost:9000/__agent

再生コントロール

メソッド	エンドポイント	本文	レスポンス
GET	/status	—	{connected, frame, duration, fps, paused, sceneName, errors}
POST	/seek	{frame: 120}	{ok, frame}
POST	/next-frame	—	{ok, frame}
POST	/prev-frame	—	{ok, frame}
POST	/play	—	{ok}
POST	/pause	—	{ok}

スクリーンショット

メソッド	エンドポイント	本文	レスポンス
POST	/screenshot	{name: "my-shot"}	{ok, path, frame}
POST	/screenshot-base64	—	{ok, data, frame}

設定

メソッド	エンドポイント	本文	レスポンス
GET	/settings	—	{background, range, size, previewFps, previewScale, renderingFps, renderingScale}
POST	/settings/background	{color: "#0F172A"}	{ok}
POST	/settings/range	{start: 0, end: 300}	{ok}
POST	/settings/size	{width: 1920, height: 1080}	{ok}
POST	/settings/preview-fps	{fps: 30}	{ok}
POST	/settings/preview-scale	{scale: 0.5}	{ok}
POST	/settings/rendering-fps	{fps: 60}	{ok}
POST	/settings/rendering-scale	{scale: 2}	{ok}

レンダリング

メソッド	エンドポイント	本文	レスポンス
POST	/render	{fps?, range?}	{ok, message}
POST	/render/abort	—	{ok, message}

シーン情報

メソッド	エンドポイント	本文	レスポンス
GET	/scenes	—	{scenes: [{name}], currentScene}
GET	/scene-graph	—	{scene, graph}（再帰的なノードツリー）
GET	/threads	—	{scene, slides: [{name, id}]}

エラー

メソッド	エンドポイント	本文	レスポンス
GET	/errors	—	{errors: [{message, stack}]}
POST	/clear-errors	—	{ok}

シーングラフの形式

GET /__agent/scene-graph は、次のような再帰的ツリーを返します。

{
  "scene": "my-scene",
  "graph": {
    "type": "View2D",
    "key": "my-scene/View2D[1]",
    "position": {"x": 960, "y": 540},
    "size": {"width": 1920, "height": 1080},
    "children": [
      {
        "type": "Rect",
        "position": {"x": 0, "y": 0},
        "size": {"width": 400, "height": 300},
        "fill": "#1E293B",
        "children": [
          {
            "type": "Txt",
            "text": "Hello World"
          }
        ]
      }
    ]
  }
}

各ノードには、type、key、position、size、（1 以外の場合）opacity、fill、（該当する場合）text、および children が含まれます。

AI エージェントのワークフロー

# 1. Check connection
curl -s localhost:9000/__agent/status

# 2. Set resolution
curl -s -X POST localhost:9000/__agent/settings/size \
  -H "Content-Type: application/json" -d '{"width": 1920, "height": 1080}'

# 3. Seek to a frame
curl -s -X POST localhost:9000/__agent/seek \
  -H "Content-Type: application/json" -d '{"frame": 60}'

# 4. Screenshot
curl -s -X POST localhost:9000/__agent/screenshot \
  -H "Content-Type: application/json" -d '{"name": "check-1"}'
# → Read ./screenshots/check-1.png

# 5. Inspect scene graph
curl -s localhost:9000/__agent/scene-graph

# 6. Check which scene we're in
curl -s localhost:9000/__agent/scenes

# 7. Check errors
curl -s localhost:9000/__agent/errors

# 8. Change background
curl -s -X POST localhost:9000/__agent/settings/background \
  -H "Content-Type: application/json" -d '{"color": "#000000"}'

# 9. Trigger render
curl -s -X POST localhost:9000/__agent/render

セキュリティ

• ローカルホスト限定：エージェント API は、デフォルトでローカルホストにバインドする Vite 開発サーバー上で実行されます。ネットワークに公開しないでください（本番環境では --host 0.0.0.0 を使用しないでください）
• スクリーンショットのパス：スクリーンショット名はサニタイズされます。パス区切り文字とドットが除去され、解決されたパスが設定済みの screenshotDir 内にとどまることが検証されます
• シーングラフのテキスト：シーングラフから抽出されたテキストコンテンツはサニタイズされます（制御文字を除去し、100 文字で切り詰めます）。シーングラフのデータを処理する際は、信頼できないデータとして扱ってください

仕組み

• ランタイムプラグイン（agentClient()）は、Plugin.player()、Plugin.renderer()、Plugin.project() コールバックを使用して、Player、Renderer、Project のインスタンスを取得します
• Player はシーク、フレーム送り、再生制御、現在のシーン、再生時間を提供します
• ProjectMetadata は、.get()／.set() を通じて、shared（背景、範囲、サイズ）、preview（fps、スケール）、rendering（fps、スケール、エクスポーター）の設定を提供します
• Renderer は、エクスポート用に render(settings) と abort() を提供します
• シーングラフ は、scene.getView().peekChildren() を再帰的にたどり、タイプ、位置、サイズ、塗りつぶし、テキスト、不透明度をシリアライズします
• 通信 には Vite の HMR WebSocket を使用します

ファイル

ファイル	コピー先	用途
assets/agent-plugin.ts	プロジェクトのルート	Vite プラグイン — HTTP エンドポイントと WS リレー
assets/agent-client.ts	src/	ランタイムプラグイン — Player／Renderer／Project の制御とキャンバスのキャプチャ