ImageDecoder: decode() method

Limited availability

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

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

Note: This feature is available in Dedicated Web Workers.

The decode() method of the ImageDecoder interface enqueues a control message to decode the frame of an image.

Syntax

js
decode()
decode(options)

Parameters

options Optional

An object containing the following members:

frameIndex Optional

An integer representing the index of the frame to decode. Defaults to 0 (the first frame).

completeFramesOnly Optional

A boolean defaulting to true. When false indicates that for progressive images the decoder may output an image with reduced detail. When false, the promise returned by decode() will resolve exactly once for each new level of detail.

Return value

A promise that resolves with an object containing the following members:

image

A VideoFrame containing the decoded image.

complete

A boolean, if true indicates that image contains the final full-detail output.

Exceptions

If an error occurs, the promise will resolve with following exception:

InvalidStateError DOMException

Returned if any of the following conditions apply:

  • close is true, meaning close() has already been called.
  • The requested frame does not exist.

Examples

Synchronous decoding of a completed image frame

The following example decodes the second frame (at index 1) and prints the resulting VideoFrame to the console.

js
let result = await imageDecoder.decode({ frameIndex: 1 });
console.log(result.image);

Partial decoding of a progressive image frame

The following example decodes the first frame repeatedly until its complete:

js
let complete = false;
while (!complete) {
  // The promise returned by `decode()` will only resolve when a new
  // level of detail is available or the frame is complete. I.e.,
  // calling `decode()` in a loop like this is won't needlessly spin.
  let result = await imageDecode.decode({ completeFramesOnly: false });

  // Do something with `result.image`.

  complete = result.complete;
}

Specifications

Specification
WebCodecs
# dom-imagedecoder-decode

Browser compatibility

BCD tables only load in the browser