remotion-best-practices

name	remotion-best-practices
description	Best practices for Remotion - Video creation in React
metadata	{"tags":"remotion, video, react, animation, composition"}

Prerequisites

• Executor: Use the remotion executor (provides Node.js 20, Chromium, ffmpeg, yt-dlp, deno)
• Do NOT use npx create-video — it is interactive and will hang in automated environments

Project Initialization (Non-interactive)

npx create-video uses interactive prompts that cannot be bypassed. Instead, manually initialize:

# 1. Create project and install dependencies
mkdir -p my-video && cd my-video
npm init -y

# 2. Install Remotion core + common packages
npm install remotion @remotion/cli @remotion/media-utils react react-dom

# 3. Optional: 3D / Three.js support
npm install @remotion/three @react-three/fiber @react-three/drei @react-three/postprocessing three

# 4. Optional: Zod schemas for parametrizable videos
npm install @remotion/zod-types zod@3.22.3  # zod version must match @remotion/zod-types peer dep

Minimal project structure:

my-video/
├── package.json
├── remotion.config.ts    # Config.setVideoImageFormat("jpeg"); Config.setOverwriteOutput(true);
├── tsconfig.json
├── public/               # Static assets (audio, images)
└── src/
    ├── index.ts          # registerRoot(Root)
    ├── Root.tsx           # <Composition> definitions
    └── MyVideo.tsx        # Video component

Tip: The remotion executor pre-caches common npm packages at /opt/remotion-template/node_modules/. You can copy them to skip download:

cp -r /opt/remotion-template/node_modules ./node_modules

IMPORTANT — Do NOT run tsc or npx tsc:

• npx remotion render handles TypeScript compilation internally via esbuild — it is much faster and more lenient than tsc.
• Running tsc --noEmit will produce spurious type errors (missing module declarations, JSX issues) that are irrelevant to Remotion rendering.
• If you see TypeScript errors, ignore them and proceed directly to npx remotion render. Fix only errors reported by the renderer itself.

IMPORTANT — Project directory:

• Always create projects using relative paths (e.g., mkdir -p my-video && cd my-video). Do NOT use absolute paths like /app/workspace/ or /app/my-project/.
• The executor automatically sets the working directory to the correct workspace. Using absolute paths bypasses workspace isolation.

Rendering Performance

IMPORTANT: Always use these flags for maximum rendering speed:

# Standard render (2D content — no --gl needed)
npx remotion render src/index.ts MyComposition out/video.mp4 \
  --concurrency=16

# 3D content (Three.js / WebGL) — MUST use --gl=swangle
npx remotion render src/index.ts MyComposition out/video.mp4 \
  --concurrency=16 \
  --gl=swangle

In remotion.config.ts, always set high concurrency:

import { Config } from "@remotion/cli/config";

Config.setVideoImageFormat("jpeg");
Config.setOverwriteOutput(true);
Config.setConcurrency(16);      // Use 16 parallel browser tabs (NOT default 4)
// For 3D/WebGL content only:
Config.setChromiumOpenGlRenderer("swangle");  // SwiftShader software GL for headless containers

GL renderer for 3D/WebGL content:

• --gl=swangle — Required for 3D. Uses SwiftShader (bundled in Chrome). Works without GPU. Supports full concurrency=16.
• --gl=angle — Does NOT work in headless Docker without GPU. Do not use.
• Never omit --gl for Three.js content — default mode has no WebGL support in headless containers.

Segment rendering for long videos (>60s): Split into 30-second segments and render in parallel:

# Render segment (frames 0-899 = first 30s at 30fps)
npx remotion render src/index.ts MyComp out/seg_000.mp4 \
  --frames=0-899 --concurrency=16 --gl=swangle

# Merge all segments with ffmpeg
ffmpeg -y -f concat -safe 0 -i concat_list.txt -c copy out/final.mp4

When to use

Use this skills whenever you are dealing with Remotion code to obtain the domain-specific knowledge.

Captions

When dealing with captions or subtitles, load the ./rules/subtitles.md file for more information.

Using FFmpeg

For some video operations, such as trimming videos or detecting silence, FFmpeg should be used. Load the ./rules/ffmpeg.md file for more information.

Audio visualization

When needing to visualize audio (spectrum bars, waveforms, bass-reactive effects), load the ./rules/audio-visualization.md file for more information.

How to use

Read individual rule files for detailed explanations and code examples:

• rules/3d.md - 3D content in Remotion using Three.js and React Three Fiber
• rules/animations.md - Fundamental animation skills for Remotion
• rules/assets.md - Importing images, videos, audio, and fonts into Remotion
• rules/audio.md - Using audio and sound in Remotion - importing, trimming, volume, speed, pitch
• rules/calculate-metadata.md - Dynamically set composition duration, dimensions, and props
• rules/can-decode.md - Check if a video can be decoded by the browser using Mediabunny
• rules/charts.md - Chart and data visualization patterns for Remotion (bar, pie, line, stock charts)
• rules/compositions.md - Defining compositions, stills, folders, default props and dynamic metadata
• rules/extract-frames.md - Extract frames from videos at specific timestamps using Mediabunny
• rules/fonts.md - Loading Google Fonts and local fonts in Remotion
• rules/get-audio-duration.md - Getting the duration of an audio file in seconds with Mediabunny
• rules/get-video-dimensions.md - Getting the width and height of a video file with Mediabunny
• rules/get-video-duration.md - Getting the duration of a video file in seconds with Mediabunny
• rules/gifs.md - Displaying GIFs synchronized with Remotion's timeline