recursal/MDN huggingface dataset:
RTCPeerConnection: setIdentityProvider() method
===============================================

 The **`RTCPeerConnection.setIdentityProvider()`** method sets
 the Identity Provider (IdP) to the triplet given in parameter: its name, the protocol
 used to communicate with it (optional) and an optional username. The IdP will be used
 only when an assertion is needed.

 If the `signalingState` is set to
 `"closed"`, an `InvalidStateError` is raised.

Syntax
------


```js
setIdentityProvider(domainname)
setIdentityProvider(domainname, protocol)
setIdentityProvider(domainname, protocol, username)
```

### Parameters

`domainname`

A string representing the domain name where the IdP is.

`protocol` Optional

 A string representing the protocol used to communicate with the
 IdP. It defaults to `"default"` and is used to determine the URL where the
 IdP is listening.


`username` Optional

A string representing the username associated with the IdP.

### Return value

None (`undefined`).

Example
-------


```js
const pc = new RTCPeerConnection();

pc.setIdentityAssertion("developer.mozilla.org");
```

Specifications
--------------

| Specification |
| --- |
| Identity for WebRTC 1.0 # dom-rtcpeerconnection-setidentityprovider |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
RTCPeerConnection: remoteDescription property
=============================================

 The read-only property
 **`RTCPeerConnection.remoteDescription`** returns a
 `RTCSessionDescription` describing the session (which includes
 configuration and media information) for the remote end of the connection. If this
 hasn't been set yet, this is `null`.

 The returned value typically reflects a remote description which has been received over
 the signaling server (as either an offer or an answer) and then put into effect by your
 code calling `RTCPeerConnection.setRemoteDescription()` in response.

Syntax
------


```js
const sessionDescription = peerConnection.remoteDescription
```


 On a more fundamental level, the returned value is the value of
 `RTCPeerConnection.pendingRemoteDescription` if that property isn't
 `null`; otherwise, the value of
 `RTCPeerConnection.currentRemoteDescription` is returned. See
 Pending and current descriptions in the WebRTC Connectivity page for details on this algorithm and why it's used.

Example
-------

 This example looks at the `remoteDescription` and displays an alert
 containing the `RTCSessionDescription` object's `type` and
 `sdp` fields.


