VideoFrame Class

A frame of video or a decoded image (https://w3c.github.io/webcodecs/#videoframe): its pixels in one of the formats of VideoPixelFormat, the visible rectangle, the display size, the orientation, the timestamp and the color space. A frame is created from an image (a canvas, an image element, an ImageBitmap, a video element...), from a buffer of pixels, from another frame, by an ImageDecoder or by a VideoDecoder. A frame can be drawn on a canvas, used by createImageBitmap(), encoded by a VideoEncoder, posted to a worker (serialized or transferred) and copied to a buffer in its format or converted to RGB.

public sealed class VideoFrame

Constructors

NameDescription
VideoFrame(object, VideoFrameBufferInit)Creates a frame from a buffer of pixels (https://w3c.github.io/webcodecs/#dom-videoframe-videoframe-data-init): the planes of the format are read from the buffer at the offsets and strides of the layout (tightly packed by default), and copied.
VideoFrame(object?, VideoFrameInit?)Creates a frame from an image or another frame (https://w3c.github.io/webcodecs/#dom-videoframe-videoframe): a copy of the bitmap of an img, SVG image or canvas element, an ImageBitmap or an OffscreenCanvas (whose timestamp is required); the frame at the current playback position of a video element; or the pixels of another VideoFrame (shared, with a new visible rectangle, orientation or display size).

VideoFrame overloads

VideoFrame(object, VideoFrameBufferInit)

VideoFrame.cs

Creates a frame from a buffer of pixels (https://w3c.github.io/webcodecs/#dom-videoframe-videoframe-data-init): the planes of the format are read from the buffer at the offsets and strides of the layout (tightly packed by default), and copied.

public VideoFrame(object data, VideoFrameBufferInit init)
Parameters
data object
The pixels: a buffer source of the scripts, a Byte array or a ReadOnlyMemory<T> of bytes.
init VideoFrameBufferInit
The description of the pixels.
Exceptions
TypeErrorException
The description is invalid, or the buffer is too small.
DomException
A DataCloneError when the transfer list has a detached buffer or a buffer twice.
See also

VideoFrame(object?, VideoFrameInit?)

VideoFrame.cs

Creates a frame from an image or another frame (https://w3c.github.io/webcodecs/#dom-videoframe-videoframe): a copy of the bitmap of an img, SVG image or canvas element, an ImageBitmap or an OffscreenCanvas (whose timestamp is required); the frame at the current playback position of a video element; or the pixels of another VideoFrame (shared, with a new visible rectangle, orientation or display size).

public VideoFrame(object? image, VideoFrameInit? init = null)
Parameters
image object?
The image source.
init VideoFrameInit?
The options of the frame.
Exceptions
DomException
An InvalidStateError when the image is not usable (e.g. a closed frame, a canvas without pixels), a SecurityError when it is not origin-clean.
TypeErrorException
The timestamp is missing, or the options are invalid.
See also

Properties

NameDescription
CodedHeightGets the height of the pixels (before the rotation).
CodedRectGets the rectangle of the pixels at (0, 0), or null when the frame is closed.
CodedWidthGets the width of the pixels (before the rotation).
ColorSpaceGets the color space of the pixels.
DisplayHeightGets the height of the rendered frame (after the rotation).
DisplayWidthGets the width of the rendered frame (after the rotation).
DurationGets the presentation duration in microseconds, or null (e.g. a still image).
FlipGets whether the frame is flipped horizontally when it is rendered, after the rotation.
FormatGets the format of the pixels, or null when the frame is closed.
RotationGets the clockwise rotation in degrees applied when the frame is rendered, before the flip.
TimestampGets the presentation timestamp in microseconds.
VisibleRectGets the rectangle of the visible pixels, or null when the frame is closed.

CodedHeight

VideoFrame.cs

Gets the height of the pixels (before the rotation).

public uint CodedHeight { get; }

CodedRect

VideoFrame.cs

Gets the rectangle of the pixels at (0, 0), or null when the frame is closed.

public DomRectReadOnly? CodedRect { get; }

CodedWidth

VideoFrame.cs

Gets the width of the pixels (before the rotation).

public uint CodedWidth { get; }

ColorSpace

VideoFrame.cs

Gets the color space of the pixels.

public VideoColorSpace ColorSpace { get; }

DisplayHeight

VideoFrame.cs

Gets the height of the rendered frame (after the rotation).

public uint DisplayHeight { get; }

DisplayWidth

VideoFrame.cs

Gets the width of the rendered frame (after the rotation).

public uint DisplayWidth { get; }

Gets the presentation duration in microseconds, or null (e.g. a still image).

public ulong? Duration { get; }

Gets whether the frame is flipped horizontally when it is rendered, after the rotation.

public bool Flip { get; }

Gets the format of the pixels, or null when the frame is closed.

public VideoPixelFormat? Format { get; }

Gets the clockwise rotation in degrees applied when the frame is rendered, before the flip.

public double Rotation { get; }

Timestamp

VideoFrame.cs

Gets the presentation timestamp in microseconds.

public long Timestamp { get; }

VisibleRect

VideoFrame.cs

Gets the rectangle of the visible pixels, or null when the frame is closed.

public DomRectReadOnly? VisibleRect { get; }

Methods

NameDescription
AllocationSize(VideoFrameCopyToOptions?)Returns the number of bytes VideoFrame.CopyTo writes with the options (https://w3c.github.io/webcodecs/#dom-videoframe-allocationsize).
Clone()Creates a frame that references the same pixels (https://w3c.github.io/webcodecs/#dom-videoframe-clone).
Close()Releases the reference to the pixels (https://w3c.github.io/webcodecs/#close-videoframe): the frame cannot be used anymore.
CopyPixelsTo(Span<byte>, VideoFrameCopyToOptions?)Copies the pixels of the frame into a buffer at once (the synchronous form of VideoFrame.CopyTo, e.g. for the encoders of a MediaCodecBackend): the planes of its format, or the pixels converted to an RGB format and to a color space when the options give a format.
CopyTo(Memory<byte>, VideoFrameCopyToOptions?)Copies the pixels of the frame into a buffer (https://w3c.github.io/webcodecs/#dom-videoframe-copyto): the planes of its format, or the pixels converted to an RGB format and to a color space when the options give a format.
Metadata()Returns a copy of the metadata of the frame (https://w3c.github.io/webcodecs/#dom-videoframe-metadata).

AllocationSize(VideoFrameCopyToOptions?)

VideoFrame.cs

Returns the number of bytes VideoFrame.CopyTo writes with the options (https://w3c.github.io/webcodecs/#dom-videoframe-allocationsize).

public uint AllocationSize(VideoFrameCopyToOptions? options = null)

Parameters

options VideoFrameCopyToOptions?

Returns

uint

Exceptions

DomException
An InvalidStateError when the frame is closed, a NotSupportedError for a destination format other than RGBA, RGBX, BGRA and BGRX.
TypeErrorException
The rectangle or the layout is invalid.

See also

Creates a frame that references the same pixels (https://w3c.github.io/webcodecs/#dom-videoframe-clone).

public VideoFrame Clone()

Returns

VideoFrame

Exceptions

DomException
An InvalidStateError when the frame is closed.

See also

Releases the reference to the pixels (https://w3c.github.io/webcodecs/#close-videoframe): the frame cannot be used anymore.

public void Close()

CopyPixelsTo(Span<byte>, VideoFrameCopyToOptions?)

VideoFrame.cs

Copies the pixels of the frame into a buffer at once (the synchronous form of VideoFrame.CopyTo, e.g. for the encoders of a MediaCodecBackend): the planes of its format, or the pixels converted to an RGB format and to a color space when the options give a format.

public IReadOnlyList<PlaneLayout> CopyPixelsTo(Span<byte> destination, VideoFrameCopyToOptions? options = null)

Parameters

destination Span<byte>
The buffer: at least VideoFrame.AllocationSize bytes.
options VideoFrameCopyToOptions?
The rectangle, the layout, the format and the color space of the copy.

Returns

IReadOnlyList<PlaneLayout> The layout of the planes in the buffer.

Exceptions

DomException
An InvalidStateError when the frame is closed, a NotSupportedError for a destination format other than RGBA, RGBX, BGRA and BGRX.
TypeErrorException
The rectangle or the layout is invalid, or the buffer is too small.

CopyTo(Memory<byte>, VideoFrameCopyToOptions?)

VideoFrame.cs

Copies the pixels of the frame into a buffer (https://w3c.github.io/webcodecs/#dom-videoframe-copyto): the planes of its format, or the pixels converted to an RGB format and to a color space when the options give a format.

public Task<IReadOnlyList<PlaneLayout>> CopyTo(Memory<byte> destination, VideoFrameCopyToOptions? options = null)

Parameters

destination Memory<byte>
options VideoFrameCopyToOptions?

Returns

Task<IReadOnlyList<PlaneLayout>> A task that completes with the layout of the planes in the buffer (in a task of the event loop).

See also

Metadata()

VideoFrame.cs

Returns a copy of the metadata of the frame (https://w3c.github.io/webcodecs/#dom-videoframe-metadata).

public VideoFrameMetadata Metadata()

Returns

VideoFrameMetadata

Exceptions

DomException
An InvalidStateError when the frame is closed.

See also