IFRAME API Basics
Understanding the VDO.Ninja IFRAME API: Detecting User Joins and Disconnects
The VDO.Ninja IFRAME API allows websites to embed and interact with VDO.Ninja streams. One of the most useful features is the ability to detect when users join or disconnect from your stream through event messaging. This guide will explain how to implement this functionality in your own projects.
How the IFRAME API Works
VDO.Ninja's IFRAME API uses the browser's postMessage API to communicate between your parent website and the embedded VDO.Ninja iframe. This allows you to:
Send commands to control the VDO.Ninja instance
Receive events and data from the VDO.Ninja instance
Setting Up the Basic Structure
irst, you need to create an iframe that loads VDO.Ninja:
// Create the iframe element
var iframe = document.createElement("iframe");
// Set necessary permissions
iframe.allow = "camera;microphone;fullscreen;display-capture;autoplay;";
// Set the source URL (your VDO.Ninja room)
iframe.src = "https://vdo.ninja/?room=your-room-name&cleanoutput";
// Add the iframe to your page
document.getElementById("container").appendChild(iframe);Setting Up the Event Listener
To detect joins and disconnects, you need to set up an event listener for messages from the iframe:
Detecting User Joins and Disconnects
The key events to watch for are:
Guest Connections
Disconnections
Complete Working Example
Here's a complete example that demonstrates detecting joins and disconnects:
Waiting Room Example
You can implement a waiting room like the one in the waitingroom.html file from your code samples:
Getting Additional Information About Connections
For more detailed information about connections, you can use the getStreamIDs or getDetailedState commands:
Best Practices
Always check the source: Make sure messages are coming from your VDO.Ninja iframe.
Handle disconnections gracefully: Sometimes connections drop unexpectedly.
Consider implementing reconnection logic: If important users disconnect, you might want to notify them or attempt to reconnect.
Debug with console.log: Log all events during development to understand the full message flow.
Test with multiple users: The behavior can be different depending on who connects first.
By implementing these techniques, you can build sophisticated applications that respond to users joining and leaving your VDO.Ninja sessions, creating more interactive and responsive experiences.
VDO.Ninja IFRAME API - Complete Inbound Control Reference
This document provides a comprehensive list of all inbound remote control calls available through the VDO.Ninja IFRAME API. These commands allow you to control a VDO.Ninja instance embedded in an iframe from your parent webpage.
Table of Contents
Basic Usage
To send commands to the VDO.Ninja iframe:
Audio Controls
mic - Microphone Control
Controls the local microphone mute state.
mute / speaker - Speaker Control
Controls the speaker mute state (incoming audio).
volume - Volume Control
Sets the volume level for incoming audio (0.0 to 1.0).
panning - Audio Panning
Adjusts stereo panning for incoming audio.
targetAudioBitrate - Audio Bitrate Target
Sets the target audio bitrate (in kbps).
audiobitrate - Audio Bitrate Control
Changes the audio bitrate with optional lock.
PPT - Push-to-Talk
Controls push-to-talk functionality.
Video Controls
camera - Camera Control
Controls the local camera on/off state.
pauseinvisible - Pause Invisible Videos
Controls whether videos hidden in the mixer are paused.
keyframe - Request Keyframe
Forces a keyframe to be sent to all scene connections.
Stream Management
requestStream - Request Specific Stream
Loads a specific stream by ID.
close / hangup - Disconnect Streams
Disconnects and hangs up connections.
Recording Controls
record - Local Recording Control
Controls local video recording.
Group Management
groups - Set Groups
Sets the groups for the local stream.
groupView - Set View Groups
Sets which groups are visible.
Bitrate & Quality Controls
bitrate - Video Bitrate Control
Sets video bitrate for streams (in kbps).
targetBitrate - Target Video Bitrate
Sets the fundamental bitrate target.
manualBitrate - Manual Bandwidth Control
Sets manual bandwidth limits.
scale - Resolution Scaling
Controls resolution scaling.
targetWidth / targetHeight - Resolution Request
Request specific resolution from remote connection.
Device Management
changeVideoDevice - Change Camera
Changes the active video input device.
changeAudioDevice - Change Microphone
Changes the active audio input device.
changeAudioOutputDevice - Change Speaker
Changes the audio output device.
getDeviceList - List Available Devices
Requests a list of available media devices.
Layout & Display Controls
layout - Set Layout
Sets the display layout.
previewMode - Switch Preview Mode
Switches between preview modes.
slotmode - Slot Mode Control
Controls slot mode behavior.
advancedMode - Toggle Advanced UI
Shows/hides advanced UI elements.
toggleSettings - Toggle Settings Panel
Controls the settings panel visibility.
target - DOM Manipulation
Manipulates video elements in the DOM.
Data & Messaging
sendData - Send Generic Data
Sends data through peer connections.
sendChat - Send Chat Message
Sends a chat message to all peers.
sendMessage - WebRTC Message to Viewers
Sends a message to viewer connections.
sendRequest - WebRTC Request to Publishers
Sends a request to publisher connections.
sendPeers - Message All Peers
Sends a message to all connected peers.
sendRawMIDI - Send MIDI Data
Sends raw MIDI messages.
Statistics & Monitoring
getStats - Get Quick Stats
Requests current statistics.
getFreshStats - Get Detailed Stats
Requests detailed statistics (takes ~1 second).
getRemoteStats - Request Remote Stats
Requests statistics from remote peers.
requestStatsContinuous - Continuous Stats
Enables/disables continuous statistics updates.
getLoudness - Audio Loudness Monitoring
Enables/disables loudness monitoring.
Notes:
Loudness push is opt-in and off by default.
Call
getLoudness: trueonce to subscribe.&pushloudness(or&getloudness) in the iframe URL also enables loudness push.The first message is a snapshot (
mode: "snapshot"), then continuous updates arrive asmode: "update".Loudness messages use
action: "loudness"and include aloudnessobject.cibis echoed only if you provide it on the subscribe request.Avoid polling
getLoudnesson an interval.
getStreamIDs - List Stream IDs
Gets a list of all connected stream IDs.
getStreamInfo - Detailed Stream Information
Gets detailed information about all streams.
getDetailedState - Complete State Information
Gets comprehensive state information.
For chunked viewer integrations, each remote stream entry can include:
chunkedBufferDefault- the current inherited/default chunked playout requestchunkedBufferOverride- an explicit per-stream buffer override, if one is setchunkedBufferRequested- the effective requested value for that stream before live adaptationchunkedBufferCeil- the configured viewer-side ceiling for chunked playoutchunkedBufferAdaptive- whether adaptive chunked target adjustments are enabled
getGuestList - Get Guest List
Gets a list of all connected guests.
Utility Functions
reload - Reload Page
Forces a page reload.
style - Inject Custom CSS
Injects custom CSS into the iframe.
function - Execute Built-in Functions
Executes predefined functions.
saveVideoFrameToDisk - Save Screenshot
Saves a video frame to disk.
getVideoFrame - Get Video Frame Data
Gets video frame data as base64.
copyVideoFrameToClipboard - Copy Screenshot
Copies a video frame to clipboard.
getSnapshotBySlot / getSnapshotByStreamID - Get Slot/Stream Snapshot
Gets a snapshot from a specific slot or stream using MediaStreamTrackProcessor.
Advanced Controls
sceneState - OBS Scene State
Sets the scene state for OBS integration.
layouts - OBS Layout Sync
Syncs layouts with OBS.
obsCommand - OBS Commands
Sends commands to OBS.
setBufferDelay - Audio/Video Buffer Delay
Sets the buffer delay in milliseconds.
Keeping audio synchronized: for normal WebRTC streams, load the viewer iframe with &sync=0 before connecting, for example https://vdo.ninja/?view=streamID123&sync=0. This enables Web Audio compensation so audio can follow subsequent buffer changes. The API message alone does not enable that processing path.
This is entirely viewer-side; the publisher does not need any changes. Neither &buffer2 nor chunked publishing is required. sync=0 means compensation with no extra fixed audio offset, not synchronization disabled. Changes may take time to settle and are not guaranteed to be frame accurate.
Notes:
Sending
setBufferDelaywithoutstreamID,UUID, orlabelupdates the viewer's default requested buffer.Sending it with
streamID,UUID, orlabelcreates/updates an explicit per-stream override.For normal WebRTC, native receiver buffer hints are clamped to 0-4000 ms. Larger requests are not a way to extend native video buffering and can leave separately delayed audio out of sync. See
&syncfor audio-node limits and negative-offset examples; negative sync reduces available added audio delay rather than providing negative latency.UUID: "*"fans the same request out to all currently connected streams when nostreamIDorlabelis supplied. A suppliedstreamIDtakes precedence, so omit it when targeting every stream.For chunked video workflows, the live target can still differ from the requested value if adaptive buffering is enabled.
If you need a fixed long-delay video target, load the viewer with:
That pattern is useful for music-sync tools where the audio is handled externally and VDO.Ninja is only delaying video to match it.
automixer - Automixer Control
Controls the automatic mixer behavior.
enableYouTube - YouTube Chat Integration
Enables YouTube chat integration.
nextSlide / prevSlide - Slide Navigation
Controls slide navigation.
getFaces / faceTrack - Face Detection
Controls face detection/tracking.
getEffectsData - Effects Data
Gets data from visual effects (face tracking, etc.).
action - Companion API Actions
Executes Companion API actions.
Response Handling
Many commands support a callback ID (cib) for tracking responses:
Notes
All commands are sent via
postMessageto the iframe'scontentWindowThe second parameter
"*"can be replaced with a specific origin for securitySome commands require director privileges to function
Commands that affect remote streams often accept
UUID,streamID, ortargetparametersThe
lockparameter on bitrate controls prevents automatic adjustmentsMany "get" commands return data via postMessage back to the parent window
Last updated
Was this helpful?