Native SDKs: Go, Rust, C, Python, Flutter, Android and Swift

The JavaScript SDK (vdoninja-sdk.js) is the reference implementation of the VDO.Ninja client protocol. This repository also ships native SDKs that implement the same protocol on top of established WebRTC engines, so applications written in Go, Rust, C or Python, and mobile apps in Flutter, Kotlin/Java or Swift, can publish to and view from browsers running VDO.Ninja, talk to each other, and use the hosted signaling and TURN infrastructure the same way the JavaScript SDK does.

The Flutter, Android and Swift SDKs are the "mobile basics": the same signaling, hashing, encryption, publishing, viewing, data channels, pub/sub and request/response as the others, with media supplied by the platform's own capture APIs. They deliberately leave out file transfer, resources, reserved-channel helpers, WHIP/WHEP and screen capture. Each is split into a protocol core that is unit-tested against the shared vectors without WebRTC (vdoninja_core, vdoninja-core, VDONinjaCore) and a thin engine layer.

All of them share one conformance suite: spec/vectors.json is generated from the JavaScript SDK (spec/generate-vectors.cjs) and every native SDK tests its hashing, encryption and sanitization against it. spec/interop/run_interop.py runs every publisher/viewer language pair, including the Node build of the JavaScript SDK, against a local signaling server.

Feature matrix

"reconnects" means the engine lacks ICE restart, so a failed connection is torn down and re-requested from the publisher instead; the application sees peerDisconnected and connectionFailed followed by a fresh peerConnected.

Connection lifecycle (all SDKs, as in the JavaScript SDK)

• A peer connection that fails or stays disconnected past the grace period gets one bounded recovery attempt (iceRestart: the publisher sends an ICE-restart offer over signaling, a viewer asks the publisher with iceRestartRequest). If it is still down after the connection timeout the SDK closes it and emits peerDisconnected then connectionFailed; viewers then re-request the stream after 2 s.
• bye from a peer closes both directions and, on the viewer side, re-requests the stream after 2 s. hangup closes without retrying: the peer ended the session on purpose.
• view() of a publisher that is not online yet fails with the SDK's "not yet available" error, keeps the request pending (a videoaddedtoroom or someonejoined connects it) and re-sends play every viewRetryInterval (15 minutes by default).
• disconnect() drops the connection intent (room, publish, views): a later connect() starts clean and an unexpected socket drop after it replays nothing. An unexpected drop while connected reconnects with exponential backoff and replays room, seed and views; the attempt counter resets on a manual connect().

Interoperability

spec/interop/run_interop.py connects every publisher/viewer pair over a local signaling server and exchanges data-channel probes and one request/response. All pairs between the JavaScript (Node), Go, C, Rust and Python SDKs pass, with one known engine limitation: a Rust publisher cannot be viewed by the Python SDK. The rtc crate initiates the SCTP association only when it is the DTLS client and aiortc only when it is ICE-controlling; with Rust offering, neither side sends the SCTP INIT. Browsers, pion and libdatachannel initiate from either role, so every other combination works, including Python publishing to Rust. Use another engine on one side if you need that direction. The JavaScript peer in the matrix needs node-datachannel 0.27 or newer (older builds generate DTLS certificates that aiortc rejects).

Protocol summary

The native SDKs implement the routed VDO.Ninja signaling protocol used by wss.vdo.ninja (the "wss2" format). Everything below is what the JavaScript SDK does; the native SDKs mirror it so they are indistinguishable to the server and to browser peers.

• Sanitization. Stream IDs: [^A-Za-z0-9_]+ runs become _, at most 64 characters, generated (12 random alphanumerics) when empty. Rooms: same rule, at most 30 characters. Passwords: trimmed and encodeURIComponent-encoded. Labels: line breaks removed, at most 100 characters.
• Hashing. With a password P and salt S (default vdo.ninja), published stream IDs on the wire are streamID + sha256(P+S)[:6] and room IDs are sha256(room+P+S)[:16]. The default password is someEncryptionKey123; password: false disables hashing and encryption entirely.
• Encryption. SDP and ICE candidates are JSON-serialized and encrypted with AES-256-CBC (PKCS#7), key sha256(P+S), random 16-byte IV, both sent as hex (description/candidates plus vector).
• Requests. joinroom {roomid, claim?, streamID?} → listing {list, director?, claim?}; {leave: true} leaves the room; seed {streamID} registers a publisher (one publish per signaling connection; reconnect to change it); play {streamID} asks the server to find the publisher, which receives offerSDP {UUID}; room members receive videoaddedtoroom and someonejoined; alert/error carry text.
• Routing. Any message with a UUID is forwarded to that peer with UUID rewritten to the sender. Offers carry {UUID, session (8 chars), streamID (hashed), description, vector}; answers echo session and streamID; candidates are {UUID, type: "remote" (viewer → publisher) | "local" (publisher → viewer), candidates, vector, session}, bundled with a 70 ms timer that doubles up to 1 s, and sent over the control channel once it is open. bye/hangup end a connection (viewers retry the stream after bye, not after hangup).
• Control channel. The publisher creates sendChannel. The viewer sends {audio, video, downloads, info:{label}, allowresources}; the publisher sends {info:{label, meta, ...}}. ping/pong, pipe (application data), bye, videoMuted, iceRestartRequest, fileList/requestFile and obsState share the channel. pipe payloads with type subscribe, unsubscribe, channelMessage, request or response implement pub/sub and RPC; everything else is delivered as dataReceived.
• Other channels. File transfers use a channel labeled with the file ID: a text header {type:"filetransfer", size, filename, id}, 16 KiB binary chunks, then EOF1 (complete) or EOF2 (cancelled). x- labels are reserved for applications (x-bin is the binary lane); resources carries VDO.Ninja overlay resources; chunked is VDO.Ninja's own chunked transfer and is reported as unsupported.
• TURN. GET https://turnservers.vdo.ninja/?ts=… returns {servers:[{username, credential, urls, tz, udp}]}. Clients pick the two closest UDP relays and one TCP relay by time-zone distance; a built-in list is the fallback.

Hosted service and licensing

The native SDKs are licensed under MPL-2.0 (examples and WHIP/WHEP helpers under MIT), the same terms as the JavaScript SDK core; see LICENSING.md. The mobile SDKs were written from the JavaScript SDK's protocol and verified against the shared vectors; they contain no code from the VDO.Ninja mobile apps. VDO.Ninja itself is AGPL-3.0; these SDKs are independent implementations of its client protocol and do not include VDO.Ninja code.

Connecting to wss.vdo.ninja and the hosted TURN servers is subject to the VDO.Ninja Terms of Service. The SDKs are the supported way to use that infrastructure: only WebRTC handshake data may pass through the signaling server, application data must travel over peer connections, and rate limits apply. Talking to the hosted servers with a custom client that is not one of these SDKs requires permission. For LAN or offline use, run the included vdoninja-signal server or websocket_server.