Node: insertBefore() method - Web APIs

Node: insertBefore() method
===========================

 The **`insertBefore()`** method of the `Node` interface
 inserts a node before a *reference node* as a child of a specified *parent node*.

 If the given node already exists in the document,
 `insertBefore()` moves it from its current position to the new position.
 (That is, it will automatically be removed from its existing parent
 before appending it to the specified new parent.)

This means that a node cannot be in two locations of the document simultaneously.

**Note:** The `Node.cloneNode()` can be used to make a copy
 of the node before appending it under the new parent. Note that the copies made with
 `cloneNode()` will not be automatically kept in sync.

 If the given child is a `DocumentFragment`, the entire contents of the
 `DocumentFragment` are moved into the child list of the specified parent
 node.

Syntax
------

```js
insertBefore(newNode, referenceNode)
```

### Parameters

`newNode`

The node to be inserted.

`referenceNode`

 The node before which `newNode` is inserted. If this is
 `null`, then `newNode` is inserted at the end of
 node's child nodes.

**Note:** `referenceNode` is **not** an optional parameter.
 You must explicitly pass a `Node` or `null`.
 Failing to provide it or passing invalid values may behave differently in different browser versions.

### Return value

 Returns the added child (unless `newNode` is a `DocumentFragment`,
 in which case the empty `DocumentFragment` is returned).

### Exceptions

Pre-insert validity

Example
-------

### Example 1

```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // Create the new node to insert
 const newNode = document.createElement("span");

 // Get a reference to the parent node
 const parentDiv = document.getElementById("childElement").parentNode;

 // Begin test case [ 1 ] : Existing childElement (all works correctly)
 let sp2 = document.getElementById("childElement");
 parentDiv.insertBefore(newNode, sp2);
 // End test case [ 1 ]

 // Begin test case [ 2 ] : childElement is of Type undefined
 sp2 = undefined; // Non-existent node of id "childElement"
 parentDiv.insertBefore(newNode, sp2); // Implicit dynamic cast to type Node
 // End test case [ 2 ]

 // Begin test case [ 3 ] : childElement is of Type "undefined" (string)
 sp2 = "undefined"; // Non-existent node of id "childElement"
 parentDiv.insertBefore(newNode, sp2); // Generates "Type Error: Invalid Argument"
 // End test case [ 3 ]
</script>
```

### Example 2

```html
<div id="parentElement">
  <span id="childElement">foo bar</span>
</div>

<script>
 // Create a new, plain <span> element
 let sp1 = document.createElement("span");

 // Get the reference element
 let sp2 = document.getElementById("childElement");
 // Get the parent element
 let parentDiv = sp2.parentNode;

 // Insert the new element into before sp2
 parentDiv.insertBefore(sp1, sp2);
</script>
```

**Note:** There is no `insertAfter()` method.
 It can be emulated by combining the `insertBefore` method
 with `Node.nextSibling`.

In the previous example, `sp1` could be inserted after `sp2` using:

```js
parentDiv.insertBefore(sp1, sp2.nextSibling);
```

 If `sp2` does not have a next sibling, then it must be the last child —
 `sp2.nextSibling` returns `null`, and `sp1` is inserted
 at the end of the child node list (immediately after `sp2`).

### Example 3

 Insert an element before the first child element, using the
 `firstChild` property.

```js
// Get the parent element
let parentElement = document.getElementById("parentElement");
// Get the parent's first child
let theFirstChild = parentElement.firstChild;

// Create a new element
let newElement = document.createElement("div");

// Insert the new element before the first child
parentElement.insertBefore(newElement, theFirstChild);
```

 When the element does not have a first child, then `firstChild` is
 `null`. The element is still appended to the parent, after the last child.

 Since the parent element did not have a first child, it did not have a last child,
 either. Consequently, the newly inserted element is the *only* element.

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

| Specification |
| --- |
| DOM Standard # dom-node-insertbefore |

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

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

See also
--------

* `Node.removeChild()`
* `Node.replaceChild()`
* `Node.appendChild()`
* `Node.hasChildNodes()`
* `Element.insertAdjacentElement()`
* `Element.prepend()`
* `Element.before()`
* `Element.after()`


Node: isSameNode() method - Web APIs

Node: isSameNode() method
=========================

 The **`isSameNode()`** method of the `Node` interface
 is a legacy alias the for the `===` strict equality operator.
 That is, it tests whether two nodes are the same
 (in other words, whether they reference the same object).

**Note:** There is no need to use `isSameNode()`; instead use the `===` strict equality operator.

Syntax
------

```js
isSameNode(otherNode)
```

### Parameters

`otherNode`

The `Node` to test against.

**Note:** This parameter is not optional, but can be set to `null`.

### Return value

A boolean value that is `true` if both nodes are strictly equal, `false` if not.

Example
-------

 In this example, we create three `<div>` blocks. The first and third
 have the same contents and attributes, while the second is different. Then we run some
 JavaScript to compare the nodes using `isSameNode()` and output the results.

### HTML

```html
<div>This is the first element.</div>
<div>This is the second element.</div>
<div>This is the first element.</div>

<p id="output"></p>
```

```
#output {
  width: 440px;
  border: 2px solid black;
  border-radius: 5px;
  padding: 10px;
  margin-top: 20px;
  display: block;
}
```

### JavaScript

```js
let output = document.getElementById("output");
let divList = document.getElementsByTagName("div");

output.innerHTML += `div 0 same as div 0: ${divList[0].isSameNode(
 divList[0],
)}<br/>`;
output.innerHTML += `div 0 same as div 1: ${divList[0].isSameNode(
 divList[1],
)}<br/>`;
output.innerHTML += `div 0 same as div 2: ${divList[0].isSameNode(
 divList[2],
)}<br/>`;
```

### Results

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

| Specification |
| --- |
| DOM Standard # dom-node-issamenode |

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

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

See also
--------

* `Node.isEqualNode()`


Node: nodeValue property - Web APIs

Node: nodeValue property
========================

The **`nodeValue`** property of the `Node` interface returns or sets the value of the current node.

Value
-----

 A string containing the value of the current node, if any.
 For the document itself, `nodeValue` returns `null`.
 For text, comment, and CDATA nodes, `nodeValue` returns the content of the node.
 For attribute nodes, the value of the attribute is returned.

The following table shows the return values for different types of nodes.

| Node | Value of nodeValue |
| --- | --- |
| `CDATASection` | Content of the CDATA section |
| `Comment` | Content of the comment |
| `Document` | `null` |
| `DocumentFragment` | `null` |
| `DocumentType` | `null` |
| `Element` | `null` |
| `NamedNodeMap` | `null` |
| `ProcessingInstruction` | Entire content excluding the target |
| `Text` | Content of the text node |

**Note:** When `nodeValue` is defined to be `null`, setting it has no effect.

Example
-------

```html
<div id="d1">Hello world</div>
<!-- Example of comment -->
<output id="result">Not calculated yet.</output>
```

and the following script:

```js
let node = document.querySelector("body").firstChild;
let result = "<br/>Node names are:<br/>";
while (node) {
  result += `Value of ${node.nodeName}: ${node.nodeValue}<br/>`;
  node = node.nextSibling;
}

const output = document.getElementById("result");
output.innerHTML = result;
```

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

| Specification |
| --- |
| DOM Standard # dom-node-nodevalue |

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

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


Node: parentElement property - Web APIs

Node: parentElement property
============================

 The read-only **`parentElement`** property of `Node` interface
 returns the DOM node's parent `Element`, or `null` if the node either has no
 parent, or its parent isn't a DOM `Element`.

Value
-----

 An `Element` that is the parent element of the current node,
 or `null` if there isn't one.

Example
-------

```js
if (node.parentElement) {
  node.parentElement.style.color = "red";
}
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-node-parentelement① |

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

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

See also
--------

* `Node.parentNode`


PictureInPictureEvent: PictureInPictureEvent() constructor - Web APIs

PictureInPictureEvent: PictureInPictureEvent() constructor
==========================================================

The **`PictureInPictureEvent()`** constructor returns a new `PictureInPictureEvent` object.

Syntax
------

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

### Parameters

`type`

A string representing the name of the event. It is case-sensitive and browsers set it to `enterpictureinpicture`, `leavepictureinpicture`, or `resize`.

`options`

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

`pictureInPictureWindow`

A `PictureInPictureWindow`.

### Return value

A new `PictureInPictureEvent` object.

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

| Specification |
| --- |
| Picture-in-Picture # dom-pictureinpictureevent-pictureinpictureevent |

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

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

See also
--------

* The `PictureInPictureEvent` interface it belongs to.


PictureInPictureEvent: pictureInPictureWindow property - Web APIs

PictureInPictureEvent: pictureInPictureWindow property
======================================================

The read-only **`pictureInPictureWindow`** property of the `PictureInPictureEvent` interface returns the `PictureInPictureWindow` the event relates to.

Value
-----

A `PictureInPictureWindow`.

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

| Specification |
| --- |
| Picture-in-Picture # dom-pictureinpictureevent-pictureinpicturewindow |

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

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

See also
--------

* Picture-in-Picture API


VideoFrame: clone() method - Web APIs

VideoFrame: clone() method
==========================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`clone()`** method of the `VideoFrame` interface creates a new `VideoFrame` object referencing the same media resource as the original.

Syntax
------

```js
clone()
```

### Parameters

None.

### Return value

A new cloned `VideoFrame` object.

### Exceptions

`InvalidStateError` `DOMException`

Thrown if the `VideoFrame` object has been transferred.

Examples
--------

The following example clones a copy of `VideoFrame` as `videoFrame2`.

```js
let videoFrame2 = VideoFrame.clone();
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-clone |

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

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


