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
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 totrue
. Whenfalse
indicates that for progressive images the decoder may output an image with reduced detail. Whenfalse
, the promise returned bydecode()
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
, iftrue
indicates thatimage
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, meaningclose()
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.
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:
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