外部アプリから操作する(VCam API)
VCam APIを使うと、ほかのアプリからVCamNovaを操作できます(モーションの再生、表情や視線の変更、アバター・シーン・カメラの切り替え、テキストや画像などシーンのオブジェクトの配置など)。同じMac上のアプリのほか、設定で許可すれば同じネットワークのMacやPCなどからも操作できます。AITuberシステムやStream Deck、自作スクリプトからの操作を想定しています。
モーションキャプチャーなどの動きでアバターの体を動かすときは、VMC Protocolが利用できます。詳しくはVMC Protocolのアプリと連携するを参照してください。
VCam APIはVCamNova 0.3.0以降で使えます。VCamでは使えません。
通信はWebSocket上のJSON-RPC 2.0です。すべてのメソッド・イベント・エラーの一覧はAPIリファレンスを参照してください。
サーバーは初期状態では無効です。VCamNovaの⚙️ボタンから設定を開き、「連携」タブのVCam APIで「有効にする」をオンにすると、次のエンドポイントで待ち受けます。
ws://127.0.0.1:34965ポートなどの設定は、「有効にする」をオンにするとその下に表示されます。ポートや他のデバイスからの接続の設定を変えるとサーバーが起動し直し、接続中のアプリはすべて切断されます。
出力映像を読み取るメソッド(frame.capture)は、同じ画面の「出力映像の読み取りを許可」をオンにしたときだけ使えます。シーンに映した画面やカメラも含まれるので、信頼できるアプリを使うときだけオンにしてください。
他のデバイスから接続する
Section titled “他のデバイスから接続する”同じネットワークにある別のMacやPCなどから操作するには、「他のデバイスからの接続を許可」をオンにします。オンにすると、このMacのIPアドレスを使った「接続先」(例: ws://192.168.1.10:34965)が表示されます。
他のデバイスから接続するには、設定に表示されるトークンが必要です。WebSocketのハンドシェイクで次のヘッダーを付けてください。
Authorization: Bearer <トークン>websocatを使った例:
$ websocat -H='Authorization: Bearer <トークン>' ws://192.168.1.10:34965このMacのアプリからws://127.0.0.1:34965に接続するときは、トークンは要りません。
トークンが漏れたときは、「再生成」で新しいトークンにしてください。接続中のアプリはすべて切断され、他のデバイスのアプリは新しいトークンで接続し直す必要があります。
問題の切り分けや動作の確認のために、「トークンによる認証を求める」をオフにしてトークンなしで接続することもできます。オフの間は同じネットワークの誰でもVCamNovaを操作できるので、確認が終わったらオンに戻してください。この設定はアプリを再起動しても戻りません。
VCam CLIを使う
Section titled “VCam CLIを使う”VCam CLIを使うと、プログラムを書かずに、ターミナルやシェルスクリプト、AIエージェントからVCam APIを呼び出せます。
macOSとLinuxではHomebrewでインストールできます。Windowsでのインストール方法は、VCam CLIのREADMEを参照してください。
$ brew install vcamapp/tap/vcam-cliメソッド名をそのままコマンドにして、パラメータを--名前 値で渡します。結果はJSONで表示されます。
$ vcam methods$ vcam scene.list$ vcam scene.load --sceneId 3 --duration 0.5$ vcam text.add --text "こんにちは" --placement '{"x":0.3,"y":0.35,"width":0.25}'$ vcam image.import photo.png$ vcam frame.capture -o frame.png$ vcam events motion.stopped --count 1メソッドのパラメータはvcam <メソッド名> --helpで確認できます。他のデバイスのVCamNovaに接続するときは、--hostで接続先を指定し、環境変数VCAM_TOKENにトークンを設定します。
AIエージェントから操作する
Section titled “AIエージェントから操作する”vcam mcpはMCPサーバーとして動きます。ClaudeなどのMCPクライアントに登録すると、AIがシーンを組み立てたり、テキストや画像を配置したり、モーションを再生したりできます。配置した結果はframe_captureで映像を見て確かめます。Claude Codeに登録する例:
$ claude mcp add --scope user vcam -- vcam mcpリクエストを送る
Section titled “リクエストを送る”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.3.0","capabilities":["avatar","motion","expression","scene","camera","subtitle","tracking","events","vrma","avatarImport","poseEditor","emoji","sceneObjects","sceneLighting"]}}{"jsonrpc":"2.0","id":2,"method":"motion.play","params":{"motionId":"builtin:hi"}}{"jsonrpc":"2.0","id":2,"result":true}イベントを受け取る
Section titled “イベントを受け取る”VCamNovaは状態の変化(モーションの開始・終了、表情の変更、シーンのオブジェクトの変更など)を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のエラーレスポンスで返ります。data.codeには数値のcodeと同じ識別子が文字列で入るため、どちらでも分岐できます。
{"jsonrpc":"2.0","id":4,"error":{"code":1002,"message":"Motion was not found.","data":{"code":"motion_not_found"}}}バージョンとAPI仕様の取得
Section titled “バージョンとAPI仕様の取得”app.getInfoはAPIバージョンと、実行中のVCamNovaが対応している機能(capabilities)を返します。frameCaptureは「出力映像の読み取りを許可」がオンのときだけ含まれます。rpc.discoverはこのAPIを記述したOpenRPCドキュメント全体を返すため、ツールから実行時にメソッド一覧を取得できます。
セキュリティ
Section titled “セキュリティ”- 初期状態では無効で、設定でVCam APIを有効にするまで何も待ち受けません
- 初期状態ではこのMacからの接続だけを受け付けます。他のデバイスからは「他のデバイスからの接続を許可」をオンにしたときだけ接続でき、トークンが必要です
- Originヘッダー付きのハンドシェイクは拒否されるため、ブラウザ上のWebページからはアクセスできません
- 出力映像は、「出力映像の読み取りを許可」をオンにしたときだけ読み取れます
