Skip to main content

renderMedia()

Available since v3.0 - Part of the @remotion/renderer package.

Render a video or an audio programmatically.

render.mjs
tsx
await renderMedia({
  composition,
  serveUrl,
  codec: 'h264',
  outputLocation,
  inputProps,
});
render.mjs
tsx
await renderMedia({
  composition,
  serveUrl,
  codec: 'h264',
  outputLocation,
  inputProps,
});

See an example of renderMedia() together with bundle() and selectComposition() on the server-side rendering page.

Arguments​

An object with the following properties:

serveUrl​

string

Either a local path pointing to a Remotion Webpack bundle generated by bundle() or a URL where the bundle is hosted.

port?​

Prefer a specific port that will be used to serve the Remotion project. If not specified, a random port will be used.

outputLocation?​

string - optional since v3.0.26

Where to save the output artifact to. Either an absolute path or a relative path that will be resolved relative to the current working directory. Must be a file path (not a folder).

If not specified or set to null, the file will be returned in-memory as a buffer.

composition​

VideoConfig

An object describing a composition using id, width, height, fps and durationInFrames, defaultProps and props.
Call selectComposition() or getCompositions() to get an array of possible configs.

codec​

"h264" | "h265" | "vp8" | "vp9" | "mp3" | "aac" | "wav" | "prores" | "h264-mkv" | "gif"

Choose a suitable codec for your output media. Refer to the Encoding guide to find the best codec for your use case.

inputProps?​

object - optional

Input Props to pass to the selected composition of your video..
Must be a JSON object.
From the root component the props can be read using getInputProps().
You may transform input props using calculateMetadata().

Make sure to also pass the same inputProps to selectComposition() for this to work correctly.

frameRange?​

number | [number, number] - optional

Specify a single frame (passing a number) or a range of frames (passing a tuple [number, number]) to be rendered. By passing null (default) all frames of a composition get rendered.

concurrency?​

optional

A number specifying how many render processes should be started in parallel, a string specifying the percentage of the CPU threads to use, or null to let Remotion decide based on the CPU of the host machine. Default is half of the CPU threads available.

metadatav4.0.216​

object - optional

An object containing metadata to be embedded in the video. See here for which metadata is accepted.

logLevel?v4.0.0​

One of verbose, info, warn, error.
Determines how much is being logged to the console.
verbose will also log console.log's from the browser.
Default info.

onArtifact?v4.0.176​

Handle an artifact that was emitted by the <Artifact> component.

audioCodec?​

"pcm-16" | "aac" | "mp3" | "opus", available from v3.3.41

Choose the encoding of your audio.

  • The default is dependent on the chosen codec.
  • Choose pcm-16 if you need uncompressed audio.
  • Not all video containers support all audio codecs.
  • This option takes precedence if the codec option also specifies an audio codec.

Refer to the Encoding guide to see defaults and supported combinations.

audioBitrate?v3.2.32​

Specify the target bitrate for the generated video. The syntax for FFmpeg's -b:a parameter should be used. FFmpeg may encode the video in a way that will not result in the exact audio bitrate specified. Example values: 512K for 512 kbps, 1M for 1 Mbps. Default: 320k

videoBitrate?v3.2.32​

Specify the target bitrate for the generated video. The syntax for FFmpeg's-b:v parameter should be used. FFmpeg may encode the video in a way that will not result in the exact video bitrate specified. Example values: 512K for 512 kbps, 1M for 1 Mbps.

crf?​

number | null - optional

The constant rate factor, controlling the quality. See: Controlling quality using the CRF setting.

bufferSize?v4.0.78​

The value for the -bufsize flag of FFmpeg. Should be used in conjunction with the encoding max rate flag.

maxRate?v4.0.78​

The value for the -maxrate flag of FFmpeg. Should be used in conjunction with the encoding buffer size flag.

imageFormat?​

"jpeg" (default) | "png" | "none" - optional since v3.2.27

