Skip to main content

Configuration file

To configure Remotion, create a remotion.config.ts file in the root of your Remotion project.

These options will apply to CLI commands such as npm start and npm run build.

danger

The configuration file has no effect when using SSR APIs.

You can control several behaviors of Remotion here.

ts
import { Config } from "remotion";
 
Config.Rendering.setConcurrency(8);
Config.Output.setPixelFormat("yuv444p");
Config.Output.setCodec("h265");
ts
import { Config } from "remotion";
 
Config.Rendering.setConcurrency(8);
Config.Output.setPixelFormat("yuv444p");
Config.Output.setCodec("h265");

Bundling​

overrideWebpackConfig()​

Available from Version 1.1.

Allows you to insert your custom Webpack config. See the page about custom Webpack configs for more information.

ts
Config.Bundling.overrideWebpackConfig((currentConfiguration) => {
  // Return a new Webpack configuration
  return {
    ...currentConfiguration,
    // new configuration
  };
});
ts
Config.Bundling.overrideWebpackConfig((currentConfiguration) => {
  // Return a new Webpack configuration
  return {
    ...currentConfiguration,
    // new configuration
  };
});

setCachingEnabled()​

Available from Version 2.0.

Enable or disable webpack caching. Default is true which will make the Webpack step in the first run a bit slower but will massively speed up subsequent runs. We recommend to keep this option enabled in all cases and encourage to report issues on GitHub if you encounter some.

ts
Config.Bundling.setCachingEnabled(false);
ts
Config.Bundling.setCachingEnabled(false);

The command line flag --bundle-cache will take precedence over this option.

setPort()​

Define on which port Remotion should start it's HTTP servers during preview and rendering. By default, Remotion will try to find a free port. If you specify a port, but it's not available, Remotion will throw an error.

ts
Config.Bundling.setPort(3003);
ts
Config.Bundling.setPort(3003);

The command line flag --port will take precedence over this option.

setPublicDir()​

Available from v3.2.13

Define the location of the public/ directory.
By default it is a folder named "public" inside the current working directory.
You can either set an absolute path, or a relative path that will be resolved from the closest package.json location.

ts
Config.Bundling.setPublicDir("./publico");
ts
Config.Bundling.setPublicDir("./publico");

The command line flag --public-dir will take precedence over this option.

Log​

setLevel()​

Available from Version 2.0.1

Increase or decrease the amount of log messages in the CLI. Acceptable values:

  • error: Silent except error messages.
  • warn: Only showing errors and warnings.
  • info (default): Default output - besides errors and warnings, prints progress and output location.
  • verbose: All of the above, plus browser logs and other debug info.
ts
Config.Log.setLevel("verbose");
ts
Config.Log.setLevel("verbose");

The command line flag --log will take precedence over this option.

Preview​

setMaxTimelineTracks()​

Available from Version 2.1.10.

Set how many tracks are being displayed in the timeline at most. This does not affect your video, just the amount of tracks shown when previewing. Default 15.

ts
Config.Preview.setMaxTimelineTracks(20);
ts
Config.Preview.setMaxTimelineTracks(20);

setKeyboardShortcutsEnabled()​

Whether the Preview should react to keyboard shortcuts. Default true.

ts
Config.Preview.setKeyboardShortcutsEnabled(false);
ts
Config.Preview.setKeyboardShortcutsEnabled(false);

The command line flag --disable-keyboard-shortcuts will take precedence over this option.

Puppeteer​

setBrowserExecutable()​

Available from Version 1.5.

Set a custom Chrome or Chromium executable path. By default Remotion will try to find an existing version of Chrome on your system and if not found, it will download one. This flag is useful if you don't have Chrome installed in a standard location and you want to prevent downloading an additional browser or need support for the H264 codec.

ts
Config.Puppeteer.setBrowserExecutable("/usr/bin/google-chrome-stable");
ts
Config.Puppeteer.setBrowserExecutable("/usr/bin/google-chrome-stable");

The command line flag --browser-executable will take precedence over this option.

setTimeoutInMilliseconds()​

Available from Version 2.6.3.

Define how long a single frame may take to resolve all delayRender() calls before it times out. Default: 30000

ts
Config.Puppeteer.setTimeoutInMilliseconds(60000);
ts
Config.Puppeteer.setTimeoutInMilliseconds(60000);

The command line flag --timeout will take precedence over this option.

setChromiumDisableWebSecurity()​

Available from Version 2.6.5.

This will most notably disable CORS among other security features.

tsx
Config.Puppeteer.setChromiumDisableWebSecurity(true);
tsx
Config.Puppeteer.setChromiumDisableWebSecurity(true);

The command line flag --disable-web-security will take precedence over this option.

setChromiumIgnoreCertificateErrors()​

