Type

ConversionOptions

The options for media file conversion.

type ConversionOptions = {
	input: Input;
	output: Output;
	tracks?: 'all' | 'primary';
	video?: ConversionVideoOptions
		| ConversionVideoOptions[]
		| ((track: InputVideoTrack, n: number) => MaybePromise<
			ConversionVideoOptions | ConversionVideoOptions[] | undefined
		>);
	audio?: ConversionAudioOptions
		| ConversionAudioOptions[]
		| ((track: InputAudioTrack, n: number) => MaybePromise<
			ConversionAudioOptions | ConversionAudioOptions[] | undefined
		>);
	trim?: {
		start?: number;
		end?: number;
	};
	tags?: MetadataTags | ((inputTags: MetadataTags) => MaybePromise<MetadataTags>);
	showWarnings?: boolean;
	composable?: boolean;
};

See Input, Output, ConversionVideoOptions, InputVideoTrack, MaybePromise, ConversionAudioOptions, InputAudioTrack, and MetadataTags.

Used by

• Conversion.init()

Properties

input

input: Input;

The input file.

See Input.

output

output: Output;

The output file.

See Output.

tracks

tracks?: 'all' | 'primary';

Defines which input tracks are used for conversion. Defaults to 'all' unless the input is an HLS input, in which case it defaults to 'primary'.

• 'all': All input tracks are eligible for conversion.
• 'primary': Only the primary video and audio track from the input are eligible for conversion.

video

video?: ConversionVideoOptions
	| ConversionVideoOptions[]
	| ((track: InputVideoTrack, n: number) => MaybePromise<
		ConversionVideoOptions | ConversionVideoOptions[] | undefined
	>);

Video-specific options. When passing an object, the same options are applied to all video tracks. When passing a function, it will be invoked for each video track and is expected to return or resolve to the options for that specific track. The function is passed an instance of InputVideoTrack as well as a number n, which is the 1-based index of the track in the list of all video tracks. Using n is deprecated, prefer the identical track.number instead.

When passing an array of a function that returns an array, one output track per array element will be created, allowing for "fan-out". Useful for creating multiple variants from a single track, for example with different resolutions.

See ConversionVideoOptions, InputVideoTrack, and MaybePromise.

audio

audio?: ConversionAudioOptions
	| ConversionAudioOptions[]
	| ((track: InputAudioTrack, n: number) => MaybePromise<
		ConversionAudioOptions | ConversionAudioOptions[] | undefined
	>);

Audio-specific options. When passing an object, the same options are applied to all audio tracks. When passing a function, it will be invoked for each audio track and is expected to return or resolve to the options for that specific track. The function is passed an instance of InputAudioTrack as well as a number n, which is the 1-based index of the track in the list of all audio tracks. Using n is deprecated, prefer the identical track.number instead.

When passing an array of a function that returns an array, one output track per array element will be created, allowing for "fan-out". Useful for creating multiple variants from a single track, for example with different bitrates.

See ConversionAudioOptions, InputAudioTrack, and MaybePromise.

trim

trim?: {
	/**
	 * The time in the input file in seconds at which the output file should start. Must be less than `end`.
	 * When omitted, defaults to the earliest start timestamp of the non-discarded tracks, or to 0, whichever
	 * is higher.
	 */
	start?: number;
	/**
	 * The time in the input file in seconds at which the output file should end. Must be greater than `start`.
	 * Defaults to the duration of the input when omitted.
	 */
	end?: number;
};

Options to trim the input file.

tags

tags?: MetadataTags | ((inputTags: MetadataTags) => MaybePromise<MetadataTags>);

An object or a callback that returns or resolves to an object containing the descriptive metadata tags that should be written to the output file. If a function is passed, it will be passed the tags of the input file as its first argument, allowing you to modify, augment or extend them.

If no function is set, the input's metadata tags will be copied to the output.

See MetadataTags and MaybePromise.

showWarnings

showWarnings?: boolean;

Whether to show potential console warnings about discarded tracks after calling Conversion.init(), defaults to true. Set this to false if you're properly handling the discardedTracks and isValid fields already and want to keep the console output clean.

composable

composable?: boolean;

Whether this conversion is composable, defaults to false. A non-composable conversion takes full ownership of the output: it requires a fresh output and controls its entire lifecycle, meaning it starts it, writes its metadata tags, and finalizes it.

A composable conversion only adds tracks to the output and drives their media data; starting and finalizing the output is an outside responsibility. This is useful when only some output tracks should be driven by a conversion, and other are to be driven manually. Additionally, it can be used to have multiple conversions target the same output.