convertMedia()v4.0.229

Part of the @remotion/webcodecs package.

💼 Important License Disclaimer

This package is licensed under the Remotion License.
We consider a team of 4 or more people a "company".

For "companies": A Remotion Company license needs to be obtained to use this package.
In a future version of @remotion/webcodecs, this package will also require the purchase of a newly created "WebCodecs Conversion Seat". Get in touch with us if you are planning to use this package.

For individuals and teams up to 3: You can use this package for free.

This is a short, non-binding explanation of our license. See the License itself for more details.

🚧 Unstable API

This package is experimental.
We might change the API at any time, until we remove this notice.

Re-encodes a video using WebCodecs and @remotion/media-parser.

Converting a video
tsx
import {convertMedia} from '@remotion/webcodecs';
 
await convertMedia({
  src: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
  container: 'webm',
});

API

src

A string or File or Blob.
If it is a string, it must be a URL.
If it is a File, the reader field must be set to webFileReader.

reader

A reader interface.
Default value: fetchReader, which uses fetch() to read the video.
If you pass webFileReader, you must also pass a File as the src argument.

container

string ConvertMediaContainer

The container format to convert to. Currently, "mp4", "webm" and "wav" is supported.

videoCodec?

string ConvertMediaVideoCodec

The video codec to convert to. Currently, "h264", "vp8" and "vp9" are supported.
The default is defined by getDefaultVideoCodec().
If a onVideoTrack handler is provided, it will override this setting.

audioCodec?

string ConvertMediaAudioCodec

The audio codec to convert to. Currently, only "opus" is supported.
The default is defined by getDefaultAudioCodec().
If an onAudioTrack handler is provided, it will override this setting.

rotate?

number

The number of degrees to rotate the video. See Rotate a video for more information.

resize?

object ResizeOperation

Resize the video. See Resize a video for more information.

apiKey?

If you are a customer of a Remotion Company License, you can provide an API key from your dashboard to track your conversions.

note

Telemetry is enabled even if you don't provide an API key.

logLevel?

string LogLevel

One of "error", "warn", "info", "debug", "trace".
Default value: "info", which logs only important information.

onProgress?

Function ConvertMediaOnProgress

Allows receiving progress updates. The following fields are available:

tsx
import type {ConvertMediaOnProgress, ConvertMediaProgress} from '@remotion/webcodecs';
 
export const onProgress: ConvertMediaOnProgress = ({decodedVideoFrames, decodedAudioFrames, encodedVideoFrames, encodedAudioFrames, bytesWritten, millisecondsWritten, expectedOutputDurationInMs, overallProgress}: ConvertMediaProgress) => {
  console.log(decodedVideoFrames);
                      
(parameter) decodedVideoFrames: number
  console.log(decodedAudioFrames);
                      
(parameter) decodedAudioFrames: number
  console.log(encodedVideoFrames);
                      
(parameter) encodedVideoFrames: number
  console.log(encodedAudioFrames);
                      
(parameter) encodedAudioFrames: number
  console.log(bytesWritten);
                   
(parameter) bytesWritten: number
  console.log(millisecondsWritten);
                      
(parameter) millisecondsWritten: number
  console.log(expectedOutputDurationInMs);
                          
(parameter) expectedOutputDurationInMs: number | null
  console.log(overallProgress);
                    
(parameter) overallProgress: number | null
};

onVideoFrame?

Function ConvertMediaOnVideoFrame

Allows you to hook into the video frames. The frames are VideoFrame objects.

tsx
import type {ConvertMediaOnVideoFrame} from '@remotion/webcodecs';
 
export const onVideoFrame: ConvertMediaOnVideoFrame = ({frame}) => {
  console.log(frame);
               
(parameter) frame: VideoFrame
 
  // Do something with the frame, for example:
  // - Draw to a canvas
  // - Modify the frame
 
  // Then return the frame to be used for encoding.
  return frame;
};

The callback function may be async.

When the function returns, the returned frame is used for video encoding.
You may return the same frame or replace it with a new VideoFrame object.

After the function returns, convertMedia() will call .close() on the input and output frames.
This will destroy the frame and free up memory. If you need a reference to the frame that lasts longer than the lifetime of this function, you must call .clone() on it.

If you return a different frame than the one you received, it must have the same values for codedWidth, codedHeight, displayWidth and displayHeight, timestamp and duration as the input frame.

onAudioData?

Function ConvertMediaOnAudioData

Allows you to hook into the audio data. The items are native AudioData objects.

tsx
import type {ConvertMediaOnAudioData} from '@remotion/webcodecs';
 
export const onAudioData: ConvertMediaOnAudioData = ({audioData}) => {
  console.log(audioData);
                 
(parameter) audioData: AudioData
 
  // Do something with the audiodata, for example:
  // - Change the pitch
  // - Lower the volume
 
  // Then return the frame to be used for encoding.
  return audioData;
};

The callback function may be async.

When the function returns, the returned audio data is used for audio encoding.
You may return the same audio data or replace it with a new AudioData object.

After the function returns, convertMedia() will call .close() on the input and output audio data.
This will destroy the audio data and free up memory. If you need a reference to the audio data that lasts longer than the lifetime of this function, you must call .clone() on it.

If you return a different audio data than the one you received, it should have the same duration, numberOfChannels, sampleRate, timestamp, numberOfChannels, format and numberOfChannels as the input audio data.

signal?

An AbortSignal to cancel the conversion process whenever the signal is aborted.

writer?

object WriterInterface

A writer interface. The following interfaces are available:

Buffer writer
tsx
import {bufferWriter} from '@remotion/webcodecs/buffer';
             
(alias) const bufferWriter: WriterInterface
import bufferWriter

Write to a resizable Array Buffer.

Web File System writer
tsx
import {canUseWebFsWriter, webFsWriter} from '@remotion/webcodecs/web-fs';
                               
(alias) const webFsWriter: WriterInterface
import webFsWriter
 
await canUseWebFsWriter(); // boolean

Use the Web File System API to write to a file.

By default the writer is webFsWriter.

onAudioTrack?

Function ConvertMediaOnAudioTrackHandler

Take control of what to do for each audio track in the file: Re-encoding, copying, or dropping.
See Track Transformation for a guide on how to use this callback.

onVideoTrack?

Function ConvertMediaOnVideoTrackHandler

Take control of what to do for each video track in the file: Re-encoding, copying, or dropping.
See Track Transformation for a guide on how to use this callback.

progressIntervalInMs?

number

The interval in milliseconds at which the onProgress callback is called.
Default 100. Set to 0 for unthrottled updates.
Note that updates are fired very often and updating the DOM often may slow down the conversion process.

fields? and Callbacks

You can obtain information about the video file while you are converting it.
This feature is inherited from parseMedia(), but only the callback-style API is available.

Converting a video
tsx
import {convertMedia} from '@remotion/webcodecs';
 
await convertMedia({
  src: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
  container: 'webm',
  videoCodec: 'vp8',
  audioCodec: 'opus',
  fields: {
    size: true,
  },
  onSize: (size) => {
    console.log(size);
                 
(parameter) size: number | null
  },
});

License

See notes about @remotion/webcodecs.

See also

• Source code for this function
• @remotion/webcodecs
• parseMedia()