RTCPeerConnection: setRemoteDescription() method

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

ThesetRemoteDescription() method of theRTCPeerConnection interface sets the specified session description as the remote peer's current offer or answer.The description specifies the properties of the remote end of the connection, including the media format.The method takes a single parameter—the session description—and it returns aPromise which is fulfilled once the description has been changed, asynchronously.

This is typically called after receiving an offer or answer from another peer over the signaling server.Keep in mind that ifsetRemoteDescription() is called while a connection is already in place, it means renegotiation is underway (possibly to adapt to changing network conditions).

Because descriptions will be exchanged until the two peers agree on a configuration, the description submitted by callingsetRemoteDescription() does not immediately take effect.Instead, the current connection configuration remains in place until negotiation is complete.Only then does the agreed-upon configuration take effect.

Syntax

setRemoteDescription(sessionDescription)// deprecatedsetRemoteDescription(sessionDescription, successCallback, errorCallback)

Parameters

sessionDescription

An object which specifies the remote peer's current offer or answer. It should contain the following properties:

type: A string indicating the type of the session description. SeeRTCSessionDescription.type.
sdpOptional: A string containing the SDP describing the session. If sdp is not provided, it defaults to an empty string. Iftype is"rollback",sdp must be null or an empty string. SeeRTCSessionDescription.sdp.

You can also pass an actualRTCSessionDescription instance, but there's no difference. For this reason, theRTCSessionDescription constructor is deprecated.

In older code and documentation, you may see a callback-based version of this function used.This has been deprecated and its use isstrongly discouraged.You should update any existing code to use thePromise-based version ofsetRemoteDescription() instead.The parameters for the older form ofsetRemoteDescription() are described below, to aid in updating existing code.

successCallbackDeprecated: A JavaScriptFunction which accepts no input parameters to be called once the description has been successfully set.At that time, the offer can be sent to a remote peer via the signaling server.
errorCallbackDeprecated: A function matching the signatureRTCPeerConnectionErrorCallback which gets called if the description can't be set.It is passed a singleDOMException object explaining why the request failed.

This deprecated form of the method returns instantaneously without waiting for the actual setting to be done: in case of success, thesuccessCallback will be called; in case of failure, theerrorCallback will be called.

Return value

APromise which is fulfilled once the value of the connection'sremoteDescription is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).The promise fulfillment handler receives no input parameters.

Note:The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.SeePending and current descriptions in the WebRTC Connectivity page for more details on this process.

Exceptions

The following exceptions are reported to the rejection handler for the promise returned bysetRemoteDescription():

InvalidAccessErrorDOMException: Returned if the content of the description is invalid.
InvalidStateErrorDOMException: Returned if theRTCPeerConnection is closed, or it's in a state that is not compatible with the specified description'stype.For example, this exception is thrown if thetype isrollback and the signaling state is one ofstable,have-local-pranswer, orhave-remote-pranswer because you cannot roll back a connection that's either fully established or is in the final stage of becoming connected.
OperationErrorDOMException: Returned if an error does not match the ones specified here. This includes identity validation errors.
RTCErrorDOMException: Returned with theerrorDetail set tosdp-syntax-error if theSDP specified byRTCSessionDescription.sdp is not valid.The error object'ssdpLineNumber property indicates the line number within the SDP on which the syntax error was detected.
TypeError: Returned if thesessionDescription is missing thetype property, or no description parameter was provided at all.

When using the deprecated callback-based version ofsetRemoteDescription(), the following exceptions may occur:

InvalidStateErrorDeprecated: The connection'ssignalingState is"closed", indicating that the connection is not currently open, so negotiation cannot take place.
InvalidSessionDescriptionErrorDeprecated: ThesessionDescription parameter is invalid.

Usage notes

When you callsetRemoteDescription(), the ICE agent checks to make sure theRTCPeerConnection is in either thestable orhave-remote-offersignalingState.These states indicate that either an existing connection is being renegotiated or that an offer previously specified by an earlier call tosetRemoteDescription() is to be replaced with the new offer.In either of those two cases, we're at the beginning of the negotiation process, and the offer is set as the remote description.

On the other hand, if we're in the middle of an ongoing negotiation and an offer is passed intosetRemoteDescription(), the ICE agent automatically begins an ICE rollback in order to return the connection to a stable signaling state, then, once the rollback is completed, sets the remote description to the specified offer.This begins a new negotiation session, with the newly-established offer as the starting point.

Upon starting the new negotiation with the newly-established offer, the local peer is now the callee, even if it was previously the caller.This happens instead of throwing an exception, thereby reducing the number of potential errors which might occur, and simplifies the processing you need to do when you receive an offer, by eliminating the need to handle the offer/answer process differently depending on whether the local peer is the caller or callee.

Note:Earlier implementations of WebRTC would throw an exception if an offer was set outside astable orhave-remote-offer state.

Examples

Here we see a function which handles an offer received from the remote peer.This code is derived from the example and tutorial in the articleSignaling and video calling; take a look at that for more details and a more in-depth explanation of what's going on.

function handleOffer(msg) {  createMyPeerConnection();  myPeerConnection    .setRemoteDescription(msg.description)    .then(() => navigator.mediaDevices.getUserMedia(mediaConstraints))    .then((stream) => {      document.getElementById("local_video").srcObject = stream;      return myPeerConnection.addStream(stream);    })    .then(() => myPeerConnection.createAnswer())    .then((answer) => myPeerConnection.setLocalDescription(answer))    .then(() => {      // Send the answer to the remote peer using the signaling server    })    .catch(handleGetUserMediaError);}

After creating ourRTCPeerConnection and saving it asmyPeerConnection, we pass the description included in the received offermessage,msg, directly intosetRemoteDescription() to tell the user agent's WebRTC layer what configuration the caller has proposed using.When our promise fulfillment handler is called, indicating that this has been done, we create a stream, add it to the connection, then create an SDP answer and callsetLocalDescription() to set that as the configuration at our end of the call before forwarding that answer to the caller.