@vdoninja/sdk

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>VDO.Ninja SDK — API Reference</title> <meta name="description" content="Complete API reference for VDO.Ninja SDK - methods, events, configuration options for P2P WebRTC communication."> <link rel="icon" type="image/svg+xml" href="../favicon.svg"> <link rel="icon" type="image/png" href="https://vdo.ninja/favicon.png"> <link rel="apple-touch-icon" href="https://vdo.ninja/apple-touch-icon.png"> <style> body { font-family: Arial, sans-serif; max-width: 900px; margin: 0 auto; padding: 24px; line-height: 1.5; color: #e0e0e0; background: #1a1a1a; } h1, h2, h3 { color: #fff; } code { background: #2a2a2a; padding: 2px 4px; border-radius: 4px; } pre { background: #2a2a2a; padding: 12px; border-radius: 6px; overflow: auto; } a { color: #4CAF50; } .tip { font-size: 14px; color: #bbb; } ul { margin-top: 6px; } </style> </head> <body> <h1>VDO.Ninja SDK — API Reference</h1> <p class="tip">Tip: avoid reserved SDK types (<code>subscribe</code> | <code>unsubscribe</code> | <code>channelMessage</code>) for custom protocols.</p> <p class="tip">For detailed option and event payloads, see the <a href="./api-reference.md">Markdown API reference</a>.</p> <h2>Constructor</h2> <pre><code>const vdo = new VDONinjaSDK(options)</code></pre> <ul> <li><b>host</b>: WebSocket URL (default: <code>wss://wss.vdo.ninja</code>)</li> <li><b>room</b>: Initial room to join (optional)</li> <li><b>password</b>: Room password or false to disable encryption</li> <li><b>label</b>: Optional human-readable label</li> <li><b>debug</b>: Enable verbose logs</li> <li><b>turnServers</b>: null=auto, false=disable, or custom ICE servers</li> <li><b>forceTURN</b>: Force relay mode (boolean)</li> <li><b>autoRecover</b>: Recover failed peer directions automatically (default: true)</li> <li><b>autoRelay</b>: Temporarily try TURN after direct recovery fails (default: true)</li> <li><b>disconnectGracePeriod</b>: Temporary ICE disconnect grace period (default: 5000 ms)</li> <li><b>connectionTimeout</b>: Initial peer connection timeout (default: 20000 ms)</li> <li><b>recoveryTimeout</b>: Wait between bounded recovery phases (default: 12000 ms)</li> <li><b>relayRestoreDelay</b>: Restore direct-first ICE policy after recovery (default: 45000 ms)</li> </ul> <h2>Connection</h2> <ul> <li><code>connect()</code> → <code>Promise<void></code></li> <li><code>disconnect()</code> → <code>Promise<void></code>; await it until peer, timer, and signaling cleanup genuinely finishes</li> <li><code>joinRoom({ room, password })</code>, <code>leaveRoom()</code></li> <li><code>autoConnect(roomOrOptions, filter?)</code> → <code>{ stop, streamID }</code></li> </ul> <h2>Publishing</h2> <ul> <li><code>publish(stream, { streamID, room?, label?, password? })</code></li> <li><code>announce({ streamID?, room?, label?, password? })</code></li> <li><code>stopPublishing()</code></li> </ul> <h2>Viewing</h2> <ul> <li><code>view(streamID, { audio=true, video=true, label?, downloads=true, allowresources=false })</code></li> <li><code>stopViewing(streamID)</code></li> </ul> <h2>Quick Helpers</h2> <ul> <li><code>quickPublish({ stream, room?, streamID?, label?, password? })</code></li> <li><code>quickView({ streamID, room?, audio?, video?, label?, password?, dataOnly? })</code></li> <li><code>quickSubscribe({ streamID, room?, ... })</code> (defaults to data-only)</li> </ul> <h2>Data Communication</h2> <ul> <li><code>sendData(data, target?)</code> — data-channel routing defaults to publisher first, then viewer. WebSocket signaling fallback is separate, disabled by default, and enabled with <code>{ allowFallback: true }</code>.</li> <li><code>sendBinary(data, uuid, options?)</code> — raw bytes on the reserved <code>x-bin</code> lane, never the control channel</li> <li><code>openChannel(uuid, label, options?)</code>, <code>getChannel(uuid, label)</code></li> <li><code>getBufferedAmount(uuid, label?)</code>, <code>getMaxMessageSize(uuid)</code></li> <li><code>sendPing(uuid?)</code></li> <li><code>request(type, data, targetUUID, timeout?)</code>, <code>respond(id, data, targetUUID)</code></li> <li><code>onRequest(type, handler)</code></li> </ul> <h2>Native File and Resource Transfer</h2> <ul> <li><code>hostFile(source, options?)</code>, <code>unhostFile(id)</code>, <code>getHostedFiles()</code></li> <li><code>requestFile(uuid, fileId, options?)</code> — receive bytes or stream <code>fileChunk</code> events</li> <li><code>sendResource(uuid, metadata, data)</code> — requires the peer to advertise <code>allowresources</code></li> <li>Events: <code>fileList</code>, <code>fileTransferStart</code>, <code>fileTransferProgress</code>, <code>fileChunk</code>, <code>fileTransferComplete</code>, <code>fileTransferCancelled</code>, <code>fileTransferError</code>, <code>resourceReceived</code></li> </ul> <h2>Pub/Sub</h2> <ul> <li><code>subscribe(channels)</code>, <code>unsubscribe(channels)</code>, <code>getSubscriptions()</code></li> <li><code>publishToChannel(channel, data, target='all')</code></li> <li><code>getPeerSubscriptions(uuid)</code></li> <li>Events: <code>channelMessage</code>, <code>peerSubscribed</code>, <code>peerUnsubscribed</code></li> </ul> <h2>Utilities & Aliases</h2> <ul> <li><code>getStats(uuid?)</code></li> <li><code>getPeerQuality(uuid)</code> — normalized RTT, loss, route, relay, bitrate, and byte metrics</li> <li>Aliases: <code>play|watch|startViewing → view</code>, <code>stream|broadcast|startPublishing|share → publish</code>, <code>quickStream|quickBroadcast|quickShare → quickPublish</code>, <code>stop|stopPlaying|stopWatching → stopViewing</code>, <code>stopStreaming|stopBroadcasting|stopSharing|unpublish → stopPublishing</code>, <code>join|enterRoom|enter → joinRoom</code>, <code>leave|exitRoom → leaveRoom</code></li> </ul> <h2>TypeScript</h2> <p>Browser and Node declarations ship with the package; no separate <code>@types</code> package is required. The root, <code>/browser</code>, and <code>/node</code> exports each resolve the matching declarations.</p> <h2>Events (Selected)</h2> <ul> <li>Connection: <code>connected</code>, <code>disconnected</code>, <code>teardownComplete</code>, <code>reconnecting</code>, <code>reconnected</code>, <code>reconnectFailed</code></li> <li>Recovery: <code>connectionRecovering</code>, <code>connectionRecovered</code>, <code>connectionFailed</code>, <code>relayEscalated</code>, <code>relayRestored</code></li> <li>Iframe-friendly aliases: <code>hss-connection</code>, <code>room-peer-listing</code>, <code>push-connection</code>, <code>view-connection</code></li> <li>Room: <code>roomJoined</code>, <code>roomLeft</code>, <code>listing</code>, <code>peerListing</code></li> <li>Peer/DC: <code>peerConnected</code>, <code>peerDisconnected</code>, <code>dataChannelOpen</code>, <code>dataChannelClose</code>, <code>peerInfo</code>, <code>peerLatency</code></li> <li>Data: <code>dataReceived</code> (<code>dataRecieved</code> alias), <code>data</code>, <code>binaryReceived</code>, <code>channelOpen</code>, <code>bufferedAmountLow</code>, <code>unsupportedChannel</code></li> <li>Media: <code>track</code>, <code>trackAdded</code>, <code>trackRemoved</code>, <code>trackReplaced</code></li> <li>State: <code>publishing</code>, <code>publishingStopped</code>, <code>viewingStopped</code>, <code>iceRestart</code>, <code>connectionFailed</code>, <code>alert</code>, <code>error</code></li> </ul> <h2>WHIP/WHEP Clients</h2> <p>Standalone clients for standard WebRTC-HTTP streaming protocols. Works independently of the VDO.Ninja P2P system.</p> <h3>WHIPClient (whip-client.js)</h3> <p>Publish media streams to WHIP-compatible endpoints (Twitch, Meshcast, Cloudflare, etc.)</p> <pre><code>const client = new WHIPClient(endpoint, options)</code></pre> <ul> <li><b>endpoint</b>: WHIP endpoint URL (required)</li> <li><b>authToken</b>: Bearer token for authentication</li> <li><b>videoCodec</b>: Preferred codec ('h264', 'vp8', 'vp9', 'av1')</li> <li><b>videoBitrate</b>: Target video bitrate in kbps</li> <li><b>audioBitrate</b>: Target audio bitrate in kbps</li> <li><b>trickleIce</b>: Enable trickle ICE (default: true)</li> </ul> <p>Methods:</p> <ul> <li><code>publish(stream)</code> — Publish a MediaStream</li> <li><code>replaceTrack(oldTrack, newTrack)</code> — Replace a track mid-session</li> <li><code>stop()</code> — Stop publishing and cleanup</li> <li><code>getStats()</code> — Get RTCStatsReport</li> <li><code>restartIce()</code> — Restart ICE connection</li> </ul> <p>Events: <code>connecting</code>, <code>connected</code>, <code>icestate</code>, <code>connectionstate</code>, <code>error</code>, <code>disconnected</code>, <code>stopped</code></p> <h3>WHEPClient (whep-client.js)</h3> <p>Consume media streams from WHEP-compatible endpoints.</p> <pre><code>const client = new WHEPClient(endpoint, options)</code></pre> <ul> <li><b>endpoint</b>: WHEP endpoint URL (required)</li> <li><b>authToken</b>: Bearer token for authentication</li> <li><b>audio</b>: Request audio track (default: true)</li> <li><b>video</b>: Request video track (default: true)</li> <li><b>trickleIce</b>: Enable trickle ICE (default: true)</li> </ul> <p>Methods:</p> <ul> <li><code>view()</code> — Start viewing, returns MediaStream</li> <li><code>getStream()</code> — Get the received MediaStream</li> <li><code>muteAudio(muted)</code>, <code>muteVideo(muted)</code> — Mute locally</li> <li><code>stop()</code> — Stop viewing and cleanup</li> <li><code>getStats()</code> — Get RTCStatsReport</li> </ul> <p>Events: <code>connecting</code>, <code>connected</code>, <code>track</code>, <code>icestate</code>, <code>connectionstate</code>, <code>error</code>, <code>disconnected</code>, <code>stopped</code></p> <h3>Supported Services</h3> <ul> <li><b>Meshcast.io</b>: <code>https://cae1.meshcast.io/whip/{id}</code> / <code>https://cae1.meshcast.io/whep/{id}</code></li> <li><b>Twitch</b>: <code>https://g.webrtc.live-video.net:4443/v2/offer</code> (WHIP only)</li> <li><b>Cloudflare Stream</b>: Your Stream WHIP/WHEP endpoint</li> <li><b>Dolby.io</b>: Your Dolby WHIP/WHEP endpoint</li> </ul> <p>See <a href="../README.md">README</a> and <a href="../demos/index.html">demos</a> for examples.</p> </body> </html>