Skip to main content

renderMedia()

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

Render a video or an audio programmatically.

Example​

See an example of renderMedia() together with bundle() and getCompositions() 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.

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" (default) | "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.

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​

string - optional

Specify the target bitrate for the generated video.
The syntax for FFMPEGs -b:a parameter should be used.
FFMPEG may encode the video in a way that will not result in the exact audio bitrate specified.
This option cannot be set if --crf is set. Example values: 512K for 512 kbps, 1M for 1 Mbps.
Default: 320k

videoBitrate?v3.2.32​

string - optional

Specify the target bitrate for the generated video.
The syntax for FFMPEGs -b:v parameter should be used.
FFMPEG may encode the video in a way that will not result in the exact video bitrate specified.
This option cannot be set if --crf is set. Example values: 512K for 512 kbps, 1M for 1 Mbps.

inputProps?​

object - optional

An object of arbitrary shape that will be passed as props to your composition and that can be retrieved using getInputProps().

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.

crf?​

number | null - optional

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

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

Set the looping behavior. This option may only be set when rendering GIFs. See here for more details.

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.

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.

muted?v3.2.1​

boolean - optional

If set to true, no audio is being rendered.

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 }: OnStartData) => {
  console.log(`Beginning to render ${frameCount}.`);
  // From Remotion v4.0.52
  if (parallelEncoding) {
    console.log("Parallel encoding is enabled.");
  }
};
tsx
import { OnStartData } from "@remotion/renderer";
 
const onStart = ({ frameCount, parallelEncoding }: OnStartData) => {
  console.log(`Beginning to render ${frameCount}.`);
  // From Remotion v4.0.52
  if (parallelEncoding) {
    console.log("Parallel encoding is enabled.");
  }
};

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 Preset profile. Only applies to videos rendered with h264 codec. Possible values: superfast, veryfast, faster, fast, medium, slow, slower, veryslow, placebo, Default: medium

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.

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.

ignoreCertificateErrors​

boolean - default false

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

headless​

boolean - default true

If disabled, the render will open an actual Chrome window where you can see the render happen.

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"

userAgentv3.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.

danger

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", "bt709"

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​