RTCPeerConnection.setLocalDescription()

This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The RTCPeerConnection.setLocalDescription() method changes the local description associated with the connection. This description specifies the properties of the local end of the connection, including the media format. The method takes a single parameter—the session description—and it returns a Promise which is fulfilled once the description has been changed, asynchronously.

If setLocalDescription() 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 calling setLocalDescription() 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

aPromise = RTCPeerConnection.setLocalDescription(sessionDescription);

pc.setLocalDescription(sessionDescription, successCallback, errorCallback);  

Parameters

sessionDescription
An RTCSessionDescriptionInit or RTCSessionDescription which specifies the configuration to be applied to the local end of the connection.

About the session description parameter

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.createOffer().then(function(offer) {
  return myPeerConnection.setLocalDescription(new RTCSessionDescription(offer));
});

to simply be:

myPeerConnection.createOffer().then(myPeerConnection.setLocalDescription);

For this reason, the RTCSessionDescription() constructor is deprecated.

Return value

A Promise which is fulfilled once the value of RTCPeerConnection.localDescription 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's fulfillment handler receives no input parameters.

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. See Pending and current descriptions in WebRTC connectivity for more details on this process.

Deprecated parameters

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, as it will be removed in the future. You should update any existing code to use the Promise-based version of setLocalDescription() instead. The parameters for the older form of setLocalDescription() are described below, to aid in updating existing code.

successCallback
A JavaScript Function which accepts no input parameters to be 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
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.

Deprecated exceptions

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

InvalidStateError
The connection's signalingState is "closed", indicating that the connection is not currently open, so negotiation cannot take place.
InvalidSessionDescriptionError
The RTCSessionDescription specified by the sessionDescription parameter is invalid.

Example

In the example below, we see the implementation of a handler for the negotiationneeded event.

function handleNegotiationNeededEvent() {
  pc.createOffer().then(function(offer) {
    return pc.setLocalDescription(offer);
  })
  .then(function() {
    // Send the offer to the remote peer using the signaling server
  })
  .catch(reportError);
}

This begins by creating an offer by calling createOffer(); when that succeeds, we call setLocalDescription(). The fulfillment handler for that promise can then send the newly-created offer along to the other peer using the signaling server.

Specifications

Specification Status Comment
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.setLocalDescription()' in that specification.
Candidate Recommendation Initial specification.
WebRTC 1.0: Real-time Communication Between Browsers
The definition of 'RTCPeerConnection.setLocalDescription()' in that specification.
Candidate Recommendation Initial specification.

Browser compatibility

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support

561

50 — 562

1522 ?

432

37 — 43

?
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support

561

50 — 562

561

50 — 562

Yes44

432

37 — 43

?

6.01

5.0 — 6.02

1. Promise based version and unprefixed.

2. Promise based version.

See also

Document Tags and Contributors

Last updated by: fscholz,