RTCPeerConnection.createOffer()

The createOffer() method of the RTCPeerConnection interface initiates the creation of an SDP offer which includes information about any MediaStreamTracks already attached to the WebRTC session, codec and options supported by the browser, and any candidates already gathered by the ICE agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.

The return value is a Promise which, when the offer has been created, is resolved with a RTCSessionDescription object containing the newly-created offer.

Syntax

aPromise = myPeerConnection.createOffer([options]);
myPeerConnection.createOffer(successCallback, failureCallback, [options])  

Parameters

options Optional

An RTCOfferOptions dictionary providing options requested for the offer.

RTCOfferOptions dictionary

The RTCOfferOptions dictionary is used to customize the offer created by this method.

iceRestart Optional

To restart ICE on an active connection, set this to true. This will cause the returned offer to have different credentials than those already in place. If you then apply the returned offer, ICE will restart. Specify false to keep the same credentials and therefore not restart ICE. The default is false.

voiceActivityDetection Optional

Some codecs and hardware are able to detect when audio begins and ends by watching for "silence" (or relatively low sound levels) to occur. This reduces network bandwidth used for audio by only sending audio data when there's actually something to broadcast. However, in some cases, this is unwanted. For example, in the case of music or other non-voice transmission, this can cause loss of important low-volume sounds. Also, emergency calls should never cut audio when quiet. This option defaults to true (voice activity detection enabled).

Deprecated parameters

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

successCallback

An RTCSessionDescriptionCallback which will be passed a single RTCSessionDescription object describing the newly-created offer.

errorCallback

An RTCPeerConnectionErrorCallback which will be passed a single DOMError object explaining why the request to create an offer failed.

options Optional

An optional RTCOfferOptions dictionary providing options requested for the offer.

Return value

A Promise whose fulfillment handler will receive an object conforming to the RTCSessionDescriptionInit dictionary which contains the SDP describing the generated offer. That received offer should be delivered through the signaling server to a remote peer.

Example

Here we see a handler for the negotiationneeded event which creates the offer and sends it to the remote system over a signaling channel.

  myPeerConnection.createOffer().then(function(offer) {
    return myPeerConnection.setLocalDescription(offer);
  })
  .then(function() {
    sendToServer({
      name: myUsername,
      target: targetUsername,
      type: "video-offer",
      sdp: myPeerConnection.localDescription
    });
  })
  .catch(function(reason) {
    // An error occurred, so handle the failure to connect
  });

In this code, the offer is created, and once successful, the local end of the RTCPeerConnection is configured to match by passing the offer (which is represented using an object conforming to RTCSessionDescriptionInit) into setLocalDescription(). Once that's done, the offer is sent to the remote system over the signaling channel; in this case, by using a custom function called sendToServer(). The implementation of the signaling server is independent from the WebRTC specification, so it doesn't matter how the offer is sent as long as both the caller and potential receiver are using the same one.

Use Promise.catch() to trap and handle errors.

See Signaling and video calling for the complete example from which this snippet is derived; this will help you to understand how the signaling code here works.

Specifications

Browser compatibility

[1] The callback-based version of this method was deprecated in Chrome 49.

[2] Though this method is not prefixed, the interface it belongs to was until Chrome 56

[3] Starting in Firefox 46, VP9 support was added, but disabled by default. To enable it, set the preference media.peerconnection.video.vp9_enabled to true using about:config. If you enable VP9 in Firefox 46 through Firefox 50, it's the preferred video codec. Starting in Firefox 51, it's enabled by default but VP8 is preferred.