TextTrackCue: id property - Web APIs

TextTrackCue: id property
=========================

The **`id`** property of the `TextTrackCue` interface returns and sets the identifier for this cue.

Value
-----

A string containing the ID of this cue.

Examples
--------

In the following example a new `VTTCue` (which inherits from `TextTrackCue`) is created. The `id` property is then set to "first", before the cue is added.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.id = "first";
track.addCue(cue1);
```

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

| Specification |
| --- |
| HTML Standard # dom-texttrackcue-id |

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

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


TextTrackCue: enter event - Web APIs

TextTrackCue: enter event
=========================

The **`enter`** event fires when a cue becomes active. In the case of subtitles or a caption this is when it displays over the media.

Syntax
------

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

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

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

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

A generic `Event` with no added properties.

Example
-------

In the following example, `cue1` prints to the console when it is the active cue.

```js
cue1.addEventListener("enter", (event) => {
  console.log("Cue 1 has displayed");
});
```

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

| Specification |
| --- |
| HTML Standard # event-media-enter |
| HTML Standard # handler-texttrackcue-onenter |

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

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


CSSStyleValue: parseAll() static method - Web APIs

CSSStyleValue: parseAll() static method
=======================================

 The **`parseAll()`** static method of the `CSSStyleValue`
 interface sets all occurrences of a specific CSS property to the specified value and
 returns an array of `CSSStyleValue` objects, each containing one of the
 supplied values.

Syntax
------

```js
CSSStyleValue.parseAll(property, value)
```

### Parameters

`property`

A CSS property to set.

`value`

 A comma-separated string containing one or more values that apply to the provided
 property.

### Return value

 An array of `CSSStyleValue` objects, each containing one of the supplied
 values.

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssstylevalue-parseall |

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

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

See also
--------

* `CSSStyleValue.parse()`
* Using the CSS Typed OM
* CSS Typed Object Model API


CSSStyleValue: parse() static method - Web APIs

CSSStyleValue: parse() static method
====================================

 The **`parse()`** static method of the `CSSStyleValue`
 interface sets a specific CSS property to the specified values and returns the first
 value as a `CSSStyleValue` object.

Syntax
------

```js
CSSStyleValue.parse(property, cssText)
```

### Parameters

`property`

A CSS property to set.

`cssText`

 A comma-separated string containing one or more values to apply to the provided
 property.

### Return value

A `CSSStyleValue` object containing the first supplied value.

Examples
--------

 The code below parses a set of declarations for the `transform` property.
 The second code block shows the structure of the returned object as it would be rendered
 in a developer tools console.

```js
const css = CSSStyleValue.parse(
  "transform",
  "translate3d(10px,10px,0) scale(0.5)",
);
```

```css
CSSTransformValue {0: CSSTranslate, 1: CSSScale, length: 2, is2D: false}
```

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssstylevalue-parse |

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

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

See also
--------

* `CSSStyleValue.parseAll()`
* Using the CSS Typed OM
* CSS Typed Object Model API


Working with the History API - Web APIs

Working with the History API
============================

The History API enables a website to interact with the browser's session history: that is, the list of pages that the user has visited in a given window. As the user visits new pages, for example by clicking links, those new pages are added to the session history. The user can also move back and forth through the history using the browser's "Back" and "Forward" buttons.

The main interface defined in the History API is the `History` interface, and this defines two quite distinct sets of methods:

1. Methods to navigate to a page in the session history:
    * `History.back()`
    * `History.forward()`
    * `History.go()`
2. Methods to modify the session history:
    * `History.pushState()`
    * `History.replaceState()`

In this guide we'll be concerned only with the second set of methods, as these have more complex behavior.

The `pushState()` method adds a new entry to the session history, while the `replaceState()` method updates the session history entry for the current page. Both these methods take a `state` parameter which can contain any serializable object . When the browser navigates to this history entry, the browser fires a `popstate` event, which contains the state object associated with that entry.

The main purpose of these APIs is to support websites like Single-page applications, that use JavaScript APIs such as `fetch()` to update the page with new content, instead of loading a whole new page.

Single-page applications and session history
--------------------------------------------

Traditionally, websites are implemented as a collection of pages. When users navigate to different parts of the site by clicking links, the browser loads a whole new page each time.

While this is great for many sites, it can have some disadvantages:

* It can be inefficient to load a whole page every time, when only part of the page needs to be updated.
* It is hard to maintain application state when navigating across pages

For these reasons, a popular pattern for web apps is the single-page application (SPA), in which the site consists of a single page, and when the user clicks links, the page:

1. Prevents the default behavior of loading a new page
2. Fetches new content to display
3. Updates the page with the new content

For example:

```js
document.addEventListener("click", async (event) => {
  const creature = event.target.getAttribute("data-creature");
  if (creature) {
    // Prevent a new page from loading
    event.preventDefault();
    try {
      // Fetch new content
      const response = await fetch(`creatures/${creature}.json`);
      const json = await response.json();
      // Update the page with the new content
      displayContent(json);
    } catch (err) {
      console.error(err);
    }
  }
});
```

In this click handler, if the link contains a data attribute `"data-creature"`, then we use the value of that attribute to fetch a JSON file containing the new content for the page.

The JSON file might look like this:

```json
{
  "description": "Bald eagles are not actually bald.",
  "image": {
    "src": "images/eagle.jpg",
    "alt": "A bald eagle"
  },
  "name": "Eagle"
}
```

Our `displayContent()` function updates the page with the JSON:

```js
// Update the page with the new content
function displayContent(content) {
  document.title = `Creatures: ${content.name}`;

  const description = document.querySelector("#description");
  description.textContent = content.description;

  const photo = document.querySelector("#photo");
  photo.setAttribute("src", content.image.src);
  photo.setAttribute("alt", content.image.alt);
}
```

The problem is that it breaks the expected behavior of the browser's "Back" and "Forward" buttons.

From the user's point of view, they clicked a link and the page updated, so it looks like a new page. If they then press the browser's "Back" button, they expect to go to the state before they clicked the link.

But as far as the browser is concerned, the last link didn't load a new page, so "Back" will take the browser to whichever page was loaded before the user opened the SPA.

This is essentially the problem that `pushState()`, `replaceState()`, and the `popstate` event solve. They enable us to synthesize history entries, and to be notified when the current session history entry changes to one of these entries (for example, because the user pressed the "Back" or "Forward" buttons).

Using `pushState()`
-------------------

We can add a history entry to the click handler above as follows:

```js
document.addEventListener("click", async (event) => {
  const creature = event.target.getAttribute("data-creature");
  if (creature) {
    event.preventDefault();
    try {
      const response = await fetch(`creatures/${creature}.json`);
      const json = await response.json();
      displayContent(json);
      // Add a new entry to the history.
      // This simulates loading a new page.
      history.pushState(json, "", creature);
    } catch (err) {
      console.error(err);
    }
  }
});
```

Here, we're calling `pushState()` with three arguments:

* `json`: this is the content we just fetched. It will be stored with the history entry, and later included as the `state` property of the argument passed to the `popstate` event handler.
* `""`: this is needed for backward compatibility with legacy sites, and should always be an empty string
* `creature`: this will be used as the URL for the entry. It will be shown in the browser's URL bar, and will be used as the value of the `Referer` header in any HTTP requests that the page makes. Note that this must be same-origin with the page.
Using the `popstate` event
--------------------------

Suppose the user:

1. Clicks a link in our SPA, so we update the page and add history entry A using `pushState()`
2. Clicks another link in our SPA, so we update the page and add history entry B using `pushState()`
3. Presses the "Back" button

Now the new current history entry is A, so the browser fires the `popstate` event, and the event handler argument includes the JSON that we passed to `pushState()` when we handled the navigation to A. This means we can restore the correct content with an event handler like this:

```js
// Handle forward/back buttons
window.addEventListener("popstate", (event) => {
  // If a state has been provided, we have a "simulated" page
  // and we update the current page.
  if (event.state) {
    // Simulate the loading of the previous page
    displayContent(event.state);
  }
});
```

Using `replaceState()`
----------------------

There's one more piece we need to add. When the user loads the SPA, the browser adds a history entry. Because this was an actual page load, the entry has no state associated with it. So suppose the user:

1. Loads the SPA: the browser adds a history entry
2. Clicks a link inside the SPA: the click handler updates the page and adds a history entry with `pushState()`
3. Presses the "Back" button

Now we want to go back to the SPA's initial state, but since this is a navigation in the same document, the page will not be reloaded, and since the history entry for the initial page has no state, we can't use `popstate` to restore it.

The solution here is to use `replaceState()` to set the state object for the initial page. For example:

```js
// Create state on page load and replace the current history with it
const image = document.querySelector("#photo");
const initialState = {
  description: document.querySelector("#description").textContent,
  image: {
    src: image.getAttribute("src"),
    alt: image.getAttribute("alt"),
  },
  name: "Home",
};
history.replaceState(initialState, "", document.location.href);
```

On page load, we collect all the parts of the page that we need to restore when the user returns to the starting point for the SPA. This has the same structure as the JSON we fetch when handling other navigations. We pass this `initialState` object into `replaceState()`, which effectively adds the state object to the current history entry.

When the user returns to our starting point, the `popstate` event will contain this initial state, and we can use our `displayContent()` function to update the page.

A complete example
------------------

You can find this complete example at https://github.com/mdn/dom-examples/tree/main/history-api, and see the demo live at https://mdn.github.io/dom-examples/history-api/.

See also
--------

* History API
* `history` global object


BroadcastChannel: postMessage() method - Web APIs

BroadcastChannel: postMessage() 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 **`BroadcastChannel.postMessage()`** sends a message,
 which can be of any kind of `Object`,
 to each listener in any browsing context with the same origin.
 The message is transmitted as a 'message' event
 targeted at each `BroadcastChannel` bound to the channel.

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

Syntax
------

```js
channel.postMessage(message)
```

### Parameters

`message`

 Data to be sent to the other window. The data is serialized using the structured clone algorithm.
 This means you can pass a broad variety of data objects safely to the destination window without having to serialize them yourself.

### Return value

None.

### Exceptions

`InvalidStateError` `DOMException`

Thrown if the `BroadcastChannel` has already been closed.

`DataCloneError` `DOMException`

Thrown if any part of the input data is not serializable.

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

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-postmessage-dev |

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

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

See also
--------

* `BroadcastChannel`, the interface it belongs to.


BroadcastChannel: close() method - Web APIs

BroadcastChannel: 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 **`BroadcastChannel.close()`** terminates the connection to
 the underlying channel, allowing the object to be garbage collected.
 This is a necessary step to perform
 as there is no other way for a browser to know
 that this channel is not needed anymore.

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

Syntax
------

```js
channel.close()
```

Example
-------

```js
// Connect to a channel
const bc = new BroadcastChannel("test\_channel");

