VideoDecoder: configure() 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
**Secure context:** This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

The **`configure()`** method of the `VideoDecoder` interface enqueues a control message to configure the video decoder for decoding chunks.

Syntax
------


```js
configure(config)
```

### Parameters

`config`

An object containing the following members:

`codec`

A string containing a valid codec string. See "codecs" parameter for details on codec string construction.

`description` Optional

An `ArrayBuffer`, a `TypedArray`, or a `DataView` containing a sequence of codec specific bytes, commonly known as extradata.

`codedWidth` Optional

An integer representing the width of the `VideoFrame` in pixels, including any non-visible padding, before any ratio adjustments.

`codedHeight` Optional

An integer representing the height of the `VideoFrame` in pixels, including any non-visible padding, before any ratio adjustments.

`displayAspectWidth` Optional

An integer representing the horizontal dimension of the `VideoFrame` in pixels when displayed.

`displayAspectHeight` Optional

An integer representing the vertical dimension of the `VideoFrame` in pixels when displayed.

`colorSpace`

An object representing a `VideoColorSpace`, containing the following members:

`primaries`

A string representing the color gamut of the video sample. One of:

* `"bt709"`
* `"bt470bg"`
* `"smpte170m"`

`transfer`

A string representing transfer characteristics. One of:

* `"bt709"`
* `"smpte170m"`
* `"iec61966-2-1"`

`matrix`

A string representing a matrix coefficient. One of:

* `"rgb"`
* `"bt709"`
* `"bt470bg"`
* `"smpte170m"`


`hardwareAcceleration`

A hint as to the hardware acceleration method to use. One of:

* `"no-preference"`
* `"prefer-hardware"`
* `"prefer-software"`

`optimizeForLatency`

A boolean. If `true` this is a hint that the selected decoder should be optimized to minimize the number of `EncodedVideoChunk` objects that have to be decoded before a `VideoFrame` is output.


**Note:** The registrations in the WebCodecs Codec Registry link to a specification detailing whether and how to populate the optional `description` member.

### Return value

None (`undefined`).

### Exceptions

`TypeError`

Thrown if the provided `config` is invalid.

`InvalidStateError` `DOMException`

Thrown if the `state` is `"closed"`.

`NotSupportedError` `DOMException`

Thrown if the provided `config` is valid but the user agent cannot provide a codec that can decode this profile.

Examples
--------

The following example creates a new `VideoDecoder` and configures it with the `"vp8"` codec, a `codedWidth` of 640 pixels and a `codedHeight` of 480 pixels.


```js
const init = {
  output: handleFrame,
  error: (e) => {
    console.log(e.message);
  },
};

const config = {
  codec: "vp8",
  codedWidth: 640,
  codedHeight: 480,
};

let decoder = new VideoDecoder(init);
decoder.configure(config);
```

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

| Specification |
| --- |
| WebCodecs # dom-videodecoder-configure |

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

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