Connect your application to VDO.Ninja

Use the JavaScript SDK for a custom camera viewer, broadcast control panel, browser-to-browser messaging, or Node.js media automation. Use VDO.Ninja's iframe API when you want to embed and control its existing interface. Python and Flutter integrations are separate projects; they are not runtimes of this npm package.

Two peers exchanging data

Load vdoninja-sdk.js in each browser page. For Node.js, install @vdoninja/sdk and a WebRTC implementation such as @roamhq/wrtc, then import require('@vdoninja/sdk/node').

Run the following in two peers, using the same unique room name. autoConnect connects signaling, joins the room, announces each peer with its own stream ID, and establishes data connections.

const vdo = new VDONinjaSDK({ salt: 'vdo.ninja' });
vdo.addEventListener('dataReceived', ({ detail }) => {
    console.log(detail.uuid, detail.data);
});
vdo.addEventListener('dataChannelOpen', ({ detail }) => {
    vdo.sendData({ message: 'Hello!' }, detail.uuid);
});
await vdo.autoConnect({ room: 'replace_with_a_shared_unique_room' });
// When finished: await vdo.disconnect();

connect() means signaling is open. joinRoom() means the room was joined. Neither means a peer can receive application data yet. Wait for dataChannelOpen and check the boolean returned by sendData. Application data is not queued for offline peers or stored by the signaling service.

Choose discovery and network options

half chooses which peer initiates each pair by comparing stream IDs, giving one bidirectional data connection per pair when both peers use compatible settings. Asymmetric filters can prevent that pair from connecting: for a selective viewer, use explicit view() or mode: 'full' with the desired filter. Avoid global/sticky regular expressions because their mutable lastIndex affects repeated matching.

A predicate receives { streamID, uuid, label }, but UUID/label can be missing in discovery events. Return a boolean synchronously; a thrown predicate skips that peer. A discovery filter controls outgoing connection attempts, not incoming access or command authorization. Authenticate and authorize application messages separately.

Keep the controller returned by autoConnect and call controller.stop() to remove its discovery listeners before replacing it. That method leaves current connections open. Call await vdo.disconnect() to tear down the SDK; stop captured media tracks separately when finished. See recovery options for retry timing and lifecycle events.

Publish video to a VDO.Ninja viewer

Run capture in a browser on HTTPS or localhost, with user permission:

const room = 'replace_with_your_unique_room';
const streamID = 'my_camera';
const password = 'your own shared password'; // Original text, not URL-encoded
const vdo = new VDONinjaSDK({ password, salt: 'vdo.ninja', host: 'wss://apibackup.vdo.ninja' });
const media = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
await vdo.connect();
await vdo.publish(media, { room, streamID });

const viewer = new URL('https://vdo.ninja/alpha/');
viewer.search = new URLSearchParams({
    view: streamID, room, password: encodeURIComponent(password),
    scene: '0', wss2: 'apibackup.vdo.ninja'
}).toString();
console.log('Open in the viewer browser:', viewer.href);

// When finished:
// media.getTracks().forEach(track => track.stop());
// await vdo.disconnect();

Both ends must agree on room, stream ID, password, salt, and signaling host. The SDK sanitizes room and stream IDs, replacing punctuation such as hyphens with underscores; use letters, numbers, and underscores to keep URLs predictable. A publisher that joined a room needs that room in its viewer URL. Use wss2 to select the matching VDO.Ninja signaling host.

VDO.Ninja decodes its password query value an extra time after parsing the URL. The encodeURIComponent(password) inside URLSearchParams above preserves literal sequences such as %20. That extra encoding is only for the viewer URL: always give the SDK the original password text.

Set salt: 'vdo.ninja' explicitly when hosting the SDK on your own domain and connecting to vdo.ninja. Without an explicit salt, the SDK derives it from the browser hostname. Omit the viewer's password parameter for the SDK's default password; use password: false and password=false together to disable signaling password encryption. A default password is shared, so choose your own for private applications.

Constructor and connect options treat null or an empty string as the shared default. The older joinRoom({ password: null }) behavior disables password hashing/encryption; use explicit false for that purpose and avoid passing null between APIs. Password encryption covers signaling metadata; WebRTC still encrypts media and data even when password encryption is disabled.

Requests and responses

request, respond, and onRequest are SDK application messages, not native VDO.Ninja remote-control commands. The responding peer must implement the SDK request handler. A request resolves only for a reply from its target UUID; handler errors reject it. Disconnecting cancels outstanding requests. Use the iframe API or documented remote-control API to control a VDO.Ninja page.

Troubleshooting

Hosted signaling coordinates connections. WebRTC encrypts media and data in transit; a TURN server may relay that encrypted traffic when direct connectivity fails. Peer bandwidth and room/service limits still apply. Large rooms and durable message history need application-level design beyond this SDK.

See the API reference, compatibility contract, and live interop tests.