VideoFrame: duration property - Web APIs

VideoFrame: duration property
=============================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`duration`** property of the `VideoFrame` interface returns an integer indicating the duration of the video in microseconds.

Value
-----

An integer.

Examples
--------

The following example prints the `duration` to the console.

```js
console.log(VideoFrame.duration);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-duration |

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

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


VideoFrame: format property - Web APIs

VideoFrame: format property
===========================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`format`** property of the `VideoFrame` interface returns the pixel format of the `VideoFrame`.

Value
-----

A string containing a video pixel format, one of:

`"I420"`

Also known as *Planar YUV 4:2:0*, this format is composed of three distinct planes, one plane of luma and two planes of chroma, denoted Y, U and V, and present in this order. The U an V planes are sub-sampled horizontally and vertically by a factor of 2 compared to the Y plane. Each sample in this format is 8 bits.

`"I420A"`

Also known as *Planar YUV 4:2:0 with an alpha channel*, this format is composed of four distinct planes, one plane of Luma, two planes of Chroma, denoted Y, U and V, and one place of alpha values, all present in this order. The U an V planes are sub-sampled horizontally and vertically by a factor of 2 compared to the Y and Alpha planes. Each sample in this format is 8 bits.

`"I422"`

Also known as *Planar YUV 4:2:2*, this format is composed of three distinct planes, one plane of Luma and two planes of Chroma, denoted Y, U and V, and present in this order. The U an V planes are sub-sampled horizontally by a factor of 2 compared to the Y plane, and not sub-sampled vertically. Each sample in this format is 8 bits.

`"I444"`

Also known as *Planar YUV 4:4:4*, this format is composed of three distinct planes, one plane of Luma and two planes of Chroma, denoted Y, U and V, and present in this order. Each sample in this format is 8 bits. This format does not use sub-sampling.

`"NV12"`

This format is composed of two distinct planes, one plane of Luma and then another plane for the two Chroma components. The two planes are present in this order, and are referred to as respectively the Y plane and the UV plane. The U an V components are sub-sampled horizontally and vertically by a factor of 2 compared to the components in the Y planes. Each sample in this format is 8 bits.

`"RGBA"`

This format is composed of a single plane, that encodes four components: red, green, blue, and an alpha value, present in this order. Each sample in this format is 8 bits, and each pixel is therefore 32 bits.

`"RGBX"`

This format is composed of a single plane, that encodes four components: Red, Green, Blue, and a padding value, present in this order. Each sample in this format is 8 bits. The fourth element in each pixel is to be ignored, the image is always fully opaque.

`"BGRA"`

This format is composed of a single plane, that encodes four components: Blue, Green, Red, and an alpha value, present in this order. Each sample in this format is 8 bits.

`"BGRX"`

This format is composed of a single plane, that encodes four components: Blue, Green, Red, and a padding value, present in this order. Each sample in this format is 8 bits. The fourth element in each pixel is to be ignored, the image is always fully opaque.

Examples
--------

The following example prints the `format` to the console.

```js
console.log(VideoFrame.format);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-format |

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

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


VideoFrame: displayHeight property - Web APIs

VideoFrame: displayHeight property
==================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`displayHeight`** property of the `VideoFrame` interface returns the height of the `VideoFrame` after applying aspect ratio adjustments.

Value
-----

An integer.

Examples
--------

The following example prints the `displayHeight` to the console.

```js
console.log(VideoFrame.displayHeight);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-displayheight |

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

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


VideoFrame: codedHeight property - Web APIs

VideoFrame: codedHeight property
================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`codedHeight`** property of the `VideoFrame` interface returns the height of the VideoFrame in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.

Value
-----

An integer.

Examples
--------

The following example prints the `codedHeight` to the console.

```js
console.log(VideoFrame.codedHeight);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-codedheight |

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

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


VideoFrame: displayWidth property - Web APIs

VideoFrame: displayWidth property
=================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`displayWidth`** property of the `VideoFrame` interface returns the width of the `VideoFrame` after applying aspect ratio adjustments.

Value
-----

An integer.

Examples
--------

The following example prints the `displayWidth` to the console.

```js
console.log(VideoFrame.displayWidth);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-displaywidth |

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

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


VideoFrame: colorSpace property - Web APIs

VideoFrame: colorSpace property
===============================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`colorSpace`** property of the `VideoFrame` interface returns a `VideoColorSpace` object representing the color space of the video.

Value
-----

A `VideoColorSpace` object.

Examples
--------

The following example prints the `colorSpace` to the console.

```js
const cnv = document.createElement("canvas");
// draw something on the canvas
// ...
const videoFrame = new VideoFrame(cnv, { timestamp: 0 });
console.log(videoFrame.colorSpace);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-colorspace |

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

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


VideoFrame: copyTo() method - Web APIs

VideoFrame: copyTo() method
===========================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`copyTo()`** method of the `VideoFrame` interface copies the contents of the `VideoFrame` to an `ArrayBuffer`.

Syntax
------

```js
copyTo(destination)
copyTo(destination, options)
```

### Parameters

`destination`

An `ArrayBuffer`, a `TypedArray`, or a `DataView` to copy to.

`options` Optional

An object containing the following:

`rect` Optional

The rectangle of pixels to copy from the `VideoFrame`. If unspecified, the `visibleRect` will be used. This is in the format of a dictionary object containing:

* `x`: The x-coordinate.
* `y`: The y-coordinate.
* `width`: The width of the frame.
* `height`: The height of the frame.

`layout` Optional

A list containing the following values for each plane in the `VideoFrame`:

`offset`

An integer representing the offset in bytes where the given plane begins.

`stride`

 An integer representing the number of bytes, including padding, used by each row of the plane.
 Planes may not overlap. If no `layout` is specified, the planes will be tightly packed.

### Return value

A `Promise` that resolves to the layout of the copy when the copy has completed.

Examples
--------

The following example copies the entire contents of `videoFrame`.

```js
let buffer = new Uint8Array(videoFrame.allocationSize());
let layout = await videoFrame.copyTo(buffer);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-copyto |

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

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


VideoFrame: timestamp property - Web APIs

VideoFrame: timestamp property
==============================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`timestamp`** property of the `VideoFrame` interface returns an integer indicating the timestamp of the video in microseconds.

Value
-----

An integer.

Examples
--------

The following example prints the `timestamp` to the console.

```js
console.log(VideoFrame.timestamp);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-timestamp |

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

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


VideoFrame: close() method - Web APIs

VideoFrame: close() method
==========================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`close()`** method of the `VideoFrame` interface clears all states and releases the reference to the media resource.

Syntax
------

```js
close()
```

### Parameters

None.

### Return value

Undefined.

Examples
--------

The following example shows the `VideoFrame` object being closed.

```js
VideoFrame.close();
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-close |

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

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


VideoFrame: codedWidth property - Web APIs

VideoFrame: codedWidth property
===============================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`codedWidth`** property of the `VideoFrame` interface returns the width of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.

Value
-----

An integer.

Examples
--------

The following example prints the `codedWidth` to the console.

```js
console.log(VideoFrame.codedWidth);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-codedwidth |

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

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


VideoFrame: codedRect property - Web APIs

VideoFrame: codedRect property
==============================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`codedRect`** property of the `VideoFrame` interface returns a `DOMRectReadOnly` with the width and height matching `VideoFrame.codedWidth` and `VideoFrame.codedHeight`.

Value
-----

A `DOMRectReadOnly`.

Examples
--------

The following example prints the `codedRect` to the console.