// More operations (like postMessage, …)

// When done, disconnect from the channel
bc.close();
```

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

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

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

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

See also
--------

* `BroadcastChannel`, the interface it belongs to.


BroadcastChannel: BroadcastChannel() constructor - Web APIs

BroadcastChannel: BroadcastChannel() constructor
================================================

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 **`BroadcastChannel()`** constructor creates a new
 `BroadcastChannel` and connects it to the underlying channel.

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

Syntax
------

```js
new BroadcastChannel(channelName)
```

### Parameters

`channelName`

 A string representing the name of the channel; there is one
 single channel with this name for all browsing
 contexts with the same origin.

Examples
--------

```js
// create a new channel listening to the "internal\_notification" channel.

const bc = new BroadcastChannel("internal\_notification");
bc.postMessage("New listening connected!");
```

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

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-dev |

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

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

See also
--------

* `BroadcastChannel`, the interface it belongs to.


BroadcastChannel: name property - Web APIs

BroadcastChannel: name 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 read-only **`BroadcastChannel.name`** property returns a string, which uniquely identifies the given channel with its name. This name is passed to the `BroadcastChannel()` constructor at creation time and is therefore read-only.

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

Values
------

A string.

Examples
--------

```js
// Connect to a channel
const bc = new BroadcastChannel("test\_channel");

// More operations (like postMessage, …)

// Log the channel name to the console
console.log(bc.name); // "test\_channel"

// When done, disconnect from the channel
bc.close();
```

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

| Specification |
| --- |
| HTML Standard # dom-broadcastchannel-name-dev |

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

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

See also
--------

* `BroadcastChannel`, the interface it belongs to.


BroadcastChannel: message event - Web APIs

BroadcastChannel: message 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 `message` event is fired on a `BroadcastChannel` object when a message arrives on that channel.

Syntax
------

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

```js
addEventListener("message", (event) => { })
onmessage = (event) => { }
```

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

A `MessageEvent`. Inherits from `Event`.

Event

MessageEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`data` Read only

The data sent by the message emitter.

`origin` Read only

A string representing the origin of the message emitter.

`lastEventId` Read only

A string representing a unique ID for the event.

`source` Read only

A *message event source*, which is either a WindowProxy, a `MessagePort`, or a `ServiceWorker` object representing the message emitter.

`ports` Read only

An array of `MessagePort` objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker).

Examples
--------

In this example there's a "sender" `<iframe>` that broadcasts the contents of a `<textarea>` when the user clicks a button. There are two "receiver" iframes that listen to the broadcast message and write the result into a `<div>` element.

### Sender
```

<h1>Sender</h1>
<label for="message">Type a message to broadcast:</label><br />
<textarea id="message" name="message" rows="1" cols="40">Hello</textarea>
<button id="broadcast-message" type="button">Broadcast message</button>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 150px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}

textarea {
  padding: 0.2rem;
}

label,
br {
  margin: 0.5rem 0;
}

