Mediabunny

Appearance

Class

VideoSample ​

Represents a raw, unencoded video sample (frame). Mainly used as an expressive wrapper around WebCodecs API's VideoFrame, but can also be used standalone.

Implements: Disposable

Used by ​

Constructors ​

ts
constructor(
	data: VideoFrame,
	init?: VideoSampleInit,
): VideoSample;

Creates a new VideoSample from a VideoFrame. This is essentially a near zero-cost wrapper around VideoFrame. The sample's metadata is optionally refined using the data specified in init.

See VideoSampleInit.

ts
constructor(
	data: CanvasImageSource,
	init: SetRequired<VideoSampleInit, 'timestamp'>,
): VideoSample;

Creates a new VideoSample from a CanvasImageSource, similar to the VideoFrame constructor. When VideoFrame is available, this is simply a wrapper around its constructor. If not, it will copy the source's image data to an internal canvas for later use.

See SetRequired and VideoSampleInit.

ts
constructor(
	data: AllowSharedBufferSource,
	init: SetRequired<VideoSampleInit, 'format' | 'codedWidth' | 'codedHeight' | 'timestamp'>,
): VideoSample;

Creates a new VideoSample from raw pixel data specified in data. Additional metadata must be provided in init.

See SetRequired and VideoSampleInit.

ts
constructor(
	resource: VideoSampleResource,
	init: SetRequired<VideoSampleInit, 'timestamp'>,
): VideoSample;

Creates a new VideoSample backed by a custom VideoSampleResource.

See SetRequired and VideoSampleInit.

Properties ​

codedHeight ​

ts
get codedHeight(): number;

The height of the frame in pixels.

codedWidth ​

ts
get codedWidth(): number;

The width of the frame in pixels.

colorSpace ​

ts
readonly colorSpace: VideoSampleColorSpace;

The color space of the frame.

See VideoSampleColorSpace.

displayHeight ​

ts
get displayHeight(): number;

The display height of the frame in pixels, after aspect ratio adjustment, rotation and flip.

displayWidth ​

ts
get displayWidth(): number;

The display width of the frame in pixels, after aspect ratio adjustment, rotation and flip.

duration ​

ts
readonly duration: number;

The duration of the frame in seconds.

encodeOptions ​

ts
readonly encodeOptions: DeepReadonly<VideoEncoderEncodeOptions>;

The encode options to use when this sample is passed to an encoder.

See DeepReadonly.

flip ​

ts
readonly flip: boolean;

Whether the frame is flipped horizontally (about the vertical axis), after rotation.

format ​

ts
readonly format: VideoSamplePixelFormat | null;

The internal pixel format in which the frame is stored. Will be null if it's using an arbitrary internal format not representable by VideoSamplePixelFormat. See pixel formats

See VideoSamplePixelFormat.

hasAlpha ​

ts
get hasAlpha(): boolean | null;

Whether this sample uses a pixel format that can hold transparency data. Note that this doesn't necessarily mean that the sample is transparent.

microsecondDuration ​

ts
get microsecondDuration(): number;

The duration of the frame in microseconds.

microsecondTimestamp ​

ts
get microsecondTimestamp(): number;

The presentation timestamp of the frame in microseconds.

pixelAspectRatio ​

ts
readonly pixelAspectRatio: Rational;

The pixel aspect ratio of the frame, as a rational number in its reduced form. Most videos use square pixels (1:1).

See Rational.

rotation ​

ts
readonly rotation: Rotation;

The rotation of the frame in degrees, clockwise. Rotation is applied before flipping.

See Rotation.

squarePixelHeight ​

ts
readonly squarePixelHeight: number;

The height of the frame in square pixels (respecting pixel aspect ratio), before rotation and flip are applied.

squarePixelWidth ​

ts
readonly squarePixelWidth: number;

The width of the frame in square pixels (respecting pixel aspect ratio), before rotation and flip are applied.

timestamp ​

ts
readonly timestamp: number;

The presentation timestamp of the frame in seconds. May be negative. Frames with negative end timestamps should not be presented.

visibleRect ​

ts
readonly visibleRect: Rectangle;

The visible region of the frame in the coded pixel grid.

See Rectangle.

Methods ​

allocationSize() ​

ts
allocationSize(
	options: VideoFrameCopyToOptions = {},
): number;

Returns the number of bytes required to hold this video sample's pixel data.

clone() ​

ts
clone(): VideoSample;

Clones this video sample.

close() ​

ts
close(): void;

Closes this video sample, releasing held resources. Video samples should be closed as soon as they are not needed anymore.

copyTo() ​

