renderMedia()<AvailableFrom v="3.0" />

Part of the @remotion/renderer package.

Render a video or an audio programmatically.

const serveUrl = '/path/to/bundle';
const outputLocation = '/path/to/frames';

import {renderMedia, selectComposition} from '@remotion/renderer';

const inputProps = {
  titleText: 'Hello World',
};

const composition = await selectComposition({
  serveUrl,
  id: 'my-video',
  inputProps,
});

// ---cut---
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.

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

string <TsType type="Codec" source="@remotion/renderer" href="/docs/renderer/types#codec" />

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

outputLocation?

string

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.

inputProps?

object

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.

port?

number

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

frameRange?

number | [number, number] | [number, null] <TsType type="FrameRange" source="@remotion/renderer" href="/docs/renderer/types#framerange" />

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. Pass [number, null] to render from a frame to the end of the composition.<AvailableFrom v="4.0.421" inline />

concurrency?

number | string | null <TsType type="Concurrency" source="@remotion/renderer" href="/docs/renderer/types#concurrency" />

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

metadata?<AvailableFrom v="4.0.216" />

object

logLevel?<AvailableFrom v="4.0.0"/>

onArtifact?<AvailableFrom v="4.0.176" />

function <TsType type="OnArtifact" source="@remotion/renderer" href="/docs/renderer/types#onartifact" />

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

audioCodec?

string <TsType type="AudioCodec" source="@remotion/renderer" href="/docs/renderer/types#audiocodec" />

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?<AvailableFrom v="3.2.32" />

videoBitrate?<AvailableFrom v="3.2.32" />

crf?

number | null <TsType type="Crf" source="@remotion/renderer" href="/docs/renderer/types#crf" />

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

:::note If you enable hardware acceleration, you cannot set a crf. Use the videoBitrate option instead. :::

bufferSize?<AvailableFrom v="4.0.78" />

maxRate?<AvailableFrom v="4.0.78" />

imageFormat?

string <TsType type="VideoImageFormat" source="@remotion/renderer" href="/docs/renderer/types#videoimageformat" />

In which image format the frames should be rendered.

• jpeg is the default and is fastest
• png if you want to render transparent videos
• none if you are rendering audio

browserExecutable?<AvailableFrom v="3.0.11" />

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?<AvailableFrom v="3.1.0" />

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?<AvailableFrom v="3.1.0" />

pixelFormat?

string <TsType type="PixelFormat" source="@remotion/renderer" href="/docs/renderer/types#pixelformat" />

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

envVariables?

Record<string, string>

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

See: Environment variables

jpegQuality?

number

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?<AvailableFrom v="3.2.1" />

boolean

If set to true, no audio is being rendered.

hardwareAcceleration?<AvailableFrom v="4.0.228" />

enforceAudioTrack?<AvailableFrom v="3.2.1" />

boolean

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

puppeteerInstance?

puppeteer.Browser

An already open 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.

:::note Despite the name, not actually compatible with puppeteer, only with openBrowser(). :::

scale?

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

overwrite?

boolean

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

onStart?

function <TsType type="OnStartData" source="@remotion/renderer" href="/docs/renderer/types#onstartdata" />

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:

import type {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 <TsType type="RenderMediaOnProgress" source="@remotion/renderer" href="/docs/renderer/types#rendermediaonprogress" />

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

import type {RenderMediaOnProgress} from '@remotion/renderer';

const onProgress: RenderMediaOnProgress = ({progress}) => {
  console.log(`Rendering is ${progress * 100}% complete`);
};

import type {RenderMediaOnProgress} from '@remotion/renderer';

const onProgress: RenderMediaOnProgress = ({renderedFrames, encodedFrames, encodedDoneIn, renderedDoneIn, stitchStage}) => {
  if (stitchStage === 'encoding') {
    // Rendering frames and encoding into video
    console.log('Encoding...');
  } else if (stitchStage === 'muxing') {
    // If parallel rendering and encoding is being used, a second stage is used to
    // encode the audio and combine it with the video. This stage does not occur on every render.
    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 <TsType type="RenderMediaOnDownload" source="@remotion/renderer" href="/docs/renderer/types#rendermediaondownload" />

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.

import type {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?

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

x264Preset?

string

onBrowserLog?

function <TsType type="BrowserLog" source="@remotion/renderer" href="/docs/renderer/types#browserlog" />

Catch a console message being printed. Example:

import type {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?

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

cancelSignal?<AvailableFrom v="3.0.15" />

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

chromiumOptions?<AvailableFrom v="2.6.5" />

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?<AvailableFrom v="4.0.42" />

boolean - default true

ignoreCertificateErrors?

boolean - default false

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

headless?

gl?

chromeMode?<AvailableFrom v="4.0.248" />

userAgent?<AvailableFrom v="3.3.83"/>

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

darkMode?<AvailableFrom v="4.0.381"/>

ffmpegOverride?<AvailableFrom v="3.2.22" />

function <TsType type="FfmpegOverrideFn" source="@remotion/renderer" href="/docs/renderer/types#ffmpegoverridefn" />

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.

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 a two-pass process for the video generation. pre-stitcher is the encoding phase and stitcher is the muxing phase. If the override function is only called once with stitcher, then encoding and muxing is done in the same step. 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. :::

disallowParallelEncoding?<AvailableFrom v="3.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.

mediaCacheSizeInBytes?<AvailableFrom v="4.0.352"/>

offthreadVideoCacheSizeInBytes?<AvailableFrom v="4.0.23"/>

offthreadVideoThreads?<AvailableFrom v="4.0.261"/>

colorSpace?<AvailableFrom v="4.0.28"/>

repro?<AvailableFrom v="4.0.88" />

boolean - default false

binariesDirectory?<AvailableFrom v="4.0.120" />

separateAudioTo?<AvailableFrom v="4.0.123" />

forSeamlessAacConcatenation?<AvailableFrom v="4.0.123" />

sampleRate?<AvailableFrom v="4.0.448" />

compositionStart?<AvailableFrom v="4.0.279"/>

An option to be used only if implementing a distributed renderer, see Distributed rendering for what to set it to.

onBrowserDownload?<AvailableFrom v="4.0.137" />

licenseKey?<AvailableFrom v="4.0.409"/>

isProduction?<AvailableFrom v="4.0.409"/>

default true

apiKey?<AvailableFrom v="4.0.375"/>

deprecated in v4.0.409

parallelism?

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

quality?

Renamed to jpegQuality in v4.0.0.

dumpBrowserLogs?

default false, deprecated in v4.0

Deprecated in favor of logLevel.

verbose?

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

An absolute path overriding the ffmpeg executable to use.

ffprobeExecutable? <AvailableFrom v="3.0.17" />

removed in v4.0

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.
• contentType: <AvailableFrom v="4.0.426" inline /> The content type of the rendered output, e.g. "video/mp4", "video/webm", "image/gif".

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.

Compatibility

See also

• Source code for this function
• Server-Side rendering
• getCompositions()
• renderStill()
• renderMediaOnLambda()