```js
console.log(VideoFrame.codedRect);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-codedrect |

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

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


VideoFrame: allocationSize() method - Web APIs

VideoFrame: allocationSize() method
===================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`allocationSize()`** method of the `VideoFrame` interface returns the number of bytes required to hold the video as filtered by options passed into the method.

Syntax
------

```js
allocationSize()
allocationSize(options)
```

### Parameters

`options` Optional

An object containing the following:

`rect` Optional

The rectangle of pixels to copy from the `VideoFrame`. If unspecified the `visibleRect` will be used. This is in the format of a dictionary object containing:

* `x`: The x-coordinate.
* `y`: The y-coordinate.
* `width`: The width of the frame.
* `height`: The height of the frame.

`layout` Optional

A list containing the following values for each plane in the `VideoFrame`. Planes may not overlap. If unspecified the planes will be tightly packed:

`offset`

An integer representing the offset in bytes where the given plane begins.

`stride`

An integer representing the number of bytes, including padding, used by each row of the plane.

### Return value

An integer containing the number of bytes needed to hold the frame as specified by `options`.

Examples
--------

In the following example the `allocationSize` is returned for the rectangle at top left with dimensions of 800 by 600.

```js
const videoRect = {
  x: 0,
  y: 0,
  width: 800,
  height: 600,
};
let size = VideoFrame.allocationSize({ rect: videoRect });
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-allocationsize |

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

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


VideoFrame: VideoFrame() constructor - Web APIs

VideoFrame: VideoFrame() constructor
====================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`VideoFrame()`** constructor creates a new `VideoFrame` object representing a frame of a video.

Syntax
------

```js
new VideoFrame(image)
new VideoFrame(image, options)
new VideoFrame(data, options)
```

### Parameters

The first type of constructor (see above) creates a new `VideoFrame` from an image. Its parameters are:

`image`

 An image containing the image data for the new `VideoFrame`. It can be one of the following objects:
 an `SVGImageElement`,
 an `HTMLVideoElement`,
 an `HTMLCanvasElement`,
 an `ImageBitmap`,
 an `OffscreenCanvas`,
 or another `VideoFrame`.

`options` Optional

An object containing the following:

`duration` Optional

An integer representing the duration of the frame in microseconds.

`timestamp`

An integer representing the timestamp of the frame in microseconds.

`alpha` Optional

A string, describing how the user agent should behave when dealing with alpha channels. The default value is "keep".

* `"keep"`: Indicates that the user agent should preserve alpha channel data.
* `"discard"`: Indicates that the user agent should ignore or remove alpha channel data.

`visibleRect` Optional

An object representing the visible rectangle of the `VideoFrame`, containing the following:

`x`

The x-coordinate.

`y`

The y-coordinate.

`width`

The width of the frame.

`height`

The height of the frame.

`displayWidth` Optional

The width of the `VideoFrame` when displayed after applying aspect-ratio adjustments.

`displayHeight` Optional

The height of the `VideoFrame` when displayed after applying aspect-ratio adjustments.

The second type of constructor (see above) creates a new `VideoFrame` from an `ArrayBuffer`. Its parameters are:

`data`

An `ArrayBuffer`, a `TypedArray`, or a `DataView` containing the data for the new `VideoFrame`.

`options`

An object containing the following:

`format`

A string representing the video pixel format. One of the following strings, which are fully described on the page for the `format` property:

* `"I420"`
* `"I420A"`
* `"I422"`
* `"I444"`
* `"NV12"`
* `"RGBA"`
* `"RGBX"`
* `"BGRA"`
* `"BGRX"`

`codedWidth`

Width of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.

`codedHeight`

Height of the `VideoFrame` in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.

`timestamp`

An integer representing the timestamp of the frame in microseconds.

`duration` Optional

An integer representing the duration of the frame in microseconds.

`layout` Optional

A list containing the following values for each plane in the `VideoFrame`:

`offset`

An integer representing the offset in bytes where the given plane begins.

`stride`

 An integer representing the number of bytes, including padding, used by each row of the plane.
 Planes may not overlap. If no `layout` is specified, the planes will be tightly packed.

`visibleRect` Optional

An object representing the visible rectangle of the `VideoFrame`, containing the following:

`x`

The x-coordinate.

`y`

The y-coordinate.

`width`

The width of the frame.

`height`

The height of the frame.

`displayWidth` Optional

The width of the `VideoFrame` when displayed after applying aspect ratio adjustments.

`displayHeight` Optional

The height of the `VideoFrame` when displayed after applying aspect ratio adjustments.

`colorSpace`

An object representing the color space of the `VideoFrame`, containing the following:

`primaries`

A string representing the video color primaries, described on the page for the `VideoColorSpace.primaries` property.

`transfer`

A string representing the video color transfer function, described on the page for the `VideoColorSpace.transfer` property.

`matrix`

A string representing the video color matrix, described on the page for the `VideoColorSpace.matrix` property.

`fullRange`

A Boolean. If `true`, indicates that full-range color values are used.

`transfer`

An array of `ArrayBuffer`s that `VideoFrame` will detach and take ownership of. If the array contains the `ArrayBuffer` backing `data`, `VideoFrame` will use that buffer directly instead of copying from it.

Examples
--------

The following examples are from the article Video processing with WebCodecs. In this first example, a `VideoFrame` is created from a canvas.

```js
const cnv = document.createElement("canvas");
// draw something on the canvas
// ...
let frame_from_canvas = new VideoFrame(cnv, { timestamp: 0 });
```

In the following example a `VideoFrame` is created from a `TypedArray`.

```js
const pixelSize = 4;
let init = {
  timestamp: 0,
  codedWidth: 320,
  codedHeight: 200,
  format: "RGBA",
};
let data = new Uint8Array(init.codedWidth \* init.codedHeight \* pixelSize);
for (let x = 0; x < init.codedWidth; x++) {
  for (let y = 0; y < init.codedHeight; y++) {
    let offset = (y \* init.codedWidth + x) \* pixelSize;
    data[offset] = 0x7f; // Red
    data[offset + 1] = 0xff; // Green
    data[offset + 2] = 0xd4; // Blue
    data[offset + 3] = 0x0ff; // Alpha
  }
}
init.transfer = [data.buffer];
let frame = new VideoFrame(data, init);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-videoframe |

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

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


VideoFrame: visibleRect property - Web APIs

VideoFrame: visibleRect property
================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`visibleRect`** property of the `VideoFrame` interface returns a `DOMRectReadOnly` describing the visible rectangle of pixels for this `VideoFrame`.

Value
-----

A `DOMRectReadOnly`.

Examples
--------

The following example prints the `visibleRect` to the console.

```js
console.log(VideoFrame.visibleRect);
```

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

| Specification |
| --- |
| WebCodecs # dom-videoframe-visiblerect |

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

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


TaskPriorityChangeEvent: previousPriority property - Web APIs

TaskPriorityChangeEvent: previousPriority property
==================================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The readonly **`previousPriority`** property of the `TaskPriorityChangeEvent` interface returns the priority of the corresponding `TaskSignal` before it was changed and this `prioritychange` event was emitted.

This is the value that was set in the `TaskPriorityChangeEvent` constructor argument `options.previous`.

The new priority of the task can be read from `event.target.priority`.

Value
-----

 A string, indicating the associated task's priority before it was changed.
 This will be one of: `"user-blocking"`, `"user-visible"`, `"background"`.

Examples
--------

The code below shows the `previousPriority` being obtained in a handler for a `prioritychange` event.

```js
// Listen for 'prioritychange' events on the controller's signal.
controller.signal.addEventListener("prioritychange", (event) => {
  const previousPriority = event.previousPriority;
  const newPriority = event.target.priority;
  console.log(
    `The priority changed from ${previousPriority} to ${newPriority}.`,
  );
});
```

A more complete live example can be found in `prioritychange` event > Examples.

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

| Specification |
| --- |
| Prioritized Task Scheduling # dom-taskprioritychangeevent-previouspriority |

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

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


TaskPriorityChangeEvent: TaskPriorityChangeEvent() constructor - Web APIs

TaskPriorityChangeEvent: TaskPriorityChangeEvent() constructor
==============================================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
The **`TaskPriorityChangeEvent()`** constructor creates a new `TaskPriorityChangeEvent` object.

This object is created with a value indicating the previous priority of the task: the priority before it changed and this event was fired.

Syntax
------

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

### Parameters

`type`

 A string with the case-sensitive name of the associated event.
 User agents set it to `"prioritychange"`.

`options`

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

`previousPriority`

 A string indicating the *previous* priority of the task.
 One of: `"user-blocking"`, `"user-visible"`, `"background"`.

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

| Specification |
| --- |
| Prioritized Task Scheduling # dom-taskprioritychangeevent-taskprioritychangeevent |

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

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


HTMLOptionElement: Option() constructor - Web APIs

HTMLOptionElement: Option() constructor
=======================================

 The **`Option()`** constructor creates a new
 `HTMLOptionElement`.

Syntax
------

```js
new Option()
new Option(text)
new Option(text, value)
new Option(text, value, defaultSelected)
new Option(text, value, defaultSelected, selected)
```

### Parameters

`text` Optional

 A string representing the content of the element, i.e. the
 displayed text. If this is not specified, a default value of "" (empty string) is
 used.

`value` Optional

 A string representing the value of the
 `HTMLOptionElement`, i.e. the value attribute of the equivalent
 `<option>`. If this is not specified, the value of text is used as the
 value, e.g. for the associated `<select>` element's value when the form
 is submitted to the server.

`defaultSelected` Optional

 A value of either `true` or `false` that sets the `selected`
 attribute value, i.e. so that this `<option>` will be the default value
 selected in the `<select>` element when the page is first loaded. If
 this is not specified, a default value of false is used. Note that a value of true
 does not set the option to selected if it is not already selected.

`selected` Optional

 A value of either `true` or `false` that sets the option's selected state; the default is false
 (not selected). If omitted, even if the defaultSelected argument is true, the option
 is not selected.

Examples
--------

### Just add new options

```js
/\* assuming we have the following HTML
<select id='s'>

