Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.

Revision 1069084 of RTCPeerConnection.createOffer()

  • Revision slug: Web/API/RTCPeerConnection/createOffer
  • Revision title: RTCPeerConnection.createOffer()
  • Revision id: 1069084
  • Created:
  • Creator: jpmedley
  • Is current revision? No
  • Comment Update compatibility table.

Revision Content

{{APIRef("WebRTC")}}{{SeeCompatTable}}

The createOffer() method of the {{domxref("RTCPeerConnection")}} interface initiates the creation of an {{Glossary("SDP")}} offer which includes information about any {{domxref("MediaStreamTrack")}}s already attached to the WebRTC session, codec and options supported by the browser, and any candidates already gathered by the {{Glossary("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 {{domxref("Promise")}} which, when the offer has been created, is resolved with a {{domxref("RTCSessionDescription")}} object containing the newly-created offer.

Syntax

aPromise = myPeerConnection.createOffer([options]);

myPeerConnection.createOffer(successCallback, failureCallback[, options]) {{deprecated_inline}}

Parameters

options {{optional_inline}}
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_inline}}
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_inline}}
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 {{jsxref("Promise")}}-based version of createOffer() instead. The parameters for this form of createOffer() are described below, to aid in updating existing code.

successCallback {{deprecated_inline}}
An {{domxref("RTCSessionDescriptionCallback")}} which will be passed a single {{domxref("RTCSessionDescription")}} object describing the newly-created offer.
errorCallback {{deprecated_inline}}
An {{domxref("RTCPeerConnectionErrorCallback")}} which will be passed a single {{domxref("DOMError")}} object explaining why the request to create an offer failed.
options {{optional_inline}}
An optional RTCOfferOptions dictionary providing options requested for the offer.

Return value

