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 VideoFrameConstructors
| Name | Description |
|---|---|
| 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.csCreates 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
dataobject- The pixels: a buffer source of the scripts, a
Bytearray or aReadOnlyMemory<T>of bytes. initVideoFrameBufferInit- The description of the pixels.
Exceptions
TypeErrorException- The description is invalid, or the buffer is too small.
DomException- A
DataCloneErrorwhen the transfer list has a detached buffer or a buffer twice.
See also
VideoFrame(object?, VideoFrameInit?)
VideoFrame.csCreates 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
imageobject?- The image source.
initVideoFrameInit?- The options of the frame.
Exceptions
DomException- An
InvalidStateErrorwhen the image is not usable (e.g. a closed frame, a canvas without pixels), aSecurityErrorwhen it is not origin-clean. TypeErrorException- The timestamp is missing, or the options are invalid.
See also
Properties
| Name | Description |
|---|---|
| CodedHeight | Gets the height of the pixels (before the rotation). |
| CodedRect | Gets the rectangle of the pixels at (0, 0), or null when the frame is closed. |
| CodedWidth | Gets the width of the pixels (before the rotation). |
| ColorSpace | Gets the color space of the pixels. |
| DisplayHeight | Gets the height of the rendered frame (after the rotation). |
| DisplayWidth | Gets the width of the rendered frame (after the rotation). |
| Duration | Gets the presentation duration in microseconds, or null (e.g. a still image). |
| Flip | Gets whether the frame is flipped horizontally when it is rendered, after the rotation. |
| Format | Gets the format of the pixels, or null when the frame is closed. |
| Rotation | Gets the clockwise rotation in degrees applied when the frame is rendered, before the flip. |
| Timestamp | Gets the presentation timestamp in microseconds. |
| VisibleRect | Gets the rectangle of the visible pixels, or null when the frame is closed. |
CodedHeight
VideoFrame.csGets the height of the pixels (before the rotation).
public uint CodedHeight { get; }CodedRect
VideoFrame.csGets the rectangle of the pixels at (0, 0), or null when the frame is closed.
public DomRectReadOnly? CodedRect { get; }CodedWidth
VideoFrame.csGets the width of the pixels (before the rotation).
public uint CodedWidth { get; }ColorSpace
VideoFrame.csGets the color space of the pixels.
public VideoColorSpace ColorSpace { get; }DisplayHeight
VideoFrame.csGets the height of the rendered frame (after the rotation).
public uint DisplayHeight { get; }DisplayWidth
VideoFrame.csGets the width of the rendered frame (after the rotation).
public uint DisplayWidth { get; }Duration
VideoFrame.csGets the presentation duration in microseconds, or null (e.g. a still image).
public ulong? Duration { get; }Flip
VideoFrame.csGets whether the frame is flipped horizontally when it is rendered, after the rotation.
public bool Flip { get; }Format
VideoFrame.csGets the format of the pixels, or null when the frame is closed.
public VideoPixelFormat? Format { get; }Rotation
VideoFrame.csGets the clockwise rotation in degrees applied when the frame is rendered, before the flip.
public double Rotation { get; }Timestamp
VideoFrame.csGets the presentation timestamp in microseconds.
public long Timestamp { get; }VisibleRect
VideoFrame.csGets the rectangle of the visible pixels, or null when the frame is closed.
public DomRectReadOnly? VisibleRect { get; }Methods
| Name | Description |
|---|---|
| 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.csReturns 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
optionsVideoFrameCopyToOptions?
Returns
Exceptions
DomException- An
InvalidStateErrorwhen the frame is closed, aNotSupportedErrorfor a destination format other than RGBA, RGBX, BGRA and BGRX. TypeErrorException- The rectangle or the layout is invalid.
See also
Clone()
VideoFrame.csCreates a frame that references the same pixels (https://w3c.github.io/webcodecs/#dom-videoframe-clone).
public VideoFrame Clone()Close()
VideoFrame.csReleases 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.csCopies 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
destinationSpan<byte>- The buffer: at least
VideoFrame.AllocationSizebytes. optionsVideoFrameCopyToOptions?- 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
InvalidStateErrorwhen the frame is closed, aNotSupportedErrorfor 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.csCopies 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
destinationMemory<byte>optionsVideoFrameCopyToOptions?
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.csReturns a copy of the metadata of the frame (https://w3c.github.io/webcodecs/#dom-videoframe-metadata).
public VideoFrameMetadata Metadata()