In which image format the frames should be rendered.

browserExecutable?v3.0.11​

optional

A string defining the absolute path on disk of the browser executable that should be used. By default Remotion will try to detect it automatically and download one if none is available. If puppeteerInstance is defined, it will take precedence over browserExecutable.

everyNthFrame?v3.1.0​

optional

Renders only every nth frame. For example only every second frame, every third frame and so on. Only works for rendering GIFs. See here for more details.

numberOfGifLoops?v3.1.0​

optional

Allows you to set the number of loops as follows:
  • null (or omitting in the CLI) plays the GIF indefinitely.
  • 0 disables looping
  • 1 loops the GIF once (plays twice in total)
  • 2 loops the GIF twice (plays three times in total) and so on.

pixelFormat?​

string - optional

A custom pixel format to use. Usually used for special use cases like transparent videos.

envVariables?​

Record<string, string> - optional

An object containing environment variables to be injected in your project.

See: Environment variables

jpegQuality?​

number - optional

Sets the quality of the generated JPEG images. Must be an integer between 0 and 100. Default is to leave it up to the browser, current default is 80.

Only applies if imageFormat is 'jpeg', otherwise this option is invalid.

muted?v3.2.1​

boolean - optional

If set to true, no audio is being rendered.

hardwareAcceleration?v4.0.228​

One of "disable", "if-possible", or "required" . Default "disable". Encode using a hardware-accelerated encoder if available. If set to "required" and no hardware-accelerated encoder is available, then the render will fail.

enforceAudioTrack?v3.2.1​

boolean - optional

Render a silent audio track if there wouldn't be any otherwise.

puppeteerInstance?​

puppeteer.Browser - optional

An already open Puppeteer Browser instance. Use openBrowser() to create a new instance. Reusing a browser across multiple function calls can speed up the rendering process. You are responsible for opening and closing the browser yourself. If you don't specify this option, a new browser will be opened and closed at the end.

scale?​

optional

Scales the output dimensions by a factor. See Scaling to learn more about this feature.

overwrite?​

boolean - optional

If set to false, the output file will not be written if a file already exists.

onStart?​

function - optional

Callback function that gets called once the renderer has prepared to start rendering and has calculated the amount of frames that are going to be rendered:

tsx
import {OnStartData} from '@remotion/renderer';
 
const onStart = ({
  frameCount,
  parallelEncoding, // available from v4.0.52
  resolvedConcurrency, // available from v4.0.180
}: OnStartData) => {
  console.log(`Beginning to render ${frameCount}.`);
 
  if (parallelEncoding) {
    console.log('Parallel encoding is enabled.');
  }
 
  console.log(`Using concurrency: ${resolvedConcurrency}`);
};
tsx
import {OnStartData} from '@remotion/renderer';
 
const onStart = ({
  frameCount,
  parallelEncoding, // available from v4.0.52
  resolvedConcurrency, // available from v4.0.180
}: OnStartData) => {
  console.log(`Beginning to render ${frameCount}.`);
 
  if (parallelEncoding) {
    console.log('Parallel encoding is enabled.');
  }
 
  console.log(`Using concurrency: ${resolvedConcurrency}`);
};

onProgress?​

function - optional

React to render progress. The following callback function is similar to how Remotion displays render progress on it's CLI:

Simple example - Log overall progress
tsx
import {RenderMediaOnProgress} from '@remotion/renderer';
 
const onProgress: RenderMediaOnProgress = ({progress}) => {
  console.log(`Rendering is ${progress * 100}% complete`);
};
Simple example - Log overall progress
tsx
import {RenderMediaOnProgress} from '@remotion/renderer';
 
const onProgress: RenderMediaOnProgress = ({progress}) => {
  console.log(`Rendering is ${progress * 100}% complete`);
};
Advanced example - Fine-grained progress values
tsx
import {RenderMediaOnProgress} from '@remotion/renderer';
 
