RTCIceCandidate: relatedAddress property - Web APIs

RTCIceCandidate: relatedAddress property
========================================

 The **`RTCIceCandidate`** interface's read-only **`relatedAddress`** property is a
 string indicating the **related address** of a relay or reflexive candidate.

If the candidate is a host candidate (that is, its `address` is in fact the real IP address of the remote peer), `relatedAddress` is `null`.

 The `relatedAddress` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `relatedAddress` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line if it's formatted properly(the `rel-address` field).

 The related address and port (`relatedPort`) are not used at all by ICE itself; they are provided
 for analysis and diagnostic purposes only, and their inclusion may be blocked by security systems, so do not rely on them having non-`null` values.

Value
-----

 A string which contains the candidate's related address. For both
 peer and server reflexive candidates, the related address (and related port) are the
 base for that server or peer reflexive candidate. For relay candidates, the related
 address and port are set to the mapped address selected by the TURN server.

For host candidates, `relatedAddress` is `null`, meaning the field is not included in the candidate's a-line.

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

 The related address is included in ICE candidates despite not being used by ICE itself.
 `relatedAddress` can be used for diagnostic purposes; by observing the
 relationships between the various types of candidates and their addresses and related
 addresses. `relatedAddress` can also be used by Quality-of-Service (QoS) mechanisms.

