How Caching Works in Remotion for High-Performance Video Rendering

Remotion implements a multi-layered caching strategy that stores decoded media assets, frame thumbnails, and computed properties in memory to eliminate redundant CPU work during video rendering and preview scrubbing.

Caching in Remotion is designed to minimize processing overhead when rendering React-based videos repeatedly across preview sessions and export jobs. The remotion-dev/remotion repository employs five distinct cache layers—from in-memory media buffers to LRU thumbnail stores—that work together to accelerate both the Studio preview and final video exports while maintaining memory safety.

The Five Layers of Caching in Remotion

Remotion’s caching architecture operates across multiple subsystems, each targeting a specific performance bottleneck in the rendering pipeline.

Media Asset Cache

The media cache stores decoded video, audio, and image assets that are referenced inside compositions via <Img> and <Video> tags. This cache lives in-memory on the Puppeteer page and is controlled by the window.remotion_mediaCacheSizeInBytes global variable.

The size limit is injected into the page by packages/renderer/src/set-props-and-env.ts (lines 29-30), which calls page.evaluateOnNewDocument to set:

window.remotion_mediaCacheSizeInBytes = cacheSizeInBytes;

When the cache reaches its byte limit, the underlying @remotion/media library automatically evicts older entries using an LRU (Least Recently Used) strategy. If no size is specified, Remotion defaults to approximately 150 MiB.

Frame Thumbnail Cache

During preview, Remotion maintains a 50 MiB LRU cache of low-resolution bitmaps for timeline thumbnails. This cache is implemented as an in-memory Map<string, Uint8Array> inside packages/renderer/src/frame-database.ts.

When the total cached data exceeds 50 MiB, the oldest entries are dropped to prevent memory exhaustion on large projects. This allows editors to scrub through timelines smoothly without re-rendering frames that were recently viewed.

Computed-Property Memoization

Remotion memoizes the results of pure helper functions to avoid redundant calculations. Utilities such as use-max-media-duration.ts and helpers/get-timeline-sequence-hash.ts use simple Map or WeakMap objects scoped to the current render job.

The first function call stores the result; subsequent calls read directly from the memoized cache. These memoization objects are recreated for each new render job, ensuring they never leak memory across separate runs.

BroadcastChannel Video-Frame Extraction

For off-thread video encoding, Remotion uses a BroadcastChannel to share decoded frames between the main page and background workers. Created in set-props-and-env.ts (lines 88-90) as new BroadcastChannel("remotion-video-frame-extraction"), this cache streams frames without a strict size limit—entries are discarded as soon as the encoder acknowledges receipt.

Studio UI Cache Settings

The Studio interface exposes real-time controls for tuning cache behavior. Components like RenderModal/WebRenderModalAdvanced.tsx render a slider that writes the selected mediaCacheSizeInBytes value into the render job payload, allowing developers to adjust performance parameters without restarting the CLI.

How Cache Configuration Propagates Through the System

Remotion follows a strict data flow to ensure cache settings are applied consistently across the rendering stack:

1. CLI or Studio UI – The user supplies --media-cache-size-in-bytes (defined in packages/renderer/src/options/video-cache-size.tsx) or leaves it null for the default.
2. Render Job Payload – The size is stored in RenderJob.mediaCacheSizeInBytes (see packages/studio-shared/src/render-job.ts).
3. Puppeteer Injection – The innerSetPropsAndEnv function in set-props-and-env.ts injects the value into the page context before any user code executes.
4. Media Loader Consumption – The @remotion/media package reads window.remotion_mediaCacheSizeInBytes and initializes its LRU cache accordingly.

Practical Code Examples

Setting the Media Cache Size from the CLI

Pass the byte limit directly to the render command:

remotion render MyVideo.tsx out.mp4 --media-cache-size-in-bytes 200000000

This flag populates RenderJob.mediaCacheSizeInBytes and ultimately sets the global window property in set-props-and-env.ts.

Accessing the Cache Size Inside a Component

Although rarely necessary, you can inspect the current limit at runtime:

import {useEffect} from 'react';

export const ShowCacheSize = () => {
  useEffect(() => {
    console.log('Current media cache limit (bytes):', 
      // @ts-ignore – injected by Remotion at runtime
      window.remotion_mediaCacheSizeInBytes);
  }, []);

  return null;
};

The value is guaranteed to be set before your component mounts.

Working with the Thumbnail Cache

The preview server exposes functions to interact with the 50 MiB LRU cache:

import {getThumbnail, storeThumbnail} from '@remotion/renderer';

// After rendering a frame:
const thumb = await renderFrame(...);
storeThumbnail(frameId, thumb);  // Stored in frame-database.ts cache

// When the UI requests a thumbnail:
const cached = getThumbnail(frameId); // Fast retrieval if present

Adjusting Cache Size in the Studio UI

The advanced render modal allows interactive tuning:

// Excerpt from WebRenderModalAdvanced.tsx
<Slider
  label="Custom @remotion/media cache size"
  min={0}
  max={500_000_000}
  step={10_000_000}
  value={mediaCacheSizeInBytes ?? defaultSize}
  onChange={v => setMediaCacheSizeInBytes(v === 0 ? null : v)}
/>

Changes are packed into the job payload and propagated through the same injection pipeline used by CLI flags.

Summary

• Multi-layered architecture: Remotion combines media decoding caches, thumbnail bitmap stores, function memoization, and BroadcastChannel streaming to minimize redundant work.
• Memory safety: The frame thumbnail cache is hard-limited to 50 MiB, while the media cache defaults to ~150 MiB but is user-configurable via window.remotion_mediaCacheSizeInBytes.
• Deterministic propagation: Cache settings flow from CLI flags → RenderJob → set-props-and-env.ts → Puppeteer page globals, ensuring consistent behavior across preview and export modes.
• Zero-config defaults: Caching operates automatically with sensible limits, but can be tuned or inspected via the Studio UI or environment variables.

Frequently Asked Questions

What is the default media cache size in Remotion?

If mediaCacheSizeInBytes is not specified via CLI or Studio UI, Remotion defaults to approximately 150 MiB. This value is used by the @remotion/media library to initialize its LRU cache for decoded video and audio assets.

How does Remotion prevent memory leaks when caching thumbnails?

The thumbnail cache in packages/renderer/src/frame-database.ts implements a strict 50 MiB LRU limit. When the cache exceeds this budget, the least-recently-used entries are automatically evicted. Additionally, computed-property memoization maps are recreated for each render job, ensuring isolated memory scopes.

Can I disable caching entirely in Remotion?

While there is no explicit "disable cache" flag, you can effectively disable the media cache by setting --media-cache-size-in-bytes 0. However, this is not recommended as it forces Remotion to re-decode video assets on every frame, significantly degrading performance.

Does caching affect the final video output quality?

No. Remotion’s caching layers store only intermediate computational data—decoded media frames, thumbnail bitmaps, and function results. The final video encoding process always uses the full-resolution source data, ensuring that cache settings do not impact output fidelity or color accuracy.

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