const onProgress: RenderMediaOnProgress = ({
  renderedFrames,
  encodedFrames,
  encodedDoneIn,
  renderedDoneIn,
  stitchStage,
}) => {
  if (stitchStage === 'encoding') {
    // First pass, parallel rendering of frames and encoding into video
    console.log('Encoding...');
  } else if (stitchStage === 'muxing') {
    // Second pass, adding audio to the video
    console.log('Muxing audio...');
  }
  // Amount of frames rendered into images
  console.log(`${renderedFrames} rendered`);
  // Amount of frame encoded into a video
  console.log(`${encodedFrames} encoded`);
  // Time to create images of all frames
  if (renderedDoneIn !== null) {
    console.log(`Rendered in ${renderedDoneIn}ms`);
  }
  // Time to encode video from images
  if (encodedDoneIn !== null) {
    console.log(`Encoded in ${encodedDoneIn}ms`);
  }
};
Advanced example - Fine-grained progress values
tsx
import {RenderMediaOnProgress} from '@remotion/renderer';
 
const onProgress: RenderMediaOnProgress = ({
  renderedFrames,
  encodedFrames,
  encodedDoneIn,
  renderedDoneIn,
  stitchStage,
}) => {
  if (stitchStage === 'encoding') {
    // First pass, parallel rendering of frames and encoding into video
    console.log('Encoding...');
  } else if (stitchStage === 'muxing') {
    // Second pass, adding audio to the video
    console.log('Muxing audio...');
  }
  // Amount of frames rendered into images
  console.log(`${renderedFrames} rendered`);
  // Amount of frame encoded into a video
  console.log(`${encodedFrames} encoded`);
  // Time to create images of all frames
  if (renderedDoneIn !== null) {
    console.log(`Rendered in ${renderedDoneIn}ms`);
  }
  // Time to encode video from images
  if (encodedDoneIn !== null) {
    console.log(`Encoded in ${encodedDoneIn}ms`);
  }
};
note

The progress attribute is available from v3.2.17.

onDownload?​

function - optional

If an audio (or a video with sound) is included in your project, Remotion needs to download it in order to use it's audio in the output file. You can use this callback to react to a download happening and progressing.

tsx
import {RenderMediaOnDownload} from '@remotion/renderer';
 
const onDownload: RenderMediaOnDownload = (src) => {
  console.log(`Downloading ${src}...`);
  return ({percent, downloaded, totalSize}) => {
    // percent and totalSize can be `null` if the downloaded resource
    // does not have a `Content-Length` header
    if (percent === null) {
      console.log(`${downloaded} bytes downloaded`);
    } else {
      console.log(`${Math.round(percent * 100)}% done)`);
    }
  };
};
tsx
import {RenderMediaOnDownload} from '@remotion/renderer';
 
const onDownload: RenderMediaOnDownload = (src) => {
  console.log(`Downloading ${src}...`);
  return ({percent, downloaded, totalSize}) => {
    // percent and totalSize can be `null` if the downloaded resource
    // does not have a `Content-Length` header
    if (percent === null) {
      console.log(`${downloaded} bytes downloaded`);
    } else {
      console.log(`${Math.round(percent * 100)}% done)`);
    }
  };
};

proResProfile?​

string - optional

Sets a ProRes profile. Only applies to videos rendered with prores codec. See Encoding guide for possible options.

x264Preset?​

string - optional

Sets a x264 preset profile. Only applies to videos rendered with h264 codec.
Possible values: superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo.
Default: medium

onBrowserLog?​

function - optional

Catch a console message being printed. Example:

tsx
import {BrowserLog} from '@remotion/renderer';
 
const onBrowserLog = (log: BrowserLog) => {
  // `type` is the console.* method: `log`, `warn`, `error`, etc.
  console.log(`[${log.type}]`);
  console.log(log.text);
  console.log(`at ${log.stackTrace}`);
};
tsx
import {BrowserLog} from '@remotion/renderer';
 