</select>
\*/

const s = document.getElementById("s");
const options = [Four, Five, Six];

options.forEach((element, key) => {
  s[key] = new Option(element, key);
});
```

### Append options with different parameters

```js
/\* assuming we have the following HTML
<select id="s">
 <option>First</option>
 <option>Second</option>
 <option>Third</option>
</select>
\*/

const s = document.getElementById("s");
const options = ["zero", "one", "two"];

options.forEach((element, key) => {
  if (element === "zero") {
    s[key] = new Option(element, s.options.length, false, false);
  }
  if (element === "one") {
    s[key] = new Option(element, s.options.length, true, false); // Will add the "selected" attribute
  }
  if (element === "two") {
    s[key] = new Option(element, s.options.length, false, true); // Just will be selected in "view"
  }
});

/\* Result
<select id="s">
 <option value="0">zero</option>
 <option value="1" selected="">one</option>
 <option value="2">two</option> // User will see this as 'selected'
</select>
\*/
```

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

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

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

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


CharacterData: deleteData() method - Web APIs

CharacterData: deleteData() method
==================================

 The **`deleteData()`** method of the `CharacterData` interface
 removes all or part of the data from this `CharacterData` node.

Syntax
------

```js
characterData.deleteData(offset, count)
```

### Parameters

`offset`

 The number of bytes from the start of the data to remove from.
 `0` is the first character of the string.

`count`

The number of bytes to remove.

### Return value

None.

Exceptions
----------

`IndexSizeError` `DOMException`

Thrown if `offset` is greater than the length of the contained data.

Example
-------

```html
<span>Result: </span>A long string.
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.deleteData(1, 5);
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-deletedata |

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

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

See also
--------

* `CharacterData.appendData()`, `CharacterData.insertData()`, `CharacterData.replaceData()`
* `CharacterData.data`


CharacterData: remove() method - Web APIs

CharacterData: remove() method
==============================

The **`remove()`** method of the `CharacterData` removes the text contained in the node.

Syntax
------

```js
remove()
```

### Parameters

None.

Example
-------

### Using `remove()`

```html
<span>Result: </span>A long string.
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.remove(); // Removes the text
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-remove① |

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

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

See also
--------

* `Element.remove()`
* `CharacterData.deleteData()`


CharacterData: appendData() method - Web APIs

CharacterData: appendData() method
==================================

 The **`appendData()`** method of the `CharacterData` interface
 adds the provided data to the end of the node's current data.

Syntax
------

```js
appendData(data)
```

### Parameters

`data`

The data to append to the current node.

### Return value

None.

Example
-------

```html
<span>Result: </span>A text
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.appendData(" - appended text.");
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-appenddata |

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

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

See also
--------

* `CharacterData.deleteData()`, `CharacterData.insertData()`, `CharacterData.replaceData()`
* `CharacterData.data`


CharacterData: substringData() method - Web APIs

CharacterData: substringData() method
=====================================

 The **`substringData()`** method of the `CharacterData` interface
 returns a portion of the existing data,
 starting at the specified index
 and extending for a given number of characters afterwards.

Syntax
------

```js
  domString = characterData.substringData(offset, count)
```

### Parameters

`offset`

 The index of the first character to include in the returned substring.
 `0` is the first character of the string.

`count`

The number of characters to return.

### Return value

A string with the substring.

Exceptions
----------

`IndexSizeError` `DOMException`

Thrown if `offset` + `count` is larger than the length of the contained data.

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-substringdata |

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

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


CharacterData: replaceWith() method - Web APIs

CharacterData: replaceWith() method
===================================

 The **`replaceWith()`** method of the `CharacterData` interface
 replaces this node in the children list of its parent
 with a set of `Node` objects or string.

Strings are inserted as `Text` nodes; the string is being passed as argument to the `Text()` constructor.

Syntax
------

```js
replaceWith(...nodes)
```

### Parameters

`nodes` Optional

A comma-separated list of `Node` objects or strings that will replace the current node.

**Note:** If there no argument is passed, this method acts just remove the node from the DOM tree.

### Return value

None (`undefined`).

### Exceptions

`HierarchyRequestError` `DOMException`

Thrown when the node cannot be inserted at the specified point in the hierarchy.

Examples
--------

```html
<p id="myText">Some text</p>
```

```js
let text = document.getElementById("myText").firstChild;
let em = document.createElement("em");
em.textContent = "Italic text";

text.replaceWith(em); // Replace `Some text` by `Italic text`
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-replacewith① |

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

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

See also
--------

* `CharacterData.replaceData()`


CharacterData: nextElementSibling property - Web APIs

CharacterData: nextElementSibling property
==========================================

 The read-only **`nextElementSibling`** property of the `CharacterData` interface
 returns the first `Element` node following the specified one in its parent's
 children list, or `null` if the specified element is the last one in the list.

Value
-----

A `Element` object, or `null` if no sibling has been found.

Example
-------

```html
TEXT
<div id="div-01">Here is div-01</div>
TEXT2
<div id="div-02">Here is div-02</div>
<pre>Here is the result area</pre>
```

```js
// Initially, set node to the Text node with `TEXT`
let node = document.getElementById("div-01").previousSibling;

let result = "Next element siblings of TEXT:\n";

while (node) {
  result += `${node.nodeName}\n`;
  node = node.nextElementSibling; // The first node is a CharacterData, the others Element objects
}

document.querySelector("pre").textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-nondocumenttypechildnode-nextelementsibling② |

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

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

See also
--------

* `CharacterData.previousElementSibling`


CharacterData: before() method - Web APIs

CharacterData: before() method
==============================

 The **`before()`** method of the `CharacterData` interface
 inserts a set of `Node` objects and strings
 in the children list of the `CharacterData`'s parent, just before the `CharacterData` node.

Strings are inserted as `Text` nodes; the string is being passed as argument to the `Text()` constructor.

Syntax
------

```js
before(...nodes)
```

### Parameters

`nodes`

A set of `Node` or strings to insert.

### Exceptions

`HierarchyRequestError` `DOMException`

Thrown when the new nodes cannot be inserted at the specified point in the hierarchy, that is if one of the following conditions is met:

* If the insertion of one of the added node would lead to a cycle, that is if one of them is an ancestor of this `CharacterData` node.
* If one of the added node is not a `DocumentFragment`, a `DocumentType`, an `Element`, or a `CharacterData`.
* If this `CharacterData` node is actually a `Text` node, and its parent is a `Document`.
* If the parent of this `CharacterData` node is a `Document` and one of the nodes to insert is a `DocumentFragment` with more than one `Element` child, or that has a `Text` child.

Examples
--------

 The `before()` method allows you to insert new nodes before a
 `CharacterData` node leaving the current node's data unchanged.

```js
const h1TextNode = document.querySelector("h1").firstChild;
h1TextNode.before("h1# ");

h1TextNode.parentElement.childNodes;
// NodeList [#text "h1# ", #text "CharacterData.before()"]

h1TextNode.data;
// "CharacterData.before()"
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-before① |

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

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

See also
--------

* `CharacterData.appendData()`
* `CharacterData.after()`
* `Element.append()`
* `Node.appendChild()`
* `Element.insertAdjacentElement()`


CharacterData: insertData() method - Web APIs

CharacterData: insertData() method
==================================

 The **`insertData()`** method of the `CharacterData` interface
 inserts the provided data into this `CharacterData` node's current data,
 at the provided offset from the start of the existing data.
 The provided data is spliced into the existing data.

Syntax
------

```js
characterData.insertData(offset, data)
```

### Parameters

`offset`

 The offset number of characters to insert the provided data at.
 `0` is the first character of the string.

`data`

The data to insert.

### Return value

None.

Exceptions
----------

`IndexSizeError` `DOMException`

Thrown if offset is negative or greater than the length of the contained data.

Example
-------

```html
<span>Result: </span>A string.
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.insertData(2, "long ");
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-insertdata |

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

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

See also
--------