Available from Version 2.6.5.

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

tsx
Config.Puppeteer.setChromiumIgnoreCertificateErrors(true);
tsx
Config.Puppeteer.setChromiumIgnoreCertificateErrors(true);

The command line flag --ignore-certificate-errors will take precedence over this option.

setChromiumHeadlessMode()​

Available from Version 2.6.5.

By default true. Disabling it will open an actual Chrome window where you can see the render happen.

tsx
Config.Puppeteer.setChromiumHeadlessMode(false);
tsx
Config.Puppeteer.setChromiumHeadlessMode(false);

The command line flag --disable-headless will take precedence over this option.

Rendering​

setConcurrency()​

Sets how many Puppeteer instances will work on rendering your video in parallel. Default: null, meaning half of the threads available on your CPU.

ts
Config.Rendering.setConcurrency(8);
ts
Config.Rendering.setConcurrency(8);

The command line flag --concurrency will take precedence over this option.

tip

Try to set your concurrency to os.cpus().length to all the threads available on your CPU for faster rendering. The drawback is that other parts of your system might slow down.

setImageFormat()​

Available from Version 1.4.

Determines which in which image format to render the frames. Either:

  • jpeg - the fastest option (default from v1.1)
  • png - slower, but supports transparency
  • none - don't render images, just calculate audio information (available from v2.0)
ts
Config.Rendering.setImageFormat("png");
ts
Config.Rendering.setImageFormat("png");

The command line flag --image-format will take precedence over this option.

setScale()​

Available from Version 2.6.7.

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. Default: 1.

ts
Config.Rendering.setScale(2);
ts
Config.Rendering.setScale(2);

The command line flag --scale will take precedence over this option.

setMuted()​

Available from Version 3.2.1.

Disables audio output. Default false.

ts
Config.Rendering.setMuted(true);
ts
Config.Rendering.setMuted(true);

The command line flag --muted will take precedence over this option.

setEnforceAudioTrack()​

Available from Version 3.2.1.

Render a silent audio track if there would be none otherwise. Default false.

ts
Config.Rendering.setEnforceAudioTrack(true);
ts
Config.Rendering.setEnforceAudioTrack(true);

The command line flag --enforce-audio-track will take precedence over this option.

setFrameRange()​

Available from Version 2.0.

Pass a number to render a still frame or a tuple to render a subset of a video. The frame sequence is zero-indexed.

ts
Config.Rendering.setFrameRange(90); // To render only the 91st frame
ts
Config.Rendering.setFrameRange(90); // To render only the 91st frame

or

ts
Config.Rendering.setFrameRange([0, 20]); // Render a video only containing the first 21 frames
ts
Config.Rendering.setFrameRange([0, 20]); // Render a video only containing the first 21 frames

The command line flag --frames will take precedence over this option.

setQuality()​

The JPEG quality of each frame. Must be a number between 0 and 100. Will not work if you render PNG frames. Default: 80.

ts
Config.Rendering.setQuality(90);
ts
Config.Rendering.setQuality(90);

The command line flag --quality will take precedence over this option.

setDotEnvLocation()​

Set a custom location for a .env file. You can specify an absolute path or a relative path in which case it gets resolved based on the current working directory.

ts
Config.Rendering.setDotEnvLocation(".my-env");
ts
Config.Rendering.setDotEnvLocation(".my-env");

The command line flag --env-file will take precedence over this option.

setFfmpegExecutable()​

Allows you to use a custom FFMPEG binary. Must be an absolute path. By default, this is null and the FFMPEG in PATH will be used.

ts
Config.Rendering.setFfmpegExecutable("/path/to/custom/ffmpeg");
ts
Config.Rendering.setFfmpegExecutable("/path/to/custom/ffmpeg");

The command line flag --ffmpeg-executable will take precedence over this option.

setFfprobeExecutable()​

Allows you to use a custom ffprobe binary. Must be an absolute path. By default, this is null and the ffprobe in PATH will be used.

ts
Config.Rendering.setFfprobeExecutable("/path/to/custom/ffprobe");
ts
Config.Rendering.setFfprobeExecutable("/path/to/custom/ffprobe");

The command line flag --ffprobe-executable will take precedence over this option.

setEveryNthFrame()​

This option may only be set when rendering GIFs. It determines how many frames are rendered, while the other ones gets skipped in order to lower the FPS of the GIF.

For example, if the fps is 30, and everyNthFrame is 2, the FPS of the GIF is 15.

ts
Config.Rendering.setEveryNthFrame(2);
ts
Config.Rendering.setEveryNthFrame(2);

The command line flag --every-nth-frame will take precedence over this option.

setNumberOfGifLoops()​

This option may only be set when rendering GIFs. If it is set, it will limit the amount of times a GIF will loop. If set to 0, the GIF will play once, if set to 1, it will play twice. If set to null or not set at all, it will play forever.

