Class

Conversion

Represents a media file conversion process, used to convert one media file into another. In addition to conversion, this class can be used to resize and rotate video, resample audio, drop tracks, or trim to a specific time range.

Static methods

init()

static init(
	options: ConversionOptions,
): Promise<Conversion>;

Initializes a new conversion process without starting the conversion.

See ConversionOptions.

Properties

discardedTracks

readonly discardedTracks: DiscardedTrack[];

The list of tracks from the input file that have been discarded, alongside the discard reason.

See DiscardedTrack.

input

readonly input: Input;

The input file.

See Input.

isValid

isValid: boolean;

Whether this conversion, as it has been configured, is valid and can be executed. If this field is false, check the discardedTracks field for reasons. Composable conversions are always valid, even if they utilize zero tracks.

Note: a conversion having discarded tracks does not automatically mean it is invalid; if the remaining, utilized tracks make for a valid output file, the conversion is still allowed.

output

readonly output: Output;

The output file.

See Output.

state

state: 'idle' | 'executing' | 'canceled' | 'done';

The current state of the conversion.

• 'idle': The conversion is not currently executing and isn't done; execute can be called.
• 'executing': A call to execute is currently running.
• 'canceled': The conversion has been canceled and can no longer be executed.
• 'done': The conversion has run to completion. Subsequent calls to execute do nothing.

utilizedTracks

readonly utilizedTracks: InputTrack[];

The list of tracks that are included in the output file. When fan-out is used, the same track appears in this array multiple times.

See InputTrack.

Events

onProgress

onProgress?: (progress: number, processedTime: number) => unknown;

A callback that is fired whenever the conversion progresses. Gets passed as first argument a number between 0 and 1, indicating the completion of the conversion. Note that a progress of 1 doesn't necessarily mean the conversion is complete; the conversion is complete once execute() resolves.

As second argument, this callback receives the input time in seconds that has been processed.

In order for progress to be computed, this property must be set before execute is called.

Methods

cancel()

cancel(): Promise<void>;

Cancels the conversion process, causing any ongoing execute call to throw a ConversionCanceledError. Does nothing if the conversion is already complete.

execute()

execute(
	options: ConversionExecuteOptions = {},
): Promise<void>;

Executes the conversion process and resolves when the conversion is complete. When ConversionExecuteOptions.until is provided, the conversion will be suspended once that output timestamp is reached and can be resumed with another call to execute. An ongoing execution may also be suspended via ConversionExecuteOptions.pauseSignal.

Execution will throw if isValid is false.