* `CharacterData.appendData()`, `CharacterData.deleteData()`, `CharacterData.replaceData()`
* `CharacterData.data`


CharacterData: previousElementSibling property - Web APIs

CharacterData: previousElementSibling property
==============================================

 The read-only **`previousElementSibling`** of the `CharacterData` interface
 returns the first `Element` before the current node in its parent's children list,
 or `null` if there is none.

Value
-----

A `Element` object, or `null` if no sibling has been found.

Example
-------

```html
<div id="div-01">Here is div-01</div>
TEXT
<div id="div-02">Here is div-02</div>
SOME TEXT
<div id="div-03">Here is div-03</div>
<pre>Result</pre>
```

```js
// Initially set node to the Text node with `SOME TEXT`
let node = document.getElementById("div-02").nextSibling;

let result = "Previous element siblings of SOME TEXT:\n";

while (node) {
  result += `${node.nodeName}\n`;
  node = node.previousElementSibling;
}

document.querySelector("pre").textContent = result;
```

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-nondocumenttypechildnode-previouselementsibling② |

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

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

See also
--------

* `CharacterData.nextElementSibling`


CharacterData: after() method - Web APIs

CharacterData: after() method
=============================

 The **`after()`** method of the `CharacterData` interface
 inserts a set of `Node` objects or strings in the children list of the
 object's parent, just after the object itself.

Strings are inserted as `Text` nodes; the string is being passed as argument to the `Text()` constructor.

Syntax
------

```js
after(...nodes)
```

### Parameters

`nodes`

A set of `Node` or strings to insert.

### Exceptions

`HierarchyRequestError` `DOMException`

 Thrown when the new nodes cannot be inserted at the specified point in the hierarchy,
 that is if one of the following conditions is met:

* If the insertion of one of the added node would lead to a cycle, that is if one of them is an ancestor of this `CharacterData` node.
* If one of the added node is not a `DocumentFragment`, a `DocumentType`, an `Element`, or a `CharacterData`.
* If this `CharacterData` node is actually a `Text` node, and its parent is a `Document`.
* If the parent of this `CharacterData` node is a `Document` and one of the nodes to insert is a `DocumentFragment` with more than one `Element` child, or that has a `Text` child.

Examples
--------

The `after()` method allows you to insert new nodes after a `CharacterData` node.

```js
const h1TextNode = document.querySelector("h1").firstChild;
h1TextNode.after(" #h1");

h1TextNode.parentElement.childNodes;
// NodeList [#text "CharacterData.after()", #text " #h1"]

h1TextNode.data;
// "CharacterData.after()"
```

**Note:** If you rather want to append text to the current node,
 the `appendData()` method lets you append to the current node's data.

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

| Specification |
| --- |
| DOM Standard # ref-for-dom-childnode-after① |

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

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

See also
--------

* `CharacterData.appendData()`
* `CharacterData.before()`
* `Element.append()`
* `Node.appendChild()`
* `Element.insertAdjacentElement()`


CharacterData: length property - Web APIs

CharacterData: length property
==============================

 The read-only **`CharacterData.length`** property
 returns the number of characters in the contained data, as a positive integer.

Value
-----

A positive integer with the length of the `CharacterData.data` string.

Example
-------

**Note:** `CharacterData` is an abstract interface.
 The examples below use `Text`, a concrete interface implementing it.

```html
Length of the string in the <code>Text</code> node: <output></output>
```

```js
const output = document.querySelector("output");
const textnode = new Text("This text has been set using 'textnode.data'.");

output.value = textnode.length;
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-length |

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

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


CharacterData: replaceData() method - Web APIs

CharacterData: replaceData() method
===================================

The **`replaceData()`** method of the `CharacterData` interface removes a certain number of characters of the existing text in a given `CharacterData` node and replaces those characters with the text provided.

Syntax
------

```js
characterData.replaceData(offset, count, data)
```

### Parameters

`offset`

 The number of characters from the start of the data to insert at.
 `0` is the first character of the string.

`count`

The number of characters to replace with the provided data.

`data`

The data to insert.

### Return value

None.

Exceptions
----------

`IndexSizeError` `DOMException`

Thrown if `offset` or `count` is negative or `offset` is greater than the length of the contained data.

Example
-------

```html
<span>Result: </span>A long string.
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.replaceData(2, 4, "replaced");
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-replacedata |

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

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

See also
--------

* `CharacterData.appendData()`
* `CharacterData.deleteData()`
* `CharacterData.insertData()`
* `CharacterData.data`


CharacterData: data property - Web APIs

CharacterData: data property
============================

The **`data`** property of the `CharacterData` interface represent the value of the current object's data.

Value
-----

A string with the character information contained in the `CharacterData` node.

Example
-------

**Note:** `CharacterData` is an abstract interface.
 The examples below use two concrete interfaces implementing it, `Text` and `Comment`.

### Reading a comment using data

```html
<!-- This is an HTML comment -->
<output id="result"></output>
```

```js
const comment = document.body.childNodes[1];
const output = document.getElementById("result");

output.value = comment.data;
```

### Setting the content of a text node using data

```html
<span>Result: </span>Not set.
```

```js
const span = document.querySelector("span");
const textnode = span.nextSibling;

textnode.data = "This text has been set using 'textnode.data'.";
```

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

| Specification |
| --- |
| DOM Standard # dom-characterdata-data |

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

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

See also
--------

* `CharacterData.length` returning the length of the data contained in the `CharacterData` node.


RTCDTMFToneChangeEvent: RTCDTMFToneChangeEvent() constructor - Web APIs

RTCDTMFToneChangeEvent: RTCDTMFToneChangeEvent() constructor
============================================================

 The **`RTCDTMFToneChangeEvent()`** constructor creates a new
 `RTCDTMFToneChangeEvent` object.

Syntax
------

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

### Parameters

`type`

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

`options` Optional

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

`tone` Optional

 A string containing a single DTMF tone character which has
 just begun to play, or an empty string (`""`) to indicate that the previous
 tone has stopped playing. It defaults to `""`.
 See Tone characters
 for details on what characters are permitted.

### Return value

 A new `RTCDTMFToneChangeEvent` object, configured as specified in the
 provided options.

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

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

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

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

See also
--------

* WebRTC
* Using DTMF with WebRTC
* Its usual target: `RTCDTMFSender`.


RTCDTMFToneChangeEvent: tone property - Web APIs

RTCDTMFToneChangeEvent: tone property
=====================================

 The read-only property **`RTCDTMFToneChangeEvent.tone`**
 returns the DTMF character which has just begun to play, or an empty string
 (`""`). if all queued tones have finished playing (that is,
 `RTCDTMFSender.toneBuffer` is empty).

Value
-----

A string with the DTML character playing, or the empty string.

Example
-------

 This example establishes a handler for the `tonechange` event which updates
 an element to display the currently playing tone in its content, or, if all tones have
 played, the string "<none>".

```js
dtmfSender.ontonechange = (ev) => {
  let tone = ev.tone;
  if (tone === "") {
    tone = "<none>";
  }

  document.getElementById("playingTone").innerText = tone;
};
```

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

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers # dom-rtcdtmftonechangeevent-tone |

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

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

See also
--------

* WebRTC
* Using DTMF with WebRTC
* `tonechange`
* `RTCDTMFToneChangeEvent`


CSSNumericArray: length property - Web APIs

CSSNumericArray: length property
================================

 The read-only **`length`** property of the
 `CSSNumericArray` interface returns the number of
 `CSSNumericValue` objects in the list.

Value
-----

 An integer representing the number of `CSSNumericValue` objects in the
 list.

Examples
--------

To Do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssnumericarray-length |

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

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


CSSRotate: y property - Web APIs

CSSRotate: y property
=====================

 The **`y`** property of the
 `CSSRotate` interface gets and sets the ordinate or y-axis of the
 translating vector.

Value
-----

A double integer or a `CSSNumericValue`

Examples
--------

To Do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssrotate-y |

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

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


CSSRotate: angle property - Web APIs

CSSRotate: angle property
=========================

 The **`angle`** property of the
 `CSSRotate` interface gets and sets the angle of rotation. A positive angle
 denotes a clockwise rotation, a negative angle a counter-clockwise one.

Value
-----

A `CSSNumericValue`

Examples
--------

To Do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssrotate-angle |

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

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


CSSRotate: x property - Web APIs

CSSRotate: x property
=====================

 The **`x`** property of the
 `CSSRotate` interface gets and sets the abscissa or x-axis of the
 translating vector.

Value
-----

A double integer or a `CSSNumericValue`

Examples
--------

To Do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssrotate-x |

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

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


CSSRotate: CSSRotate() constructor - Web APIs

CSSRotate: CSSRotate() constructor
==================================

 The **`CSSRotate()`** constructor creates a new
 `CSSRotate` object representing the rotate() value of the
 individual `transform` property in CSS.

