Skip to content

Control from other apps (VCam API)

The VCam API lets other apps control VCamNova: play motions, change expressions and gaze, switch avatars, scenes, and the camera, place scene objects such as text and images, and more. Besides apps on the same Mac, you can allow Mac computers, PCs, and other devices on the same network to connect. It is designed for AITuber systems, Stream Deck integrations, and your own scripts.

To move the avatar’s body with motion from motion capture or similar apps, you can use the VMC Protocol. See Integrate with VMC Protocol Apps.

The VCam API is available in VCamNova 0.3.0 and later. It is not available in VCam.

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

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

ws://127.0.0.1:34965

The port and other settings appear below “Enable” while it’s on. Changing the port or the settings for connections from other devices restarts the server, which disconnects all connected apps.

The method that reads the output image (frame.capture) works only while “Allow reading the output image” is on in the same screen. The image includes any screen or camera shown in the scene, so turn it on only for apps you trust.

To control VCamNova from another Mac, PC, or other device on the same network, turn on “Allow connections from other devices.” The “Address” that uses this Mac’s IP address (for example, ws://192.168.1.10:34965) then appears.

Connections from other devices require the token shown in the settings. Send it in the WebSocket handshake with this header:

Authorization: Bearer <token>

For example, with websocat:

$ websocat -H='Authorization: Bearer <token>' ws://192.168.1.10:34965

Apps on this Mac connecting to ws://127.0.0.1:34965 don’t need the token.

If the token leaks, click “Regenerate” to replace it. All connected apps are disconnected, and apps on other devices need the new token to connect again.

To troubleshoot or quickly try things out, you can turn off “Require token authentication” and connect without the token. While it’s off, anyone on the same network can control VCamNova, so turn it back on when you’re done. This setting stays as is when you restart the app.

VCam CLI lets you call the VCam API from the terminal, shell scripts, and AI agents without writing a program.

On macOS and Linux, install it with Homebrew. For Windows, see the VCam CLI README.

$ brew install vcamapp/tap/vcam-cli

Use the method name as the command and pass parameters as --name value. Results are printed as JSON.

$ vcam methods
$ vcam scene.list
$ vcam scene.load --sceneId 3 --duration 0.5
$ vcam text.add --text "Hello" --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

Run vcam <method> --help to see a method’s parameters. To connect to VCamNova on another device, specify it with --host and set the token in the VCAM_TOKEN environment variable.

vcam mcp runs as an MCP server. Add it to Claude or another MCP client, and the AI can build scenes, place text and images, and play motions, then check the result by looking at the output with frame_capture. To add it to Claude Code:

$ claude mcp add --scope user vcam -- vcam mcp

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.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}

VCamNova pushes state changes (motion started or stopped, expression changed, scene objects 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"}}

Failures use JSON-RPC error responses. data.code carries the same identifier as the numeric code, but 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"}}}

app.getInfo returns the API version and the capabilities of the running VCamNova. frameCapture is included only while “Allow reading the output image” is on. rpc.discover returns the full OpenRPC document describing this API, so tools can discover methods at runtime.

  • Nothing listens until you enable VCam API in the settings
  • By default, only connections from this Mac are accepted. Other devices can connect only while “Allow connections from other devices” is on, and they need the token
  • Handshakes carrying an Origin header are rejected, so web pages in a browser cannot reach the API
  • The output image can be read only while “Allow reading the output image” is on