const onBrowserLog = (log: BrowserLog) => {
  // `type` is the console.* method: `log`, `warn`, `error`, etc.
  console.log(`[${log.type}]`);
  console.log(log.text);
  console.log(`at ${log.stackTrace}`);
};

timeoutInMilliseconds?​

optional

A number describing how long the render may take to resolve all delayRender() calls before it times out. Default: 30000

cancelSignal?v3.0.15​

optional

A token that allows the render to be cancelled. See: makeCancelSignal()

chromiumOptions?v2.6.5​

optional

Allows you to set certain Chromium / Google Chrome flags. See: Chromium flags.

note

Chromium flags need to be set at browser launch. If you pass an instance using puppeteerInstance, options passed to renderMedia() will not apply, but rather the flags that have been passed to openBrowser().

disableWebSecurity?​

boolean - default false

This will most notably disable CORS among other security features.

enableMultiProcessOnLinux?v4.0.42​

boolean - default true

Removes the --single-process flag that gets passed to Chromium on Linux by default. This will make the render faster because multiple processes can be used, but may cause issues with some Linux distributions or if window server libraries are missing.
Default: false until v4.0.136, then true from v4.0.137 on because newer Chrome versions don't allow rendering with the --single-process flag.
This flag will be removed in Remotion v5.0.

ignoreCertificateErrors?​

boolean - default false

Results in invalid SSL certificates, such as self-signed ones, being ignored.

headless?​

Deprecated - will be removed in 5.0.0. With the migration to Chrome Headless Shell, this option is not functional anymore.

If disabled, the render will open an actual Chrome window where you can see the render happen. The default is headless mode.

gl?​

Changelog
  • From Remotion v2.6.7 until v3.0.7, the default for Remotion Lambda was swiftshader, but from v3.0.8 the default is swangle (Swiftshader on Angle) since Chrome 101 added support for it.
  • From Remotion v2.4.3 until v2.6.6, the default was angle, however it turns out to have a small memory leak that could crash long Remotion renders.

Select the OpenGL renderer backend for Chromium.
Accepted values:

  • "angle"
  • "egl"
  • "swiftshader"
  • "swangle"
  • "vulkan" (from Remotion v4.0.41)
  • "angle-egl" (from Remotion v4.0.51)

The default is null, letting Chrome decide, except on Lambda where the default is "swangle"

userAgent?v3.3.83​

Lets you set a custom user agent that the headless Chrome browser assumes.

ffmpegOverride?v3.2.22​

function - optional

Modifies the FFMPEG command that Remotion uses under the hood. It works reducer-style, meaning that you pass a function that takes a command as an argument and returns a new command.

tsx
import type {FfmpegOverrideFn} from '@remotion/renderer';
 
const ffmpegOverride: FfmpegOverrideFn = ({type, args}) => {
  console.log(type); // "stitcher" | "pre-stitcher
  return [...args, '-vf', 'eq=brightness=0:saturation=1'];
};
tsx
import type {FfmpegOverrideFn} from '@remotion/renderer';
 
const ffmpegOverride: FfmpegOverrideFn = ({type, args}) => {
  console.log(type); // "stitcher" | "pre-stitcher
  return [...args, '-vf', 'eq=brightness=0:saturation=1'];
};

The function you pass must accept an object as it's only parameter which contains the following properties:

  • type: Either "stitcher" or "pre-stitcher". If enough memory and CPU is available, Remotion may use parallel rendering and encoding, which means that a pre-stitcher process gets spawned before all frames are rendered. You can tell whether parallel encoding is enabled by adding --log=verbose to your render command.
  • args: An array of strings that is passed as arguments to the FFMPEG command.

Your function must return a modified array of strings.

warning

Using this feature is discouraged. Before using it, we want to make you aware of some caveats:

  • The render command can change with any new Remotion version, even when it is a patch upgrade. This might break your usage of this feature.
  • Depending on the selected codec, available CPU and RAM, Remotion may or may not use "parallel encoding" which will result in multiple FFMPEG commands being executed. Your function must be able to handle being called multiple times.
  • This feature is not available when using Remotion Lambda.