Syntax
------

```js
new CSSRotate(x, y, z, angle)
```

### Parameters

`x`

 A value for the x-axis of the `CSSRotate` object to be constructed.
 This must either be a double integer or a `CSSNumericValue`.

`y`

 A value for the y-axis of the `CSSRotate` object to be constructed.
 This must either be a double integer or a `CSSNumericValue`.

`z`

 A value for the z-axis of the `CSSRotate` object to be constructed.
 This must either be a double integer or a `CSSNumericValue`.

`angle`

 A value for the angle of the `CSSRotate` object to be constructed. This
 must be a `CSSNumericValue`.

### Exceptions

`TypeError`

 Raised if the value of `CSSRotate.angle` is not an <angle> value
 or `CSSRotate.x`, `CSSRotate.y`, `CSSRotate.z` are
 not <number> values.

Examples
--------

To do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssrotate-cssrotate |
| CSS Typed OM Level 1 # dom-cssrotate-cssrotate-x-y-z-angle |

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

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


CSSRotate: z property - Web APIs

CSSRotate: z property
=====================

 The **`z`** property of the
 `CSSRotate` interface representing the z-component of the translating
 vector. A positive value moves the element towards the viewer, and a negative value
 farther away.

Value
-----

A double integer or a `CSSNumericValue`

Examples
--------

To Do

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

| Specification |
| --- |
| CSS Typed OM Level 1 # dom-cssrotate-z |

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

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


BackgroundFetchRecord: request property - Web APIs

BackgroundFetchRecord: request property
=======================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`request`** read-only property of the `BackgroundFetchRecord` interface returns the details of the resource to be fetched.

Value
-----

A `Request`.

Examples
--------

In this example an individual `BackgroundFetchRecord` is returned using `BackgroundFetchManager.fetch()`. The `request` is returned and logged to the console.

```js
bgFetch.match("/ep-5.mp3").then(async (record) => {
  if (!record) {
    console.log("No record found");
    return;
  }

  console.log(`Here's the request`, record.request);
});
```

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

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchrecord-request |

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

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


BackgroundFetchRecord: responseReady property - Web APIs

BackgroundFetchRecord: responseReady property
=============================================

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
**Experimental:** **This is an experimental technology**
Check the Browser compatibility table carefully before using this in production.

The **`responseReady`** read-only property of the `BackgroundFetchRecord` interface returns a `Promise` that resolves with a `Response`.

Value
-----

A `Promise` that resolves with a `Response`.

Examples
--------

In this example an individual `BackgroundFetchRecord` is returned using `BackgroundFetchManager.fetch()`. The value of `responseReady` is returned and logged to the console.

```js
bgFetch.match("/ep-5.mp3").then(async (record) => {
  if (!record) {
    console.log("No record found");
    return;
  }

  const response = await record.responseReady;
  console.log(`Here's the response`, response);
});
```

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

| Specification |
| --- |
| Background Fetch # dom-backgroundfetchrecord-responseready |

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

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


SourceBuffer: textTracks property - Web APIs

SourceBuffer: textTracks property
=================================

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

 The **`textTracks`** read-only property of the
 `SourceBuffer` interface returns a list of the text tracks currently
 contained inside the `SourceBuffer`.

Value
-----

An `TextTrackList` object.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-texttracks |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: updating property - Web APIs

SourceBuffer: updating property
===============================

 The **`updating`** read-only property of the
 `SourceBuffer` interface indicates whether the `SourceBuffer` is
 currently being updated — i.e. whether an `SourceBuffer.appendBuffer()` or `SourceBuffer.remove()`
 operation is currently in progress.

Value
-----

A boolean value.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-updating |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: abort() method - Web APIs

SourceBuffer: abort() method
============================

 The **`abort()`** method of the `SourceBuffer`
 interface aborts the current segment and resets the segment parser.

Syntax
------

```js
abort()
```

### Parameters

None.

### Return value

None (`undefined`).

### Exceptions

`InvalidStateError` `DOMException`

 Thrown if the `MediaSource.readyState` property of the
 parent media source is not equal to `open`, or this
 `SourceBuffer` has been removed from the
 `MediaSource`.

Examples
--------

 The spec description of `abort()` is somewhat confusing — consider for
 example step 1 of reset parser state. The MSE API is fully asynchronous, but this step seems to suggest a
 synchronous (blocking) operation, which doesn't make sense.

 Saying that, current implementations can be useful in certain situations, when you want
 to stop the current append (or whatever) operation occurring on a sourcebuffer, and then
 immediately start performing operations on it again. For example, consider this code:

```js
sourceBuffer.addEventListener("updateend", (ev) => {
  // ...
});

