@twilio/webrtc

twilio-webrtc.js

twilio-webrtc.js contains the various WebRTC shims used by twilio-video.js. It is not intended for general consumption.

Installation

npm install --save @twilio/webrtc

Exports

The following WebRTC API shims are available:

const {
  getStats,
  getUserMedia,
  MediaStream,
  MediaStreamTrack,
  RTCIceCandidate,
  RTCPeerConnection,
  RTCSessionDescription
} = require('@twilio/webrtc');

getStats

getStats resolves with normalized WebRTC statistics for the active ICE candidate pair and each MediaStreamTrack, local or remote, of a particular RTCPeerConnection.

/**
 * Get the statistics for a given RTCPeerConnection.
 * @param {RTCPeerConnection} peerConnection
 * @returns {Promise<StandardizedStatsResponse>}
 */
function getStats(peerConnection) {}

NOTE: StandardizedStatsResponse normalizes the different formats of the stats returned by RTCPeerConnection#getStats in different browsers. It does not conform to the W3C spec.

getUserMedia

getUserMedia accepts a MediaStreamConstraints object and resolves with a MediaStream. By default, it requests both audio and video.

/**
 * Request media from the user.
 * @param {MediaStreamConstraints} [constraints={audio: true, video: true}]
 * @returns {Promise<MediaStream>}
 */
function getUserMedia(constraints) {}

RTCPeerConnection

RTCPeerConnection abstracts away some of the browser-specific implementations of WebRTC, and implements some WebRTC features that are not present in some browsers.

Chrome

• Adds rollback support, according to the workaround specified here.
• Adds "track" event support, as per the workaround in webrtc-adapter.
• Provides a workaround for the case where, when the SSRC of a MediaStreamTrack changes, the browser treats this as a removal of the existing MediaStreamTrack and the addition of a new MediaStreamTrack.
• Adds support for getting and setting maxPacketLifeTime on RTCDataChannels by remapping the legacy property maxRetransmitTime to maxPacketLifeTime. See this bug for more information.
• Does not depend on the native "track" event (currently behind the flag: --enable-blink-features=RTCRtpSender) because of this bug, which partly refers to "ontrack" not firing when expected. We have filed this bug specifically for this.

Firefox

• For new offers, adds support for calling setLocalDescription and setRemoteDescription in have-local-offer and have-remote-offer signaling states respectively.
• Adds support for calling createOffer in signaling state have-local-offer.
• The above features are implemented using rollback to work around this bug.
• Provides a workaround for this bug, where the browser may change the previously negotiated DTLS role in an answer, which breaks Chrome.
• Provides a workaround for this bug, where the browser throws when RTCPeerConnection.prototype.peerIdentity is accessed.
• Provides a shim for the removeTrack method in order to work around this bug.
• Provides a shim for the addTrack method. Since removeTrack is shimmed, there is a necessity to maintain an explicit list of added RTCRtpSenders.
• Provides a shim for the getSenders method. Since removeTrack is shimmed, there is a necessity to maintain an explicit list of added RTCRtpSenders.

Safari

• Adds rollback support, according to the workaround specified here.
• Provides a workaround for the case where, when the SSRC of a MediaStreamTrack changes, the browser treats this as a removal of the existing MediaStreamTrack and the addition of a new MediaStreamTrack.
• Provides a workaround for this bug, where trying to access the localDescription or remoteDescription throws an exception.
• Provides a shim for the removeTrack method in order to work around this bug.
• Provides a shim for the addTrack method. Since removeTrack is shimmed, there is a necessity to maintain an explicit list of added RTCRtpSenders.
• Provides a workaround for this bug, where webrtc-adapter's shimmed addTrack method does not return the RTCRtpSender associated with the added track.
• Provides a shim for the getSenders method. Since removeTrack is shimmed, there is a necessity to maintain an explicit list of added RTCRtpSenders.

RTCSessionDescription

RTCSessionDescription abstracts away some of the browser-specific implementations of WebRTC for Firefox and Safari, and works around this bug in Chrome, where the native RTCSessionDescription constructor throws when its argument is { type: 'rollback'}.

Others

MediaStream, MediaStreamTrack, and RTCIceCandidate abstracts away their browser-prefixed counterparts for earlier browser versions.