```js
const pc = new RTCPeerConnection();
// ...
const sd = pc.remoteDescription;
if (sd) {
  alert(`Remote session: type='${sd.type}'; sdp description='${sd.sdp}'`);
} else {
  alert("No remote session yet.");
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-remotedescription |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `RTCPeerConnection.setRemoteDescription()`,
 `RTCPeerConnection.pendingRemoteDescription`,
 `RTCPeerConnection.currentRemoteDescription`
* `RTCPeerConnection.setLocalDescription()`,
 `RTCPeerConnection.pendingLocalDescription`,
 `RTCPeerConnection.currentLocalDescription`,
 `RTCPeerConnection.localDescription`
* WebRTC
RTCPeerConnection: restartIce() method
======================================

 The WebRTC API's
 `RTCPeerConnection` interface offers the
 **`restartIce()`** method to allow a web application to easily
 request that ICE candidate gathering be redone on both ends of the
 connection.
 This simplifies the process by allowing the same method to be used
 by either the caller or the receiver to trigger an ICE restart.

 After `restartIce()` returns, the offer returned by the next call to
 `createOffer()` is automatically
 configured to trigger ICE restart on both the local peer (once the local peer has been
 set) and on the remote peer, once the offer is sent across your signaling mechanism and
 the remote peer has set its description as well.

`restartIce()` causes the
 `negotiationneeded` event to
 be fired on the `RTCPeerConnection` to inform the application that it should
 perform negotiation using its signaling channel.

 If negotiation fails to complete—either due to rollback or because incoming offers are
 in the process of being negotiated—the `RTCPeerConnection` will remember
 that you requested ICE restart. The next time the connection's
 `signalingState` changes to
 `stable`, the connection will fire the
 `negotiationneeded` event.
 This process continues until an ICE restart has been successfully completed.

Syntax
------


```js
restartIce()
```

### Parameters

None.

### Return value

None (`undefined`).

Usage notes
-----------

 After calling `restartIce()`, the next offer created using
 `createOffer()` will initiate ICE restart
 once sent to the remote peer over your signaling mechanism. Restarting ICE essentially
 resets ICE so that it creates all new candidates using new credentials. Existing media
 transmissions continue uninterrupted during this process.

 For details about how ICE restart works, see
 ICE restart and
 RFC 5245, section 9.1.1.1: ICE specification.

Examples
--------

 This example creates a handler for the
 `iceconnectionstatechange` event that handles a transition to the `failed`
 state by restarting ICE in order to try again.


```js
pc.addEventListener("iceconnectionstatechange", (event) => {
  if (pc.iceConnectionState === "failed") {
    /\* possibly reconfigure the connection in some way here \*/
    /\* then request ICE restart \*/
    pc.restartIce();
  }
});
```


 With this code in place, a transition to the `failed` state during ICE
 negotiation will cause a `negotiationneeded` event to be fired, in response to which your code should
 renegotiate as usual. However, because you have called `restartIce()`, your
 call to `createOffer()` which occurs in
 the handler for `negotiationneeded` will trigger an ICE restart rather than
 just a regular renegotiation.

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-restartice |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* Lifetime of a WebRTC session
* Signaling and video calling
RTCPeerConnection: iceConnectionState property
==============================================

 The read-only property **`RTCPeerConnection.iceConnectionState`** returns
 a string which state of the ICE agent associated with the `RTCPeerConnection`:
 `new`, `checking`, `connected`, `completed`,
 `failed`, `disconnected`, and `closed`.

 It describes the current state of the ICE agent
 and its connection to the ICE server;
 that is, the STUN or TURN server.

 You can detect when this value has changed by watching for the
 `iceconnectionstatechange` event.

Value
-----

The current state of the ICE agent and its connection. The value is one of the following strings:

`new`

 The ICE agent is gathering addresses
 or is waiting to be given remote candidates
 through calls to `RTCPeerConnection.addIceCandidate()` (or both).


`checking`

 The ICE agent has been given one or more remote candidates
 and is checking pairs of local and remote candidates against one another
 to try to find a compatible match,
 but has not yet found a pair which will allow the peer connection to be made.
 It is possible that gathering of candidates is also still underway.


`connected`

 A usable pairing of local and remote candidates has been found for all components of the connection,
 and the connection has been established.
 It is possible that gathering is still underway,
 and it is also possible that the ICE agent is still checking candidates
 against one another
 looking for a better connection to use.


`completed`

 The ICE agent has finished gathering candidates,
 has checked all pairs against one another,
 and has found a connection for all components.


`failed`

 The ICE candidate has checked all candidates pairs against one another
 and has failed to find compatible matches for all components of the connection.
 It is, however, possible that the ICE agent did find compatible connections for some components.


`disconnected`

 Checks to ensure
 that components are still connected failed
 for at least one component of the `RTCPeerConnection`.
 This is a less stringent test than `failed`
 and may trigger intermittently
 and resolve just as spontaneously on less reliable networks,
 or during temporary disconnections.
 When the problem resolves,
 the connection may return to the `connected` state.


`closed`

 The ICE agent for this `RTCPeerConnection` has shut down
 and is no longer handling requests.


Examples
--------


```js
const pc = new RTCPeerConnection();
const state = pc.iceConnectionState;
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-ice-connection-state |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* `iceconnectionstatechange`
* `RTCPeerConnection`
RTCPeerConnection: currentRemoteDescription property
====================================================

 The read-only property
 **`RTCPeerConnection.currentRemoteDescription`** returns an
 `RTCSessionDescription` object describing the remote end of the connection
 as it was most recently successfully negotiated since the last time the
 `RTCPeerConnection` finished negotiating and connecting to a remote peer.
 Also included is a list of any ICE candidates that may already have been generated by
 the ICE agent since the offer or answer represented by the description was first
 instantiated.

 To change the `currentRemoteDescription`, call
 `RTCPeerConnection.setRemoteDescription()`, which triggers a series of
 events which leads to this value being set. For details on what exactly happens and why
 the change isn't necessarily instantaneous, see
 Pending and current descriptions in the WebRTC Connectivity page.


**Note:** Unlike `RTCPeerConnection.remoteDescription`, this value represents the
 actual current state of the local end of the connection;
 `remoteDescription` may specify a description which the connection is
 currently in the process of switching over to.


