@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.
• Works around a this bug in "unified-plan" SDPs where adding a MediaStreamTrack that was previously added and removed generates an SDP where the MSID does not match the MediaStreamTrack ID.
• Does not depend on the native "track" event for "plan-b" RTCPeerConnection because of this bug, which partly refers to "ontrack" not firing when expected. We have filed this bug specifically for this. This workaround is essential for Electron 2.x support.

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.
• Works around Firefox Bug 1480277.

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 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.