button {
  vertical-align: top;
  height: 1.5rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
const messageControl = document.querySelector("#message");
const broadcastMessageButton = document.querySelector("#broadcast-message");

broadcastMessageButton.addEventListener("click", () => {
  channel.postMessage(messageControl.value);
});
```

### Receiver 1
```

<h1>Receiver 1</h1>
<div id="received"></div>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### Receiver 2
```

<h1>Receiver 2</h1>
<div id="received"></div>
```

```
body {
  border: 1px solid black;
  padding: 0.5rem;
  height: 100px;
  font-family: "Fira Sans", sans-serif;
}

h1 {
  font:
    1.6em "Fira Sans",
    sans-serif;
  margin-bottom: 1rem;
}
```

```js
const channel = new BroadcastChannel("example-channel");
channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});
```

### Result

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

| Specification |
| --- |
| HTML Standard # event-message |
| HTML Standard # handler-broadcastchannel-onmessage |

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

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

See also
--------

* Related events: `messageerror`.


BroadcastChannel: messageerror event - Web APIs

BroadcastChannel: messageerror 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 `messageerror` event is fired on a `BroadcastChannel` object when a message that can't be deserialized arrives on the channel.

Syntax
------

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

```js
addEventListener("messageerror", (event) => { })
onmessageerror = (event) => { }
```

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

A `MessageEvent`. Inherits from `Event`.

Event

MessageEventEvent properties
----------------

*In addition to the properties listed below, properties from the parent interface, `Event`, are available.*

`data` Read only

The data sent by the message emitter.

`origin` Read only

A string representing the origin of the message emitter.

`lastEventId` Read only

A string representing a unique ID for the event.

`source` Read only

A *message event source*, which is either a WindowProxy, a `MessagePort`, or a `ServiceWorker` object representing the message emitter.

`ports` Read only

An array of `MessagePort` objects representing the ports associated with the channel the message is being sent through (where appropriate, e.g. in channel messaging or when sending a message to a shared worker).

Examples
--------

This code uses `addEventListener` to listen for messages and errors:

```js
const channel = new BroadcastChannel("example-channel");

channel.addEventListener("message", (event) => {
  received.textContent = event.data;
});

channel.addEventListener("messageerror", (event) => {
  console.error(event);
});
```

The same, but using the `onmessage` and `onmessageerror` event handler properties:

```js
const channel = new BroadcastChannel("example-channel");

channel.onmessage = (event) => {
  received.textContent = event.data;
};

channel.onmessageerror = (event) => {
  console.log(event);
};
```

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

| Specification |
| --- |
| HTML Standard # event-messageerror |
| HTML Standard # handler-broadcastchannel-onmessageerror |

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

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

See also
--------

* Related events: `message`.


VTTCue: snapToLines property - Web APIs

VTTCue: snapToLines property
============================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`snapToLines`** property of the `VTTCue` interface is a `Boolean` indicating if the `VTTCue.line` property is an integer number of lines, or a percentage of the video size.

Value
-----

A `Boolean`.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `snapToLines` is set to `true`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.snapToLines = true;
console.log(cue1.snapToLines);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-snaptolines |

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

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


VTTCue: region property - Web APIs

VTTCue: region property
=======================

The **`region`** property of the `VTTCue` interface returns and sets the `VTTRegion` that this cue belongs to.

Value
-----

A `VTTRegion` object.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `region` is printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
console.log(cue1.region);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-region |

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

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


VTTCue: VTTCue() constructor - Web APIs

VTTCue: VTTCue() constructor
============================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback

 The **`VTTCue()`** constructor creates and returns a new
 `VTTCue` object.

Syntax
------

```js
new VTTCue(startTime, endTime, text)
```

### Parameters

`startTime`

 This is a `double` representing the initial text track cue start time.
 This is the time, given in seconds and fractions of a second, denoting the beginning
 of the range of the media data to which this cue applies. For example, if a cue is to
 be visible from 50 seconds to a one minute, five and a half seconds in the media's
 playback, `startTime` will be 50.0.

`endTime`

 This is a `double` representing the ending time for this text track cue.
 This is the time at which the cue should stop being presented to the user, given in
 seconds and fractions thereof. Given the example cue mentioned under
 `startTime`, the value of `endTime` would be 65.5.

`text`

 A string providing the text that will be shown during the time
 span indicated by `startTime` and `endTime`.

### Return value

 A new `VTTCue` object representing a cue which will be presented during
 the time span given.

Examples
--------

```js
// Create a cue that is shown from 2 to 3 seconds and uses the given text.
let cue = new VTTCue(2, 3, "Cool text to be displayed");
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-vttcue |

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

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


VTTCue: line property - Web APIs

VTTCue: line property
=====================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`line`** property of the `VTTCue` interface represents the cue line of this WebVTT cue.

Value
-----

A number, or `"auto"` representing the cue line of this WebVTT cue.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `line` is set to `1`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.line = "1";
console.log(cue1.line);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-line |

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

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


VTTCue: getCueAsHTML() method - Web APIs

VTTCue: getCueAsHTML() method
=============================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`getCueAsHTML()`** method of the `VTTCue` interface returns a `DocumentFragment` containing the cue content.

Syntax
------

```js
getCueAsHTML()
```

### Parameters

None.

### Return value

A `DocumentFragment` .

Examples
--------

In the following example a new `VTTCue` is created. The value as a document fragment is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
console.log(cue1.getCueAsHTML());

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-getcueashtml |

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

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


VTTCue: align property - Web APIs

VTTCue: align property
======================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`align`** property of the `VTTCue` interface represents the alignment of all of the lines of text in the text box.

Value
-----

A string containing one of the following values:

`"start"`

Start alignment.

`"center"`

Center alignment.

`"end"`

End alignment.

`"left"`

Left alignment.

`"right"`

Right alignment.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `align` is set to `"start"`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.align = "start";
console.log(cue1.align);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-align |

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

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


VTTCue: position property - Web APIs

VTTCue: position property
=========================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`position`** property of the `VTTCue` interface represents the indentation of the cue within the line.

Value
-----

A number, or `"auto"` representing the indentation of the cue within the line.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `position` is set to `2`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.position = "2";
console.log(cue1.position);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-position |

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

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


VTTCue: vertical property - Web APIs

VTTCue: vertical property
=========================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`vertical`** property of the `VTTCue` interface is a string representing the cue's writing direction.

Value
-----

A string containing one of the following values:

`""` (an empty string)

Represents a horizontal writing direction.

`"rl"`

Represents a vertical writing direction growing to the left.

`"lr"`

Represents a vertical writing direction growing to the right.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `vertical` is set to `"rl"`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.vertical = "rl";
console.log(cue1.vertical);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-vertical |

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

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


VTTCue: positionAlign property - Web APIs

VTTCue: positionAlign property
==============================

The **`positionAlign`** property of the `VTTCue` interface is used to determine what `VTTCue.position` is anchored to.

Value
-----

A string containing one of the following values:

`"line-left"`

Line-left alignment.

`"center"`

Center alignment.

`"line-right"`

Line-right alignment.

`"auto"`

Automatic alignment, which depends on the text alignment of the cue, interpreted as follows:

* **line-left:** if the text alignment is left, the cue is using a LTR language and the text alignment is start, or the cue is using a RTL language and the text alignment is end.
* **line-right:** if the text alignment is right, the cue is using a RTL language and the text alignment is start, or the cue is using a LTR language and the text-alignment is end.
* **center:** if there is no text alignment position set.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `positionAlign` is set to `"line-right"`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.positionAlign = "line-right";
console.log(cue1.positionAlign);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-positionalign |

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

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


VTTCue: text property - Web APIs

VTTCue: text property
=====================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`text`** property of the `VTTCue` interface represents the text contents of the cue.

Value
-----

A string containing the raw text of the cue.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `size` is set to the string `"new cue value"`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.text = "new cue value";
console.log(cue1.text); // 'new cue value';

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-text |

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

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


VTTCue: lineAlign property - Web APIs

VTTCue: lineAlign property
==========================

The **`lineAlign`** property of the `VTTCue` interface represents the alignment of this VTT cue.

Value
-----

A string containing one of the following values:

`"start"`

Start alignment.

`"center"`

Center alignment.

`"end"`

End alignment.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `lineAlign` is set to `"center"`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.lineAlign = "center";
console.log(cue1.lineAlign);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-linealign |

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

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


VTTCue: size property - Web APIs

VTTCue: size property
=====================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

* Learn more
* See full compatibility
* Report feedback
The **`size`** property of the `VTTCue` interface represents the size of the cue as a percentage of the video size.

Value
-----

A number representing the size of the cue as a percentage of the video size.

Examples
--------

In the following example a new `VTTCue` is created, then the value of `size` is set to `50`. The value is then printed to the console.

```js
let video = document.querySelector("video");
let track = video.addTextTrack("captions", "Captions", "en");
track.mode = "showing";

let cue1 = new VTTCue(0, 0.9, "Hildy!");
cue1.size = 50;
console.log(cue1.size);

track.addCue(cue1);
```

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

| Specification |
| --- |
| WebVTT: The Web Video Text Tracks Format # dom-vttcue-size |

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

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


SVGStyleElement: media property - Web APIs

SVGStyleElement: media property
===============================

The **`SVGStyleElement.media`** property is a media query string corresponding to the `media` attribute of the given SVG style element.

The query must be matched for the style to apply.

Value
-----

 A string defining a valid media query list with one or more comma separated values.
 For example `"screen, print"`, or `"all"` (the default).

The value is initialized with the string specified in the corresponding style's `media` attribute.

Examples
--------

This example demonstrates programmatically getting and setting the media property on a style that was defined in an SVG definition.

### HTML

 The HTML contains an SVG definition for a `<circle>` with a `<style>` element that is conditional on the media query `"all and (min-width: 600px)"`.
 We also define a `button` that will be used to display the current style and change the style.

```html
<button></button>
<svg
 xmlns="http://www.w3.org/2000/svg"
 xmlns:xlink="http://www.w3.org/1999/xlink">
  <circle cx="60" cy="60" r="50" />
</svg>
```

### JavaScript

The code below gets the `style` element (an `SVGStyleElement`) using its id.

```js
const svg = document.querySelector("svg");
// Create the `style` element in the SVG namespace
const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
const node = document.createTextNode("circle { fill: red; }");
svg.appendChild(style);
style.appendChild(node);
```

 We then add a function to set the button text to show the current value of the style's `media` property along with the current window width.
 This function is called to set the initial button text, and also when the window is resized or the button is pressed.
 The button event handler also sets the value of the style's `media` property.

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

function setButtonText() {
  button.textContent = `Media: ${style.media} (Width: ${window.innerWidth})`;
}
setButtonText();

addEventListener("resize", () => {
  setButtonText();
});

button.addEventListener("click", () => {
  style.media = "all and (min-width: 700px)";
  setButtonText();
});
```

### Result

 The result is shown below.
 The button text shows the value of the media attribute originally applied to the SVG style along with the width of the current frame (since the code is run in a frame).
 Shrink the width of the frame to the media query width shown in the button to watch the style being applied.
 Press the button to toggle the value of the `media` property on the style (which will be reflected on the button).

**Note:** The `media` property may be set to any string, but will be ignored if the string is not a valid media query.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGStyleElement\_\_media |

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

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

See also
--------

* `HTMLStyleElement.media`


SVGStyleElement: title property - Web APIs

SVGStyleElement: title property
===============================

 The **`SVGStyleElement.title`** property is a string corresponding to the `title` attribute of the given SVG style element.
 It may be used to select between alternate style sheets.

Value
-----

A string with any value.

The value is initialized with the string specified in the corresponding style's `title` attribute.

Examples
--------

This example demonstrates programmatically getting and setting the `title` property on a style that was defined in an SVG definition.

### HTML

 The HTML contains an SVG definition for a `<circle>` with a `<style>` element that has a `title`.
 We also define a text area for logging the current title.

```html
<textarea id="log" rows="3" cols="50"></textarea>
<svg
 xmlns="http://www.w3.org/2000/svg"
 xmlns:xlink="http://www.w3.org/1999/xlink">
  <style title="gold fill style">
 circle {
 fill: gold;
 }
 </style>
  <circle cx="50" cy="40" r="25" />
</svg>
```

### JavaScript

The code below gets the `style` element (an `SVGStyleElement`) using its tag name, logs the title, then changes and logs the title again.

```js
const log = document.getElementById("log");

const svg = document.querySelector("svg");
const style = svg.querySelector("style");
log.value = `Initial title: ${style.title}\n`;
style.title = "Altered Title";
log.value += `New title: ${style.title}`;
```

### Result

The text in the log below shows that the title initially reflects the matching attribute on the `<style>` element, but can then be changed to another value.

 Note that alternate styles are not applied by default; they must be selected as the preferred stylesheet by the user.
 To apply the alternate stylesheets on Firefox:

1. Open the Menu Bar (Press `F10` or tap the `Alt` key)
2. Open **View > Page Style** submenu
3. Select the stylesheets based on their names.
Specifications
--------------

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGStyleElement\_\_title |

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

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


SVGStyleElement: disabled property - Web APIs

SVGStyleElement: disabled property
==================================

The **`SVGStyleElement.disabled`** property can be used to get and set whether the stylesheet is disabled (`true`) or not (`false`).

Note that there is no corresponding `disabled` attribute on the SVG `<style>` element.

Value
-----

 Returns `true` if the stylesheet is disabled, or there is no associated stylesheet; otherwise `false`.
 The value is `false` by default (if there is an associated stylesheet).

 The property can be used to enable or disable an associated stylesheet.
 Setting the property to `true` when there is no associated stylesheet has no effect.

Examples
--------

### Disabling a style defined in the SVG

This example demonstrates programmatically setting the disabled property on a style that was defined in the HTML SVG definition.

#### HTML

The HTML contains an SVG definition for a `<circle>` with a `<style>` element, along with a button that will be used to disable the style.

```html
<button>Enable</button>
<svg
 xmlns="http://www.w3.org/2000/svg"
 xmlns:xlink="http://www.w3.org/1999/xlink">
  <style id="circle\_style\_id">
 circle {
 fill: gold;
 stroke: green;
 stroke-width: 3px;
 }
 </style>
  <circle cx="50" cy="50" r="25" />
</svg>
```

#### JavaScript

 The code below gets the `style` element (an `SVGStyleElement`) using its id, and then sets it as disabled.
 The style already exists because it is defined in the SVG, so this should succeed.

```js
const svg = document.querySelector("svg");
const style = svg.getElementById("circle\_style\_id");
style.disabled = true;
```

We then add an event handler for the button that toggles the disabled state and button text.

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

button.addEventListener("click", () => {
  style.disabled = !style.disabled;
  button.textContent = style.disabled ? "Enable" : "Disable";
});
```

#### Result

 The result is shown below.
 Press the button to toggle the `disabled` property on the style used for the circle.

### Disabling a programmatically defined style

This example is very similar to the one above, except that the style is defined programmatically.

 Note that you can have multiple styles applied both in SVG source and programmatically.
 This example is primarily provided to demonstrate how to create the style externally, and show at what point the style can be disabled.

#### HTML

The HTML is similar to the previous case, but the SVG definition does not include any default styling.

```html
<button>Enable</button>
<svg
 xmlns="http://www.w3.org/2000/svg"
 xmlns:xlink="http://www.w3.org/1999/xlink">
  <circle cx="50" cy="50" r="25" />
</svg>
```

#### JavaScript

 First we create the new SVG style node.
 This is done by first creating a style element in the SVG namespace using `Document.createElementNS()`, creating and appending a text node with the style definition, and then appending the node to the SVG defined above.

**Note:** You must use `Document.createElementNS()` and not `Document.createElement()` to create the style, or by default you'll create the equivalent HTML style element.

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

// Create the `style` element in the SVG namespace
const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
const node = document.createTextNode("circle { fill: red; }");
svg.appendChild(style);
style.appendChild(node);
```

 Then we disable the style.
 Note that this is the earliest point at which setting the property to `true` will succeed.
 Before this point the SVG did not have a style associated, and so the value defaults to `false`.

```js
//Disable the style
style.disabled = true;
```

Last of all we add an event handler for the button that toggles the disabled state and button text (this is the same as in the previous example).

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

button.addEventListener("click", () => {
  style.disabled = !style.disabled;
  button.textContent = style.disabled ? "Enable" : "Disable";
});
```

#### Result

 The result is shown below.
 Press the button to toggle the `disabled` state on the style used for the circle.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGStyleElement\_\_disabled |

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

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

See also
--------

* `HTMLStyleElement.disabled`


SVGStyleElement: sheet property - Web APIs

SVGStyleElement: sheet property
===============================

The **`SVGStyleElement.sheet`** read-only property returns the `CSSStyleSheet` corresponding to the given SVG style element, or `null` if there is none.

Value
-----

A `CSSStyleSheet`, or `null` if the element has no associated style sheet.

Examples
--------

This example demonstrates how to get the CSS sheet associated with an element.

### HTML

The HTML contains an SVG definition for a `<circle>`.

```html
<textarea id="log" rows="3" cols="50"></textarea>
<svg
 xmlns="http://www.w3.org/2000/svg"
 xmlns:xlink="http://www.w3.org/1999/xlink">
  <circle cx="50" cy="50" r="25" />
</svg>
```

### JavaScript

The code below creates a `style` element (an `SVGStyleElement`) and adds it to the SVG.

```js
const svg = document.querySelector("svg");
// Create the `style` element in the SVG namespace
const style = document.createElementNS("http://www.w3.org/2000/svg", "style");
const node = document.createTextNode("circle { fill: red; }");
svg.appendChild(style);
style.appendChild(node);
```

 The code below then logs the sheet and CSS rule associated with this new element, using `style.sheet`.
 To make

```js
// Log the sheet associated with this new element.
const log = document.getElementById("log");
log.value = `${style.sheet} with rules[0].cssText:\n ${style.sheet.rules[0].cssText}`;
```

### Result

 The result is shown below.
 On success, the log shows the `CSSStyleSheet` object applied to the SVG circle.

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

| Specification |
| --- |
| CSS Object Model (CSSOM) # dom-linkstyle-sheet |

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

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

See also
--------

* `HTMLStyleElement.sheet`


SVGStyleElement: type property - Web APIs

SVGStyleElement: type 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.

 The **`SVGStyleElement.type`** property returns the type of the current style.
 The value reflects the associated SVG `<style>` element's `type` attribute.

Authors should not use this property or rely on the value.

Value
-----

The permitted values are an empty string or a case-insensitive match for "text/css".

Exceptions
----------

 SVG 1.1 defined that a `DOMException` is raised with code `NO_MODIFICATION_ALLOWED_ERR` on an attempt to change the value of a read-only attribute.
 This restriction was removed in SVG 2.

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

| Specification |
| --- |
| Scalable Vector Graphics (SVG) 2 # \_\_svg\_\_SVGStyleElement\_\_type |

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

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

See also
--------

* `HTMLStyleElement.type`


ClipboardItem: types property - Web APIs

ClipboardItem: types property
=============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The read-only **`types`** property of the `ClipboardItem` interface returns an `Array` of MIME types available within the `ClipboardItem`

Value
-----

An `Array` of available MIME types.

Examples
--------

 In the below example, we're returning all items on the clipboard via the `Clipboard.read()` method.
 Then checking the `types` property for available types before utilizing the `ClipboardItem.getType()` method to return the `Blob` object. If no clipboards contents is found for the specified type, an error is returned.

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      for (const type of clipboardItem.types) {
        const blob = await clipboardItem.getType(type);
        // we can now use blob here
      }
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

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

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-types |

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

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

See also
--------

* Clipboard API
* Image support for Async Clipboard article


ClipboardItem: presentationStyle property - Web APIs

ClipboardItem: presentationStyle property
=========================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The read-only **`presentationStyle`** property of the `ClipboardItem` interface returns a string indicating how an item should be presented.

For example, in some contexts an image might be displayed inline, while in others it might be represented as an attachment.

Value
-----

One of either `"unspecified"`, `"inline"` or `"attachment"`.

Examples
--------

In the below example, we're returning all items on the clipboard via the `clipboard.read()` method, then logging the `presentationStyle` property.

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      console.log(clipboardItem.presentationStyle);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

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

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-presentationstyle |

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

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

See also
--------

* Clipboard API
* Image support for Async Clipboard article


ClipboardItem: ClipboardItem() constructor - Web APIs

ClipboardItem: ClipboardItem() constructor
==========================================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`ClipboardItem()`** constructor creates a new `ClipboardItem` object, which represents data to be stored or retrieved via the Clipboard API `clipboard.write()` and `clipboard.read()` methods, respectively.

**Note:** Image format support varies by browser. See the browser compatibility table for the `Clipboard` interface.

Syntax
------

```js
new ClipboardItem(data)
new ClipboardItem(data, options)
```

### Parameters

`data`

 An `Object` with the MIME type as the key and data as the value.
 The data can be represented as a `Blob`, a `String` or a `Promise` which resolves to either a blob or string.

`options` Optional

An object with the following properties:

`presentationStyle` Optional

 One of the three strings: `unspecified`, `inline` or `attachment`.
 The default is `unspecified`.

**Note:** You can also work with text via the `Clipboard.readText()` and `Clipboard.writeText()` methods of the `Clipboard` interface.

Examples
--------

 The below example requests a PNG image using the `Fetch API`, and in turn, the `responses' blob()` method, to create a new `ClipboardItem`.
 This item is then written to the clipboard, using the `Clipboard.write()` method.

**Note:** You can only pass in one clipboard item at a time.

```js
async function writeClipImg() {
  try {
    const imgURL = "/myimage.png";
    const data = await fetch(imgURL);
    const blob = await data.blob();

    await navigator.clipboard.write([
      new ClipboardItem({
        [blob.type]: blob,
      }),
    ]);
    console.log("Fetched image copied.");
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

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

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-clipboarditem |

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

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

See also
--------

* Clipboard API
* Image support for Async Clipboard article


ClipboardItem: getType() method - Web APIs

ClipboardItem: getType() method
===============================

**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`getType()`** method of the `ClipboardItem` interface returns a `Promise` that resolves with a `Blob` of the requested MIME type or an error if the MIME type is not found.

Syntax
------

```js
getType(type)
```

### Parameters

`type`

A valid MIME type.

### Return value

A `Promise` that resolves with a `Blob` object.

### Exceptions

`NotFoundError` `DOMException`

The `type` does not match a known MIME type.

`TypeError`

No parameter is specified or the `type` is not that of the `ClipboardItem`.

Examples
--------

 In the following example, we're returning all items on the clipboard via the `clipboard.read()` method.
 Then utilizing the `ClipboardItem.types` property to set the `getType()` argument and return the corresponding blob object.

```js
async function getClipboardContents() {
  try {
    const clipboardItems = await navigator.clipboard.read();

    for (const clipboardItem of clipboardItems) {
      for (const type of clipboardItem.types) {
        const blob = await clipboardItem.getType(type);
        // we can now use blob here
      }
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

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

| Specification |
| --- |
| Clipboard API and events # dom-clipboarditem-gettype |

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

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

See also
--------

* Clipboard API
* Image support for Async Clipboard article


Ink: requestPresenter() method - Web APIs

Ink: requestPresenter() method
==============================

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

The **`requestPresenter()`** method of the `Ink` interface returns a `Promise` that fulfills with an `InkPresenter` object to handle rendering strokes.

Syntax
------

```js
requestPresenter(param)
```

### Parameters

`param` Optional

An `InkPresenterParam` object that contains the following property:

`presentationArea` Optional

An `Element` inside which rendering of ink strokes is confined (the element's border box, to be precise). If `param` is not included, or `presentationArea` is set to `null`, ink rendering is confined to the containing viewport by default.

### Return value

A `Promise` that resolves to an `InkPresenter` object instance.

### Exceptions

`Error` `DOMException`

An error is thrown and the operation is aborted if `presentationArea` is not a valid `Element`, or is not in the same document as the associated `Ink` object.

Example
-------

```js
async function inkInit() {
  const ink = navigator.ink;
  let presenter = await ink.requestPresenter({ presentationArea: canvas });

  //...
}
```

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

| Specification |
| --- |
| Ink API # dom-ink-requestpresenter |

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

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

See also
--------

* Enhancing Inking on the Web


OfflineAudioCompletionEvent: OfflineAudioCompletionEvent() constructor - Web APIs

OfflineAudioCompletionEvent: OfflineAudioCompletionEvent() constructor
======================================================================

 The **`OfflineAudioCompletionEvent()`** constructor of the Web Audio API creates a new
 `OfflineAudioCompletionEvent` object.

**Note:** You wouldn't generally use the constructor manually.
 `OfflineAudioCompletionEvent` events are dispatched to
 `OfflineAudioContext` instances for legacy reasons.

Syntax
------

```js
new OfflineAudioCompletionEvent(type, options)
```

### Parameters

`type`

 A string with the name of the event.
 It is case-sensitive and browsers set it to `complete`.

`options`

An object that, *in addition of the properties defined in `Event()`*, can have the following properties:

`renderedBuffer`

The rendered `AudioBuffer` containing the audio data.

### Return value

A new `OfflineAudioCompletionEvent` object.

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocompletionevent-offlineaudiocompletionevent |

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

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


OfflineAudioCompletionEvent: renderedBuffer property - Web APIs

OfflineAudioCompletionEvent: renderedBuffer property
====================================================

 The **`renderedBuffer`** read-only property of the
 `OfflineAudioCompletionEvent` interface is an `AudioBuffer`
 containing the result of processing an `OfflineAudioContext`.

Value
-----

An `AudioBuffer`.

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

| Specification |
| --- |
| Web Audio API # dom-offlineaudiocompletionevent-renderedbuffer |

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

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


TouchList: length property - Web APIs

TouchList: length property
==========================

 The **`length`** read-only property indicates the number of
 items (touch points) in a given `TouchList`.

Value
-----

The number of touch points in `touchList`.

Examples
--------

 This code example illustrates the use of the `TouchList` interface's
 `item` method and the
 `length` property.

```js
const target = document.getElementById("target");

target.addEventListener(
  "touchstart",
  (ev) => {
    // If this touchstart event started on element target,
    // set touch to the first item in the targetTouches list;
    // otherwise set touch to the first item in the touches list
    const touch =
      ev.targetTouches.length >= 1
        ? ev.targetTouches.item(0)
        : ev.touches.item(0);
  },
  false,
);
```

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

| Specification |
| --- |
| Touch Events # dom-touchlist-length |

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

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


TouchList: item() method - Web APIs

TouchList: item() method
========================

 The **`item()`** method returns the `Touch`
 object at the specified index in the `TouchList`.

Syntax
------

```js
item(index)
```

### Parameters

`index`

 The index of the `Touch` object to retrieve. The index is a number in
 the range of 0 to one less than the length of the `TouchList`.

### Return value

`touchPoint`

 The requested `Touch` object from the `TouchList`.
 Returns `null` if the index is not less than the length of the list.

Examples
--------

 This code example illustrates the use of the `TouchList` interface's
 `item` method and the
 `length` property.

```js
const target = document.getElementById("target");

target.addEventListener(
  "touchstart",
  (ev) => {
    // If this touchstart event started on element target,
    // set touch to the first item in the targetTouches list;
    // otherwise set touch to the first item in the touches list
    const touch =
      ev.targetTouches.length >= 1
        ? ev.targetTouches.item(0)
        : ev.touches.item(0);
  },
  false,
);
```

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

| Specification |
| --- |
| Touch Events # dom-touchlist-item |

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

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


CSSAnimation: animationName property - Web APIs

CSSAnimation: animationName property
====================================

 The **`animationName`** property of the
 `CSSAnimation` interface returns the `animation-name`. This
 specifies one or more keyframe at-rules which describe the animation applied to the
 element.

Value
-----

A string.

Examples
--------

### Returning the animationName

 The animation in the following example is defined in CSS with the name
 `slide-in`. Calling `Element.getAnimations()` returns an array
 of all `Animation` objects. The `animationName` property returns
 the name given to the animation, in our case `slide-in`.

```css
.animate {
  animation: slide-in 0.7s both;
}

@keyframes slide-in {
  0% {
    transform: translateY(-1000px);
  }
  100% {
    transform: translateY(0);
  }
}
```

```js
let animations = document.querySelector(".animate").getAnimations();
console.log(animations[0].animationName);
```

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

| Specification |
| --- |
| CSS Animations Level 2 # dom-cssanimation-animationname |

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

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


XMLSerializer: serializeToString() method - Web APIs

XMLSerializer: serializeToString() method
=========================================

 The `XMLSerializer` method
 **`serializeToString()`** constructs a string representing the
 specified DOM tree in XML form.

Syntax
------

```js
serializeToString(rootNode)
```

### Parameters

`rootNode`

 The `Node` to use as the root of the DOM tree or subtree for which to
 construct an XML representation.

### Return value

A string containing the XML representation of the specified DOM tree.

### Exceptions

`TypeError`

 Thrown if the specified `rootNode` is not a compatible node type. The root node
 must be either `Node` or `Attr`.

`InvalidStateError` `DOMException`

 Thrown if the tree could not be successfully serialized, probably due to issues with the
 content's compatibility with XML serialization.

`SyntaxError` `DOMException`

 Thrown if a serialization of HTML was requested but could not succeed due to the content not
 being well-formed.

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

### Compatible node types

 The specified root node—and all of its descendants—must be compatible with the XML
 serialization algorithm. The root node itself must be either a `Node` or
 `Attr` object.

 The following types are also permitted as descendants of the root node, in addition to
 `Node` and `Attr`:

* `DocumentType`
* `Document`
* `DocumentFragment`
* `Element`
* `Comment`
* `Text`
* `ProcessingInstruction`
* `Attr`

If any other type is encountered, a `TypeError` exception is thrown.

### Notes on the resulting XML

 There are some things worth noting about the XML output by
 `serializeToString()`:

* For XML serializations, `Element` and `Attr` nodes are always
 serialized with their `namespaceURI` intact. This
 may mean that a previously-specified `prefix` or default
 namespace may be dropped or altered.
* The resulting XML is compatible with the HTML parser.
* Elements in the HTML namespace that have no child nodes (thereby representing empty
 tags) are serialized with both begin and end tags
 (`"<someelement></someelement>"`) instead of using the
 empty-element tag (`"<someelement/>"`).
Specifications
--------------

| Specification |
| --- |
| DOM Parsing and Serialization # dom-xmlserializer-serializetostring |

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

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

See also
--------

* Parsing and serializing XML
* Serializing to HTML: `Element.innerHTML` and
 `Element.outerHTML`
* Parsing HTML or XML to create a DOM tree: `DOMParser`


XMLSerializer: XMLSerializer() constructor - Web APIs

XMLSerializer: XMLSerializer() constructor
==========================================

The **`XMLSerializer()`** constructor creates a new `XMLSerializer`.

Syntax
------

```js
new XMLSerializer()
```

### Parameters

None.

### Return value

A new `XMLSerializer` object.

Examples
--------

### Serializing XML into a string

This example serializes an entire document into a string containing XML.

```js
const s = new XMLSerializer();
const d = document;
const str = s.serializeToString(d);
saveXML(str);
```

This involves creating a new `XMLSerializer` object, then passing the `Document` to be serialized into `serializeToString()`, which returns the XML equivalent of the document. `saveXML()` represents a function that would then save the serialized string.

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

| Specification |
| --- |
| DOM Parsing and Serialization # dom-xmlserializer-constructor |

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

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


MediaTrackConstraints: frameRate property - Web APIs

MediaTrackConstraints: frameRate property
=========================================

 The `MediaTrackConstraints` dictionary's
 **`frameRate`** property is a `ConstrainDouble`
 describing the requested or mandatory constraints placed upon the value of the
 `frameRate` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.frameRate` as returned by a
 call to `MediaDevices.getSupportedConstraints()`. However, typically this
 is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 A `ConstrainDouble` describing the acceptable or required value(s) for a
 video track's frame rate, in frames per second.

 If this value is a number, the user agent will attempt to obtain media whose frame rate
 is as close as possible to this number given the capabilities of the hardware and the
 other constraints specified. Otherwise, the value of this `ConstrainDouble`
 will guide the user agent in its efforts to provide an exact match to the required frame
 rate (if `exact` is specified or both `min` and `max`
 are provided and have the same value) or to a best-possible value.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: displaySurface property - Web APIs

MediaTrackConstraints: displaySurface property
==============================================

The `MediaTrackConstraints` dictionary's **`displaySurface`** property is a `ConstrainDOMString` describing the preferred value for the `displaySurface` constrainable property.

This is set by the application to identify to the user agent the type of display surface (`window`, `browser`, or `monitor`) preferred by the application. It has no effect on what the user can choose to share, but may be used to present the options in a different order.

If needed, you can determine whether or not this constraint is supported by checking the value of `MediaTrackSupportedConstraints.displaySurface` as returned by a call to `MediaDevices.getSupportedConstraints()`. However, typically this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 A `ConstrainDOMString` which specifies the type of display surface preferred by the application.
 This value *does not* add or remove display sources in the browser's user interface, but may reorder them. You can't use this property to limit the user to a subset of the three display-surface values `window`, `browser`, and `monitor` — but, as you will see below, you can see what was chosen, and reject it.

See how constraints are defined.

**Note:** You cannot set `monitorTypeSurfaces: "exclude"` at the same time as `displaySurface: "monitor"` as the two settings are contradictory. Trying to do so will result in the associated `getDisplayMedia()` call failing with a `TypeError`.

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

 You can check the setting selected by the user agent after the display media has been
 created by `getDisplayMedia()` by calling
 `getSettings()` on the display media's
 video `MediaStreamTrack`, then checking the value of the returned
 `MediaTrackSettings` object's
 `displaySurface` object.

 For example, if your app prefers not to share a monitor — meaning that there's possibly a non-content backdrop being captured — it can use code similar
 to this:

```js
let mayHaveBackdropFlag = false;
let displaySurface = displayStream
  .getVideoTracks()[0]
  .getSettings().displaySurface;

if (displaySurface === "monitor") {
  mayHaveBackdropFlag = true;
}
```

 Following this code, `mayHaveBackdrop` is `true` if the display
 surface contained in the stream is of type `monitor`.
 Later code can use this flag to determine whether or not to perform special processing,
 such as to remove or replace the backdrop, or to "cut" the individual display areas out
 of the received frames of video.

Examples
--------

 Here are some example constraints objects for `getDisplayMedia()` that make
 use of the `displaySurface` property.

```js
dsConstraints = { displaySurface: "window" }; // 'browser' and 'monitor' are also possible
applyConstraints(dsConstraints);
// The user still may choose to share the monitor or the browser,
// but we indicated that a window is preferred.
```

 In addition, see the
 Constraint exerciser example
 that demonstrates how constraints are used.

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

| Specification |
| --- |
| Screen Capture # dom-mediatrackconstraintset-displaysurface |

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
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`


MediaTrackConstraints: logicalSurface property - Web APIs

MediaTrackConstraints: logicalSurface property
==============================================

The `MediaTrackConstraints` dictionary's **`logicalSurface`** property is a `ConstrainDOMString` describing the requested or mandatory constraints placed upon the value of the `logicalSurface` constrainable property.

 This is used to specify whether or
 not `getDisplayMedia()` should allow the
 user to choose display surfaces which are not necessarily fully visible on the screen,
 such as occluded windows or the complete content of windows which are large enough to
 require scrolling to see their entire contents.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.logicalSurface` as returned by
 a call to `MediaDevices.getSupportedConstraints()`. However, typically this
 is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

A `ConstrainBoolean` which is `true` if logical surfaces should be permitted among the selections available to the user.

See how constraints are defined.

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

 You can check the setting selected by the user agent after the display media has been
 created by `getDisplayMedia()` by calling
 `getSettings()` on the display media's
 video `MediaStreamTrack`, then checking the value of the returned
 `MediaTrackSettings` object's
 `logicalSurface` object.

 For example, if your app needs to know if the selected display surface is a logical
 one:

```js
let isLogicalSurface = displayStream
  .getVideoTracks()[0]
  .getSettings().logicalSurface;
```

 Following this code, `isLogicalSurface` is `true` if the display
 surface contained in the stream is a logical surface; that is, one which may not be
 entirely onscreen, or may even be entirely offscreen.

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

| Specification |
| --- |
| Screen Capture # dom-mediatrackconstraintset-logicalsurface |

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
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`


MediaTrackConstraints: suppressLocalAudioPlayback property - Web APIs

MediaTrackConstraints: suppressLocalAudioPlayback property
==========================================================

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

The `MediaTrackConstraints` dictionary's **`suppressLocalAudioPlayback`** property is a `ConstrainBoolean` describing the requested or mandatory constraints placed upon the value of the `suppressLocalAudioPlayback` constrainable property. This property controls whether the audio playing in a tab will continue to be played out of a user's local speakers when the tab is captured.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.suppressLocalAudioPlayback` as returned
 by a call to `MediaDevices.getSupportedConstraints()`. However, typically
 this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

A `ConstrainBoolean` value.

 If this value is a simple `true` or `false`, the user agent will
 attempt to obtain media with local audio playback enabled or disabled as specified, if
 possible, but will not fail if this can't be done.

 If the value is given as `ideal`, that field's boolean value indicates an ideal
 setting for the local audio playback suppression feature; if it can't be met, then the request will
 result in an error.

Examples
--------

```js
let isLocalAudioSuppressed = displayStream
  .getVideoTracks()[0]
  .getSettings().suppressLocalAudioPlayback;
```

The Constraint exerciser example shows how to use media track constraints.

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

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

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

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

See also
--------

* Media Capture and Streams API
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: latency property - Web APIs

MediaTrackConstraints: latency property
=======================================

 The `MediaTrackConstraints` dictionary's
 **`latency`** property is a `ConstrainDouble`
 describing the requested or mandatory constraints placed upon the value of the
 `latency` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.latency` as returned by a call
 to `MediaDevices.getSupportedConstraints()`. However, typically this is
 unnecessary since browsers will ignore any constraints they're unfamiliar with.

 Because RTP doesn't include this information, tracks associated with a
 WebRTC `RTCPeerConnection`
 will never include this property.

Value
-----

 A `ConstrainDouble` describing the acceptable or required value(s) for an
 audio track's latency, with values specified in seconds. In audio processing, latency is
 the time between the start of processing (when sound occurs in the real world, or is
 generated by a hardware device) and the data being made available to the next step in
 the audio input or output process. In most cases, low latency is desirable for
 performance and user experience purposes, but when power consumption is a concern, or
 delays are otherwise acceptable, higher latency might be acceptable.

 If this property's value is a number, the user agent will attempt to obtain media whose
 latency tends to be as close as possible to this number given the capabilities of the
 hardware and the other constraints specified. Otherwise, the value of this
 `ConstrainDouble` will guide the user agent in its efforts to provide an
 exact match to the required latency (if `exact` is specified or both
 `min` and `max` are provided and have the same value) or to a
 best-possible value.

**Note:** Latency is always prone to some variation due to hardware usage demands, network
 constraints, and so forth, so even in an "exact" match, some variation should be
 expected.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: height property - Web APIs

MediaTrackConstraints: height property
======================================

 The `MediaTrackConstraints` dictionary's
 **`height`** property is a `ConstrainULong`
 describing the requested or mandatory constraints placed upon the value of the
 `height` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.height` as returned by a call
 to `MediaDevices.getSupportedConstraints()`. However, typically this is
 unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 If this value is a number, the user agent will attempt to obtain media whose height is
 as close as possible to this number given the capabilities of the hardware and the other
 constraints specified. Otherwise, the value of this `ConstrainULong` will
 guide the user agent in its efforts to provide an exact match to the required height (if
 `exact` is specified or both `min` and `max` are
 provided and have the same value) or to a best-possible value.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: sampleRate property - Web APIs

MediaTrackConstraints: sampleRate property
==========================================

 The `MediaTrackConstraints` dictionary's
 **`sampleRate`** property is a `ConstrainULong`
 describing the requested or mandatory constraints placed upon the value of the
 `sampleRate` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.sampleRate` as returned by a
 call to `MediaDevices.getSupportedConstraints()`. However, typically this
 is unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 If this value is a number, the user agent will attempt to obtain media whose sample
 rate is as close as possible to this number given the capabilities of the hardware and
 the other constraints specified. Otherwise, the value of this
 `ConstrainULong` will guide the user agent in its efforts to provide an
 exact match to the required sample rate (if `exact` is specified or both
 `min` and `max` are provided and have the same value) or to a
 best-possible value.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: autoGainControl property - Web APIs

MediaTrackConstraints: autoGainControl property
===============================================

 The `MediaTrackConstraints` dictionary's **`autoGainControl`** property is a `ConstrainBoolean` describing the requested or mandatory constraints placed
 upon the value of the `autoGainControl` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.autoGainControl` as returned
 by a call to `MediaDevices.getSupportedConstraints()`. However, typically
 this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

 Automatic gain control is typically a feature provided by microphones, although it can
 be provided by other input sources as well.

Value
-----

 If this value is a simple `true` or `false`, the user agent will
 attempt to obtain media with automatic gain control enabled or disabled as specified, if
 possible, but will not fail if this can't be done. If, instead, the value is given as an
 object with an `exact` field, that field's Boolean value indicates a required
 setting for the automatic gain control feature; if it can't be met, then the request
 will result in an error.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: volume property - Web APIs

MediaTrackConstraints: 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 `MediaTrackConstraints` dictionary's
 **`volume`** property is a `ConstrainDouble`
 describing the requested or mandatory constraints placed upon the value of the
 `volume` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.volume` as returned by a call
 to `MediaDevices.getSupportedConstraints()`. However, typically this is
 unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 A `ConstrainDouble` describing the acceptable or required value(s) for an
 audio track's volume, on a linear scale where 0.0 means silence and 1.0 is the highest
 supported volume.

 If this value is a number, the user agent will attempt to obtain media whose volume is
 as close as possible to this number given the capabilities of the hardware and the other
 constraints specified. Otherwise, the value of this `ConstrainDouble` will
 guide the user agent in its efforts to provide an exact match to the required volume (if
 `exact` is specified or both `min` and `max` are
 provided and have the same value) or to a best-possible value.

 Any constraint set which only permits values outside the range 0.0 to 1.0 cannot be
 satisfied and will result in failure.

Examples
--------

See the Constraint exerciser example.

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

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

See also
--------

* Media Capture and Streams API
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: noiseSuppression property - Web APIs

MediaTrackConstraints: noiseSuppression property
================================================

The `MediaTrackConstraints` dictionary's **`noiseSuppression`** property is a `ConstrainBoolean` describing the requested or mandatory constraints placed upon the value of the `noiseSuppression` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.noiseSuppression` as returned
 by a call to `MediaDevices.getSupportedConstraints()`. However, typically
 this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

 Noise suppression is typically provided by microphones, although it can be provided by
 other input sources as well.

Value
-----

 If this value is a simple `true` or `false`, the user agent will
 attempt to obtain media with noise suppression enabled or disabled as specified, if
 possible, but will not fail if this can't be done. If, instead, the value is given as an
 object with an `exact` field, that field's Boolean value indicates a required
 setting for the noise suppression feature; if it can't be met, then the request will
 result in an error.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: groupId property - Web APIs

MediaTrackConstraints: groupId property
=======================================

 The `MediaTrackConstraints` dictionary's
 **`groupId`** property is a `ConstrainDOMString`
 describing the requested or mandatory constraints placed upon the value of the
 `groupId` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.groupId` as returned by a call
 to `MediaDevices.getSupportedConstraints()`. However, typically this is
 unnecessary since browsers will ignore any constraints they're unfamiliar with.

Value
-----

 An object based on `ConstrainDOMString` specifying one or more acceptable,
 ideal, and/or exact (mandatory) group IDs which are acceptable as the source of media
 content.

 Group IDs are unique for a given origin for the duration of a single browsing session,
 and are shared by all media sources that come from the same physical device. For
 example, the microphone and speaker on the same headset would share a group ID. This
 makes it possible to use the group ID to ensure that the audio and input devices are on
 the same headset by retrieving the group ID of the input device and specifying it when
 asking for an output device, perhaps.

 However, the value of the `groupId` is determined by the source of the
 track's content, and there's no particular format mandated by the specification
 (although some kind of GUID is recommended). That means that a given track will only
 return one value for the `groupId` when you call
 `getCapabilities()`, and keep in mind
 that this value will change for each browsing session.

 Because of this, there's no use for the group ID when calling
 `MediaStreamTrack.applyConstraints()`, since there is only one possible
 value, and you can't use it to ensure the same group is used across multiple browsing
 sessions when calling `getUserMedia()`.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: deviceId property - Web APIs

MediaTrackConstraints: deviceId property
========================================

 The `MediaTrackConstraints` dictionary's
 **`deviceId`** property is a `ConstrainDOMString`
 describing the requested or mandatory constraints placed upon the value of the
 `deviceId` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.deviceId` as returned by a
 call to `MediaDevices.getSupportedConstraints()`. However, typically this
 is unnecessary since browsers will ignore any constraints they're unfamiliar with.

 Because RTP doesn't include this information, tracks associated with a
 WebRTC `RTCPeerConnection`
 will never include this property.

Value
-----

 An object based on `ConstrainDOMString` specifying one or more acceptable,
 ideal, and/or exact (mandatory) device IDs which are acceptable as the source of media
 content.

 Device IDs are unique for a given origin, and are guaranteed to be the same across
 browsing sessions on the same origin. However, the value of the `deviceId` is
 determined by the source of the track's content, and there's no particular format
 mandated by the specification (although some kind of GUID is recommended). That means
 that a given track will only return one value for the `deviceId` when you
 call `getCapabilities()`.

 Because of this, there's no use for the device ID when calling
 `MediaStreamTrack.applyConstraints()`, since there is only one possible
 value; however, you can record a `deviceId` and use it to ensure that you get
 the same source for multiple calls to `getUserMedia()`.

**Note:** An exception to the rule that device IDs are the same across browsing sessions:
 private browsing mode will use a different ID, and will change it each browsing
 session.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`


MediaTrackConstraints: echoCancellation property - Web APIs

MediaTrackConstraints: echoCancellation property
================================================

 The `MediaTrackConstraints` dictionary's
 **`echoCancellation`** property is a
 `ConstrainBoolean` describing the requested or mandatory constraints placed
 upon the value of the `echoCancellation` constrainable property.

 If needed, you can determine whether or not this constraint is supported by checking
 the value of `MediaTrackSupportedConstraints.echoCancellation` as returned
 by a call to `MediaDevices.getSupportedConstraints()`. However, typically
 this is unnecessary since browsers will ignore any constraints they're unfamiliar with.

 Because RTP doesn't include this information, tracks associated with a
 WebRTC `RTCPeerConnection`
 will never include this property.

Value
-----

 If this value is a simple `true` or `false`, the user agent will
 attempt to obtain media with echo cancellation enabled or disabled as specified, if
 possible, but will not fail if this can't be done. If, instead, the value is given as an
 object with an `exact` field, that field's Boolean value indicates a required
 setting for the echo cancellation feature; if it can't be met, then the request will
 result in an error.

Examples
--------

See the Constraint exerciser example.

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

| Specification |
| --- |
| Media Capture and Streams # dom-mediatrackconstraintset-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
* Capabilities, constraints, and settings
* `MediaTrackConstraints`
* `MediaDevices.getSupportedConstraints()`
* `MediaTrackSupportedConstraints`
* `MediaStreamTrack`