WebRTC data notes
Operational constraints of VDO.Ninja's peer-to-peer data channels, drawn from the VDO.Ninja SDK documentation, and how Ninja MCP builds on them. These notes cover the default WebRTC transport. The optional HTTP relay is a separate transport with its own limits.
Platform constraints
- Signaling is not an app-data tunnel.
- Only handshake and signaling data should cross the WebSocket.
- Application payloads are expected over WebRTC data channels.
- Room size is bounded.
- The documented guidance is about 80 peers per room, and viewer limits can apply.
- For wider fan-out, split rooms or use a server-mediated pattern.
- The network is serverless for app data.
- VDO.Ninja doesn't relay or store your application protocol on its servers.
- Design peer to peer first. Ninja MCP's HTTP relay is a separate service you run yourself.
Topologies that work
- Two-peer data link (recommended).
- Peer A:
announce({ streamID }) - Peer B:
view(streamID, { audio: false, video: false }) - Result: one bidirectional data channel.
- Peer A:
- Multi-peer data mesh.
- Use
autoConnect(room)half-mesh mode to avoid duplicate pair connections. - Move to a full mesh only when media exchange needs two directional audio/video links.
- Use
- Targeted delivery.
- Use
sendData(data, "uuid")or an advanced target object. - Keep
preference: "any"unless you specifically need publisher-only, viewer-only, or all-channel behavior.
- Use
Delivery semantics
- The SDK's default data channels are reliable and ordered.
- That reliability applies once a channel is established. It doesn't guarantee every network can establish one.
- TURN improves the chance of connecting through restrictive NAT and firewalls, but doesn't guarantee reachability.
- Ninja MCP adds application-level reliability for file transfer:
- SHA-256 validation of every chunk and of the whole file
- ACK and NACK feedback with retries
- resume from
next_seqafter an interruption
Firewalls and NAT
- Use TURN when needed.
forceTURN: trueroutes connections through relay infrastructure.- This helps on restrictive networks but adds latency and relay cost.
- Treat signaling fallback as a last resort.
allowFallback: trueletssendDatafall back to the signaling server when no peer-to-peer channel is open.- Use it for small control messages, not sustained throughput.
- Expect some networks to fail.
- Some enterprise, WSL, and other network setups block WebRTC's UDP traffic entirely.
- Build retry and reconnection logic regardless of TURN, or use the HTTP relay.
Keep-alive and continuity
- Keep a heartbeat.
- Send lightweight, periodic application-level heartbeats.
- Optionally send SDK pings (
sendPing) to connected peers.
- Reconnect predictably.
- On disconnect or error, recreate the SDK instance, reconnect, rejoin the room, re-announce, and re-view targets.
- Make handlers idempotent so duplicate or delayed messages around a reconnect are harmless.
- Use canonical IDs.
- Room and stream IDs should use letters, numbers, and underscores.
- Use the same sanitized IDs on every peer.
Data bridge settings
The standalone bridge script scripts/vdo-data-bridge.js reads these environment variables:
VDON_ROOM: required in real deploymentsVDON_STREAM_ID: optional; random if omittedVDON_TARGET_STREAM_ID: optional; views that peer's stream for a two-peer linkVDON_HOST: defaultwss://wss.vdo.ninjaVDON_PASSWORD:falsedisables handshake encryption; omitted uses the SDK defaultVDON_FORCE_TURN:trueorfalseVDON_LABEL: optional display labelVDON_HEARTBEAT_MS: default15000VDON_RECONNECT_MS: default3000VDON_MAX_RECONNECT_MS: default30000VDON_DEBUG:trueorfalse
Application envelopes
Use explicit envelope types and IDs rather than raw strings:
{
"type": "mcp.request",
"id": "req_123",
"method": "tool.call",
"payload": { "name": "lookup", "args": { "q": "abc" } }
}
{
"type": "mcp.response",
"id": "req_123",
"ok": true,
"payload": { "result": "..." }
}
Avoid the SDK's reserved pub/sub types (subscribe, unsubscribe, channelMessage) for custom envelopes.
Ninja MCP's protocol envelopes
Ninja MCP reserves envelopes that carry:
__vdo_mcp: "vdo_mcp_bridge_v1"kind: "sync.*" | "file.*" | "state.*"
File transfer handshake:
file.offerfile.acceptfile.chunk, answered byfile.ackorfile.nackfile.completefile.complete_ack
Resume flow:
file.resume_reqfile.resume_state, carryingnext_seq
Large files
- Ninja MCP can spool large incoming transfers to disk.
- Tune spooling with these
vdo_connectoptions:file_spool_dirfile_spool_threshold_byteskeep_spool_files
- Use
vdo_file_send_pathto avoid base64 memory overhead for large local files. - Use
vdo_file_saveto write completed incoming transfers straight to disk.