Type

VideoTransformOptions

Options for transforming video frames before encoding.

type VideoTransformOptions = {
	width?: number;
	height?: number;
	fit?: 'fill' | 'contain' | 'cover';
	rotate?: Rotation;
	crop?: CropRectangle;
	frameRate?: number;
	process?: (sample: VideoSample) => MaybePromise<
		CanvasImageSource | VideoSample | (CanvasImageSource | VideoSample)[] | null
	>;
	force?: boolean;
};

See Rotation, CropRectangle, VideoSample, and MaybePromise.

Used by

• VideoEncodingConfig.transform

Properties

width

width?: number;

The width in pixels to resize the frames to. If height is not set, it will be deduced automatically based on aspect ratio.

height

height?: number;

The height in pixels to resize the frames to. If width is not set, it will be deduced automatically based on aspect ratio.

fit

fit?: 'fill' | 'contain' | 'cover';

The fitting algorithm in case both width and height are set.

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

To avoid ambiguity, this field must not be set when sizeChangeBehavior is 'fill', 'contain' or 'deny', since sizeChangeBehavior already determines the fitting algorithm.

rotate

rotate?: Rotation;

The clockwise rotation by which to rotate the frames. Rotation is applied before resizing.

See Rotation.

crop

crop?: CropRectangle;

Specifies the rectangular region of the frames to crop to. The crop region will automatically be clamped to the dimensions of the frame. Cropping is performed after rotation but before resizing.

See CropRectangle.

frameRate

frameRate?: number;

The frame rate in hertz to normalize the video frame stream to.

process

process?: ((sample: VideoSample) => MaybePromise<VideoSample | CanvasImageSource | (VideoSample | CanvasImageSource)[] | null>);

Allows for custom user-defined processing of video frames, e.g. for applying overlays, color transformations, or timestamp modifications. Will be called for each video frame after transformations and frame rate corrections.

Must return a VideoSample or a CanvasImageSource, an array of them, or null for dropping the frame. When non-timestamped data is returned, the timestamp and duration from the input sample will be used.

See VideoSample and MaybePromise.

force

force?: boolean;

Forces every video frame through the transformation step even if no transformation properties are defined. This can be used, for example, to bake rotation into the encoded video frames.