sourceBuffer.appendBuffer(buf);
```

 Let's say that after the call to `appendBuffer` BUT before the
 `updateend` event fires (i.e. a buffer is being appended but the operation
 has not yet completed) a user "scrubs" the video seeking to a new point in time. In
 this case you would want to manually call `abort()` on the source buffer to
 stop the decoding of the current buffer, then fetch and append the newly requested
 segment that relates to the current new position of the video.

 You can see something similar in action in Nick Desaulnier's bufferWhenNeeded demo — in line 48, an event listener is added to the playing video so a function called
 `seek()` is run when the `seeking` event fires. In lines 92-101, the seek() function is defined — note that `abort()` is called
 if `MediaSource.readyState` is set to `open`, which means that
 it is ready to receive new source buffers — at this point it is worth aborting the
 current segment and just getting the one for the new seek position (see
 `checkBuffer()`
 and
 `getCurrentSegment()`.)

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-abort |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: appendBufferAsync() method - Web APIs

SourceBuffer: appendBufferAsync() method
========================================

**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.

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

 The **`appendBufferAsync()`** method
 of the `SourceBuffer` interface begins the process of asynchronously
 appending media segment data from an `ArrayBuffer`,
 a `TypedArray` or a `DataView` object to the `SourceBuffer` object.
 It returns a `Promise` which is fulfilled once the buffer has been appended.

Syntax
------

```js
appendBufferAsync(source)
```

### Parameters

`source`

Either an `ArrayBuffer`, a `TypedArray` or a `DataView` object that contains the media segment data you want to add to the `SourceBuffer`.

### Return value

 A `Promise` which is fulfilled when the buffer has been added successfully to the `SourceBuffer` object,
 or `null`, if the request could not be initiated.

Examples
--------

 This simplified example async function, `fillSourceBuffer()`, takes as input
 parameters `buffer`, an `ArrayBuffer`, a `TypedArray`, or a `DataView`, and a
 `SourceBuffer` object to which to append the source media from the buffer.

```js
async function fillSourceBuffer(buffer, msBuffer) {
  try {
    while (true) {
      await msBuffer.appendBufferAsync(buffer);
    }
  } catch (e) {
    handleException(e);
  }
}
```

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

This feature is not part of any specification. It is not on track to become a standard.

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

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

See also
--------

* Media Source Extensions API
* `SourceBuffer.appendBuffer()`
* `MediaSource`
* `SourceBufferList`


SourceBuffer: audioTracks property - Web APIs

SourceBuffer: audioTracks property
==================================

 The **`audioTracks`** read-only property of the
 `SourceBuffer` interface returns a list of the audio tracks currently
 contained inside the `SourceBuffer`.

Value
-----

An `AudioTrackList` object.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-audiotracks |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: appendBuffer() method - Web APIs

SourceBuffer: appendBuffer() method
===================================

 The **`appendBuffer()`** method of the
 `SourceBuffer` interface appends media segment data from an
 `ArrayBuffer`, a `TypedArray` or a `DataView` object
 to the `SourceBuffer`.

Syntax
------

```js
appendBuffer(source)
```

### Parameters

`source`

 Either an `ArrayBuffer`, a `TypedArray` or a `DataView` object
 that contains the media segment data you want to add to the `SourceBuffer`.

### Return value

None (`undefined`).

### Exceptions

None.

Examples
--------

TBD.

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-appendbuffer |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: remove() method - Web APIs

SourceBuffer: remove() method
=============================

 The **`remove()`** method of the `SourceBuffer`
 interface removes media segments within a specific time range from the
 `SourceBuffer`. This method can only be called when
 `SourceBuffer.updating` equals `false`. If
 `SourceBuffer.updating` is not equal to `false`, call
 `SourceBuffer.abort()`.

Syntax
------

```js
remove(start, end)
```

### Parameters

`start`

A double representing the start of the time range, in seconds.

`end`

A double representing the end of the time range, in seconds.

### Return value

None (`undefined`).

### Exceptions

`InvalidAccessError` `DOMException`

Thrown if either the `MediaSource.duration` property is equal to `NaN`, the `start` parameter is negative or greater than `MediaSource.duration`, or the `end` parameter is less than or equal to `start` or equal to `NaN`.

`InvalidStateError` `DOMException`

 Thrown if the `SourceBuffer.updating` property is equal
 to `true`, or this `SourceBuffer` has been removed
 from `MediaSource`.

Examples
--------

TBD.

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-remove |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: appendWindowStart property - Web APIs

SourceBuffer: appendWindowStart property
========================================

 The **`appendWindowStart`** property of the
 `SourceBuffer` interface controls the timestamp for the start of the append window, a
 timestamp range that can be used to filter what media data is appended to the
 `SourceBuffer`. Coded media frames with timestamps within this range will be
 appended, whereas those outside the range will be filtered out.

 The default value of `appendWindowStart` is the presentation start time,
 which is the beginning time of the playable media.

Value
-----

A double, indicating the start time of the append window, in seconds.

### Exceptions

The following exceptions may be thrown when setting a new value for this property:

`InvalidAccessError` `DOMException`

 Thrown if an attempt was made to set the value to less than 0 or to a value greater
 than or equal to
 `SourceBuffer.appendWindowEnd`.

`InvalidStateError` `DOMException`

 Thrown if this `SourceBuffer` object is being updated (i.e.
 its `SourceBuffer.updating` property is
 currently `true`), or this `SourceBuffer` has been
 removed from the `MediaSource`.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-appendwindowstart |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: videoTracks property - Web APIs

SourceBuffer: videoTracks property
==================================

 The **`videoTracks`** read-only property of the
 `SourceBuffer` interface returns a list of the video tracks currently
 contained inside the `SourceBuffer`.

Value
-----

An `VideoTrackList` object.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-videotracks |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: timestampOffset property - Web APIs

SourceBuffer: timestampOffset property
======================================

 The **`timestampOffset`** property of the
 `SourceBuffer` interface controls the offset applied to timestamps inside
 media segments that are appended to the `SourceBuffer`.

The initial value of `timestampOffset` is 0.

Value
-----

A double, with the offset amount expressed in seconds.

### Exceptions

The following exception may be thrown when setting a new value for this property:

`InvalidStateError` `DOMException`

 Thrown if one or more of the `SourceBuffer` objects in
 `MediaSource.sourceBuffers` are being updated
 (i.e. their `SourceBuffer.updating` property is
 currently `true`), a media segment inside the
 `SourceBuffer` is currently being parsed, or this
 `SourceBuffer` has been removed from the
 `MediaSource`.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-timestampoffset |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: appendWindowEnd property - Web APIs

SourceBuffer: appendWindowEnd property
======================================

 The **`appendWindowEnd`** property of the
 `SourceBuffer` interface controls the timestamp for the end of the append window, a
 timestamp range that can be used to filter what media data is appended to the
 `SourceBuffer`. Coded media frames with timestamps within this range will be
 appended, whereas those outside the range will be filtered out.

The default value of `appendWindowEnd` is positive infinity.

Value
-----

A double, indicating the end time of the append window, in seconds.

### Exceptions

The following exceptions may be thrown when setting a new value for this property:

`InvalidAccessError` `DOMException`

 Thrown if an attempt was made to set the value to less than or equal to
 `SourceBuffer.appendWindowStart` or `NaN`.

`InvalidStateError` `DOMException`

 Thrown if this `SourceBuffer` object is being updated (i.e.
 its `SourceBuffer.updating` property is
 currently `true`), or this `SourceBuffer` has been
 removed from the `MediaSource`.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-appendwindowend |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: changeType() method - Web APIs

SourceBuffer: changeType() method
=================================

 The **`changeType()`** method of the
 `SourceBuffer` interface sets the MIME type that future calls to
 `appendBuffer()` should expect the new media
 data to conform to. This makes it possible to change codecs or container type
 mid-stream.

 One scenario in which this is helpful is to support adapting the media source to
 changing bandwidth availability, by transitioning from one codec to another as resource
 constraints change.

Syntax
------

```js
changeType(type)
```

### Parameters

`type`

 A string specifying the MIME type that future buffers will conform
 to.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the specified string is empty, rather than indicating a valid MIME type.

`InvalidStateError` `DOMException`

 Thrown if the `SourceBuffer` is not a member of the parent media source's
 `sourceBuffers` list, or the buffer's
 `updating` property indicates that a previously
 queued `appendBuffer()` or
 `remove()` is still being processed.

`NotSupportedError` `DOMException`

 Thrown if the specified MIME type is not supported, or is not supported with the types of
 `SourceBuffer` objects present in the
 `MediaSource.sourceBuffers` list.

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

 If the `readyState` property of the parent `MediaSource` is set to `"ended"`, calling `changeType()`
 will set the `readyState` property to`"open"` and
 fire a simple event named `sourceopen` at the parent media source.

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: mode property - Web APIs

SourceBuffer: mode property
===========================

 The **`mode`** property of the `SourceBuffer`
 interface controls whether media segments can be appended to the
 `SourceBuffer` in any order, or in a strict sequence.

The two available values are:

* `segments`: The media segment timestamps determine the order in which the
 segments are played. The segments can be appended to the `SourceBuffer` in
 any order.
* `sequence`: The order in which the segments are appended to the
 `SourceBuffer` determines the order in which they are played. Segment
 timestamps are generated automatically for the segments that observe this order.

 The mode value is initially set when the `SourceBuffer` is created using
 `MediaSource.addSourceBuffer()`. If timestamps already exist for the media
 segments, then the value will be set to `segments`; if they don't, then the
 value will be set to `sequence`.

 If you try to set the `mode` property value to `segments` when
 the initial value is `sequence`, an exception will be thrown. The existing
 segment order must be maintained in `sequence` mode. You can, however, change
 the value from `segments` to `sequence`. It just means the play
 order will be fixed, and new timestamps generated to reflect this.

 This property cannot be changed during while the `SourceBuffer` is
 processing either an `appendBuffer()` or
 `remove()` call.

Value
-----

A string.

### Exceptions

The following exceptions may be thrown when setting a new value for this property:

`InvalidAccessError` `DOMException`

 Thrown if an attempt was made to set the value to `segments` when the
 initial value is `sequence`.

`InvalidStateError` `DOMException`

 Thrown if the `SourceBuffer` object is being updated (i.e.
 its `SourceBuffer.updating` property is
 currently `true`), the last media segment appended to this
 `SourceBuffer` is incomplete, or this
 `SourceBuffer` has been removed from the
 `MediaSource`.

Examples
--------

 This snippet sets the `sourceBuffer` mode to `'sequence'` if it
 is currently set to `'segments'`, thus setting the play order to the sequence
 in which media segments are appended.

```js
const curMode = sourceBuffer.mode;
if (curMode === "segments") {
  sourceBuffer.mode = "sequence";
}
```

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-mode |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: buffered property - Web APIs

SourceBuffer: buffered property
===============================

 The **`buffered`** read-only property of the
 `SourceBuffer` interface returns the time ranges that are currently
 buffered in the `SourceBuffer` as a normalized `TimeRanges`
 object.

Value
-----

A `TimeRanges` object.

Examples
--------

TBD

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

| Specification |
| --- |
| Media Source Extensions™ # dom-sourcebuffer-buffered |

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

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

See also
--------

* `MediaSource`
* `SourceBufferList`


SourceBuffer: removeAsync() method - Web APIs

SourceBuffer: removeAsync() method
==================================

**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.

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

 The **`removeAsync()`** method of the
 `SourceBuffer` interface starts the process of asynchronously removing
 from the `SourceBuffer` media segments found within a specific time
 range. A `Promise` is returned, which is fulfilled when the buffers
 in the specified time range have been removed.

 This method can only be called when `updating` is
 `false`. If that's not the case, call `abort()` instead.

Syntax
------

```js
removeAsync(start, end)
```

### Parameters

`start`

A double representing the start of the time range, in seconds.

`end`

A double representing the end of the time range, in seconds.

### Return value

 A `Promise` whose fulfillment handler is executed once the buffers in the
 specified time range have been removed from the `SourceBuffer`.

Examples
--------

 This example establishes an asynchronous function, `emptySourceBuffer()`,
 which clears the contents of the specified `SourceBuffer`.

```js
async function emptySourceBuffer(msBuffer) {
  await msBuffer.removeAsync(0, Infinity).catch((e) => {
    handleException(e);
  });
}
```

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

This feature is not part of any specification. It is not on track to become a standard.

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

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

See also
--------

* Media Source Extensions API
* `SourceBuffer.remove()`
* `MediaSource`
* `SourceBufferList`


DocumentPictureInPicture: enter event - Web APIs

DocumentPictureInPicture: enter event
=====================================

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

The **`enter`** event of the `DocumentPictureInPicture` interface is fired when the Picture-in-Picture window is successfully opened.

Syntax
------

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

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

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

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

A `DocumentPictureInPictureEvent`.

Examples
--------

```js
documentPictureInPicture.addEventListener("enter", (event) => {
  const pipWindow = event.window;
  console.log("Video player has entered the pip window");

  const pipMuteButton = pipWindow.document.createElement("button");
  pipMuteButton.textContent = "Mute";
  pipMuteButton.addEventListener("click", () => {
    const pipVideo = pipWindow.document.querySelector("#video");
    if (!pipVideo.muted) {
      pipVideo.muted = true;
      pipMuteButton.textContent = "Unmute";
    } else {
      pipVideo.muted = false;
      pipMuteButton.textContent = "Mute";
    }
  });

  pipWindow.document.body.append(pipMuteButton);
});
```

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

| Specification |
| --- |
| Document Picture-in-Picture Specification # dom-documentpictureinpicture-onenter |

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

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

See also
--------

* Document Picture-in-Picture API
* Using the Document Picture-in-Picture API


DocumentPictureInPicture: requestWindow() method - Web APIs

DocumentPictureInPicture: requestWindow() method
================================================

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

 The **`requestWindow()`** method of the
 `DocumentPictureInPicture` interface opens the Picture-in-Picture window for the current main browsing context. It returns a `Promise` that fulfills with a `Window` instance representing the browsing context inside the Picture-in-Picture window.

The `requestWindow()` method requires transient activation, i.e. it must be invoked in response to a user action such as a mouse click or button press.

Syntax
------

```js
requestWindow()
requestWindow(options)
```

### Parameters

`options` Optional

An options object containing the following properties:

`height`

A non-negative number representing the height to set for the Picture-in-Picture window's viewport, in pixels. If `options` is not specified, the default value 0 is used.

`width`

A non-negative number representing the width to set for the Picture-in-Picture window's viewport, in pixels. If `options` is not specified, the default value 0 is used.

**Note:** If one of the options is specified, the other one must be too, otherwise an error is thrown. If both values are not specified, specified as 0, or set too large, the browser will clamp or ignore the values as appropriate to provide a reasonable user experience. The clamped size will vary depending on implementation, display size, and other factors.

### Return value

A `Promise` that fulfills with a `Window` object instance representing the browsing context inside the Picture-in-Picture window.

### Exceptions

`NotSupportedError` `DOMException`

Thrown if the API has been explicitly disabled (for example via browser settings).

`NotAllowedError` `DOMException`

Thrown if:

* `requestWindow()` is not called from a top-level `window` object.
* `requestWindow()` is called from the `window` object of the Picture-in-Picture window (i.e. `DocumentPictureInPicture.window`).
* `requestWindow()` is called without transient activation.

`RangeError` `DOMException`

Thrown if only one of `height` and `width` are set, or if `height` and `width` are set with negative values.

Examples
--------

```js
const videoPlayer = document.getElementById("player");

