VideoFrame

Limited availability

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

Note: This feature is available in Dedicated Web Workers.

The VideoFrame interface of the Web Codecs API represents a frame of a video.

VideoFrame is a transferable object.

Description

A VideoFrame object can be created or accessed in a number of ways. The MediaStreamTrackProcessor breaks a media track into individual VideoFrame objects.

A VideoFrame is an image source and has a constructor that accepts any other canvas source ( an SVGImageElement, an HTMLVideoElement, an HTMLCanvasElement, an ImageBitmap, an OffscreenCanvas, or another VideoFrame). This means that a frame can be created from an image or video element.

A second constructor enables the creation of a VideoFrame from its binary pixel representation in an ArrayBuffer, a TypedArray, or a DataView.

Created frames may then turned into a media track, for example with the MediaStreamTrackGenerator interface that creates a media track from a stream of frames.

Constructor

VideoFrame(): Creates a new VideoFrame object.

Instance properties

VideoFrame.format Read only: Returns the pixel format of the VideoFrame.
VideoFrame.codedWidth Read only: Returns the width of the VideoFrame in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
VideoFrame.codedHeight Read only: Returns the height of the VideoFrame in pixels, potentially including non-visible padding, and prior to considering potential ratio adjustments.
VideoFrame.codedRect Read only: Returns a DOMRectReadOnly with the width and height matching codedWidth and codedHeight.
VideoFrame.visibleRect Read only: Returns a DOMRectReadOnly describing the visible rectangle of pixels for this VideoFrame.
VideoFrame.displayWidth Read only: Returns the width of the VideoFrame when displayed after applying aspect ratio adjustments.
VideoFrame.displayHeight Read only: Returns the height of the VideoFrame when displayed after applying aspect ratio adjustments.
VideoFrame.duration Read only: Returns an integer indicating the duration of the video in microseconds.
VideoFrame.timestamp Read only: Returns an integer indicating the timestamp of the video in microseconds.
VideoFrame.colorSpace Read only: Returns a VideoColorSpace object.

Instance methods

VideoFrame.allocationSize(): Returns the number of bytes required to hold the VideoFrame as filtered by options passed into the method.
VideoFrame.copyTo(): Copies the contents of the VideoFrame to an ArrayBuffer.
VideoFrame.clone(): Creates a new VideoFrame object with reference to the same media resource as the original.
VideoFrame.close(): Clears all states and releases the reference to the media resource.

Examples

In the following example frames are returned from a MediaStreamTrackProcessor, then encoded. See the full example and read more about it in the article Video processing with WebCodecs.

let frame_counter = 0;

const track = stream.getVideoTracks()[0];
const media_processor = new MediaStreamTrackProcessor(track);

const reader = media_processor.readable.getReader();
while (true) {
  const result = await reader.read();
  if (result.done) break;

  let frame = result.value;
  if (encoder.encodeQueueSize > 2) {
    // Too many frames in flight, encoder is overwhelmed
    // let's drop this frame.
    frame.close();
  } else {
    frame_counter++;
    const insert_keyframe = frame_counter % 150 === 0;
    encoder.encode(frame, { keyFrame: insert_keyframe });
    frame.close();
  }
}

Specifications

Specification
WebCodecs # videoframe-interface

Browser compatibility

desktop mobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
VideoFrame
VideoFrame() constructor
allocationSize
clone
close
codedHeight
codedRect
codedWidth
colorSpace
copyTo
displayHeight
displayWidth
duration
format
timestamp
visibleRect

	desktop					mobile
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on iOS	Samsung Internet	WebView Android	WebView on iOS
`VideoFrame`
`VideoFrame()` constructor
`allocationSize`
`clone`
`close`
`codedHeight`
`codedRect`
`codedWidth`
`colorSpace`
`copyTo`
`displayHeight`
`displayWidth`
`duration`
`format`
`timestamp`
`visibleRect`