Note: This feature is available in Dedicated Web Workers.
The VideoFrame() constructor creates a new VideoFrame object representing a frame of a video.
new VideoFrame(image)
new VideoFrame(image, options)
new VideoFrame(data, options)The first type of constructor creates a new VideoFrame from an image. Its parameters are:
imageAn 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 OptionalAn object containing the following:
alpha OptionalA 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.displayHeight OptionalThe height of the VideoFrame when displayed after applying aspect-ratio adjustments.
displayWidth OptionalThe width of the VideoFrame when displayed after applying aspect-ratio adjustments.
duration OptionalAn integer representing the duration of the frame in microseconds.
flip OptionalA boolean. If true, horizontal mirroring is applied. Defaults to false.
metadata OptionalAn object containing metadata describing the video frame, specified by the WebCodecs VideoFrame Metadata Registry, which can contain the following properties:
rtpTimestamp OptionalThe RTP timestamp of the corresponding encoded frame. Only video frames originating from WebRTC sources should have rtpTimestamp metadata set.
Note: A video frame's metadata can be returned using the VideoFrame.metadata() method.
rotation OptionalAn integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to 0. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
timestampAn integer representing the timestamp of the frame in microseconds.
visibleRect OptionalAn object representing the visible rectangle of the VideoFrame, containing the following:
The second type of constructor creates a new VideoFrame from an ArrayBuffer. Its parameters are:
dataAn ArrayBuffer, a TypedArray, or a DataView containing the data for the new VideoFrame.
optionsAn object containing the following:
codedHeightHeight of the VideoFrame in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
codedWidthWidth of the VideoFrame in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
colorSpaceAn object representing the color space of the VideoFrame, containing the following:
primariesA string representing the video color primaries, described on the page for the VideoColorSpace.primaries property.
transferA string representing the video color transfer function, described on the page for the VideoColorSpace.transfer property.
matrixA string representing the video color matrix, described on the page for the VideoColorSpace.matrix property.
fullRangeA Boolean. If true, indicates that full-range color values are used.
displayHeight OptionalThe height of the VideoFrame when displayed after applying aspect ratio adjustments.
displayWidth OptionalThe width of the VideoFrame when displayed after applying aspect ratio adjustments.
duration OptionalAn integer representing the duration of the frame in microseconds.
flip OptionalA boolean. If true, horizontal mirroring is applied. Defaults to false.
formatA 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"layout OptionalA list containing the following values for each plane in the VideoFrame:
metadata OptionalAn object containing metadata describing the video frame, specified by the WebCodecs VideoFrame Metadata Registry, which can contain the following properties:
rtpTimestamp OptionalThe RTP timestamp of the corresponding encoded frame.
rotation OptionalAn integer representing the rotation (0, 90, 180, or 270) in degrees clockwise. Defaults to 0. Arbitrary numbers (including negatives) are rounded to the next quarter turn.
timestampAn integer representing the timestamp of the frame in microseconds.
transferAn array of ArrayBuffers 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.
visibleRect OptionalAn object representing the visible rectangle of the VideoFrame, containing the following:
The following examples are from the article Video processing with WebCodecs. In this first example, a VideoFrame is created from a canvas.
const cnv = document.createElement("canvas");
// draw something on the canvas
// …
const frameFromCanvas = new VideoFrame(cnv, { timestamp: 0 });In the following example a VideoFrame is created from a TypedArray.
const pixelSize = 4;
const init = {
timestamp: 0,
codedWidth: 320,
codedHeight: 200,
format: "RGBA",
};
const data = new Uint8Array(init.codedWidth * init.codedHeight * pixelSize);
for (let x = 0; x < init.codedWidth; x++) {
for (let y = 0; y < init.codedHeight; y++) {
const 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];
const frame = new VideoFrame(data, init);