外部アプリから操作する（VCam API）

VCam APIを使うと、同じMac上のほかのアプリからVCamを操作できます（モーションの再生、表情の適用、アバターやシーンの切り替えなど）。AITuberシステムやStream Deck連携、自作スクリプトからの操作を想定しています。

通信はlocalhost上のWebSocketで行うJSON-RPC 2.0です。すべてのメソッド・イベント・エラーの一覧はAPIリファレンスを参照してください。

有効にする

サーバーは初期状態では無効です。VCamの⚙️ボタンから設定を開き、「連携」タブのVCam APIで「有効にする」をオンにすると、次のエンドポイントで待ち受けます。

ws://127.0.0.1:34965

ポートは、サーバーが無効のときに同じ設定画面で変更できます。

リクエストを送る

JSON-RPC 2.0のリクエストをWebSocketのテキストメッセージとして送ります。パラメータは名前渡しです。websocatを使った例:

$ websocat ws://127.0.0.1:34965
{"jsonrpc":"2.0","id":1,"method":"app.getInfo","params":{}}
{"jsonrpc":"2.0","id":1,"result":{"apiVersion":"0.1.0","appVersion":"0.15.0","capabilities":["avatar","motion","expression","scene","camera","events","vrma"]}}
{"jsonrpc":"2.0","id":2,"method":"motion.play","params":{"motionId":"builtin:hi"}}
{"jsonrpc":"2.0","id":2,"result":true}

イベントを受け取る

VCamは状態の変化（モーションの開始・終了、表情の変更など）をJSON-RPCのnotificationとして送信します。接続はevents.subscribeを呼ぶまで何も受信しません。eventsパラメータを省略するとすべてのイベントを受信します。

{"jsonrpc":"2.0","id":3,"method":"events.subscribe","params":{}}
{"jsonrpc":"2.0","id":3,"result":true}
{"jsonrpc":"2.0","method":"motion.started","params":{"motionId":"builtin:hi"}}
{"jsonrpc":"2.0","method":"motion.stopped","params":{"motionId":"builtin:hi"}}

エラー

失敗はJSON-RPCのエラーレスポンスで返ります。数値のcodeは安定しており、data.codeには同じ識別子が文字列で入るため、どちらでも分岐できます。

{"jsonrpc":"2.0","id":4,"error":{"code":1002,"message":"Motion was not found.","data":{"code":"motion_not_found"}}}

バージョンとAPI仕様の取得

app.getInfoはAPIバージョンと、実行中のVCamが対応している機能（capabilities）を返します。rpc.discoverはこのAPIを記述したOpenRPCドキュメント全体を返すため、ツールから実行時にメソッド一覧を取得できます。既存メソッドの挙動はリリースをまたいで維持され、新機能は新しいメソッドとして追加されます。

セキュリティ

• サーバーは127.0.0.1だけにバインドされ、ほかのマシンからは接続できません
• Originヘッダー付きのハンドシェイクは拒否されるため、ブラウザ上のWebページからはアクセスできません
• 初期状態では無効で、設定でVCam APIを有効にするまで何も待ち受けません