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

> Master Remotion video cache control with CLI flags or programmatic options. Optimize render performance and memory usage. Learn how to manage your cache effectively.

- Repository: [Remotion/remotion](https://github.com/remotion-dev/remotion)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/remotion-dev/remotion/blob/main/packages/renderer/src/options/video-cache-size.tsx), the default behavior is defined as:

```typescript
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`](https://github.com/remotion-dev/remotion/blob/main/packages/renderer/src/options/offthreadvideo-cache-size.tsx) defines this separate variable:

```typescript
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:

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

```

To configure the OffthreadVideo cache specifically:

```bash
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:

```bash
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`](https://github.com/remotion-dev/remotion/blob/main/packages/cli/src/get-cli-options.ts), with specific extraction for still renders visible in [`packages/cli/src/still.ts`](https://github.com/remotion-dev/remotion/blob/main/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.

```typescript
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`:

```typescript
BrowserSafeApis.options.mediaCacheSizeInBytesOption.setConfig(null);

```

The `setConfig` methods modify the internal variables defined in [`packages/renderer/src/options/video-cache-size.tsx`](https://github.com/remotion-dev/remotion/blob/main/packages/renderer/src/options/video-cache-size.tsx) (line 45) and [`packages/renderer/src/options/offthreadvideo-cache-size.tsx`](https://github.com/remotion-dev/remotion/blob/main/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`](https://github.com/remotion-dev/remotion/blob/main/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`](https://github.com/remotion-dev/remotion/blob/main/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`](https://github.com/remotion-dev/remotion/blob/main/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`](https://github.com/remotion-dev/remotion/blob/main/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`](https://github.com/remotion-dev/remotion/blob/main/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.