Value
-----

 The current description of the remote end of the connection, if one has been set. If
 none has been successfully set, this value is `null`.

Examples
--------

 This example looks at the `currentRemoteDescription` and displays an alert
 containing the `RTCSessionDescription` object's `type` and
 `sdp` fields.


```js
const pc = new RTCPeerConnection();
// ...
const sd = pc.currentRemoteDescription;
if (sd) {
  alert(`Local session: type='${sd.type}'; sdp description='${sd.sdp}'`);
} else {
  alert("No local session yet.");
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-currentremotedesc |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* `RTCPeerConnection.setRemoteDescription()`,
 `RTCPeerConnection.pendingRemoteDescription`,
 `RTCPeerConnection.remoteDescription`
* `RTCPeerConnection.setRemoteDescription()`,
 `RTCPeerConnection.remoteDescription`,
 `RTCPeerConnection.pendingRemoteDescription`,
 `RTCPeerConnection.currentRemoteDescription`
* WebRTC
RTCPeerConnection: canTrickleIceCandidates property
===================================================

 The read-only **`RTCPeerConnection`** property **`canTrickleIceCandidates`**
 returns a boolean value which indicates whether or not the remote peer can accept
 trickled ICE candidates.

**ICE trickling** is the process of continuing to send candidates after
 the initial offer or answer has already been sent to the other peer.

 This property is only set after having called
 `RTCPeerConnection.setRemoteDescription()`. Ideally, your signaling
 protocol provides a way to detect trickling support, so that you don't need to rely on
 this property. A WebRTC browser will always support trickle ICE. If trickling isn't
 supported, or you aren't able to tell, you can check for a falsy value for this
 property and then wait until the value of
 `iceGatheringState` changes to
 `"completed"` before creating and sending the initial offer. That way, the
 offer contains all of the candidates.

Value
-----

 A boolean value that is `true` if the remote peer can accept
 trickled ICE candidates and `false` if it cannot. If no remote peer has
 been established, this value is `null`.


**Note:** This property's value is determined once the local peer has
 called `RTCPeerConnection.setRemoteDescription()`; the provided
 description is used by the ICE agent to determine whether or not the remote peer
 supports trickled ICE candidates.


Examples
--------


```js
const pc = new RTCPeerConnection();

function waitToCompleteIceGathering(pc) {
  return new Promise((resolve) => {
    pc.addEventListener(
      "icegatheringstatechange",
      (e) =>
        e.target.iceGatheringState === "complete" &&
        resolve(pc.localDescription),
    );
  });
}

// The following code might be used to handle an offer from a peer when
// it isn't known whether it supports trickle ICE.
async function newPeer(remoteOffer) {
  await pc.setRemoteDescription(remoteOffer);
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  if (pc.canTrickleIceCandidates) return pc.localDescription;
  const answer = await waitToCompleteIceGathering(pc);
  sendAnswerToPeer(answer); //To peer via signaling channel
}
// Handle error with try/catch

pc.addEventListener(
  "icecandidate",
  (e) => pc.canTrickleIceCandidates && sendCandidateToPeer(e.candidate),
);
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-cantrickleicecandidates |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC
* `RTCPeerConnection.addIceCandidate()`
* Lifetime of a WebRTC session
RTCPeerConnection: icegatheringstatechange event
================================================

 The **`icegatheringstatechange`** event is sent to the `onicegatheringstatechange` event handler on an `RTCPeerConnection` when the state of the ICE candidate gathering process changes.
 This signifies that the value of the connection's `iceGatheringState` property has changed.

When ICE first starts to gather connection candidates, the value changes from `new` to `gathering` to indicate that the process of collecting candidate configurations for the connection has begun. When the value changes to `complete`, all of the transports that make up the `RTCPeerConnection` have finished gathering ICE candidates.

**Note:** While you can determine that ICE candidate gathering is complete by watching for `icegatheringstatechange` events and checking for the value of `iceGatheringState` to become `complete`, you can also have your handler for the `icecandidate` event look to see if its `candidate` property is `null`. This also indicates that collection of candidates is finished.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("icegatheringstatechange", (event) => {});

