VideoFrame
==========

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
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.


```js
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
---------------------

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

See also
--------

* Video processing with WebCodecs
* WebCodecs examples