ts
copyTo(
	destination: AllowSharedBufferSource,
	options: VideoFrameCopyToOptions = {},
): Promise<PlaneLayout[]>;

Copies this video sample's pixel data to an ArrayBuffer or ArrayBufferView.

Returns: The byte layout of the planes of the copied data.

draw() ​

ts
draw(
	context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
	dx: number,
	dy: number,
	dWidth?: number,
	dHeight?: number,
): void;

Draws the video sample to a 2D canvas context. Rotation and flip metadata will be taken into account.

Parameters:

  • dx: The x-coordinate in the destination canvas at which to place the top-left corner of the source image.
  • dy: The y-coordinate in the destination canvas at which to place the top-left corner of the source image.
  • dWidth: The width in pixels with which to draw the image in the destination canvas.
  • dHeight: The height in pixels with which to draw the image in the destination canvas.

draw() ​

ts
draw(
	context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
	sx: number,
	sy: number,
	sWidth: number,
	sHeight: number,
	dx: number,
	dy: number,
	dWidth?: number,
	dHeight?: number,
): void;

Draws the video sample to a 2D canvas context. Rotation and flip metadata will be taken into account.

Parameters:

  • sx: The x-coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
  • sy: The y-coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
  • sWidth: The width of the sub-rectangle of the source image to draw into the destination context.
  • sHeight: The height of the sub-rectangle of the source image to draw into the destination context.
  • dx: The x-coordinate in the destination canvas at which to place the top-left corner of the source image.
  • dy: The y-coordinate in the destination canvas at which to place the top-left corner of the source image.
  • dWidth: The width in pixels with which to draw the image in the destination canvas.
  • dHeight: The height in pixels with which to draw the image in the destination canvas.

drawWithFit() ​

ts
drawWithFit(
	context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D,
	options: {
		/**
		 * Controls the fitting algorithm.
		 *
		 * - `'fill'` will stretch the image to fill the entire box, potentially altering aspect ratio.
		 * - `'contain'` will contain the entire image within the box while preserving aspect ratio. This may lead to
		 * letterboxing.
		 * - `'cover'` will scale the image until the entire box is filled, while preserving aspect ratio.
		 */
		fit: 'fill' | 'contain' | 'cover';
		/** A way to override rotation. Defaults to the rotation of the sample. Rotation is applied before flipping. */
		rotation?: Rotation;
		/**
		 * A way to override the horizontal flip. Defaults to the flip of the sample. The flip is applied
		 * after rotation.
		 */
		flip?: boolean;
		/**
		 * Specifies the rectangular region of the video sample to crop to. The crop region will automatically be
		 * clamped to the dimensions of the video sample. Cropping is performed after rotation and flip but before
		 * resizing. The crop region is in the _display pixel space_ of the underlying video data.
		 */
		crop?: CropRectangle;
	},
): void;

Draws the sample in the middle of the canvas corresponding to the context with the specified fit behavior.

See Rotation and CropRectangle.

setDuration() ​

ts
setDuration(
	newDuration: number,
): void;

Sets the duration of this video sample, in seconds.

setEncodeOptions() ​

ts
setEncodeOptions(
	newEncodeOptions: VideoEncoderEncodeOptions,
): void;

Sets the encode options used when this sample is passed to an encoder.

setFlip() ​

ts
setFlip(
	newFlip: boolean,
): void;

Sets the flip metadata of this video sample.

setRotation() ​

ts
setRotation(
	newRotation: Rotation,
): void;

Sets the rotation metadata of this video sample.

See Rotation.

setTimestamp() ​

ts
setTimestamp(
	newTimestamp: number,
): void;

Sets the presentation timestamp of this video sample, in seconds.

toCanvasImageSource() ​

ts
toCanvasImageSource(): VideoFrame | OffscreenCanvas;

Converts this video sample to a CanvasImageSource for drawing to a canvas.

You must use the value returned by this method immediately, as any VideoFrame created internally may automatically be closed in the next microtask.

toVideoFrame() ​

ts
toVideoFrame(): VideoFrame;

Converts this video sample to a VideoFrame for use with the WebCodecs API. The VideoFrame returned by this method must be closed separately from this video sample.

transform() ​

ts
transform(
	options: VideoSampleTransformOptions,
): Promise<VideoSample>;

Transform this video sample to a new video sample given the options. Can be used to resize, rotate, flip, and crop the sample.

In non-browser environments, this method will not work by default. To make it work, register a custom transformer function via registerVideoSampleTransformer.

See VideoSampleTransformOptions.

[Symbol.dispose]() ​

ts
[Symbol.dispose](): void;

Calls .close().

Released under the Mozilla Public License 2.0.

Copyright © 2026-present Vanilagy