onicegatheringstatechange = (event) => {};
```

Event type
----------

A generic `Event`.

Examples
--------

This example creates a handler for `icegatheringstatechange` events.


```js
pc.onicegatheringstatechange = (ev) => {
  let connection = ev.target;

  switch (connection.iceGatheringState) {
    case "gathering":
      /\* collection of candidates has begun \*/
      break;
    case "complete":
      /\* collection of candidates is finished \*/
      break;
  }
};
```


Likewise, you can use `addEventListener()` to add a listener for `icegatheringstatechange` events:


```js
pc.addEventListener(
  "icegatheringstatechange",
  (ev) => {
    let connection = ev.target;

    switch (connection.iceGatheringState) {
      case "gathering":
        // collection of candidates has begun
        break;
      case "complete":
        // collection of candidates is finished
        break;
    }
  },
  false,
);
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcpeerconnection-onicegatheringstatechange |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* Signaling and video calling
* WebRTC connectivity
* Lifetime of a WebRTC session
RTCPeerConnection: pendingRemoteDescription property
====================================================

 The read-only property
 **`RTCPeerConnection.pendingRemoteDescription`** returns an
 `RTCSessionDescription` object describing a pending configuration change
 for the remote end of the connection. This does not describe the connection as it
 currently stands, but as it may exist in the near future. Use
 `RTCPeerConnection.currentRemoteDescription` or
 `RTCPeerConnection.remoteDescription` to get the current session
 description for the remote endpoint. For details on the difference, see
 Pending and current descriptions in the WebRTC Connectivity page.

Value
-----

 If a remote description change is in progress, this is an
 `RTCSessionDescription` describing the proposed configuration. Otherwise,
 this returns `null`.

Examples
--------

 This example looks at the `pendingRemoteDescription` to determine whether or
 not there's a description change being processed.


```js
const pc = new RTCPeerConnection();
// ...
const sd = pc.pendingRemoteDescription;
if (sd) {
  // There's a description change underway!
} else {
  // No description change pending
}
```

Specifications
--------------

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-peerconnection-pendingremotedesc |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** The addition of `pendingRemoteDescription` and
 `currentRemoteDescription`
 to the WebRTC spec is relatively recent. In browsers which don't support them, only
 `remoteDescription` is available.


See also
--------

* `RTCPeerConnection.setRemoteDescription()`,
 `RTCPeerConnection.currentRemoteDescription`,
 `RTCPeerConnection.remoteDescription`
* `RTCPeerConnection.setLocalDescription()`,
 `RTCPeerConnection.localDescription`,
 `RTCPeerConnection.pendingLocalDescription`,
 `RTCPeerConnection.currentLocalDescription`
* WebRTC
RTCPeerConnection: addstream event
==================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

**Non-standard:** This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

The obsolete **`addstream`** event is sent to an `RTCPeerConnection` when new media, in the form of a `MediaStream` object, has been added to it.

**Warning:** This event has been removed from the WebRTC specification. You should instead watch for the `track` event, which is sent for each media track added to the `RTCPeerConnection`.

You can, similarly, watch for streams to be removed from the connection by monitoring the `removestream` event.

This event is not cancelable and does not bubble.

Syntax
------

Use the event name in methods like `addEventListener()`, or set an event handler property.


```js
addEventListener("addstream", (event) => {});

onaddstream = (event) => {};
```

Event type
----------

A `MediaStreamEvent`. Inherits from `Event`.

Event properties
----------------

*A `MediaStreamEvent` being an `Event`, this event also implements these properties*.

`MediaStreamEvent.stream` Read only 

Contains the `MediaStream` containing the stream associated with the event.

Examples
--------

This example looks to determine if the user's browser supports the `track` event. If it does, a `track` event listener is set up; otherwise, an `addstream` event listener is set up. `pc` is an `RTCPeerConnection`.


```js
if (pc.addTrack !== undefined) {
  pc.ontrack = (ev) => {
    ev.streams.forEach((stream) => doAddStream(stream));
  };
} else {
  pc.onaddstream = (ev) => {
    doAddStream(ev.stream);
  };
}
```


This calls a function `doAddStream()` once for each stream being added to the `RTCPeerConnection`, regardless of whether the browser sends `addstream` or `track`.

You can also use the `addEventListener()` method to set an event listener:


```js
pc.addEventListener("addstream", (ev) => doAddStream(ev.stream), false);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* WebRTC API
* `RTCPeerConnection.addStream()`
* `MediaStreamEvent`