ConversionVideoOptions
Video-specific options.
type ConversionVideoOptions = {
discard?: boolean;
width?: number;
height?: number;
fit?: 'fill' | 'contain' | 'cover';
rotate?: Rotation;
flip?: boolean;
allowTransformationMetadata?: boolean;
allowRotationMetadata?: boolean;
crop?: CropRectangle;
frameRate?: number;
codec?: VideoCodec;
quality?: Quality;
bitrate?: number | Quality;
alpha?: 'discard' | 'keep';
keyFrameInterval?: number;
hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';
forceTranscode?: boolean;
process?: (sample: VideoSample) => MaybePromise<
CanvasImageSource | VideoSample | VideoSampleResource
| (CanvasImageSource | VideoSample | VideoSampleResource)[] | null
>;
processedWidth?: number;
processedHeight?: number;
group?: OutputTrackGroup | OutputTrackGroup[];
maximumPacketCount?: number;
};See Rotation, CropRectangle, VideoCodec, Quality, VideoSample, MaybePromise, VideoSampleResource, and OutputTrackGroup.
Used by
Properties
discard
discard?: boolean;If true, all video tracks will be discarded and will not be present in the output.
width
width?: number;The desired width of the output video in pixels, defaulting to the video's natural display width. If height is not set, it will be deduced automatically based on aspect ratio.
height
height?: number;The desired height of the output video in pixels, defaulting to the video's natural display height. 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, or if the input video changes its size over time.
'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.
rotate
rotate?: Rotation;The angle in degrees to rotate the input video by, clockwise. Rotation is applied before flipping, cropping and resizing. This rotation is in addition to the natural rotation of the input video as specified in input file's metadata.
See Rotation.
flip
flip?: boolean;Whether to flip the input video horizontally (about the vertical axis). The flip is applied after rotation but before cropping and resizing. This flip is in addition to the natural flip of the input video as specified in the input file's metadata.
allowTransformationMetadata
allowTransformationMetadata?: boolean;Defaults to true. When enabled, Mediabunny will use the rotation and flip metadata in the output file to perform video rotation and flipping whenever possible. Set this field to false if you want to ensure the output file does not make use of such metadata and that any rotation and flip is baked into the video frames directly.
allowRotationMetadata
allowRotationMetadata?: boolean;Defaults to true. When enabled, Mediabunny will use the rotation metadata in the output file to perform video rotation whenever possible.
crop
crop?: CropRectangle;Specifies the rectangular region of the input video to crop to. The crop region will automatically be clamped to the dimensions of the input video track. Cropping is performed after rotation and flip but before resizing.
See CropRectangle.
frameRate
frameRate?: number;The desired frame rate of the output video, in hertz. If not specified, the original input frame rate will be used (which may be variable).
codec
codec?: VideoCodec;The desired output video codec.
See VideoCodec.
quality
quality?: Quality;The desired quality of the output video.
See Quality.
bitrate
bitrate?: number | Quality;The desired bitrate of the output video.
See Quality.
alpha
alpha?: 'discard' | 'keep';Whether to discard or keep the transparency information of the input video. The default is 'discard'. Note that for 'keep' to produce a transparent video, you must use an output config that supports it, such as WebM with VP9.
keyFrameInterval
keyFrameInterval?: number;The interval, in seconds, of how often frames are encoded as a key frame. The default is 5 seconds. Frequent key frames improve seeking behavior but increase file size. When using multiple video tracks, you should give them all the same key frame interval.
Setting this fields forces a transcode.
hardwareAcceleration
hardwareAcceleration?: 'no-preference' | 'prefer-hardware' | 'prefer-software';A hint that configures the hardware acceleration method used when transcoding, which applies to both decoding and encoding. This is best left on 'no-preference', the default.
forceTranscode
forceTranscode?: boolean;When true, video will always be re-encoded instead of directly copying over the encoded packets.
process
process?: (sample: VideoSample) => MaybePromise<
CanvasImageSource | VideoSample | VideoSampleResource
| (CanvasImageSource | VideoSample | VideoSampleResource)[] | 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 input video sample after transformations and frame rate corrections.
Must return a VideoSample, a VideoSampleResource 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 source sample will be used. Rotation and flip metadata of the returned sample will be ignored.
This function can also be used to manually resize frames. When doing so, you should signal the post-process dimensions using the processedWidth and processedHeight fields, which enables the encoder to better know what to expect. If these fields aren't set, Mediabunny will assume you won't perform any resizing.
See VideoSample, MaybePromise, and VideoSampleResource.
processedWidth
processedWidth?: number;An optional hint specifying the width of video samples returned by the process function, for better encoder configuration.
processedHeight
processedHeight?: number;An optional hint specifying the height of video samples returned by the process function, for better encoder configuration.
group
group?: OutputTrackGroup | OutputTrackGroup[];Defines the group(s) the output track is a part of. For more, see BaseTrackMetadata.group.
If left blank, tracks will internally be assigned to groups such that the output track pairability graph exactly matches the input track pairability graph.
See OutputTrackGroup.
maximumPacketCount
maximumPacketCount?: number;Sets BaseTrackMetadata.maximumPacketCount for the output track. Only relevant when the output format requires it (see OutputFormat.requiresMaximumPacketCount), in which case it is otherwise estimated automatically. Set this field when the estimate doesn't work for you, for example when process returns more than one frame per input frame. Required for live input tracks when no trim end is set.