How to Control the Video Cache Size in Remotion: A Complete Guide

Control the video cache size in Remotion using the --media-cache-size-in-bytes and --offthreadvideo-cache-size-in-bytes CLI flags, or programmatically via BrowserSafeApis.options to optimize render performance and memory usage.

Remotion, the React framework for creating videos programmatically, provides granular control over memory management through configurable video caches. Whether you are rendering complex compositions locally or scaling up on Lambda, understanding how to control the video cache size in Remotion ensures efficient resource utilization without overwhelming system RAM.

Understanding Remotion's Video Cache Architecture

Remotion implements two distinct caching mechanisms to handle different media processing workflows. Each operates independently and can be sized separately according to your render requirements.

Media Cache for Video and Audio Components

The media cache supports the <Video> and <Audio> components from the @remotion/media package. It stores decoded video and audio frames that are streamed during a render process. By default, this cache allocates half of the available system memory at render start, represented internally as null.

According to the source code in packages/renderer/src/options/video-cache-size.tsx, the default behavior is defined as:

let mediaCacheSizeInBytes: number | null = null;

OffthreadVideo Cache for Frame Rendering

The OffthreadVideo cache specifically optimizes <OffthreadVideo> components by caching rendered frames sent to the off-thread video encoder. Like the media cache, it defaults to half of system memory (null), but serves a different architectural purpose by buffering pre-rendered frames rather than decoded media streams.

The implementation in packages/renderer/src/options/offthreadvideo-cache-size.tsx defines this separate variable:

let offthreadVideoCacheSizeInBytes: number | null = null;

How to Set the Video Cache Size via CLI

Remotion exposes both cache configurations as CLI flags that accept positive integers representing bytes, or null to use the default half-memory allocation.

To configure the media cache for standard Video and Audio components:

npx remotion render src/Video.jsx MyComposition out.mp4 \
  --media-cache-size-in-bytes=1073741824

To configure the OffthreadVideo cache specifically:

npx remotion render src/Video.jsx MyComposition out.mp4 \
  --offthreadvideo-cache-size-in-bytes=2147483648

You can combine both flags in a single command to optimize different aspects of the same render:

npx remotion render src/Video.jsx MyComposition out.mp4 \
  --media-cache-size-in-bytes=1073741824 \
  --offthreadvideo-cache-size-in-bytes=536870912

The CLI parsing logic resides in packages/cli/src/get-cli-options.ts, with specific extraction for still renders visible in packages/cli/src/still.ts at lines 96-100.

Controlling Video Cache Size Programmatically

For custom Node.js scripts using Remotion's APIs, you can configure cache sizes directly through the BrowserSafeApis client before invoking render functions.

import {renderMedia} from '@remotion/renderer';
import {BrowserSafeApis} from '@remotion/renderer/client';

// Allocate 2 GiB for media cache (Video/Audio components)
BrowserSafeApis.options.mediaCacheSizeInBytesOption.setConfig(2 * 1024 ** 3);

// Allocate 1 GiB for OffthreadVideo cache
BrowserSafeApis.options.offthreadVideoCacheSizeInBytesOption.setConfig(1 * 1024 ** 3);

await renderMedia({
  composition: 'MyComposition',
  serveUrl: 'http://localhost:3000',
  output: 'out.mp4',
  // Additional options...
});

To revert to the default behavior (half of system memory), explicitly pass null:

BrowserSafeApis.options.mediaCacheSizeInBytesOption.setConfig(null);

The setConfig methods modify the internal variables defined in packages/renderer/src/options/video-cache-size.tsx (line 45) and packages/renderer/src/options/offthreadvideo-cache-size.tsx (line 53).

Validation Rules and Constraints

Both cache size options enforce strict validation to prevent invalid configurations from reaching the Rust compositor. According to the validation logic in packages/renderer/src/options/offthreadvideo-cache-size.tsx (lines 58-82), the following constraints apply:

• The value must be a number or null
• If a number, it must be positive (greater than 0)
• The number must be a finite integer

Invalid values will throw runtime errors before the render process begins, protecting the underlying Rust cache allocator from malformed inputs.

How the Cache Size Flows Through the System

Understanding the data flow helps debug cache-related memory issues. When you specify a cache size, the value propagates through several architectural layers:

1. CLI/Programmatic Input: Values enter via flags or setConfig() calls
2. Options Map: Both options are registered in packages/renderer/src/options/options-map.ts, making them available to all render commands
3. Render Flow: Functions like renderMediaFlow and renderStillFlow receive the values as parameters
4. Offthread Video Server: In packages/renderer/src/offthread-video-server.ts, the cache size is forwarded to the Rust compositor process
5. Rust Compositor: The native layer in packages/compositor/rust/main.rs (line 58) logs the allocation: "Starting Rust process. Max video cache size: {}MB, max threads = {}" and creates a bounded in-memory cache for rendered frames

This architecture ensures that cache limits are respected across the JavaScript/TypeScript boundary and enforced at the native level where memory allocation actually occurs.

Summary

• Remotion provides two independent caches: the media cache for <Video>/<Audio> components and the OffthreadVideo cache for <OffthreadVideo> frames.
• Both default to half of available system memory (represented as null).
• Use --media-cache-size-in-bytes and --offthreadvideo-cache-size-in-bytes CLI flags to set specific byte limits.
• Programmatically configure caches via BrowserSafeApis.options.mediaCacheSizeInBytesOption.setConfig() and offthreadVideoCacheSizeInBytesOption.setConfig().
• Values must be positive integers or null; validation occurs before the Rust compositor initializes the bounded cache.

Frequently Asked Questions

What is the default video cache size in Remotion?

By default, both the media cache and the OffthreadVideo cache allocate half of the available system memory at the moment the render starts. This is represented internally as null rather than a specific byte value, allowing Remotion to dynamically calculate the limit based on current RAM availability.

Can I set different cache sizes for media and OffthreadVideo components?

Yes. Remotion treats these as separate caches with independent configuration options. You can set --media-cache-size-in-bytes for standard <Video> and <Audio> components while using --offthreadvideo-cache-size-in-bytes specifically for <OffthreadVideo> elements, allowing fine-grained memory management based on which components dominate your composition.

What happens if I set the video cache size too low?

Setting an insufficient cache size forces Remotion to evict frames from memory more frequently, potentially causing frame re-rendering or re-decoding that significantly slows export times. In extreme cases with very low limits, the render may fail or produce corrupted output if the compositor cannot allocate working memory for essential frames.

How do I check the current cache size being used?

When the Rust compositor initializes, it logs the configured cache size to stdout. Look for the message "Starting Rust process. Max video cache size: {}MB, max threads = {}" in your render logs (located in packages/compositor/rust/main.rs). Programmatically, you can verify your configuration by inspecting the values passed to renderMedia() or by checking the CLI flags in your command output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}