A {{jsxref("Promise")}} whose fulfillment handler will receive an {{domxref("RTCSessionDescription")}} 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 {{event("negotiationneeded")}} event which creates the offer and sends it to the remote system over a signaling channel.

Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you. In this case, a WebSocket connection is used to send a {{Glossary("JSON")}} message with a type field with the value "video-offer" to the other peer. The contents of the object being passed to the sendToServer() function, along with everything else in the promise fulfillment handler, depend entirely on your design.

  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 {{domxref("RTCPeerConnection")}} is configured to match by calling {{domxref("RTCPeerConnection.setLocalDescription", "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 {{jsxref("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

Specification Status Comment
{{SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-createOffer-Promise-RTCSessionDescription--RTCOfferOptions-options', 'createOffer()')}} {{Spec2('WebRTC 1.0')}} Initial definition.

Browser compatibility

{{CompatibilityTable}}
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support {{CompatVersionUnknown}} [1] {{CompatGeckoDesktop(22)}} [2] {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}
Promise-based version {{CompatChrome(51.0)}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}
Feature Android Android Webview Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile Chrome for Android
Basic support {{CompatNo}} {{CompatNo}} [1] {{CompatGeckoMobile(24)}} [2] {{CompatUnknown}} [2] {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatVersionUnknown}} [1]
Promise-based version {{CompatNo}} {{CompatChrome(51.0)}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}} {{CompatChrome(51.0)}}

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

[2] The callback-based version of this method was deprecated in Firefox 37.

Revision Source

<p>{{APIRef("WebRTC")}}{{SeeCompatTable}}</p>

<p>The <strong><code>createOffer()</code></strong> method of the {{domxref("RTCPeerConnection")}} interface initiates the creation of an {{Glossary("SDP")}} offer which includes information about any {{domxref("MediaStreamTrack")}}s already attached to the WebRTC session, codec and options supported by the browser, and any candidates already gathered by the {{Glossary("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.</p>

<p>The return value is a {{domxref("Promise")}} which, when the offer has been created, is resolved with a {{domxref("RTCSessionDescription")}} object containing the newly-created offer.</p>

<h2 id="Syntax">Syntax</h2>

<pre class="syntaxbox">
<em>aPromise</em> = <em>myPeerConnection</em>.createOffer([<em>options</em>]);

<em>myPeerConnection</em>.createOffer(<em>successCallback</em>, <em>failureCallback</em>[, <em>options</em>]) {{deprecated_inline}}
</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
 <dt><code>options</code> {{optional_inline}}</dt>
 <dd>An <code><a href="#RTCOfferOptions_dictionary">RTCOfferOptions</a></code> dictionary providing options requested for the offer.</dd>
</dl>

<h3 id="RTCOfferOptions_dictionary">RTCOfferOptions dictionary</h3>

<p>The <code>RTCOfferOptions</code> dictionary is used to customize the offer created by this method.</p>

<dl>
 <dt>iceRestart {{optional_inline}}</dt>
 <dd>To restart ICE on an active connection, set this to <code>true</code>. 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 <code>false</code> to keep the same credentials and therefore not restart ICE. <strong>The default is <code>false</code></strong>.</dd>
 <dt><code>voiceActivityDetection</code> {{optional_inline}}</dt>
 <dd>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. <strong>This option defaults to <code>true</code></strong> (voice activity detection <em>enabled</em>).</dd>
</dl>

<dl>
 <dt>
 <h3 id="Deprecated_parameters">Deprecated parameters</h3>
 </dt>
</dl>

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

<dl>
 <dt><code>successCallback</code> {{deprecated_inline}}</dt>
 <dd>An {{domxref("RTCSessionDescriptionCallback")}} which will be passed a single {{domxref("RTCSessionDescription")}} object describing the newly-created offer.</dd>
 <dt><code>errorCallback</code> {{deprecated_inline}}</dt>
 <dd>An {{domxref("RTCPeerConnectionErrorCallback")}} which will be passed a single {{domxref("DOMError")}} object explaining why the request to create an offer failed.</dd>
 <dt><code>options</code> {{optional_inline}}</dt>
 <dd>An optional <code><a href="#RTCOfferOptions_dictionary">RTCOfferOptions</a></code> dictionary providing options requested for the offer.</dd>
</dl>

<h3 id="Return_value">Return value</h3>

<p>A {{jsxref("Promise")}} whose fulfillment handler will receive an {{domxref("RTCSessionDescription")}} which contains the SDP describing the generated offer. That received offer should be delivered through the signaling server to a remote peer.</p>

<h2 id="Example">Example</h2>

<p>Here we see a handler for the {{event("negotiationneeded")}} event which creates the offer and sends it to the remote system over a signaling channel.</p>

<div class="note">
<p>Keep in mind that this is part of the signaling process, the transport layer for which is an implementation detail that's entirely up to you. In this case, a <a href="/en-US/docs/Web/API/WebSocket_API">WebSocket</a> connection is used to send a {{Glossary("JSON")}} message with a <code>type</code> field with the value "video-offer" to the other peer. The contents of the object being passed to the <code>sendToServer()</code> function, along with everything else in the promise fulfillment handler, depend entirely on your design.</p>
</div>

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

<p>In this code, the offer is created, and once successful, the local end of the {{domxref("RTCPeerConnection")}} is configured to match by calling {{domxref("RTCPeerConnection.setLocalDescription", "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 <code>sendToServer()</code>. 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.</p>

<p>Use {{jsxref("Promise.catch()")}} to trap and handle errors.</p>

<p>See <a href="/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling">Signaling and video calling</a> for the complete example from which this snippet is derived; this will help you to understand how the signaling code here works.</p>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-createOffer-Promise-RTCSessionDescription--RTCOfferOptions-options', 'createOffer()')}}</td>
   <td>{{Spec2('WebRTC 1.0')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatVersionUnknown}} [1]</td>
   <td>{{CompatGeckoDesktop(22)}} [2]</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Promise-based version</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}} [1]</td>
   <td>{{CompatGeckoMobile(24)}} [2]</td>
   <td>{{CompatUnknown}} [2]</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}} [1]</td>
  </tr>
  <tr>
   <td>Promise-based version</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(51.0)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(51.0)}}</td>
  </tr>
 </tbody>
</table>
</div>

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

<p>[2] The callback-based version of this method was deprecated in Firefox 37.</p>
Revert to this revision