VDO.Ninja SDK — API Reference

Tip: avoid reserved SDK types (subscribe | unsubscribe | channelMessage) for custom protocols.

For detailed option and event payloads, see the Markdown API reference.

Constructor

const vdo = new VDONinjaSDK(options)

• host: WebSocket URL (default: wss://wss.vdo.ninja)
• room: Initial room to join (optional)
• password: Room password or false to disable encryption
• label: Optional human-readable label
• debug: Enable verbose logs
• turnServers: null=auto, false=disable, or custom ICE servers
• forceTURN: Force relay mode (boolean)
• autoRecover: Recover failed peer directions automatically (default: true)
• autoRelay: Temporarily try TURN after direct recovery fails (default: true)
• disconnectGracePeriod: Temporary ICE disconnect grace period (default: 5000 ms)
• connectionTimeout: Initial peer connection timeout (default: 20000 ms)
• recoveryTimeout: Wait between bounded recovery phases (default: 12000 ms)
• relayRestoreDelay: Restore direct-first ICE policy after recovery (default: 45000 ms)

Connection

• connect() → Promise<void>
• disconnect() → Promise<void>; await it until peer, timer, and signaling cleanup genuinely finishes
• joinRoom({ room, password }), leaveRoom()
• autoConnect(roomOrOptions, filter?) → { stop, streamID }

Publishing

• publish(stream, { streamID, room?, label?, password? })
• announce({ streamID?, room?, label?, password? })
• stopPublishing()

Viewing

• view(streamID, { audio=true, video=true, label?, downloads=true, allowresources=false })
• stopViewing(streamID)

Quick Helpers

• quickPublish({ stream, room?, streamID?, label?, password? })
• quickView({ streamID, room?, audio?, video?, label?, password?, dataOnly? })
• quickSubscribe({ streamID, room?, ... }) (defaults to data-only)

Data Communication

• sendData(data, target?) — data-channel routing defaults to publisher first, then viewer. WebSocket signaling fallback is separate, disabled by default, and enabled with { allowFallback: true }.
• sendBinary(data, uuid, options?) — raw bytes on the reserved x-bin lane, never the control channel
• openChannel(uuid, label, options?), getChannel(uuid, label)
• getBufferedAmount(uuid, label?), getMaxMessageSize(uuid)
• sendPing(uuid?)
• request(type, data, targetUUID, timeout?), respond(id, data, targetUUID)
• onRequest(type, handler)

Native File and Resource Transfer

• hostFile(source, options?), unhostFile(id), getHostedFiles()
• requestFile(uuid, fileId, options?) — receive bytes or stream fileChunk events
• sendResource(uuid, metadata, data) — requires the peer to advertise allowresources
• Events: fileList, fileTransferStart, fileTransferProgress, fileChunk, fileTransferComplete, fileTransferCancelled, fileTransferError, resourceReceived

Pub/Sub

• subscribe(channels), unsubscribe(channels), getSubscriptions()
• publishToChannel(channel, data, target='all')
• getPeerSubscriptions(uuid)
• Events: channelMessage, peerSubscribed, peerUnsubscribed

Utilities & Aliases

• getStats(uuid?)
• getPeerQuality(uuid) — normalized RTT, loss, route, relay, bitrate, and byte metrics
• Aliases: play|watch|startViewing → view, stream|broadcast|startPublishing|share → publish, quickStream|quickBroadcast|quickShare → quickPublish, stop|stopPlaying|stopWatching → stopViewing, stopStreaming|stopBroadcasting|stopSharing|unpublish → stopPublishing, join|enterRoom|enter → joinRoom, leave|exitRoom → leaveRoom

TypeScript

Browser and Node declarations ship with the package; no separate @types package is required. The root, /browser, and /node exports each resolve the matching declarations.

Events (Selected)

• Connection: connected, disconnected, teardownComplete, reconnecting, reconnected, reconnectFailed
• Recovery: connectionRecovering, connectionRecovered, connectionFailed, relayEscalated, relayRestored
• Iframe-friendly aliases: hss-connection, room-peer-listing, push-connection, view-connection
• Room: roomJoined, roomLeft, listing, peerListing
• Peer/DC: peerConnected, peerDisconnected, dataChannelOpen, dataChannelClose, peerInfo, peerLatency
• Data: dataReceived (dataRecieved alias), data, binaryReceived, channelOpen, bufferedAmountLow, unsupportedChannel
• Media: track, trackAdded, trackRemoved, trackReplaced
• State: publishing, publishingStopped, viewingStopped, iceRestart, connectionFailed, alert, error

WHIP/WHEP Clients

Standalone clients for standard WebRTC-HTTP streaming protocols. Works independently of the VDO.Ninja P2P system.

WHIPClient (whip-client.js)

Publish media streams to WHIP-compatible endpoints (Twitch, Meshcast, Cloudflare, etc.)

const client = new WHIPClient(endpoint, options)

• endpoint: WHIP endpoint URL (required)
• authToken: Bearer token for authentication
• videoCodec: Preferred codec ('h264', 'vp8', 'vp9', 'av1')
• videoBitrate: Target video bitrate in kbps
• audioBitrate: Target audio bitrate in kbps
• trickleIce: Enable trickle ICE (default: true)

Methods:

• publish(stream) — Publish a MediaStream
• replaceTrack(oldTrack, newTrack) — Replace a track mid-session
• stop() — Stop publishing and cleanup
• getStats() — Get RTCStatsReport
• restartIce() — Restart ICE connection

Events: connecting, connected, icestate, connectionstate, error, disconnected, stopped

WHEPClient (whep-client.js)

Consume media streams from WHEP-compatible endpoints.

const client = new WHEPClient(endpoint, options)

• endpoint: WHEP endpoint URL (required)
• authToken: Bearer token for authentication
• audio: Request audio track (default: true)
• video: Request video track (default: true)
• trickleIce: Enable trickle ICE (default: true)

Methods:

• view() — Start viewing, returns MediaStream
• getStream() — Get the received MediaStream
• muteAudio(muted), muteVideo(muted) — Mute locally
• stop() — Stop viewing and cleanup
• getStats() — Get RTCStatsReport

Events: connecting, connected, track, icestate, connectionstate, error, disconnected, stopped

Supported Services

• Meshcast.io: https://cae1.meshcast.io/whip/{id} / https://cae1.meshcast.io/whep/{id}
• Twitch: https://g.webrtc.live-video.net:4443/v2/offer (WHIP only)
• Cloudflare Stream: Your Stream WHIP/WHEP endpoint
• Dolby.io: Your Dolby WHIP/WHEP endpoint

See README and demos for examples.