API reference - AI Generated
VDO.Ninja Remote Control API Documentation
Overview
VDO.Ninja's Remote Control API allows programmatic control of VDO.Ninja sessions via HTTP or WebSocket connections. This powerful API enables integration with stream decks, custom applications, and automation tools for controlling cameras, microphones, layouts, and other features.
Basic Setup
To enable the API on any VDO.Ninja instance, add the &api
parameter with a unique API key:
This key must be kept private and will be used to authenticate API requests. The same key must be used when making API calls to control this specific VDO.Ninja instance.
Connection Methods
The API supports three connection methods:
WebSocket API (recommended for real-time control)
HTTP GET API (good for simple controllers and hotkeys)
Server-Sent Events (SSE) for one-way event monitoring
WebSocket API
Connect to wss://api.vdo.ninja:443
and authenticate with your API key:
HTTP GET API
Structure: https://api.vdo.ninja/{apiKey}/{action}/{target}/{value}
Examples:
Server-Sent Events (SSE)
For monitoring events without sending commands:
API Commands Reference
Self-Targeted Commands
These commands affect the local VDO.Ninja instance that has the API key enabled.
mic
true
, false
, toggle
Control microphone state
camera
true
, false
, toggle
Control camera state
speaker
true
, false
, toggle
Control speaker state
volume
0
to 200
Set playback volume (percentage)
bitrate
Integer (kbps), -1
for auto
Set video bitrate
record
true
, false
Control local recording
hangup
N/A
Disconnect current session
reload
N/A
Reload the page
sendChat
Text string
Send a chat message
togglehand
N/A
Toggle raised hand status
togglescreenshare
N/A
Toggle screen sharing
forceKeyframe
N/A
Force video keyframes ("rainbow puke fix")
getDetails
N/A
Get detailed state information
getGuestList
N/A
Get list of connected guests with IDs
Layout Control Commands
layout
0
or false
Switch to auto-mixer layout
layout
Integer (1
, 2
, etc.)
Switch to specific predefined layout
layout
Layout object/array
Apply custom layout configuration
Camera Control (PTZ) Commands
zoom
-1.0
to 1.0
Adjust zoom level (relative)
zoom
0.0
to 1.0
with value2="abs"
Set absolute zoom level
focus
-1.0
to 1.0
Adjust focus (relative)
pan
-1.0
to 1.0
Adjust camera pan (negative=left)
tilt
-1.0
to 1.0
Adjust camera tilt (negative=down)
exposure
0.0
to 1.0
Adjust camera exposure
Group Communication Commands
group
1
to 8
Toggle participation in specified group
joinGroup
1
to 8
Join a specific group
leaveGroup
1
to 8
Leave a specific group
viewGroup
1
to 8
Toggle view of specified group
joinViewGroup
1
to 8
View a specific group
leaveViewGroup
1
to 8
Stop viewing a specific group
Timer Commands
startRoomTimer
Integer (seconds)
Start countdown timer for room
pauseRoomTimer
N/A
Pause the room timer
stopRoomTimer
N/A
Stop and reset the room timer
Presentation Control
nextSlide
N/A
Advance to next slide (for PowerPoint integration)
prevSlide
N/A
Go to previous slide
soloVideo
true
, false
, toggle
Highlight video for all guests
Director-Only Guest Commands
These commands target specific guests when you are the director.
forward
Guest ID/slot
Room name
Transfer guest to another room
addScene
Guest ID/slot
Scene ID (1-8)
Toggle guest in/out of scene
muteScene
Guest ID/slot
Scene ID
Toggle guest's audio in scene
mic
Guest ID/slot
true
, false
, toggle
Control guest's microphone
hangup
Guest ID/slot
N/A
Disconnect a specific guest
soloChat
Guest ID/slot
N/A
Private chat with guest
soloChatBidirectional
Guest ID/slot
N/A
Two-way private chat
speaker
Guest ID/slot
N/A
Toggle guest's speaker
display
Guest ID/slot
N/A
Toggle guest's display
forceKeyframe
Guest ID/slot
N/A
Fix video artifacts for guest
soloVideo
Guest ID/slot
N/A
Highlight specific guest's video
volume
Guest ID/slot
0
to 100
Set guest's microphone volume
mixorder
Guest ID/slot
-1
or 1
Change guest's position in mixer
Target Parameter Explanation
When using director commands, you can specify targets in two ways:
Slot number: Simple integers like
1
,2
,3
(corresponds to position in room)Stream ID: The unique ID for a specific guest (more reliable as slots can change)
Examples:
Callbacks and Responses
API commands receive callbacks with the current state after execution:
Custom Layout Format
The layout API supports complex scene configurations. Layouts can be arrays of objects with properties:
Layout object properties:
x
,y
: Position (percentage of canvas)w
,h
: Width and height (percentage)slot
: Which video slot to display (0-indexed)z
: Z-index for layering (optional)c
: Cover mode (true/false, optional)
Implementation Examples
Python Example
JavaScript HTTP Example
Integration with Automation Tools
The API integrates well with:
Stream Deck: Can use HTTP requests for button actions
Node-RED: Great for complex automation workflows
Home Assistant: For smart home integration
Security Considerations
Keep your API key private
Consider using unique keys for different productions
The API has full control over the VDO.Ninja instance it's connected to
All connections are encrypted over SSL/TLS
Troubleshooting
Ensure the API key matches exactly between VDO.Ninja and your requests
For WebSocket connections, implement reconnection logic (connections timeout after ~1 minute of inactivity)
When using HTTP API, a
timeout
response means the request couldn't reach the target
Additional Resources
For Python implementations: See the Python sample in the repository
Advanced Usage: Self-Hosting the API
For production environments, you can self-host the API server:
Clone the repository from GitHub
Install dependencies with
npm install
Modify the server URL in your VDO.Ninja instances:
Run the server with proper SSL certificates
Note: Self-hosting support is limited and should only be attempted by experienced developers.
Last updated
Was this helpful?