RTCPeerConnection
lastmod 2022-10-15created 2019-08-1413 edits
The RTCPeerConnection interface represents a WebRTC connection between the local computer and a remote peer. It provides methods to connect to a remote peer, maintain and monitor the connection, and close the connection once it's no longer needed.
addIceCandidate
When a website or app using RTCPeerConnection receives a new ICE candidate from the remote user over its signaling channel, it delivers the newly received candidate to the browser's ICE agent by calling RTCPeerConnection.addIceCandidate(). This method adds the new remote candidate, which describes the state of the remote end of the connection, to the RTCPeerConnection's remote description.
If the candidate parameter is missing or its value is null when addIceCandidate() is called, the added ICE candidate is an "end-of-candidates" indicator. The same is true if the specified object's candidate value is missing or is an empty string (""): it signals that all remote candidates have been delivered.
The "end-of-candidates" notification is sent to the remote user with a candidate whose a-line value is end-of-candidates.
During negotiation, the app may receive many candidates to deliver to the ICE agent in this way, which lets it build up a list of possible connection methods. See WebRTC connectivity and Signaling and video calling for details.
Forcing use of a TURN server
Use the iceTransportPolicy: "relay" option.
Troubleshooting
Both username and credential are required when the URL scheme is "turn" or "turns"
Failed to construct 'RTCPeerConnection': Both username and credential are required when the URL scheme is "turn" or "turns".
Add a username and password to the TURN server.
Can't create RTCPeerConnections when the network is down
When creating an RTCPeerConnection in Firefox while the network is offline, it throws the error above and goes no further.
The RTCPeerConnection constructor implementation in the gecko engine looks like this:
RTCPeerConnection.prototype = {
classDescription: "mozRTCPeerConnection",
classID: PC_CID,
contractID: PC_CONTRACT,
QueryInterface: XPCOMUtils.generateQI([Ci.nsISupports,
Ci.nsIDOMGlobalPropertyInitializer]),
init: function(win) { this._win = win; },
__init: function(rtcConfig) {
if (!rtcConfig.iceServers ||
!Services.prefs.getBoolPref("media.peerconnection.use_document_iceservers")) {
rtcConfig.iceServers =
JSON.parse(Services.prefs.getCharPref("media.peerconnection.default_iceservers"));
}
this._winID = this._win.QueryInterface(Ci.nsIInterfaceRequestor)
.getInterface(Ci.nsIDOMWindowUtils).currentInnerWindowID;
this._mustValidateRTCConfiguration(rtcConfig,
"RTCPeerConnection constructor passed invalid RTCConfiguration");
if (_globalPCList._networkdown || !this._win.navigator.onLine) {
throw new this._win.DOMException(
"Can't create RTCPeerConnections when the network is down",
"InvalidStateError");
}
this.makeGetterSetterEH("onaddstream");
this.makeGetterSetterEH("onaddtrack");
this.makeGetterSetterEH("onicecandidate");
this.makeGetterSetterEH("onnegotiationneeded");
this.makeGetterSetterEH("onsignalingstatechange");
this.makeGetterSetterEH("onremovestream");
this.makeGetterSetterEH("ondatachannel");
this.makeGetterSetterEH("oniceconnectionstatechange");
this.makeGetterSetterEH("onidentityresult");
this.makeGetterSetterEH("onpeeridentity");
this.makeGetterSetterEH("onidpassertionerror");
this.makeGetterSetterEH("onidpvalidationerror");
this._pc = new this._win.PeerConnectionImpl();
this._taskChain = this._win.Promise.resolve();
this.__DOM_IMPL__._innerObject = this;
this._observer = new this._win.PeerConnectionObserver(this.__DOM_IMPL__);
// Add a reference to the PeerConnection to global list (before init).
_globalPCList.addPC(this);
this._impl.initialize(this._observer, this._win, rtcConfig,
Services.tm.currentThread);
this._initIdp();
_globalPCList.notifyLifecycleObservers(this, "initialized");
},
Either proceed with the network connected, or force the network status to stay online.
On the about:config page in Firefox, change the network.manage-offline-status setting to false.