ts
Config.Rendering.setNumberOfGifLoops(2);
ts
Config.Rendering.setNumberOfGifLoops(2);

The command line flag --number-of-gif-loops will take precedence over this option.

Output​

setOutputLocation()​

Available from v3.1.6

Set the output location of the video or still, relative to the current working directory. The default is out/{composition}.{container}. For example, out/HelloWorld.mp4.

ts
Config.Output.setOutputLocation("out/video.mp4");
ts
Config.Output.setOutputLocation("out/video.mp4");

If you pass another argument to the render command, it will take precedence: npx remotion render src/index.tsx HelloWorld out/video.mp4.

setOverwriteOutput()​

Set this to false to prevent overwriting Remotion outputs when they already exists.

ts
Config.Output.setOverwriteOutput(false);
ts
Config.Output.setOverwriteOutput(false);
info

In version 1.x, the default behavior was inverse - Remotion would not override by default.

setPixelFormat()​

Controls the pixel format in FFMPEG. Read more about it here. Acceptable values: yuv420p, yuv422p, yuv444p, yuv420p10le, yuv422p10le, yuv444p10le. Since v1.4, yuva420p is also supported for transparent WebM videos. Since v2.1.7, yuva444p10le is also supported for transparent ProRes videos Default value: yuv420p

ts
Config.Output.setPixelFormat("yuv420p");
ts
Config.Output.setPixelFormat("yuv420p");

The command line flag --pixel-format will take precedence over this option.

setCodec()​

Available from Version 1.4.

Choose one of the supported codecs: h264 (default), h265, vp8, vp9.

  • h264 is the classic MP4 file as you know it.
  • h265 is the successor of H264, with smaller file sizes. Also known as HEVC. Poor browser compatibility.
  • vp8 is the codec for WebM.
  • vp9 is the next-generation codec for WebM. Lower file size, longer compression time.
  • prores is a common codec if you want to import the output into another video editing program (available from v2.1.6)
  • mp3 will export audio only as an MP3 file (available from v2.0)
  • wav will export audio only as an WAV file (available from v2.0)
  • aac will export audio only as an AAC file (available from v2.0)
  • mkv will export using H264 codec, MKV container format and WAV audio codec. (available from v2.1.12)
ts
Config.Output.setCodec("h265");
ts
Config.Output.setCodec("h265");

The command line flag --codec will take precedence over this option.

See also: Encoding guide

setProResProfile()​

Available from Version 2.1.6.

Set the ProRes profile. This option is only valid if the codec has been set to prores. Possible values: 4444-xq, 4444, hq, standard, light, proxy. See here for explanation of possible values. Default: hq

ts
Config.Output.setProResProfile("4444");
ts
Config.Output.setProResProfile("4444");

The command line flag --prores-profile will take precedence over this option.

See also: Encoding guide, Transparent videos

setImageSequence()​

Available from Version 1.4.

Set to true if you want to output an image sequence instead of a video.

ts
Config.Output.setImageSequence(true);
ts
Config.Output.setImageSequence(true);

The command line flag --sequence will take precedence over this option.

setOutputFormat()​

Deprecated. Use setCodec() and setImageSequence() instead.

Either 'mp4' or 'png-sequence'.

ts
Config.Output.setOutputFormat("mp4");
ts
Config.Output.setOutputFormat("mp4");

The command line flags --sequence and --codec will take precedence over this option.

The command line flag --quality will take precedence over this option.

setCrf()​

Available from Version 1.4.

The "Constant Rate Factor" (CRF) of the output. Use this setting to tell FFMPEG how to trade off size and quality.

Ranges for CRF scale, by codec:

  • h264 crf range is 1-51 where crf 18 is default.
  • h265 crf range is 0-51 where crf 23 is default.
  • vp8 crf range is 4-63 where crf 9 is default.
  • vp9 crf range is 0-63 where crf 28 is default.

The lowest value is lossless, and the highest value is the worst quality possible. Higher values decrease the filesize at the cost of quality.

The range is exponential, so increasing the CRF value +6 results in roughly half the bitrate / file size, while -6 leads to roughly twice the bitrate.

Choose the highest CRF value that still provides an acceptable quality. If the output looks good, then try a higher value. If it looks bad, choose a lower value.

ts
Config.Output.setCrf(16);
ts
Config.Output.setCrf(16);

The command line flag --crf will take precedence over this option.

overrideFfmpegCommand​

available from v3.2.22

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
Config.Output.overrideFfmpegCommand(({ args }) => {
  return [...args, "-vf", "eq=brightness=0:saturation=1"];
});
tsx
Config.Output.overrideFfmpegCommand(({ args }) => {
  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.

See also​