Control VCam from other apps (VCam API)

The VCam API lets other apps on the same Mac control VCam: play motions, apply expressions, switch avatars and scenes, and more. It is designed for AITuber systems, Stream Deck integrations, and your own scripts.

Communication uses JSON-RPC 2.0 over a localhost WebSocket. See the API reference for every method, event, and error.

Enabling the server

The server is off by default. Open the settings from the ⚙️ button in VCam, and turn on “Enable” under VCam API in the “Integration” tab. VCam then listens on:

ws://127.0.0.1:34965

The port can be changed in the same settings section while the server is off.

Making requests

Send JSON-RPC 2.0 requests as WebSocket text messages, with parameters passed by name. For example, with 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}

Receiving events

VCam pushes state changes (motion started or stopped, expression changed, and so on) as JSON-RPC notifications. A connection receives nothing until it subscribes with events.subscribe; omit the events parameter to receive everything.

{"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"}}

Errors

Failures use JSON-RPC error responses. The numeric code is stable, and data.code carries the same identifier as a string, so clients can branch on either.

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

Versioning and discovery

app.getInfo returns the API version and the capabilities of the running VCam build. rpc.discover returns the full OpenRPC document describing this API, so tools can discover methods at runtime. Existing methods keep their behavior across releases; new capabilities arrive as new methods.

Security

• The server binds to 127.0.0.1 and is never reachable from other machines
• Handshakes carrying an Origin header are rejected, so web pages in a browser cannot reach the API
• Nothing listens until you enable VCam API in the settings