Here's an SDP attribute line (a-line) describing an ICE candidate discovered by the STUN server:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 6502 typ srflx raddr 198.51.100.45 rport 32768 generation 0
```

 The remote address, `relatedAddress`, is the dotted quad (for IPv4) or
 colon-delineated 64-bit address (for IPv6) immediately following the text `"raddr"`, or `"198.51.100.45"`.

Examples
--------

 In this example, the candidate's `type` is
 checked, and then debugging output is presented, based on the candidate type, including
 the candidate's `ip` and `relatedAddress`.

```js
switch (candidate.type) {
  case "host":
    console.log(`Host candidate's IP address is ${candidate.ip}`);
    break;
  case "srflx":
    console.log(
      `Server reflexive candidate's base address is ${candidate.relatedAddress}; reachable at ${candidate.ip}`,
    );
    break;
  case "prflx":
    console.log(
      `Peer reflexive candidate's base address is ${candidate.relatedAddress}; reachable at ${candidate.ip}`,
    );
    break;
  case "relay":
    console.log(
      `Relay candidate's address assigned by the TURN server is ${candidate.relatedAddress}; reachable at ${candidate.ip}`,
    );
    break;
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-relatedaddress |

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

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

See also
--------

* WebRTC API
* Introduction to WebRTC protocols
* WebRTC connectivity
* Lifetime of a WebRTC session
* `RTCIceCandidate.relatedPort`
* `RTCIceCandidate.address` and `RTCIceCandidate.port`


RTCIceCandidate: protocol property - Web APIs

RTCIceCandidate: protocol property
==================================

 The **`RTCIceCandidate`** interface's read-only **`protocol`** property is a string
 which indicates whether the candidate uses UDP or TCP as its transport protocol.

 The `protocol` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `protocol` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line, if it's formatted properly.

`protocol` is `null` by default if not specified properly in the SDP, but this is an error condition and will result in a thrown exception when you call `RTCPeerConnection.addIceCandidate()`.

Value
-----

A string that indicates what network protocol the candidate uses:

`tcp`

The candidate, if selected, would use TCP as the transport protocol for its data. The `tcpType` property provides additional information about the kind of TCP candidate represented by the object.

`udp`

The candidate will use the UDP transport protocol for its data. This is the preferred protocol for media interactions because of its better performance profile.

**Note:** If `protocol` is `null` — and `protocol` is supported by the user agent — passing the
 candidate to `addIceCandidate()` will fail, throwing an `OperationError` exception.

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

Here's an example candidate a-line from an ICE transaction:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

 The third field, `"udp"`, is the protocol type, indicating that the
 candidate would use the UDP transport protocol.

Examples
--------

 This code snippet examines the value of `protocol` to decide if it should
 look at the value of `tcpType` to see if it's a
 **simultaneous-open** (**S-O**) candidate.

```js
if (candidate.protocol === "tcp") {
  if (candidate.tcpType === "so") {
    adjustForSimultaneousOpen(candidate);
  }
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-protocol |

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

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


RTCIceCandidate: tcpType property - Web APIs

RTCIceCandidate: tcpType property
=================================

The **`RTCIceCandidate`** interface's read-only **`tcpType`** property is included on TCP candidates to provide additional details about the candidate type.

 The `tcpType` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `tcpType` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line, if it's formatted properly.

Value
-----

If the `protocol` is "tcp", `tcpType` has one of the following values:

`"active"`

The transport will try to open an outbound connection but won't receive incoming connection requests.

`"passive"`

The transport will receive incoming connection requests but won't try to open an outbound connection.

`"so"`

The transport will try to open a connection simultaneously with its peer.

`tcpType` is `null` for UDP candidates.

Examples
--------

 In this example, the candidate's `protocol`
 and `tcpType` are used to adjust the user interface for simultaneous-open TCP candidates.

```js
if (candidate.protocol === "tcp" && candidate.tcpType === "so") {
  adjustForSimultaneousOpen(candidate);
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-tcptype |

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

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

See also
--------

* WebRTC API
* Introduction to WebRTC protocols
* WebRTC connectivity
* `RTCIceCandidate.protocol`
* `RTCIceCandidate.type`


RTCIceCandidate: usernameFragment property - Web APIs

RTCIceCandidate: usernameFragment property
==========================================

 The read-only **`usernameFragment`** property on the `RTCIceCandidate` interface is a string indicating the
 username fragment ("ufrag") that uniquely identifies a single ICE interaction session.

 This value is specified using the `usernameFragment` property in the `candidateInfo` options object that is passed to the `RTCIceCandidate()` constructor.
 If you call the constructor with an m-line string instead of the options object, the value of `usernameFragment` is extracted from the specified candidate m-line string.

Note that 24 bits of the username fragment are required to be randomized by the browser. See Randomization below for details.

Value
-----

 A string containing the username fragment (usually referred to in
 shorthand as "ufrag" or "ice-ufrag") that, along with the ICE password ("ice-pwd"),
 uniquely identifies a single ongoing ICE interaction, including for any communication
 with the STUN server. The string may be up to 256 characters long, and
 has no default value.

### Randomization

 At least 24 bits of the text in the `ufrag` are required to be randomly
 selected by the ICE layer at the beginning of the ICE session. The specifics for which
 bits are random and what the remainder of the `ufrag` text are left up to the
 browser implementation to decide. For example, a browser might choose to always use a
 24-character `ufrag` in which bit 4 of each character is randomly selected
 between 0 and 1. Another example: it might take a user-defined string and append three
 8-bit random bytes to the end. Or perhaps every character is entirely random.

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

 ICE uses the `usernameFragment` and password to ensure message integrity.
 This avoids crosstalk among multiple ongoing ICE sessions, but, more importantly, helps
 secure ICE transactions (and all of WebRTC by extension) against attacks that might try
 to inject themselves into an ICE exchange.

**Note:** There is no API to obtain the ICE password, for what should be fairly obvious security reasons.

The `usernameFragment` and password both change every time an ICE restart occurs.

Examples
--------

 Although the WebRTC infrastructure will filter out obsolete candidates for you after an
 ICE restart, you can do it yourself if you're trying to absolutely minimize the number
 of messages going back and forth.

 To do so, you can compare the value of `usernameFragment` to the current
 `usernameFragment` being used for the connection after receiving the
 candidate from the signaling server and before calling
 `addIceCandidate()` to add it to the
 set of possible candidates.

 When the web app receives a message from the signaling server that includes a candidate
 to be added to the `RTCPeerConnection`, you can (and generally
 *should*) call `addIceCandidate()`. There's not typically a need to
 manually worry about filtering the candidates.

 However, let's imagine that we do need to minimize traffic. The function below,
 `ssNewCandidate()`, is called when a message, `signalMsg`, arrives
 from the signaling server that contains an ICE candidate to be added to the
 `RTCPeerConnection`. To avoid including candidates obsoleted by an ICE
 restart, we can use code like this:

```js
const ssNewCandidate = (signalMsg) => {
  let candidate = new RTCIceCandidate(signalMsg.candidate);
  let receivers = pc.getReceivers();

  for (const receiver of receivers) {
    let parameters = receiver.transport.getParameters();

    if (parameters.usernameFragment === candidate.usernameFragment) {
      return;
    }
  }

  pc.addIceCandidate(candidate).catch(reportError);
};
```

 This walks through the list of the `RTCRtpReceiver` objects being used to
 receive ICE data, and looks to see if the `usernameFragment` indicated in the
 candidate matches any of them. If it does, `ssNewCandidate()` aborts.
 Otherwise, after checking every receiver, it adds the new candidate to the connection.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-usernamefragment |

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

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


RTCIceCandidate: port property - Web APIs

RTCIceCandidate: port property
==============================

 The **`RTCIceCandidate`** interface's read-only **`port`** property contains the port
 number on the device at the address given by `RTCIceCandidate.address` at which the candidate's peer can be reached.

 The `port` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `port` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line, if it's formatted properly.

Value
-----

A 16-bit number indicating the port number on the device at the address indicated by `address` at which the candidate's peer can be reached.

`port` is initialized to `null` if it is not specified in the
 `candidate`, or if the `candidate` string can't be parsed properly.

**Note:** If `port` is `null`, passing the candidate to `addIceCandidate()`
 will fail, throwing an `OperationError` exception.
 This applies only if the candidate implements `port`.

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

 Consider this SDP attribute line (a-line) which describes an ICE
 candidate:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

The port number is found in the sixth field, which is `"44323"`. In this case, the value of `port` will be 44323.

Examples
--------

 This code snippet fetches the IP address and port number of the candidate, storing them
 into an object for future use.

```js
const candidateLoc = {
  address: candidate.ip,
  port: candidate.port,
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-port |

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

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


RTCIceCandidate: sdpMLineIndex property - Web APIs

RTCIceCandidate: sdpMLineIndex property
=======================================

 The read-only **`sdpMLineIndex`** property on the `RTCIceCandidate` interface
 is a zero-based index of the m-line describing the media associated with the candidate.

 This property can be configured by specifying the value of the `sdpMLineIndex` property in the `candidateInfo` options object that is passed to the `RTCIceCandidate()` constructor.
 If you call the constructor with an m-line string instead of the options object, the value of `sdpMLineIndex` is extracted from the specified candidate m-line string.

Value
-----

 A number containing a 0-based index into the set of m-lines providing media descriptions,
 indicating which media source is associated with the candidate, or `null` if no such association is available.

**Note:** Attempting to add a candidate (using
 `addIceCandidate()`) that has a
 value of `null` for either `sdpMid` or
 `sdpMLineIndex` will throw a `TypeError` exception.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-sdpmlineindex |

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

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


RTCIceCandidate: component property - Web APIs

RTCIceCandidate: component property
===================================

 The read-only **`component`** property
 on the `RTCIceCandidate` interface is a string which indicates whether
 the candidate is an RTP or
 an RTCP candidate.

 If a candidate represents both RTP and RTCP multiplexed together, it is reported as an
 RTP candidate.

Value
-----

A string which is one of the following:

`rtp`

Identifies an ICE transport which is being used for the Real-time Transport Protocol (RTP), or for RTP multiplexed with the RTP Control Protocol (RTCP). RTP is defined in RFC 3550. This value corresponds to the component ID field in the `candidate` a-line with the value 1.

`rtcp`

Identifies an ICE transport being used for RTCP, which is defined in RFC 3550, section 6. This value corresponds to the component ID 2.

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

Consider this SDP attribute line (a-line):
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

 This is an ICE candidate a-line, whose `foundation` is 4234997325. The next field on the a-line, `"1"`, is the
 component ID. A value of `"1"` indicates RTP, which is recorded in the
 `component` property as `"rtp"`. If this value were instead
 `"2"`, the a-line would be describing an RTCP candidate, and
 `component` would be `"rtcp"`.

Examples
--------

 This code snippet examines a candidate's component type and dispatches the candidate to
 different handlers depending on the value.

```js
if (candidate.component === "rtp") {
  handleRTPCandidate(candidate);
} else if (candidate.component === "rtcp") {
  handleRTCPCandidate(candidate);
} else {
  handleUnknownCandidate(candidate);
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-component |

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

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


RTCIceCandidate: priority property - Web APIs

RTCIceCandidate: priority property
==================================

The **`RTCIceCandidate`** interface's read-only **`priority`** property specifies the candidate's priority according to the remote peer; the higher this value is, the better the remote peer considers the candidate to be.

 The `priority` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `priority` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line, if it's formatted properly.

Value
-----

 A long, unsigned integer value indicating the priority of the candidate according to the remote peer.
 The larger this value is, the more preferable the remote peer considers this candidate to be.

`priority` is initialized to `null` if it is not specified in the `candidate`, or if the `candidate` string can't be parsed properly.

**Note:** If `priority` is `null`, passing the
 candidate to `addIceCandidate()`
 will fail, throwing an `OperationError` exception. This applies only if the
 candidate implements the `priority` property.

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

Consider this SDP attribute line (a-line) which describes an ICE candidate:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

 The priority is the number after the protocol, so it's the fourth field in the candidate string.
 In this example, the priority is 2043278322.

Examples
--------

 This candidate examines the `priority` of the candidate and, if it's greater
 than the priority of a previously-seen candidate, remembers the candidate for later use.

```js
let bestCandidate = {
  candidate: "",
  sdpMid: null,
  sdpMLineIndex: null,
  priority: 0,
};

function handleCandidate(candidateString) {
  const candidate = new RTCIceCandidate(candidateString);

  if (candidate.priority > bestCandidate.priority) {
    bestCandidate = candidate;
  }
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-priority |

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

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


RTCIceCandidate: RTCIceCandidate() constructor - Web APIs

RTCIceCandidate: RTCIceCandidate() constructor
==============================================

 The
 **`RTCIceCandidate()`**
 constructor creates and returns a new `RTCIceCandidate` object, which can
 be configured to represent a single ICE candidate.

Syntax
------

```js
new RTCIceCandidate()
new RTCIceCandidate(candidateInfo)
```

### Parameters

`candidateInfo` Optional

 An optional object that can be provided to configure the candidate.
 The object has the following properties:

`candidate` Optional

 A string describing the properties of the candidate, taken directly from the SDP attribute `"candidate"`.
 The candidate string specifies the network connectivity information for the candidate.
 If the `candidate` is an empty string (`""`), the end of the candidate list has been reached; this candidate is known as the "end-of-candidates" marker.

 The syntax of the candidate string is described in RFC 5245, section 15.1.
 For an a-line (attribute line) that looks like this:

```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

 the corresponding `candidate` string's value will be
 `"candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host"`.

 The user agent always prefers candidates with the highest `priority`, all else being equal.
 In the example above, the priority is `2043278322`. The attributes are all separated by a single space character, and are in a specific order.
 The complete list of attributes for this example candidate is:

* `foundation` = 4234997325
* `component` = `"rtp"` (the number 1 is encoded to this string; 2 becomes `"rtcp"`)
* `protocol` = `"udp"`
* `priority` = 2043278322
* `ip` = `"192.0.2.172"`
* `port` = 44323
* `type` = `"host"`

Additional information can be found in `RTCIceCandidate.candidate`.

**Note:** For backward compatibility with older versions of the WebRTC specification, the constructor also accepts this string directly as an argument.

`sdpMid` Optional

A string containing the identification tag of the media stream with which the candidate is associated, or `null` if there is no associated media stream. The default is `null`.

Additional information can be found in `RTCIceCandidate.sdpMid`.

`sdpMLineIndex` Optional

A number property containing the zero-based index of the m-line with which the candidate is associated, within the SDP of the media description, or `null` if no such associated exists. The default is `null`.

Additional information can be found in `RTCIceCandidate.sdpMLineIndex`.

`usernameFragment` Optional

 A string containing the username fragment (usually referred to in shorthand as "ufrag" or "ice-ufrag").
 This fragment, along with the ICE password ("ice-pwd"), uniquely identifies a single ongoing ICE interaction (including for any communication with the STUN server).

 The string is generated by WebRTC at the beginning of the session.
 It may be up to 256 characters long, and at least 24 bits must contain random data.
 It has no default value and is not present unless set explicitly.

Additional information can be found in `RTCIceCandidate.usernameFragment`.

### Return value

A newly-created `RTCIceCandidate` object.

If `candidateInfo` is provided, the new `RTCIceCandidate` is initialized as follows:

* Each member of the `RTCIceCandidate` object is initialized to the value of the property by the same name from `candidateInfo`.
 This includes the `candidate`, `sdpMid`, `sdpMLineIndex`, and `usernameFragment` properties.
* The `candidate` string (which is SDP text) is parsed; each property found is stored in the corresponding field in the `RTCIceCandidate`.
 If any of the fields is invalid, parsing of the string silently aborts without throwing an exception.
 The default value of `candidate` is the empty string, which indicates that the candidate is an "end-of-candidates" message.
* The following fields are initialized to `null` if they are not included in the `RTCIceCandidate.candidate` property:
 `foundation`,
 `component`,
 `priority`, `address`, `protocol`,
 `port`, `type`, `tcpType`,
 `relatedAddress`, and `relatedPort`.

**Note:** Parsing of the `candidate` string is performed using the candidate-attribute grammar from the WebRTC Specification.

### Exceptions

`TypeError`

Thrown if the specified `candidateInfo` has values of `null` in **both** the `sdpMid` and `sdpMLineIndex` properties.

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

This constructor does not do complete validation of the specified `candidateInfo` object or string.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-constructor |

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

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

See also
--------

* Introduction to WebRTC protocols
* WebRTC connectivity
* Lifetime of a WebRTC session
* Signaling and video calling


RTCIceCandidate: address property - Web APIs

RTCIceCandidate: address property
=================================

 The **`RTCIceCandidate`** interface's read-only **`address`** property is a string providing the IP address of the device which is the source of the candidate.
 The `address` is `null` by default if not otherwise specified.

 The `address` field's value is set from the `candidateInfo` options object passed to the `RTCIceCandidate()` constructor.
 You can't specify the value of `address` directly in the options object, but its value is automatically extracted from the object's `candidate` a-line, if it's formatted properly.

Value
-----

A string providing the IP address from which the candidate comes.

**Note:** If `port` is `null` — and
 `port` is supported by the user agent — passing the
 candidate to `addIceCandidate()`
 will fail, throwing an `OperationError` exception.

Security notes
--------------

 It's important to note here that although WebRTC does not require the two peers on an
 `RTCPeerConnection` to know one another's true IP addresses, the
 `address` property on `RTCIceCandidate` *can* expose more
 information about the source of the remote peer than the user expects. The IP address
 can be used to derive information about the remote device's location, network topology,
 and so forth. It can also be used for fingerprinting purposes.

 The candidate IP addresses are *always* exposed to the application through
 `address`, and unsavory applications can in turn potentially reveal the
 address to the user. This can occur without the remote peer's consent.

 Applications being built with user privacy and security in mind can choose to limit the
 permitted candidates to relay candidates only. Doing so prevents the remote user's
 address from being exposed, but reduces the pool of available candidates to choose from.
 To do this, configure the ICE agent's ICE transport policy with an object confirming to the `configuration` property described in `RTCPeerConnection.setConfiguration`, like this:

```js
const rtcConfig = {
  iceServers: [
    {
      urls: "turn:myturn.server.ip",
      username: "username",
      credential: "password",
    },
  ],
  iceTransportPolicy: "relay",
};
```

 By setting `iceTransportPolicy` to `"relay"`,
 any host candidates (candidates where the IP address is the peer's own IP address) are
 left out of the pool of candidates, as are any other candidates which aren't relay candidates.

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

Consider this SDP attribute line (a-line) which describes an ICE candidate:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

The fifth field, `"192.0.2.172"` is the IP address in this candidate's a-line string.

Examples
--------

This code snippet uses the value of `address` to implement an IP address based ban feature.

```js
if (ipBanList.includes(candidate.address)) {
  rejectCandidate(candidate);
} else {
  acceptCandidate(candidate);
}
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-address |

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

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


RTCIceCandidate: candidate property - Web APIs

RTCIceCandidate: candidate property
===================================

 The read-only property **`candidate`** on the `RTCIceCandidate` interface returns a string describing the candidate in detail.
 Most of the other properties of `RTCIceCandidate` are actually extracted from this string.

This property can be configured using the `candidate` property of the object passed into the `RTCIceCandidate() constructor` or `RTCPeerConnection.addIceCandidate()`.

Value
-----

 A string describing the properties of the candidate, taken directly from the SDP attribute `"candidate"`.
 The candidate string specifies the network connectivity information for the candidate.
 If the `candidate` is an empty string (`""`), the end of the candidate list has been reached; this candidate is known as the "end-of-candidates" marker.

The syntax of the candidate string is described in RFC 5245, section 15.1. For an a-line (attribute line) that looks like this:
```

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host
```

the corresponding `candidate` string's value will be: `"candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host"`.

 The user agent always prefers candidates with the highest
 `priority`, all else being equal. In the
 example above, the priority is `2043278322`. The attributes are all separated
 by a single space character, and are in a specific order. The complete list of
 attributes for this example candidate is:

* `foundation` = 4234997325
* `component` = `"rtp"` (the number 1 is encoded to this string; 2 becomes `"rtcp"`)
* `protocol` = `"udp"`
* `priority` = 2043278322
* `ip` = `"192.0.2.172"`
* `port` = 44323
* `type` = `"host"`
Examples
--------

 In this example, we see a function which receives as input an SDP string containing an
 ICE candidate received from the remote peer during the signaling process.

```js
function handleNewIceCandidate(candidateSDP) {
  const candidateObj = new RTCIceCandidate(candidateSDP);

  myPeerConnection.addIceCandidate(candidateObj).catch({
    /\* handle the error thrown by addIceCandidate() \*/
  });
}
```

 The `handleNewIceCandidate()` function shown here passes the received
 candidate's SDP text into `RTCIceCandidate()` to receive an `RTCIceCandidate` object in return,
 which represents the candidate.

 The new candidate is then passed into `RTCPeerConnection.addIceCandidate()` to add the candidate to the list of
 candidates for WebRTC to consider using for the connection being established.

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcicecandidate-candidate |

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

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


XRRay: origin property - Web APIs

XRRay: origin property
======================

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

The *read-only* **`origin`** property of the `XRRay` interface is a `DOMPointReadOnly` representing the 3-dimensional point in space that the ray originates from, in meters.

Value
-----

A `DOMPointReadOnly` object.

Examples
--------

### Using the `origin` property

The `origin` property contains the 3-dimensional point in space that the ray originates from, in meters.

```js
let origin = { x: 10.0, y: 10.0, z: 10.0, w: 1.0 };
let direction = { x: 10.0, y: 0.0, z: 0.0, w: 0.0 };
let ray = new XRRay(origin, direction);

ray.origin;
// returns DOMPointReadOnly {x : 10.0, y : 10.0, z : 10.0, w : 1.0}
```

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

| Specification |
| --- |
| WebXR Hit Test Module # dom-xrray-origin |

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

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

See also
--------

* `DOMPointReadOnly`


XRRay: matrix property - Web APIs

XRRay: matrix property
======================

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

The *read-only* **`matrix`** property of the `XRRay` interface is a transform that can be used to position objects along the `XRRay`. This is a 4 by 4 matrix given as a 16 element `Float32Array` in column major order.

The transform from a ray originates at [0, 0, 0] and extends down the negative z-axis to the ray described by the `XRRay`'s `origin` and `direction`.

Value
-----

A 16 element `Float32Array` object representing a 4 by 4 matrix in column major order.

Examples
--------

### Using the `matrix` property

The `matrix` property can be used to position graphical representations of the ray when rendering.

```js
let origin = { x: 10.0, y: 10.0, z: 10.0, w: 1.0 };
let direction = { x: 10.0, y: 0.0, z: 0.0, w: 0.0 };
let ray = new XRRay(origin, direction);

// Render the ray using the `ray.matrix` transform
```

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

| Specification |
| --- |
| WebXR Hit Test Module # dom-xrray-matrix |

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

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

See also
--------

* `Float32Array`


XRRay: direction property - Web APIs

XRRay: direction property
=========================

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

The *read-only* **`direction`** property of the `XRRay` interface is a `DOMPointReadOnly` representing the ray's 3-dimensional directional vector, normalized to a unit vector with a length of 1.0.

Value
-----

A `DOMPointReadOnly` object.

Examples
--------

### Using the `direction` property

The `direction` property contains the normalized ray's 3-dimensional directional vector.

```js
let origin = { x: 10.0, y: 10.0, z: 10.0, w: 1.0 };
let direction = { x: 10.0, y: 0.0, z: 0.0, w: 0.0 };
let ray = new XRRay(origin, direction);

ray.direction;
// returns DOMPointReadOnly {x : 1.0, y : 0.0, z : 0.0, w : 0.0}
```

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

| Specification |
| --- |
| WebXR Hit Test Module # dom-xrray-direction |

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

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

See also
--------

* `DOMPointReadOnly`


XRRay: XRRay() constructor - Web APIs

XRRay: XRRay() constructor
==========================

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

The **`XRRay()`** constructor creates a new `XRRay` object which is a geometric ray described by an origin point and a direction vector.

Syntax
------

```js
new XRRay()
new XRRay(origin)
new XRRay(origin, direction)
new XRRay(transform)
```

### Parameters

`origin` Optional

A point object defining the 3-dimensional point in space that the ray originates from, in meters. All dimensions are optional, however, if provided, the origin's `w` property must be 1.0. The object is initialized to `{ x: 0.0, y: 0.0, z: 0.0, w: 1.0 }` by default.

`direction` Optional

A vector object defining the ray's 3-dimensional directional vector. All dimensions are optional, however, if provided, the direction's `w` property must be 0.0. The object is initialized to: `{ x: 0.0, y: 0.0, z: -1.0, w: 0.0 }` by default.

`transform` Optional

An `XRRigidTransform` object representing the position and orientation of the ray.

### Return value

A newly-created `XRRay` object.

### Exceptions

`TypeError`

Thrown if one of the following conditions is met:

* all of `direction`'s `x`, `y`, and `z` coordinates are zero.
* `direction`'s `w` coordinate is not 0.0.
* `origin`'s `w` coordinate is not 1.0.

Examples
--------

### Creating `XRRay` objects

The `XRRay()` constructor allows to creating new rays by either providing an `origin` point and a `direction` vector, or by passing in an `XRRigidTransform` object.

```js
// Default configuration
let ray1 = new XRRay();

// Specifying origin, leaving direction as default
let ray2 = new XRRay({ y: 0.5 });

// Specifying both, origin and direction
let origin = { x: 10.0, y: 10.0, z: 10.0, w: 1.0 };
let direction = { x: 10.0, y: 0.0, z: 0.0, w: 0.0 };
let ray3 = new XRRay(origin, direction);

// Using DOMPoint.fromPoint
let ray4 = new XRRay(DOMPoint.fromPoint(origin), DOMPoint.fromPoint(direction));

// Using rigid transform
let rigidTransform = new XRRigidTransform(
  DOMPoint.fromPoint(origin),
  DOMPoint.fromPoint(direction),
);
let ray5 = new XRRay(rigidTransform);
```

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

| Specification |
| --- |
| WebXR Hit Test Module # dom-xrray-xrray |

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

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

See also
--------

* `DOMPoint`
* `DOMPoint.fromPoint()`


IDBFactory: databases() method - Web APIs

IDBFactory: databases() method
==============================

The **`databases`** method of the `IDBFactory` interface returns a list representing all the available databases, including their names and versions.

**Note:** This feature is available in Web Workers

**Note:** This method is introduced in a draft of a specifications and browser compatibility is limited.

Syntax
------

```js
databases()
```

### Parameters

The method does not take in any parameters.

### Return value

A promise that resolves either to an error or a list of dictionaries, each with two elements, `name` and `version`:

`name`

The database name.

`version`

The database version.

### Exceptions

`SecurityError` `DOMException`

Thrown if the method is called from an opaque origin.

Examples
--------

```js
const promise = indexedDB.databases();
promise.then((databases) => {
  console.log(databases);
});
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbfactory-databases① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


IDBFactory: cmp() method - Web APIs

IDBFactory: cmp() method
========================

 The **`cmp()`** method of the `IDBFactory`
 interface compares two values as keys to determine equality and ordering for IndexedDB
 operations, such as storing and iterating.

**Note:** This feature is available in Web Workers

**Note:** Do not use this method for comparing arbitrary JavaScript
 values, because many JavaScript values are either not valid IndexedDB keys (booleans
 and objects, for example) or are treated as equivalent IndexedDB keys (for example,
 since IndexedDB ignores arrays with non-numeric properties and treats them as empty
 arrays, so any non-numeric arrays are treated as equivalent). This throws an exception
 if either of the values is not a valid key.

Syntax
------

```js
cmp(first, second)
```

### Parameters

`first`

The first key to compare.

`second`

The second key to compare.

### Return value

 An integer that indicates the result of the comparison; the table below lists the
 possible values and their meanings:

| Returned value | Description |
| --- | --- |
| -1 | 1st key is less than the 2nd key |
| 0 | 1st key is equal to the 2nd key |
| 1 | 1st key is greater than the 2nd key |

### Exceptions

`DataError` `DOMException`

Thrown if one of the supplied keys was not a valid key.

Examples
--------

```js
const a = 1;
const b = 2;
const result = window.indexedDB.cmp(a, b);
console.log(`Comparison results: ${result}`);
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbfactory-cmp① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


IDBFactory: deleteDatabase() method - Web APIs

IDBFactory: deleteDatabase() method
===================================

 The **`deleteDatabase()`** method of the
 `IDBFactory` interface requests the deletion of a database. The method
 returns an `IDBOpenDBRequest` object immediately, and performs the deletion
 operation asynchronously.

 If the database is successfully deleted, then a `success` event is fired on
 the request object returned from this method, with its `result` set to
 `undefined`. If an error occurs while the database is being deleted, then an
 `error` event is fired on the request object that is returned from this
 method.

 When `deleteDatabase()` is called, any other open connections to this
 particular database will get a versionchange event.

**Note:** This feature is available in Web Workers

Syntax
------

```js
// For the current standard:
deleteDatabase(name)

// For the experimental version with `options` (see below):
deleteDatabase(name)
deleteDatabase(name, options)
```

### Parameters

`name`

 The name of the database you want to delete. Note that attempting to delete a
 database that doesn't exist does not throw an exception, in contrast to
 `IDBDatabase.deleteObjectStore()`, which does throw an exception if the
 named object store does not exist.

`options` Optional
Non-standard

 In Gecko, since version 26, you can include
 a non-standard optional storage parameter that specifies whether you want to delete a
 `permanent` (the default value) IndexedDB, or an indexedDB in
 `temporary` storage (aka shared pool.)

### Return value

A `IDBOpenDBRequest` on which subsequent events related to this request are fired.

If the operation is successful, the value of the request's `result` property is `null`.

Examples
--------

```js
const DBDeleteRequest = window.indexedDB.deleteDatabase("toDoList");

DBDeleteRequest.onerror = (event) => {
  console.error("Error deleting database.");
};

DBDeleteRequest.onsuccess = (event) => {
  console.log("Database deleted successfully");

  console.log(event.result); // should be undefined
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbfactory-deletedatabase① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


IDBFactory: open() method - Web APIs

IDBFactory: open() method
=========================

The **`open()`** method of the `IDBFactory` interface requests opening a connection to a database.

 The method returns an `IDBOpenDBRequest` object immediately, and performs the open operation asynchronously.
 If the operation is successful, a `success` event is fired on the request object that is returned from this method, with its `result` attribute set to the new `IDBDatabase` object for the connection.

May trigger `upgradeneeded`, `blocked` or `versionchange` events.

**Note:** This feature is available in Web Workers

Syntax
------

```js
open(name)
open(name, version)
```

### Parameters

`name`

The name of the database.

`version` Optional

 Optional. The version to open the database with. If the version is not provided and the database exists, then a connection to the database will be opened without changing its version.
 If the version is not provided and the database does not exist, then it will be created with version `1`.

### Return value

A `IDBOpenDBRequest` object on which subsequent events related to this request are fired.

If the operation is successful, the value of the request's `result` property is a `IDBDatabase` object representing the connection to the database.

### Exceptions

`TypeError`

Thrown if the value of `version` is not a number greater than zero.

Examples
--------

Example of calling `open` with the current specification's `version` parameter:

```js
const request = window.indexedDB.open("toDoList", 4);
```

 In the following code snippet, we make a request to open a database, and include handlers for the success and error cases.
 For a full working example, see our To-do Notifications app (View the example live).

```js
const note = document.querySelector("ul");

// Let us open version 4 of our database
const DBOpenRequest = window.indexedDB.open("toDoList", 4);

// these two event handlers act on the database being opened
// successfully, or not
DBOpenRequest.onerror = (event) => {
  note.innerHTML += "<li>Error loading database.</li>";
};

DBOpenRequest.onsuccess = (event) => {
  note.innerHTML += "<li>Database initialized.</li>";

  // store the result of opening the database in the db
  // variable. This is used a lot later on, for opening
  // transactions and suchlike.
  db = DBOpenRequest.result;
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbfactory-open② |

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

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

See also
--------

* Using IndexedDB
* Browser storage quotas and eviction criteria.
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (View the example live).


WEBGL_lose_context: loseContext() method - Web APIs

WEBGL\_lose\_context: loseContext() method
==========================================

 The **WEBGL\_lose\_context.loseContext()** method is part of the WebGL API and allows you to simulate losing
 the context of a `WebGLRenderingContext` context.

 It triggers the steps described in the WebGL specification for handling context lost.
 The context will remain lost until `WEBGL_lose_context.restoreContext()` is
 called.

Syntax
------

```js
loseContext()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

 With this method, you can simulate the
 `webglcontextlost`
 event:

```js
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextlost",
  (e) => {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").loseContext();

// WebGLContextEvent event with type "webglcontextlost" is logged.
```

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

| Specification |
| --- |
| WebGL WEBGL\_lose\_context Khronos Ratified Extension Specification  |

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

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

See also
--------

* `WebGLRenderingContext.isContextLost()`
* Events:
 `webglcontextlost`,
 `webglcontextrestored`,
 `webglcontextcreationerror`


WEBGL_lose_context: restoreContext() method - Web APIs

WEBGL\_lose\_context: restoreContext() method
=============================================

 The **WEBGL\_lose\_context.restoreContext()** method is part of the WebGL API and allows you to simulate
 restoring the context of a `WebGLRenderingContext` object.

Syntax
------

```js
restoreContext()
```

### Parameters

None.

### Return value

None (`undefined`).

### Exceptions

Browsers may not report WebGL errors by default. WebGL's error reporting works by calling `getError()` and checking for errors. The following exceptions may be thrown:

`INVALID_OPERATION`

Thrown if the context was not lost.

Examples
--------

 With this method, you can simulate the
 `webglcontextrestored`
 event:

```js
const canvas = document.getElementById("canvas");
const gl = canvas.getContext("webgl");

canvas.addEventListener(
  "webglcontextrestored",
  (e) => {
    console.log(e);
  },
  false,
);

gl.getExtension("WEBGL\_lose\_context").restoreContext();
```

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

| Specification |
| --- |
| WebGL WEBGL\_lose\_context Khronos Ratified Extension Specification  |

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

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

See also
--------

* `WebGLRenderingContext.isContextLost()`
* Events:
 `webglcontextlost`,
 `webglcontextrestored`,
 `webglcontextcreationerror`


HTMLDialogElement: showModal() method - Web APIs

HTMLDialogElement: showModal() method
=====================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`showModal()`** method of the
 `HTMLDialogElement` interface displays the dialog as a modal, over the top
 of any other dialogs that might be present. It displays in the top layer, along with a
 `::backdrop` pseudo-element. Interaction outside the dialog is blocked and
 the content outside it is rendered inert.

Syntax
------

```js
showModal()
```

### Parameters

None.

### Return value

None (`undefined`).

### Exceptions

`InvalidStateError` `DOMException`

Thrown if the dialog is already open (i.e. if the `open` attribute is already set on the `<dialog>` element), or if the dialog is also a popover that is already being shown.

Examples
--------

### Opening a modal dialog

The following example shows a button that, when clicked, opens a modal `<dialog>` containing a form via the `HTMLDialogElement.showModal()` function. While open, everything other than the modal dialog's contents is inert. From there you can click the *Cancel* button to close the dialog (via the `HTMLDialogElement.close()` function), or submit the form via the submit button. Selecting the cancel button closes the dialog, creating a `close` event, not a `cancel` event.

#### HTML

```html
<!-- pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <p>
      <label for="favAnimal">Favorite animal:</label>
      <select id="favAnimal" name="favAnimal">
        <option></option>
        <option>Brine shrimp</option>
        <option>Red panda</option>
        <option>Spider monkey</option>
      </select>
    </p>
    <div>
      <button id="cancel" type="reset">Cancel</button>
      <button type="submit">Confirm</button>
    </div>
  </form>
</dialog>

<div>
  <button id="updateDetails">Update details</button>
</div>
```

#### JavaScript

```js
const updateButton = document.getElementById("updateDetails");
const cancelButton = document.getElementById("cancel");
const dialog = document.getElementById("favDialog");
dialog.returnValue = "favAnimal";

function openCheck(dialog) {
  if (dialog.open) {
    console.log("Dialog open");
  } else {
    console.log("Dialog closed");
  }
}

// Update button opens a modal dialog
updateButton.addEventListener("click", () => {
  dialog.showModal();
  openCheck(dialog);
});

// Form cancel button closes the dialog box
cancelButton.addEventListener("click", () => {
  dialog.close("animalNotChosen");
  openCheck(dialog);
});
```

#### Result

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

| Specification |
| --- |
| HTML Standard # dom-dialog-showmodal-dev |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


HTMLDialogElement: open property - Web APIs

HTMLDialogElement: open property
================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`open`** property of the
 `HTMLDialogElement` interface is a boolean value reflecting the
 `open` HTML attribute, indicating whether the `<dialog>` is
 available for interaction.

Value
-----

 A boolean value representing the state of the `open` HTML attribute. `true` means it is set, and therefore the dialog
 is shown. `false` means it not set, and therefore the dialog is not shown.

 The property is not read only — it is possible to set the value to programmatically
 show or hide the dialog.

Examples
--------

 The following example shows a simple button that, when clicked, opens a
 `<dialog>` containing a form via the `showModal()` method.
 From there you can click the *Cancel* button to close the dialog (via the
 `HTMLDialogElement.close()` method), or submit the form via the submit
 button.

```html
<!-- Simple pop-up dialog box -->
<dialog id="dialog">
  <form method="dialog">
    <button type="submit">Close</button>
  </form>
</dialog>

<p>
  <button id="openDialog">Open Dialog</button>
</p>
<p id="dialogStatus"></p>

<script>
 (() => {
 const openDialog = document.getElementById("openDialog");
 const dialog = document.getElementById("dialog");
 const text = document.getElementById("dialogStatus");

 function openCheck(dialog) {
 if (dialog.open) {
 text.innerText = "Dialog open";
 } else {
 text.innerText = "Dialog closed";
 }
 }

 // Update button opens a modal dialog
 openDialog.addEventListener("click", () => {
 dialog.showModal();
 openCheck(dialog);
 });

 dialog.addEventListener("close", () => {
 openCheck(dialog);
 });
 })();
</script>
```

### Result

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

| Specification |
| --- |
| HTML Standard # dom-dialog-open |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


HTMLDialogElement: returnValue property - Web APIs

HTMLDialogElement: returnValue property
=======================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The **`returnValue`** property of the `HTMLDialogElement` interface gets or sets the return value for the `<dialog>`, usually to indicate which button the user pressed to close it.

Value
-----

A string representing the `returnValue` of the dialog.

Examples
--------

 The following example displays a button to open a `<dialog>` containing a form via the `showModal()` method.
 The script assigns the `returnValue` an initial value of `initialValue`.
 The confirm button (`confirmBtn`) submits the form with validation and the "X" button submits the form without validation. Submitting a form with a `method="dialog"` closes the dialog and sets the return value to the `value`, if any, of the `button` or `input` elements of `type=submit`.
 The reset button has an event handler that closes the dialog; it has no impact on the `returnValue`. Neither does closing the dialog with the `Esc` key.

```html
<!-- Simple pop-up dialog box containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <input
 type="submit"
 aria-label="close"
 value="X"
 name="Xbutton"
 formnovalidate />
    <p>
      <label
 >Favorite animal:
        <select name="favAnimal" required>
          <option></option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </label>
    </p>
    <menu>
      <button type="reset" value="resetBtn">Reset</button>
      <button type="submit" value="confirmBtn">Confirm</button>
    </menu>
  </form>
</dialog>

<p>
  <button id="openDialog">Open Dialog</button>
</p>
<p id="text"></p>

<script>
 (() => {
 const openDialog = document.getElementById("openDialog");
 const dialog = document.getElementById("favDialog");
 const text = document.getElementById("text");
 const reset = document.querySelector("[type='reset']");
 dialog.returnValue = "initialValue";

 function openCheck(dialog) {
 if (dialog.open) {
 text.innerText = "Dialog open";
 } else {
 text.innerText = "Dialog closed";
 }
 }

 function handleUserInput(returnValue) {
 if (!returnValue) {
 text.innerText += ". There was no return value";
 } else {
 text.innerText += ". Return value: " + returnValue;
 }
 }

 // "Open Dialog" button opens the <dialog> modally
 openDialog.addEventListener("click", () => {
 dialog.showModal();
 openCheck(dialog);
 handleUserInput(dialog.returnValue);
 });

 reset.addEventListener("click", () => {
 dialog.close();
 });

 // when the dialog is closed, no matter how it is closed
 dialog.addEventListener("close", () => {
 openCheck(dialog);
 handleUserInput(dialog.returnValue);
 });
 })();
</script>
<style>
 [aria-label="close"] {
 appearance: none;
 border-radius: 50%;
 border: 1px solid;
 float: right;
 }
</style>
```

### Result

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

| Specification |
| --- |
| HTML Standard # dom-dialog-returnvalue-dev |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


HTMLDialogElement: close event - Web APIs

HTMLDialogElement: close event
==============================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
The `close` event is fired on an `HTMLDialogElement` object when the `<dialog>` it represents has been closed.

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("close", (event) => {});

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

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

A generic `Event`.

Examples
--------

### Live example

#### HTML

```html
<dialog class="example-dialog">
  <form method="dialog">
    <button>Close via method="dialog"</button>
  </form>
  <button class="close">Close via .close() method</button>
  <p>Or hit the <kbd>Esc</kbd> key</p>
</dialog>

<button class="open-dialog">Open dialog</button>

<div class="result"></div>
```

```
button,
div {
  margin: 0.5rem;
}
```

#### JavaScript

```js
const result = document.querySelector(".result");

const dialog = document.querySelector(".example-dialog");
dialog.addEventListener("close", (event) => {
  result.textContent = "dialog was closed";
});

const openDialog = document.querySelector(".open-dialog");
openDialog.addEventListener("click", () => {
  dialog.showModal();
  result.textContent = "";
});

const closeButton = document.querySelector(".close");
closeButton.addEventListener("click", () => {
  dialog.close();
});
```

#### Result

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

| Specification |
| --- |
| HTML Standard # event-close |

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

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

See also
--------

* HTML `<dialog>` element


HTMLDialogElement: show() method - Web APIs

HTMLDialogElement: show() method
================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`show()`** method of the `HTMLDialogElement`
 interface displays the dialog modelessly, i.e. still allowing interaction with content
 outside of the dialog.

Syntax
------

```js
show()
```

### Parameters

None.

### Return value

None (`undefined`).

Examples
--------

 The following example shows a simple button that, when clicked, opens a
 `<dialog>` containing a form via the `show()` method. From
 there you can click the *Cancel* button to close the dialog (via the
 `HTMLDialogElement.close()` method), or submit the form via the submit
 button.

```html
<!-- Simple pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <section>
      <p>
        <label for="favAnimal">Favorite animal:</label>
        <select id="favAnimal" name="favAnimal">
          <option></option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </p>
    </section>
    <menu>
      <button id="cancel" type="reset">Cancel</button>
      <button type="submit">Confirm</button>
    </menu>
  </form>
</dialog>

<menu>
  <button id="updateDetails">Update details</button>
</menu>

<script>
 (() => {
 const updateButton = document.getElementById("updateDetails");
 const cancelButton = document.getElementById("cancel");
 const dialog = document.getElementById("favDialog");
 dialog.returnValue = "favAnimal";

 function openCheck(dialog) {
 if (dialog.open) {
 console.log("Dialog open");
 } else {
 console.log("Dialog closed");
 }
 }

 // Update button opens a modeless dialog
 updateButton.addEventListener("click", () => {
 dialog.show();
 openCheck(dialog);
 });

 // Form cancel button closes the dialog box
 cancelButton.addEventListener("click", () => {
 dialog.close("animalNotChosen");
 openCheck(dialog);
 });
 })();
</script>
```

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

| Specification |
| --- |
| HTML Standard # dom-dialog-show-dev |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


HTMLDialogElement: close() method - Web APIs

HTMLDialogElement: close() method
=================================

Baseline 2022
-------------

Newly availableSince March 2022, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback

 The **`close()`** method of the `HTMLDialogElement` interface closes the `<dialog>`.
 An optional string may be passed as an argument, updating the `returnValue` of the dialog.

Syntax
------

```js
close()
close(returnValue)
```

### Parameters

`returnValue` Optional

A string representing an updated value for the `HTMLDialogElement.returnValue` of the dialog.

### Return value

None (`undefined`).

Examples
--------

 The following example shows a simple button that, when clicked, opens a `<dialog>` containing a form via the `showModal()` method.
 From there you can click the *X* button to close the dialog (via the `HTMLDialogElement.close()` method), or submit the form via the submit button.

```html
<!-- Simple pop-up dialog box, containing a form -->
<dialog id="favDialog">
  <form method="dialog">
    <button id="close" aria-label="close" formnovalidate>X</button>
    <section>
      <p>
        <label for="favAnimal">Favorite animal:</label>
        <select id="favAnimal" name="favAnimal">
          <option></option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </p>
    </section>
    <menu>
      <button type="reset">Reset</button>
      <button type="submit">Confirm</button>
    </menu>
  </form>
</dialog>

<menu>
  <button id="updateDetails">Update details</button>
</menu>

<script>
 (() => {
 const updateButton = document.getElementById("updateDetails");
 const closeButton = document.getElementById("close");
 const dialog = document.getElementById("favDialog");
 dialog.returnValue = "favAnimal";

 function openCheck(dialog) {
 if (dialog.open) {
 console.log("Dialog open");
 } else {
 console.log("Dialog closed");
 }
 }

 // Update button opens a modal dialog
 updateButton.addEventListener("click", () => {
 dialog.showModal();
 openCheck(dialog);
 });

 // Form close button closes the dialog box
 closeButton.addEventListener("click", () => {
 dialog.close("animalNotChosen");
 openCheck(dialog);
 });
 })();
</script>
```

 If the "X" button was of `type="submit"`, the dialog would have closed without requiring JavaScript.
 A form submission closes the `<dialog>` it is nested within if the form's method is `dialog`, so no "close" button is required.

### Result

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

| Specification |
| --- |
| HTML Standard # dom-dialog-close-dev |

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

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

See also
--------

* The HTML element implementing this interface: `<dialog>`.


FileList: item() method - Web APIs

FileList: item() method
=======================

**Note:** This feature is available in Web Workers

The **`item()`** method of the `FileList` interface returns a `File` object representing the file at the specified index in the file list.

Syntax
------

```js
item(index)
```

### Parameters

`index`

The zero-based index of the file to retrieve from the list.

### Return value

A `File` object representing the requested file.

Examples
--------

### Printing the name of a file

In this example, we use `item()` to select the first item in the `FileList`.

#### HTML

```html
<input type="file" />
<div class="output"></div>
```

#### JavaScript

```js
const fileInput = document.querySelector("input[type=file]");
const output = document.querySelector(".output");

fileInput.addEventListener("change", () => {
  const fileList = fileInput.files;
  if (fileList.length > 0) {
    const file = fileList.item(0);
    output.textContent = `You selected: ${file.name}`;
  }
});
```

#### Result

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

| Specification |
| --- |
| File API # dfn-item |

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

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


FileList: length property - Web APIs

FileList: length property
=========================

**Note:** This feature is available in Web Workers

The **`length`** read-only property of the `FileList` interface returns the number of files in the `FileList`.

Value
-----

A number indicating the number of files in the list.

Examples
--------

### Printing the number of files selected

In this example, we use `length` to find the number of items in the `FileList`.

#### HTML

```html
<input type="file" multiple />
<div class="output"></div>
```

#### JavaScript

```js
const fileInput = document.querySelector("input[type=file]");
const output = document.querySelector(".output");

fileInput.addEventListener("change", () => {
  const fileList = fileInput.files;
  output.textContent = `You've selected: ${fileList.length} file(s)`;
});
```

#### Result

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

| Specification |
| --- |
| File API # dfn-length |

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

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


MediaTrackSupportedConstraints: latency property - Web APIs

MediaTrackSupportedConstraints: latency property
================================================

 The `MediaTrackSupportedConstraints` dictionary's **`latency`** property is a read-only Boolean value which is present (and set to `true`) in the object returned by `MediaDevices.getSupportedConstraints()` if and only if the user agent supports the `latency` constraint.
 If the constraint isn't supported, it's not included in the list, so this value will never be `false`.

You can access the supported constraints dictionary by calling `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`) if the user agent supports the `latency` constraint.
 If the property isn't present, this property is missing from the supported constraints dictionary, and you'll get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().latency;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-latency |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: deviceId property - Web APIs

MediaTrackSupportedConstraints: deviceId property
=================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`deviceId`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `deviceId` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `deviceId` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().deviceId;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-deviceid |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: volume property - Web APIs

MediaTrackSupportedConstraints: volume property
===============================================

**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 `MediaTrackSupportedConstraints` dictionary's
 **`volume`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `volume` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `volume` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().volume;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: aspectRatio property - Web APIs

MediaTrackSupportedConstraints: aspectRatio property
====================================================

 The `MediaTrackSupportedConstraints` dictionary's **`aspectRatio`** property is a read-only Boolean value which is present (and set to `true`) in the object returned by `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `aspectRatio` constraint.
 If the constraint isn't supported, it's not included in the list, so this value will never be `false`.

You can access the supported constraints dictionary by calling `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `aspectRatio` constraint. If the property
 isn't present, this property is missing from the supported constraints dictionary, and
 you'll get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().aspectRatio;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-aspectratio |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: width property - Web APIs

MediaTrackSupportedConstraints: width property
==============================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`width`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `width` constraint. If the constraint
 isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Syntax
------

```js
widthConstraintSupported = supportedConstraintsDictionary.width
```

### Value

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `width` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Example
-------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().width;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-width |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: groupId property - Web APIs

MediaTrackSupportedConstraints: groupId property
================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`groupId`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `groupId` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `groupId` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().groupId;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-groupid |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: height property - Web APIs

MediaTrackSupportedConstraints: height property
===============================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`height`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `height` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `height` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().height;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-height |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: noiseSuppression property - Web APIs

MediaTrackSupportedConstraints: noiseSuppression property
=========================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`noiseSuppression`** property is a read-only Boolean value
 which is present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the **`noiseSuppression`**
 constraint. If the constraint isn't supported, it's not included in the list, so this
 value will never be `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

 The `noiseSuppression` constraint indicates whether or not the browser
 offers the ability to automatically control the gain (volume) on media tracks; this
 obviously is contingent on whether or not the individual device supports automatic gain
 control as well.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `noiseSuppression` constraint (and therefore
 supports noise suppression on audio tracks). If the property isn't present, this
 property is missing from the supported constraints dictionary, and you'll get
 `undefined` if you try to look at its value.

Examples
--------

 This example displays whether or not your browser supports the
 `noiseSuppression` constraint.
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported =
  navigator.mediaDevices.getSupportedConstraints().noiseSuppression;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-noisesuppression |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: sampleRate property - Web APIs

MediaTrackSupportedConstraints: sampleRate property
===================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`sampleRate`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `sampleRate` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `sampleRate` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().sampleRate;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-samplerate |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: autoGainControl property - Web APIs

MediaTrackSupportedConstraints: autoGainControl property
========================================================

 The `MediaTrackSupportedConstraints` dictionary's **`autoGainControl`** property is a read-only Boolean value which is present (and set to `true`) in the object returned by `MediaDevices.getSupportedConstraints()` if and only if the user agent supports the **`autoGainControl`** constraint.
 If the constraint isn't supported, it's not included in the list, so this value will never be `false`.

You can access the supported constraints dictionary by calling `navigator.mediaDevices.getSupportedConstraints()`.

The `autoGainControl` constraint indicates whether or not the browser offers the ability to automatically control the gain (volume) on media tracks; this obviously is contingent on whether or not the individual device supports automatic gain control as well; it's typically a feature provided by microphones.

Value
-----

 This property is present in the dictionary (and its value is always `true`) if the user agent supports the `autoGainControl` constraint.
 If the property isn't present, this property is missing from the supported constraints dictionary, and you'll get `undefined` if you try to look at its value.

Examples
--------

This example displays whether or not your browser supports the `autoGainControl` constraint.
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported =
  navigator.mediaDevices.getSupportedConstraints().autoGainControl;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-autogaincontrol |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: echoCancellation property - Web APIs

MediaTrackSupportedConstraints: echoCancellation property
=========================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`echoCancellation`** property is a read-only Boolean value
 which is present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `echoCancellation` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `echoCancellation` constraint. If the property
 isn't present, this property is missing from the supported constraints dictionary, and
 you'll get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported =
  navigator.mediaDevices.getSupportedConstraints().echoCancellation;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-echocancellation |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: channelCount property - Web APIs

MediaTrackSupportedConstraints: channelCount property
=====================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`channelCount`** property is a read-only Boolean value which
 is present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `channelCount` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `channelCount` constraint. If the property
 isn't present, this property is missing from the supported constraints dictionary, and
 you'll get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().channelCount;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-channelcount |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: sampleSize property - Web APIs

MediaTrackSupportedConstraints: sampleSize property
===================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`sampleSize`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `sampleSize` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `sampleSize` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().sampleSize;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-samplesize |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: facingMode property - Web APIs

MediaTrackSupportedConstraints: facingMode property
===================================================

 The `MediaTrackSupportedConstraints` dictionary's
 **`facingMode`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by
 `MediaDevices.getSupportedConstraints()` if and only if the
 user agent supports the `facingMode` constraint. If the
 constraint isn't supported, it's not included in the list, so this value will never be
 `false`.

 You can access the supported constraints dictionary by calling
 `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

 This property is present in the dictionary (and its value is always `true`)
 if the user agent supports the `facingMode` constraint. If the property isn't
 present, this property is missing from the supported constraints dictionary, and you'll
 get `undefined` if you try to look at its value.

Examples
--------
```

<div id="result"></div>
```

```
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().facingMode;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### Result

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-facingmode |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: frameRate property - Web APIs

MediaTrackSupportedConstraints: frameRate property
==================================================

 The `MediaTrackSupportedConstraints` dictionary's **`frameRate`** property is a read-only Boolean value which is
 present (and set to `true`) in the object returned by `MediaDevices.getSupportedConstraints()` if and only if the user agent supports the `frameRate` constraint.

If the constraint isn't supported, it's not included in the list, so this value will never be `false`.

 The `frameRate` constraint can be used to establish acceptable upper and lower bounds on the video frame rate for a new video track, or to specify an exact frame rate that must be provided for the request to succeed.
 Checking the value of this property lets you determine if the user agent allows constraining the video track configuration by frame rate. See the example to see how this can be used.

Value
-----

 This property is present in the dictionary if the user agent supports the `frameRate` constraint.
 If the property isn't present, the user agent doesn't allow specifying limits on the frame rate for video tracks.

**Note:** If this property is present, its value is always `true`.

Examples
--------

This simple example looks to see if your browser supports constraining the frame rate when requesting video tracks.

### JavaScript

```js
const result = document.getElementById("result");
const supported = navigator.mediaDevices.getSupportedConstraints().frameRate;
result.textContent = supported ? "Supported!" : "Not supported!";
```

### HTML

```html
<div id="result"></div>
```

### CSS

```css
#result {
  font:
    14px "Arial",
    sans-serif;
}
```

### Result

The output, showing if your browser supports the `frameRate` constraint, is:

 While this example is trivial, you can replace the simple output of "Supported" vs.
 "Not supported" with code to provide alternative methods for presenting the audiovisual information you want to share with the user or otherwise work with.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatracksupportedconstraints-framerate |

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

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

See also
--------

* Media Capture and Streams API
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackSupportedConstraints: suppressLocalAudioPlayback property - Web APIs

MediaTrackSupportedConstraints: suppressLocalAudioPlayback property
===================================================================

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

The `MediaTrackSupportedConstraints` dictionary's **`suppressLocalAudioPlayback`** property indicates whether or not the `suppressLocalAudioPlayback` constraint is supported by the user agent and the device on which the content is being used.

The supported constraints list is obtained by calling `navigator.mediaDevices.getSupportedConstraints()`.

Value
-----

A boolean value which is `true` if the `suppressLocalAudioPlayback` constraint is supported by the device and user agent.

Examples
--------

The function below sets up the options object for the call to `getDisplayMedia()`. It adds the `suppressLocalAudioPlayback` constraint (requesting that captured audio is not played out of the user's local speakers) only if it is known to be supported by the browser. Capturing is then started by calling `getDisplayMedia()` and attaching the returned stream to the video element referenced by the variable `videoElem`.

```js
async function capture() {
  const supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
  const displayMediaOptions = {
    audio: {},
  };

  if (supportedConstraints.suppressLocalAudioPlayback) {
    displayMediaOptions.audio.suppressLocalAudioPlayback = true;
  }

  try {
    videoElem.srcObject =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    /\* handle the error \*/
  }
}
```

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

| Specification |
| --- |
| Screen Capture # dom-mediatracksupportedconstraints-suppresslocalaudioplayback |

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

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

See also
--------

* Screen Capture API
* Using the screen capture API
* Capabilities, constraints, and settings
* `MediaDevices.getDisplayMedia()`
* `MediaStreamTrack.getConstraints()`
* `MediaStreamTrack.applyConstraints()`
* `MediaStreamTrack.getSettings()`