// ...

// Open a Picture-in-Picture window.
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
});

// ...
```

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

| Specification |
| --- |
| Document Picture-in-Picture Specification # dom-documentpictureinpicture-requestwindow |

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

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

See also
--------

* Document Picture-in-Picture API
* Using the Document Picture-in-Picture API


DocumentPictureInPicture: window property - Web APIs

DocumentPictureInPicture: window property
=========================================

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

 The **`window`** read-only property of the
 `DocumentPictureInPicture` interface returns a `Window` instance representing the browsing context inside the Picture-in-Picture window.

Value
-----

A `Window` object instance if the Picture-in-Picture window has already been opened using `DocumentPictureInPicture.requestWindow()`, or `null` otherwise.

Examples
--------

```js
const videoPlayer = document.getElementById("player");

// ...

await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
});

// ...

const pipWindow = window.documentPictureInPicture.window;
if (pipWindow) {
  // Mute video playing in the Picture-in-Picture window.
  const pipVideo = pipWindow.document.querySelector("#video");
  pipVideo.muted = true;
}
```

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

| Specification |
| --- |
| Document Picture-in-Picture Specification # dom-documentpictureinpicture-window |

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

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

See also
--------

* Document Picture-in-Picture API
* Using the Document Picture-in-Picture API


Worklet: addModule() method - Web APIs

Worklet: addModule() method
===========================

 The **`addModule()`** method of the
 `Worklet` interface loads the module in the given JavaScript file and
 adds it to the current `Worklet`.

Syntax
------

```js
addModule(moduleURL)
addModule(moduleURL, options)
```

### Parameters

`moduleURL`

 A `String` containing the URL of a JavaScript file with the module to
 add.

`options` Optional

An object with any of the following options:

`credentials`

 A `Request.credentials` value that
 indicates whether to send credentials (e.g. cookies and HTTP authentication)
 when loading the module. Can be one of `"omit"`,
 `"same-origin"`, or `"include"`. Defaults to
 `"same-origin"`. See also `Request.credentials`.

### Return value

 A `Promise` that resolves once the module from the given URL has been
 added. The promise doesn't return any value.

### Exceptions

 If `addModule()` fails, it rejects the promise, delivering one of the
 following errors to the rejection handler.

`AbortError` `DOMException`

The specified script is invalid or could not be loaded.

`SyntaxError` `DOMException`

The specified `moduleURL` is invalid.

Examples
--------

### AudioWorklet example

```js
const audioCtx = new AudioContext();
const audioWorklet = audioCtx.audioWorklet;
audioWorklet.addModule("modules/bypassFilter.js", {
  credentials: "omit",
});
```

### PaintWorklet example

```js
CSS.paintWorklet.addModule(
  "https://mdn.github.io/houdini-examples/cssPaint/intro/worklets/hilite.js",
);
```

 Once the script has been added to the paint worklet, the CSS `paint()` function
 can be used to include the image created by the worklet:

```css
@supports (background-image: paint(id)) {
  h1 {
    background-image: paint(hollowHighlights, filled, 3px);
  }
}
```

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

| Specification |
| --- |
| HTML Standard # dom-worklet-addmodule-dev |

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

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


InputEvent: inputType property - Web APIs

InputEvent: inputType property
==============================

Baseline 2023
-------------

Newly availableSince March 2023, 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 **`inputType`** read-only property of the
 `InputEvent` interface returns the type of change made to editable content.
 Possible changes include for example inserting, deleting, and formatting text.

Value
-----

 A string containing the type of input that was made. There are many
 possible values, such as `insertText`, `deleteContentBackward`,
 `insertFromPaste`, and `formatBold`. For a complete list of the
 available input types, see the Attributes section of the Input Events Level 2 spec.

Examples
--------

 This example logs the `inputType` for input events on an editable
 `<div>`.

### HTML

```html
<p id="log">Input type:</p>
<div
 contenteditable="true"
 style="margin: 20px;padding: 20px;border:2px dashed red;">
  <p>
    Some sample text. Try inserting line breaks, or deleting text in different
    ways, or pasting different content in.
  </p>
  <hr />
  <ul>
    <li>A sample</li>
    <li>bulleted</li>
    <li>list.</li>
  </ul>
  <p>Another paragraph.</p>
</div>
```

### JavaScript

```js
const log = document.getElementById("log");
const editable = document.querySelector("div[contenteditable]");
editable.addEventListener("input", logInputType);

function logInputType(event) {
  log.textContent = `Input type: ${event.inputType}`;
}
```

### Result

Try editing the text inside the `<div>` and see what happens.

**Note:** See also Masayuki Nakano's InputEvent test suite for a more detailed example.

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

| Specification |
| --- |
| UI Events # dom-inputevent-inputtype |

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

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


InputEvent: isComposing property - Web APIs

InputEvent: isComposing property
================================

Baseline 2023
-------------

Newly availableSince March 2023, 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 **`InputEvent.isComposing`** read-only property returns a
 boolean value indicating if the event is fired after
 `compositionstart` and before `compositionend`.

Value
-----

A boolean.

Examples
--------

```js
const inputEvent = new InputEvent("syntheticInput", false);
console.log(inputEvent.isComposing); // return false
```

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

| Specification |
| --- |
| UI Events # dom-inputevent-iscomposing |

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

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

See also
--------

* `compositionstart` and `compositionend`
* `InputEvent`


InputEvent: data property - Web APIs

InputEvent: data property
=========================

Baseline 2023
-------------

Newly availableSince March 2023, 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 **`data`** read-only property of the
 `InputEvent` interface returns a string with inserted
 characters. This may be an empty string if the change doesn't insert text, such as when
 characters are deleted.

Value
-----

A string.

Examples
--------

 In the following example, an event listener receives the input event. Any textual change
 to the `<input>` element is retrieved by `InputEvent.data` and
 inserted into a paragraph using the
 `Node.textContent`
 property.

```html
<p>Some text to copy and paste.</p>

<input type="text" />

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

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

editable.addEventListener("input", (e) => {
  result.textContent = `Inputted text: ${e.data}`;
});
```

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

| Specification |
| --- |
| Input Events Level 2 # dfn-data |

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

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