VDO.Ninja SDK — API Reference

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

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)

Connection

• connect(), disconnect()
• 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? })
• 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?) — flexible targeting with DC and fallback
• sendPing(uuid?)
• request(type, data, targetUUID, timeout?), respond(id, data, targetUUID)
• onRequest(type, handler)

Pub/Sub

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

Utilities & Aliases

• getStats(uuid?)
• 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

Events (Selected)

• Connection: connected, disconnected, reconnecting, reconnected, reconnectFailed
• Room: roomJoined, roomLeft, listing, peerListing
• Peer/DC: peerConnected, peerDisconnected, dataChannelOpen, dataChannelClose, peerInfo, peerLatency
• Data: dataReceived (dataRecieved alias), data
• 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.