Skip to main content

renderFrames()

Part of the @remotion/renderer package.

Renders a series of images using Puppeteer and computes information for mixing audio.

If you want to render only a still image, use renderStill().

info

In Remotion 3.0, we added the renderMedia() API which combines renderFrames() and stitchFramesToVideo() into one simplified step and performs the render faster. Prefer renderMedia() if you can.

info

Configuration in remotion.config.ts and CLI flags do not apply to this function. You must pass all options explicitly.

Arguments​

Takes an object with the following keys:

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.

onStart​

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}`);
};

onFrameUpdate​

A callback function that gets called whenever a frame finished rendering. An argument is passed containing how many frames have been rendered (not the frame number of the rendered frame).

In v3.0.0, a second argument was added: frame, returning the frame number that was just rendered.

In v3.2.30, a third argument was rendered: timeToRenderInMilliseconds, describing the time it took to render that frame in milliseconds.

ts
const onFrameUpdate = (
  framesRendered: number,
  frame: number,
  timeToRenderInMilliseconds: number,
) => {
  console.log(`${framesRendered} frames rendered.`);
 
  // From v3.0.0
  console.log(`${frame} was just rendered.`);
 
  // From v3.2.30
  console.log(`It took ${timeToRenderInMilliseconds}ms to render that frame.`);
};
ts
const onFrameUpdate = (
  framesRendered: number,
  frame: number,
  timeToRenderInMilliseconds: number,
) => {
  console.log(`${framesRendered} frames rendered.`);
 
  // From v3.0.0
  console.log(`${frame} was just rendered.`);
 
  // From v3.2.30
  console.log(`It took ${timeToRenderInMilliseconds}ms to render that frame.`);
};

outputDir​

A string specifying the directory (absolute path) to which frames should be saved. Pass null to this option and use the onFrameBuffer callback instead to get a Buffer of the frame rather than to write it to any location.

inputProps​

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

serveUrl​

Either a Webpack bundle or a URL pointing to a bundled Remotion project. Call bundle() to generate a bundle. You can either pass the file location or deploy it as a website and pass the URL.

imageFormat​

optional since v4.0 - default "jpeg"

  • Choose jpeg by default because it is the fastest.
  • Choose png if you want your image sequence to have an alpha channel (for transparency).
  • Choose none if you only want to render audio.

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.

scale?v2.6.7​

number - default: 1

Scales the output frames by the factor you pass in. For example, a 1280x720px frame will become a 1920x1080px frame with a scale factor of 1.5. Vector elements like fonts and HTML markups will be rendered with extra details.

jpegQuality?​

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.

port?​

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

frameRange?​

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.

mutedv3.2.1​

optional

Disables audio output. This option may only be set in combination with a video codec and should also be passed to stitchFramesToVideo().

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.

puppeteerInstance?​

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.

envVariables?v2.2.0​

optional

An object containing key-value pairs of environment variables which will be injected into your Remotion projected and which can be accessed by reading the global process.env object.

onBrowserLog?v3.0.0​

optional

Gets called when your project calls console.log or another method from console. A browser log has three properties:

  • text: The message being printed
  • stackTrace: An array of objects containing the following properties:
    • url: URL of the resource that logged.
    • lineNumber: 0-based line number in the file where the log got called.
    • columnNumber: 0-based column number in the file where the log got called.
  • type: The console method - one of log, debug, info, error, warning, dir, dirxml, table, trace, clear, startGroup, startGroupCollapsed, endGroup, assert, profile, profileEnd, count, timeEnd, verbose
tsx
renderFrames({
  onBrowserLog: (info) => {
    console.log(`${info.type}: ${info.text}`);
    console.log(
      info.stackTrace
        .map((stack) => {
          return `  ${stack.url}:${stack.lineNumber}:${stack.columnNumber}`;
        })
        .join('\n'),
    );
  },
});
tsx
renderFrames({
  onBrowserLog: (info) => {
    console.log(`${info.type}: ${info.text}`);
    console.log(
      info.stackTrace
        .map((stack) => {
          return `  ${stack.url}:${stack.lineNumber}:${stack.columnNumber}`;
        })
        .join('\n'),
    );
  },
});

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.

cancelSignal?v3.0.15​

optional

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

onFrameBuffer?v3.0.0​

optional

If you passed null to outputDir, this method will be called passing a buffer of the current frame. This is mostly used internally by Remotion to implement renderMedia() and might have limited usefulness for end users.

timeoutInMilliseconds?v2.6.3​

optional

A number describing how long one frame may take to resolve all delayRender() calls before the [render times out and fails(/docs/timeout). Default: 30000

everyNthFramev3.1.0​

optional

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

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 renderFrames() 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?​

string

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.

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

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.

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.

quality?​

Renamed to jpegQuality in v4.0.0.

dumpBrowserLogs?​

optional - default false, deprecated in v4.0

Deprecated in favor of logLevel.

parallelism?​

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

ffmpegExecutable​

removed in v4.0, 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​

A promise resolving to an object containing the following properties:

  • frameCount: number - describing how many frames got rendered.
  • assetsInfo: RenderAssetInfo - information that can be passed to stitchFramesToVideo() to mix audio. The shape of this object should be considered as Remotion internals and may change across Remotion versions.

See also​