Conversion

Convert media files with transcoding, resizing, and transformation options

The Conversion class provides a high-level API for converting one media file into another. It supports transcoding, resizing, rotating, trimming, and processing video and audio tracks.

Static methods

Conversion.init()

static async init(options: ConversionOptions): Promise<Conversion>

Initializes a new conversion process without starting the conversion. This method analyzes the input file, determines which tracks can be converted, and prepares the output configuration.

options · ConversionOptions · required

Configuration for the conversion

Show ConversionOptions properties

input · Input · required

The input file.

output · Output · required

The output file.

video · ConversionVideoOptions | Function

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 the options for that specific track.

audio · ConversionAudioOptions | Function

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 the options for that specific track.

trim · object

Options to trim the input file

Show Trim options

start · number

The time in the input file in seconds at which the output file should start. When omitted, defaults to the start timestamp of the input or to 0, whichever is higher.

end · number

The time in the input file in seconds at which the output file should end. Defaults to the duration of the input when omitted.

tags · MetadataTags | Function

An object or a callback that returns 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. If not set, the input’s metadata tags will be copied to the output.

showWarnings · boolean · default: "true"

Whether to show potential console warnings about discarded tracks after calling Conversion.init().

Properties

input · Input

The input file.

output · Output

The output file.

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.

utilizedTracks · InputTrack[]

The list of tracks that are included in the output file.

discardedTracks · DiscardedTrack[]

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

Show DiscardedTrack properties

track · InputTrack

The track that was discarded.

reason · string

The reason for discarding the track:

• 'discarded_by_user': You discarded this track by setting discard: true.
• 'max_track_count_reached': The output had no more room for another track.
• 'max_track_count_of_type_reached': The output had no more room for another track of this type.
• 'unknown_source_codec': We don’t know the codec of the input track.
• 'undecodable_source_codec': The input track’s codec cannot be decoded.
• 'no_encodable_target_codec': We can’t find a codec that we can encode and that can be contained within the output format.

onProgress · (progress: number) => unknown

A callback that is fired whenever the conversion progresses. Returns a number between 0 and 1, indicating the completion of the conversion. Must be set before execute() is called for progress to be computed.

Methods

execute()

async execute(): Promise<void>

Executes the conversion process. Resolves once conversion is complete.

Will throw if isValid is false.

cancel()

async cancel(): Promise<void>

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

Video options

ConversionVideoOptions

discard · boolean

If true, all video tracks will be discarded and will not be present in the output.

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

rotate · Rotation

The angle in degrees to rotate the input video by, clockwise. Must be 0, 90, 180, or 270. Rotation is applied before cropping and resizing. This rotation is in addition to the natural rotation of the input video.

allowRotationMetadata · boolean · default: "true"

When enabled, Mediabunny will use the rotation metadata in the output file to perform video rotation whenever possible. Set this field to false if you want to ensure the output file does not make use of rotation metadata.

crop · object

Specifies the rectangular region of the input video to crop to

Show Crop properties

left · number

The distance in pixels from the left edge of the source frame to the left edge of the crop rectangle.

top · number

The distance in pixels from the top edge of the source frame to the top edge of the crop rectangle.

width · number

The width in pixels of the crop rectangle.

height · number

The height in pixels of the crop rectangle.

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 · VideoCodec

The desired output video codec.

bitrate · number | Quality

The desired bitrate of the output video.

alpha · 'discard' | 'keep' · default: "'discard'"

Whether to discard or keep the transparency information of the input video. Note that for 'keep' to produce a transparent video, you must use an output config that supports it, such as WebM with VP9.

keyFrameInterval · number · default: "5"

The interval, in seconds, of how often frames are encoded as a key frame. Frequent key frames improve seeking behavior but increase file size.

hardwareAcceleration · 'no-preference' | 'prefer-hardware' | 'prefer-software' · default: "'no-preference'"

A hint that configures the hardware acceleration method used when transcoding.

forceTranscode · boolean

When true, video will always be re-encoded instead of directly copying over the encoded samples.

process · Function

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.

processedWidth · number

An optional hint specifying the width of video samples returned by the process function, for better encoder configuration.

processedHeight · number

An optional hint specifying the height of video samples returned by the process function, for better encoder configuration.

Audio options

ConversionAudioOptions

discard · boolean

If true, all audio tracks will be discarded and will not be present in the output.

numberOfChannels · number

The desired channel count of the output audio.

sampleRate · number

The desired sample rate of the output audio, in hertz.

codec · AudioCodec

The desired output audio codec.

bitrate · number | Quality

The desired bitrate of the output audio.

forceTranscode · boolean

When true, audio will always be re-encoded instead of directly copying over the encoded samples.

process · Function

Allows for custom user-defined processing of audio samples, e.g. for applying audio effects, transformations, or timestamp modifications. Will be called for each input audio sample after remixing and resampling.

processedNumberOfChannels · number

An optional hint specifying the channel count of audio samples returned by the process function, for better encoder configuration.

processedSampleRate · number

An optional hint specifying the sample rate of audio samples returned by the process function, for better encoder configuration.

Example

import { Conversion, Input, Output, FileSource, StreamTarget } from '@mediabunny/browser';
import { Mp4InputFormat, Mp4OutputFormat } from '@mediabunny/browser';

const input = new Input({
  formats: [Mp4InputFormat],
  source: new FileSource(inputFile)
});

const output = new Output({
  format: Mp4OutputFormat,
  target: new StreamTarget()
});

const conversion = await Conversion.init({
  input,
  output,
  video: {
    width: 1280,
    height: 720,
    fit: 'contain',
    codec: 'avc',
    bitrate: 2_000_000,
    frameRate: 30
  },
  audio: {
    codec: 'aac',
    bitrate: 128_000,
    sampleRate: 48000,
    numberOfChannels: 2
  },
  trim: {
    start: 10,
    end: 60
  },
  tags: (inputTags) => ({
    ...inputTags,
    title: 'Converted Video'
  })
});

if (!conversion.isValid) {
  console.error('Conversion is invalid:', conversion.discardedTracks);
  return;
}

conversion.onProgress = (progress) => {
  console.log(`Progress: ${(progress * 100).toFixed(1)}%`);
};

try {
  await conversion.execute();
  console.log('Conversion complete!');
} catch (error) {
  console.error('Conversion failed:', error);
}

Per-track options

You can provide different options for each track by passing a function instead of an object:

const conversion = await Conversion.init({
  input,
  output,
  video: (track, n) => {
    if (track.number === 1) {
      // Main video track - high quality
      return {
        width: 1920,
        height: 1080,
        bitrate: 5_000_000
      };
    } else {
      // Additional tracks - lower quality
      return {
        width: 1280,
        height: 720,
        bitrate: 2_000_000
      };
    }
  },
  audio: (track, n) => {
    if (track.languageCode === 'eng') {
      return { codec: 'aac', bitrate: 192_000 };
    } else {
      // Discard non-English audio tracks
      return { discard: true };
    }
  }
});