lib/webrtc

Peer-connection side of the WebRTC transport.

The server offers and the client answers. The offer arrives through lib/signaling.js; the answer is munged before it becomes the local description (sps-pps-idr-in-keyframe=1 on the H.264 line, and on the Opus line stereo=1 plus a minptime matching the server's a=ptime, which is how audio frames shorter than 10 ms get through) and ICE candidates are exchanged the same way, non-relay ones dropped when forceTurn is set. The server's video and audio arrive as media tracks on the given element; the audio and video m-lines it offers recvonly are reserved as sendonly transceivers for the microphone and the webcam, which are attached later with replaceTrack and no renegotiation.

Everything else rides the two data channels the server creates: input and control upstream through sendDataChannelMessage on the ordered input channel, coalesced pointer motion through sendMotionMessage on the unordered pointer channel, JSON messages downstream, routed by type to the on* callbacks (pipeline, stream_info, stream_stats, cursor, system, ping, latency_measurement, server_settings, display_config_update and clipboard-msg*). Either side may gzip a message once the _gz,1 handshake has been exchanged; the multipart clipboard and server_settings kinds keep their arrival order across asynchronous inflation, the rest route as soon as they are readable.

Classes

WebRTCClient

Defined in: lib/webrtc.js:69

WebRTC client: one peer connection plus its data channel.

Callbacks are assigned as properties: onstatus, ondebug and onerror receive messages, onconnectionstatechange the peer connection state, ondatachannelopen and ondatachannelclose nothing, onplaystreamrequired fires when autoplay was refused and a user gesture is needed, and onclipboardcontent, oncursorchange, onsystemaction, onstreaminfo, onstreamstats, onlatencymeasurement, onserversettings and ondisplayconfig receive the payload of the data channel message of the same kind.

Constructors

Constructor

new WebRTCClient(
   signaling, 
   element, 
   peer_id
): WebRTCClient;

Defined in: lib/webrtc.js:75

Parameters

Returns

WebRTCClient

Properties

signaling

signaling: WebRTCSignaling;

Defined in: lib/webrtc.js:77

element

element: HTMLVideoElement;

Defined in: lib/webrtc.js:80

peer_id

peer_id: number;

Defined in: lib/webrtc.js:83

forceTurn

forceTurn: boolean;

Defined in: lib/webrtc.js:86

Accept only relay ICE candidates and force iceTransportPolicy to relay.

rtcPeerConfig

rtcPeerConfig: any;

Defined in: lib/webrtc.js:89

Configuration handed to RTCPeerConnection.

peerConnection

peerConnection: RTCPeerConnection;

Defined in: lib/webrtc.js:103

onstatus

onstatus: (arg0) => void;

Defined in: lib/webrtc.js:114

Parameters

Returns

void

ondebug

ondebug: (arg0) => void;

Defined in: lib/webrtc.js:117

Parameters

Returns

void

onerror

onerror: (arg0) => void;

Defined in: lib/webrtc.js:120

Parameters

Returns

void

onconnectionstatechange

onconnectionstatechange: (arg0) => void;

Defined in: lib/webrtc.js:123

Parameters

Returns

void

ondatachannelopen

ondatachannelopen: () => void;

Defined in: lib/webrtc.js:126

Returns

void

ondatachannelclose

ondatachannelclose: () => void;

Defined in: lib/webrtc.js:129

Returns

void

onstreaminfo

onstreaminfo: (arg0) => void;

Defined in: lib/webrtc.js:132

Parameters

Returns

void

onlatencymeasurement

onlatencymeasurement: (arg0) => void;

Defined in: lib/webrtc.js:135

Parameters

Returns

void

onplaystreamrequired

onplaystreamrequired: () => void;

Defined in: lib/webrtc.js:138

Returns

void

onclipboardcontent

onclipboardcontent: (arg0) => void | Promise<void>;

Defined in: lib/webrtc.js:141

May return a promise, which the ordered receive queue awaits.

Parameters

Returns

void | Promise<void>

onsystemaction

onsystemaction: (arg0) => void;

Defined in: lib/webrtc.js:144

Parameters

Returns

void

oncursorchange

oncursorchange: (arg0) => void;

Defined in: lib/webrtc.js:147

Parameters

Returns

void

cursor_cache

cursor_cache: Map<any, any>;

Defined in: lib/webrtc.js:150

onstreamstats

onstreamstats: (arg0) => void;

Defined in: lib/webrtc.js:153

Parameters

Returns

void

input

input: Input;

Defined in: lib/webrtc.js:172

clipboardcontent

clipboardcontent: any[];

Defined in: lib/webrtc.js:175

onserversettings

onserversettings: (arg0) => void;

Defined in: lib/webrtc.js:178

Parameters

Returns

void

ondisplayconfig

ondisplayconfig: (arg0) => void;

Defined in: lib/webrtc.js:181

Parameters

Returns

void

onprintdocument

onprintdocument: (arg0) => void;

Defined in: lib/webrtc.js:184

Parameters

Returns

void

streams

streams: any[];

Defined in: lib/webrtc.js:514

Accessors

webcamTrack

Get Signature

get webcamTrack(): MediaStreamTrack;

Defined in: lib/webrtc.js:498

The live camera track sent to the server, or null.

Returns

MediaStreamTrack

Methods

setMicrophone()

setMicrophone(enabled, deviceId?): Promise<boolean>;

Defined in: lib/webrtc.js:361

Enables or disables the microphone: attaches a getUserMedia track to the reserved sendonly transceiver (the browser encodes Opus over RTP), or detaches and stops it.

Parameters

Returns

Promise<boolean>

False when getUserMedia is unavailable.

Throws

When the server withheld the microphone m-line (the microphone is disabled server-side); raised before prompting for permission so the UI never claims an active mic that streams nothing.

setWebcam()

setWebcam(
   enabled, 
   deviceId?, 
   hints?
): Promise<boolean>;

Defined in: lib/webrtc.js:407

Enables or disables the webcam: attaches a getUserMedia video track to the reserved sendonly transceiver (the browser encodes H.264, VP8, VP9, H.265 or AV1 over RTP and the server's virtual camera decodes it), or detaches and stops it. Disabling also deactivates the sender's encodings, because a null or ended track alone does not silence every engine (Firefox keeps the encoder running on it); enabling re-activates them, all without renegotiation.

Parameters

Returns

Promise<boolean>

False when getUserMedia is unavailable.

Throws

When the server withheld the webcam m-line (the webcam is locked off), raised before prompting for permission; or when the sender refuses the track (its transceiver stopped), the camera released again.

setWebcamCodec()

setWebcamCodec(codec): Promise<boolean>;

Defined in: lib/webrtc.js:454

Sends the camera as one codec: the webcam_encoder name (h264, h265, vp8, vp9, av1) is set on the sender's encoding from the codecs the answer negotiated, so the browser leaves the negotiated order for it; auto, mjpeg or a codec the answer lacks returns to that order. The codec of an encoding is what the engine offers for this, and an engine without it keeps the negotiated order, logged once.

Parameters

Returns

Promise<boolean>

Whether the named codec is what goes out.

dataChannelBufferedAmount()

dataChannelBufferedAmount(): number;

Defined in: lib/webrtc.js:747

Outbound queue depth of the data channel; bulk senders (clipboard, uploads) throttle on this so they cannot starve input and stats on the same channel.

Returns

number

dataChannelOpen()

dataChannelOpen(): boolean;

Defined in: lib/webrtc.js:758

Whether the data channel can carry a send right now. Bulk senders check this to report "not connected" instead of dropping into sendDataChannelMessage's quiet no-op.

Returns

boolean

waitForDataChannelDrain()

waitForDataChannelDrain(threshold?): Promise<void>;

Defined in: lib/webrtc.js:773

Resolves once queued sends (including the asynchronous gzip queue) have reached the channel and its buffered amount is below threshold. Bulk senders call this between chunks; without it a burst overflows the SCTP send buffer and Chromium closes the channel with OperationError, killing the session. It resumes on the bufferedamountlow event rather than a poll: polling lets the buffer drain to empty between chunks, which collapses throughput, while keeping about threshold bytes queued keeps the pipe full and still yields the channel to input and stats.

Parameters

Returns

Promise<void>

sendMotionMessage()

sendMotionMessage(message): void;

Defined in: lib/webrtc.js:792

Sends coalesced pointer motion on the unordered pointer channel while it is open, so a lost sample holds nothing behind it, else on the input channel.

Parameters

Returns

void

sendDataChannelMessage()

sendDataChannelMessage(message): void;

Defined in: lib/webrtc.js:811

Sends a message on the data channel. Nothing is sent while the channel is not open: periodic senders fire before it opens while connecting, and reporting that would mask real failures. Without negotiated gzip the send is synchronous, so the input hot path pays no latency; with it, strings of 512 bytes or more gzip asynchronously and every send passes through an order-preserving queue so a later small message cannot overtake a large one still compressing.

Parameters

Returns

void

onGamepadDisconnect()

onGamepadDisconnect(gp_num): void;

Defined in: lib/webrtc.js:841

Reports a gamepad disconnect as a status message.

Parameters

Returns

void

getConnectionStats()

getConnectionStats(): Promise<any>;

Defined in: lib/webrtc.js:862

Collects connection statistics from getStats().

general comes from the transport and candidate-pair reports (its connectionType through the selected pair's remote candidate), video and audio from the inbound-rtp reports (their codecName through the linked codec report; video.decoder reads unknown outside a capturing media context, the only state that exposes decoderImplementation), and data from the data-channel report; the raw reports are attached as reports (with the local candidates and the outbound-rtp reports of the microphone and webcam, by kind, for lib/stream-stats.js) and allReports. The audio section's NetEQ concealment counters are the RED acceptance metric; Chrome reports opus+red under the codec name opus, so RED presence is confirmed from the SDP or the packet size, never from codecName.

Returns

Promise<any>

playStream()

playStream(): void;

Defined in: lib/webrtc.js:1051

Starts playback of the element. Engines refuse autoplay before a user gesture; that refusal is reported through onplaystreamrequired.

Returns

void

connect()

connect(): void;

Defined in: lib/webrtc.js:1072

Creates the peer connection (relay-only when forceTurn is set) and connects the signaling client, which starts the offer/answer exchange.

Returns

void

reset()

reset(): void;

Defined in: lib/webrtc.js:1099

Resets the connection: forgets the cursor cache, closes the data channel and the peer connection, and reconnects, after a three-second pause when signaling was not stable.

Returns

void