RTCPeerConnection: setRemoteDescription() method

sessionDescription

An RTCSessionDescriptionInit or RTCSessionDescription which specifies the remote peer's current offer or answer. This value is an offer or answer received from the remote peer through your implementation of

The sessionDescription parameter is technically of type RTCSessionDescriptionInit, but because RTCSessionDescription serializes to be indistinguishable from RTCSessionDescriptionInit, you can also pass in an RTCSessionDescription. This lets you simplify code such as the following:

myPeerConnection
  .setRemoteDescription(new RTCSessionDescription(description))
  .then(() => createMyStream());

to be:

myPeerConnection.setRemoteDescription(description).then(() => createMyStream());

Using async/await syntax, you can further simplify this to:

await myPeerConnection.setRemoteDescription(description);
createMyStream();

Since it's unnecessary, the RTCSessionDescription() constructor is deprecated.

A Promise which is fulfilled once the value of the connection's remoteDescription 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.

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

InvalidAccessError DOMException

Returned if the content of the description is invalid.

InvalidStateError DOMException

Returned if the RTCPeerConnection is closed, or it's in a state that is not compatible with the specified description's type. For example, this exception is thrown if the type is rollback and the signaling state is one of stable, have-local-pranswer, or have-remote-pranswer because you cannot roll back a connection that's either fully established or is in the final stage of becoming connected.

OperationError DOMException

Returned if an error does not match the ones specified here. This includes identity validation errors.

RTCError DOMException

Returned with the errorDetail set to sdp-syntax-error if the SDP specified by RTCSessionDescription.sdp is not valid. The error object's sdpLineNumber property indicates the line number within the SDP on which the syntax error was detected.

TypeError

Returned if the specified RTCSessionDescriptionInit or RTCSessionDescription object is missing the type property, or no description parameter was provided at all.

When you call setRemoteDescription(), the ICE agent checks to make sure the RTCPeerConnection is in either the stable or have-remote-offer signalingState. These states indicate that either an existing connection is being renegotiated or that an offer previously specified by an earlier call to setRemoteDescription() 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 into setRemoteDescription(), 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.

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

pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);

successCallback Deprecated

A JavaScript Function 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.

errorCallback Deprecated

A function matching the signature RTCPeerConnectionErrorCallback which gets called if the description can't be set. It is passed a single DOMException 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, the successCallback will be called; in case of failure, the errorCallback will be called.

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

InvalidStateError Deprecated

The connection's signalingState is "closed", indicating that the connection is not currently open, so negotiation cannot take place.

InvalidSessionDescriptionError Deprecated

The RTCSessionDescription specified by the sessionDescription parameter is invalid.

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 article Signaling 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 our RTCPeerConnection and saving it as myPeerConnection, we pass the description included in the received offer message, msg, directly into setRemoteDescription() 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 call setLocalDescription() to set that as the configuration at our end of the call before forwarding that answer to the caller.

• WebRTC
• RTCPeerConnection.remoteDescription, RTCPeerConnection.pendingRemoteDescription, RTCPeerConnection.currentRemoteDescription