Before you use this hack, reach out to the Remotion team on Discord and ask us if we are open to implement the feature you need in a clean way - we often do implement new features quickly based on users feedback.

disallowParallelEncodingv3.2.29​

Disallows the renderer from doing rendering frames and encoding at the same time. This makes the rendering process more memory-efficient, but possibly slower.

offthreadVideoCacheSizeInBytes?v4.0.23​

From v4.0, Remotion has a cache for <OffthreadVideo> frames. The default is null, corresponding to half of the system memory available when the render starts.
This option allows to override the size of the cache. The higher it is, the faster the render will be, but the more memory will be used.
The used value will be printed when running in verbose mode.
Default: null

colorSpace?v4.0.28​

Color space to use for the video. Acceptable values: "default"(default since 5.0), "bt709" (since v4.0.28), "bt2020-ncl" (since v4.0.88), "bt2020-cl" (since v4.0.88), .
For best color accuracy, it is recommended to also use "png" as the image format to have accurate color transformations throughout.
Only since v4.0.83, colorspace conversion is actually performed, previously it would only tag the metadata of the video.

repro?v4.0.88​

boolean - default false

Create a ZIP that you can submit to Remotion if asked for a reproduction.

binariesDirectory?v4.0.120​

The directory where the platform-specific binaries and libraries that Remotion needs are located. Those include an ffmpeg and ffprobe binary, a Rust binary for various tasks, and various shared libraries. If the value is set to null, which is the default, then the path of a platform-specific package located at node_modules/@remotion/compositor-* is selected.
This option is useful in environments where Remotion is not officially supported to run like bundled serverless functions or Electron.

separateAudioTo?v4.0.123​

If set, the audio will not be included in the main output but rendered as a separate file at the location you pass. It is recommended to use an absolute path. If a relative path is passed, it is relative to the Remotion Root.

forSeamlessAacConcatenation?v4.0.123​

If enabled, the audio is trimmed to the nearest AAC frame, which is required for seamless concatenation of AAC files. This is a requirement if you later want to combine multiple video snippets seamlessly.

This option is used internally. There is currently no documentation yet for to concatenate the audio chunks.

onBrowserDownload?v4.0.137​

Gets called when no compatible local browser is detected on the system and this API needs to download a browser. Return a callback to observe progress. See here for how to use this option.

parallelism?​

Renamed to concurrency in v3.2.17. Removed in v4.0.0.

quality?​

Renamed to jpegQuality in v4.0.0.

dumpBrowserLogs?​

optional - default false, deprecated in v4.0

Deprecated in favor of logLevel.

verbose?​

optional, deprecated in v4.0

Deprecated in favor of logLevel.

onSlowestFrames?​

Introduced in v3.2.29, removed from v4.0. slowestFrames has been moved to the return type.

Callback function that gets called right before renderMedia() resolves.
The only argument slowestFrames is an array of the 10 slowest frames in the shape of {frame:<Frame number>, time:<Time to render frame ms>}. You can use this information to optimise your render times.

ffmpegExecutable​

removed in v4.0, string, optional

An absolute path overriding the ffmpeg executable to use.

ffprobeExecutable? v3.0.17​

removed in v4.0, optional

An absolute path overriding the ffprobe executable to use.

Return Value​

from v4.0.0:

The return value is an object with the following properties:

  • buffer: If outputLocation is not specified or null, contains a buffer, otherwise null.
  • slowestFrames: An array of the 10 slowest frames in the shape of {frame:<Frame number>, time:<Time to render frame ms>}. You can use this information to optimise your render times.

from v3.0.26:

If outputLocation is not specified or null, the return value is a Promise that resolves a Buffer. If an output location is specified, the return value is a Promise that resolves no value.

See also​