# Remotion — full corpus



<!-- ===== remotion/README.md ===== -->

# LLM Wiki

An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).

You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions.

## How It Works

The system has three layers:

```
raw/              Sources you collect (articles, transcripts, notes, PDFs)
wiki/             LLM-written & maintained pages (summaries, concepts, entities, syntheses)
CLAUDE.md         Schema that tells the LLM how to structure everything
```

Three operations drive the workflow:

| Operation | Trigger | What happens |
|-----------|---------|--------------|
| **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log |
| **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights |
| **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest |

## Quick Start

1. **Clone this repo**
   ```bash
   git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base
   cd my-knowledge-base
   ```

2. **Customize CLAUDE.md** for your domain
   - Update the Purpose section with your topic
   - Replace the placeholder tagging taxonomy with your own categories
   - Adjust confidence level descriptions if needed
   - Everything else (workflows, page formats, linking rules) works as-is

3. **Drop sources into `raw/`**
   - Text files, transcripts, articles, notes — any plain text
   - These are immutable once added; the LLM never modifies them

4. **Tell the LLM to ingest**
   ```
   ingest raw/my-first-source.txt
   ```
   The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index.

5. **Ask questions**
   ```
   What are the key differences between X and Y?
   ```
   The LLM answers from the wiki, citing specific pages.

6. **Run health checks**
   ```
   lint
   ```
   The LLM audits the wiki and fixes issues.

## Directory Structure

```
.
├── CLAUDE.md                      # Schema — the LLM's instructions
├── raw/                           # Your source documents (immutable)
└── wiki/
    ├── index.md                   # Master catalog of all pages
    ├── log.md                     # Append-only activity log
    ├── dashboard.md               # Dataview dashboard (Obsidian)
    ├── analytics.md               # Charts View analytics (Obsidian)
    ├── flashcards.md              # Spaced repetition cards
    ├── summaries/                 # One page per source document
    ├── concepts/                  # Concept and framework pages
    ├── entities/                  # People, tools, organizations, etc.
    ├── syntheses/                 # Cross-cutting analyses and comparisons
    ├── journal/                   # Research/session journal entries
    │   └── template.md            # Journal entry template
    └── presentations/             # Marp slide decks
```

## Enhancements

This template includes several extras beyond the core wiki pattern:

### Dataview Dashboard (`wiki/dashboard.md`)
Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin.

### Charts View Analytics (`wiki/analytics.md`)
Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin.

### Mermaid Diagrams
Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub.

### Marp Slides (`wiki/presentations/`)
Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory.

### Research Journal (`wiki/journal/`)
Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries.

### Spaced Repetition (`wiki/flashcards.md`)
Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page.

### MCP Server
This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically.

## Customizing for Your Domain

The schema in `CLAUDE.md` is domain-agnostic. To adapt it:

1. **Purpose** — Describe your knowledge domain in one paragraph
2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`)
3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards
4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.)
5. **Journal template** — Customize `wiki/journal/template.md` for your workflow

Everything else — page format, linking conventions, workflows, rules — is universal and works across domains.

## Example Domains

This template works for any knowledge-intensive topic:

- **Research notes** — papers, experiments, methodologies
- **Book analysis** — themes, characters, author techniques
- **Competitive analysis** — companies, products, market trends
- **Course notes** — lectures, readings, key concepts
- **Personal development** — frameworks, habits, book summaries
- **Technical documentation** — APIs, architectures, design patterns
- **Hobby deep-dives** — any subject you want to master

## License

MIT



<!-- ===== remotion/wiki/index.md ===== -->

---
title: "Remotion KB — Master Index"
type: index
updated: 2026-06-11
remotion_version: "4.0.475"
---

# Remotion KB — Master Index

Master catalog of all wiki pages. Every page in the wiki must have an entry here.

**Latest verified Remotion version:** 4.0.475 (2026-06-10); cadence ~1 release every 2 days
**KB pages:** 30 (13 concepts + 6 entities + 4 summaries + 5 syntheses + 2 system)

## Concepts (13)

### Authoring
- [[concepts/installation-setup]] — create-video, project structure, brownfield install, studio startup
- [[concepts/compositions-fundamentals]] — Composition/Sequence/Series, props flow, calculateMetadata, schemas, fonts
- [[concepts/animation]] — useCurrentFrame, interpolate, spring, easing, noise, deterministic randomness
- [[concepts/audio]] — audio tags, getAudioData, waveforms, sample rates
- [[concepts/video-media]] — OffthreadVideo vs Html5Video vs @remotion/media, images, assets, prefetch
- [[concepts/captions]] — @remotion/captions: parsing, transcribing, TikTok-style pages, display
- [[concepts/transitions]] — TransitionSeries, presentations, timings, overlays, audio behavior
- [[concepts/player]] — @remotion/player: embedding, props/ref API, events, autoplay policies

### Rendering & operations
- [[concepts/rendering-ssr]] — bundle/selectComposition/renderMedia, encoding, Docker, distributed rendering
- [[concepts/lambda]] — AWS Lambda rendering: setup/IAM, deploy, concurrency, cost, webhooks, limits
- [[concepts/cloudrun]] — GCP Cloud Run rendering (alpha): setup, deploy, limits
- [[concepts/cli-reference]] — npx remotion commands, config file, env vars, chromium flags
- [[concepts/licensing]] — free vs company license, cloud rendering units, who must pay

## Entities (6)

- [[entities/remotion-studio]] — the Studio: flags, props editing, render UI, deployment
- [[entities/framework-integrations]] — Angular, Figma, After Effects, Electron, Bun/Deno, React 18/19
- [[entities/packages-catalog]] — CATALOG: the ~45 @remotion/* package space mapped
- [[entities/lambda-api-catalog]] — CATALOG: every Lambda API function with signature essence
- [[entities/cloudrun-api-catalog]] — CATALOG: all 13 Cloud Run functions + light client
- [[entities/ai-integration]] — official llms.txt AI rules, remotion skills, agent prompting patterns

## Summaries (4)

- [[summaries/release-digest]] — v4.0.461–475 digest: effects system, Studio interactivity arcs
- [[summaries/casebook-rendering]] — solved cases: timeouts, delayRender, flicker, concurrency, ENAMETOOLONG
- [[summaries/casebook-platform]] — solved cases: Lambda/Cloud Run quotas, bundle-size walls, WSL, Safari player
- [[summaries/official-ai-rules]] — what remotion.dev/llms.txt mandates for AI-generated Remotion code

## Syntheses (5)

- [[syntheses/rendering-path-picker]] — CLI vs SSR vs Lambda vs Cloud Run: pick by volume and ops budget
- [[syntheses/media-tag-picker]] — which media component when, with the naming-history trap
- [[syntheses/performance-recipes]] — concurrency, GPU/hardware acceleration, prefetch, benchmark
- [[syntheses/cost-estimation]] — Lambda cost model, egress gotchas, license interplay
- [[syntheses/troubleshooting-checklist]] — signature→step triage and the 8-step sequence

## Gaps / TODO

- Per-presentation transition option docs (fade/wipe/slide/flip/clock-wipe option objects) not in raw/ — [[concepts/transitions]] confirms names only; fetch `packages/docs/docs/transitions/presentations/` next ingest.
- ~24 @remotion/* packages marked "(not yet ingested)" in [[entities/packages-catalog]] — per-item reference ring candidates if demand shows.
- No dollar pricing in license sources — [[concepts/licensing]] points to remotion.pro instead of inventing figures.
- Releases ship every ~2 days — re-verify [[summaries/release-digest]] and bump `remotion_version` each ingest. Remotion 5.0 is in migration-guide stage; re-check status next pass.

## Statistics

- **Total pages**: 30
- **Concepts**: 13
- **Entities**: 6
- **Summaries**: 4
- **Syntheses**: 5



<!-- ===== remotion/wiki/concepts/animation.md ===== -->

---
title: "Animation: Frames, Interpolation & Springs"
type: concept
tags: [animation, interpolate, spring, easing, noise, randomness]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-animating-properties-mdx.md", "raw/github_doc-packages-docs-docs-interpolate-mdx.md", "raw/github_doc-packages-docs-docs-spring-mdx.md", "raw/github_doc-packages-docs-docs-measure-spring-mdx.md", "raw/github_doc-packages-docs-docs-animation-math-mdx.md", "raw/github_doc-packages-docs-docs-noise-visualization-mdx.md", "raw/github_doc-packages-docs-docs-interpolate-colors-mdx.md", "raw/github_doc-packages-docs-docs-random-mdx.md"]
---

# Animation: Frames, Interpolation & Springs

## Definition

Animation in Remotion is a pure function of the frame number: `useCurrentFrame()` gives the current frame, and you derive every animated property from it. Two helpers do most of the work — `interpolate()` maps a value range to an output range (with easing and clamping), and `spring()` runs a physics simulation from 0 to 1. Because frames render concurrently across multiple headless browser tabs, anything time- or randomness-dependent must be deterministic per frame.

## How It Works

### The frame-driven model

A fade-in is just math on the frame: `const opacity = Math.min(1, frame / 60);`. The cardinal rule: **always animate using `useCurrentFrame()`** — CSS transitions and other wall-clock animations cause flickering during rendering because frames are captured out of order.

### `interpolate(input, inputRange, outputRange, options?)`

```ts
const opacity = interpolate(frame, [0, 60], [0, 1], {
  extrapolateRight: "clamp",
});
```

- **Multiple keyframes**: `interpolate(frame, [0, 20, durationInFrames - 20, durationInFrames], [0, 1, 1, 0])` fades in and out (`durationInFrames` from `useVideoConfig()`).
- **Any driver, not just time**: feed a spring into it — `interpolate(driver, [0, 1], [0, 200])` maps a 0→1 spring to 0→200px.
- **Extrapolation**: `extrapolateLeft` / `extrapolateRight` accept `extend` (default), `clamp`, `wrap`, `identity`. E.g. `interpolate(1.5, [0, 1], [0, 2], {extrapolateRight: 'clamp'}) // 2`.
- **Easing**: `easing: Easing.bezier(0.8, 0.22, 0.96, 0.65)` curves the progress within the active segment; from v4.0.462 pass an array with one easing per segment, e.g. `[Easing.out(Easing.cubic), Easing.in(Easing.cubic)]` for a 3-keyframe range (length must be `inputRange.length - 1`).
- **Posterize** (v4.0.470+): `posterize: 3` quantizes the input so frames 0–2 share frame 0's value — a stop-motion/sampled look.
- **CSS transform strings** (v4.0.472+): output ranges may be `scale`, `translate`, `rotate`, or `transformOrigin` strings, e.g. `translate: interpolate(frame, [0, 30], ['0px 0px', '100px 50px'])`. Units must match per component.
- **Numeric tuples** (v4.0.473+): output range entries can be same-length number tuples.
- Input and output ranges must have equal length; single-value ranges work from v4.0.469.

### `spring()` and `measureSpring()`

```ts
const value = spring({
  frame,
  fps,
  config: {
    stiffness: 100,
  },
});
```

Animates `from: 0` to `to: 1` by default; pass `fps` from `useVideoConfig()`. Config knobs: `mass` (default `1`, lower = faster), `damping` (default `10`, higher = less bounce), `stiffness` (default `100`, bounciness), `overshootClamping` (default `false`, caps at `to`). Timing knobs: `durationInFrames` stretches the curve to an exact length, `delay` holds the initial value for n frames, `reverse` plays backwards. Order of operations: stretch → reverse → delay. Delay can also be done manually via `frame - 20` as the `frame` argument.

`measureSpring({fps, config})` returns how many frames a spring needs to settle (e.g. `measureSpring({fps: 30, config: {damping: 200}}) // => 23`); `threshold` (default `0.005`) defines "settled" — lower threshold, longer measured duration. Use it to size sequences around a spring.

### Animation math

Spring values are plain numbers, so combine them arithmetically. The enter/exit idiom:

```ts
const enter = spring({fps, frame, config: {damping: 200}});
const exit = spring({fps, frame, config: {damping: 200}, durationInFrames: 20, delay: durationInFrames - 20});
const scale = enter - exit;
```

`enter` rises 0→1 at the start; `exit` rises 0→1 in the last 20 frames; their difference scales the element in and back out with one expression.

### Colors: `interpolateColors()`

`interpolateColors(frame, [0, 20], ['red', 'yellow'])` returns an `rgba()` string (e.g. `rgba(255, 128, 0, 1)`). Accepts hex, `rgb`/`rgba`, `hsl`/`hsla`, CSS color names, and (v4.0.439+) `oklch`, `oklab`, `lab`, `lch`, `hwb` with optional `/ alpha`. Options: `easing` (v4.0.475+, single function or per-segment array) and `posterize` (v4.0.470+).

### Noise and deterministic randomness

- `@remotion/noise` provides `noise3D(seed, x, y, z)` — use two dimensions for space and the third for time (`frame * speed`) to get organic motion like a floating dot grid; map its `[-1, 1]` output with `interpolate()`.
- `random(seed)` from `remotion` returns a deterministic pseudorandom number in `[0, 1)` for a `number` or `string` seed: `random(1) // 0.07301638228818774`, always. Seed per element (`random(`random-x-${i}`)`) for stable particle layouts. `Math.random()` triggers an ESLint warning because each render thread would see different values; if you truly want non-determinism, `random(null)` bypasses the warning.

## Key Parameters

- `interpolate()` options: `extrapolateLeft`, `extrapolateRight`, `easing`, `posterize`. Types `ExtrapolateType` and `InterpolateOptions` exported since v3.3.77.
- `spring()` args: `frame`, `fps`, `from`, `to`, `reverse`, `delay`, `durationInFrames`, `durationRestThreshold`, `config: {mass, damping, stiffness, overshootClamping}`.
- `measureSpring()` args: `fps`, `threshold`, `config`, `from`, `to`.
- `random()` arg: `number | string | null`.

## When To Use

- Linear/keyframed property changes → `interpolate()` with `clamp`.
- Natural, bouncy entrances and scale pops → `spring()`; flatten the bounce with `damping: 200`.
- Combined enter/exit on one element → animation math (`enter - exit`).
- Animated color shifts → `interpolateColors()`.
- Organic wobble, particles, generative art → `@remotion/noise` + `random(seed)`.

## Risks & Pitfalls

- **CSS transitions/animations flicker in renders** — never animate outside `useCurrentFrame()`.
- **Forgetting `extrapolateRight: 'clamp'`** lets values run past the output range (scale 2 at frame 40 for a `[0, 20] → [0, 1]` mapping).
- **`Math.random()` differs per render thread** — use `random(seed)`.
- **Springs overshoot by design** — values can exceed `to` briefly; use `overshootClamping: true` if that breaks layout.
- **Hardcoding spring length** — a spring's natural settle time depends on config and fps; measure with `measureSpring()` instead of guessing.
- **Per-segment easing array of wrong length** errors — must be `inputRange.length - 1`.

## Related Concepts

- [[concepts/compositions-fundamentals]] — `<Sequence>` shifts the frame that drives these helpers
- [[concepts/transitions]] — packaged scene-to-scene animations
- [[concepts/audio]] — driving animation from audio data
- [[syntheses/performance-recipes]] — keeping per-frame work cheap

## Sources

- raw/github_doc-packages-docs-docs-animating-properties-mdx.md — frame-driven model, flickering warning
- raw/github_doc-packages-docs-docs-interpolate-mdx.md — `interpolate()` full API incl. easing, posterize, CSS transforms
- raw/github_doc-packages-docs-docs-spring-mdx.md / -measure-spring-mdx.md — spring API and measurement
- raw/github_doc-packages-docs-docs-animation-math-mdx.md — enter/exit composition
- raw/github_doc-packages-docs-docs-interpolate-colors-mdx.md — color interpolation
- raw/github_doc-packages-docs-docs-noise-visualization-mdx.md — `noise3D()` technique
- raw/github_doc-packages-docs-docs-random-mdx.md — deterministic randomness



<!-- ===== remotion/wiki/concepts/audio.md ===== -->

---
title: "Audio: Playback, Analysis & Sample Rates"
type: concept
tags: [audio, visualization, media-utils, sample-rate, volume]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-html5-audio-mdx.md", "raw/github_doc-packages-docs-docs-get-audio-data-mdx.md", "raw/github_doc-packages-docs-docs-get-audio-duration-in-seconds-mdx.md", "raw/github_doc-packages-docs-docs-get-waveform-portion-mdx.md", "raw/github_doc-packages-docs-docs-sample-rate-mdx.md", "raw/github_doc-packages-docs-docs-audiobuffertodataurl-mdx.md"]
---

# Audio: Playback, Analysis & Sample Rates

## Definition

Audio in Remotion has two halves: **playback** — the `<Html5Audio>` component (previously called `<Audio>`; a newer `<Audio>` now lives in `@remotion/media`) embeds an audio file with frame-accurate volume, trimming, looping, and pitch control — and **analysis** — the `@remotion/media-utils` helpers (`getAudioData()`, `getWaveformPortion()`, `audioBufferToDataUrl()`) read waveform data for visualizations or synthesize audio. At render time, all sources are resampled to one output sample rate (48000 Hz by default).

## How It Works

### Playing audio with `<Html5Audio>`

```tsx
import {AbsoluteFill, Html5Audio, staticFile} from 'remotion';

export const MyVideo = () => {
  return (
    <AbsoluteFill>
      <Html5Audio src={staticFile('audio.mp3')} />
    </AbsoluteFill>
  );
};
```

Put files in `public/` and reference them with `staticFile()` (see [[concepts/video-media]] for asset importing). All Chrome-supported audio formats work. Volume can be static (`volume={0.5}`) or a per-frame function:

```tsx
<Html5Audio volume={(f) => interpolate(f, [0, 30], [0, 1], {extrapolateLeft: 'clamp'})} src={staticFile('voice.mp3')} />
```

Trim with `trimBefore` / `trimAfter` (frame numbers; v4.0.319+ — they replace the deprecated `startFrom`/`endAt`). At `fps: 30`, `trimBefore={60} trimAfter={120}` plays the file's 2s–4s range. Other controls: `loop`, `playbackRate` (reverse not supported; Chrome errors below `0.0625` or above `16`), `preservePitch` (default `true`, preview only), `toneFrequency` (`0.01`–`2`, render-only pitch shift), `muted` (can vary per frame, e.g. `muted={frame < 30}`), `audioStreamIndex` (zero-indexed, render-only, for multi-language streams), `loopVolumeCurveBehavior` (`"repeat"` default or `"extend"`), `pauseWhenBuffering` (default `false`, becomes `true` in 5.0), `acceptableTimeShiftInSeconds` (default seek threshold `0.45`s), `useWebAudioApi`, `onError`, `crossOrigin`, `name`, `showInTimeline`, and `delayRenderTimeoutInMilliseconds`/`delayRenderRetries`.

### Reading audio data for visualization

`getAudioData(src, options?)` from `@remotion/media-utils` loads an audio (or video) source and resolves to:

- `channelWaveforms: Float32Array[]` — one waveform per channel
- `sampleRate` — of the generated `AudioContext` (default `48000`), **not** of the file (browsers don't expose that)
- `durationInSeconds`, `numberOfChannels`, `resultId`, `isRemote`

Options: `sampleRate` (default `48000` since v4.0.121 — earlier versions used the device default, which was nondeterministic across machines) and `requestInit` (v4.0.458+, e.g. `{credentials: 'include'}` for authenticated files). Results are memoized per `src` until page reload. Prefer the `useAudioData()` hook to get state management and `delayRender()` for free; `visualizeAudio()` builds frequency-based visualizations (bass/mids/highs) on top.

`getWaveformPortion({audioData, startTimeInSeconds, durationInSeconds, numberOfSamples, channel?, outputRange?, normalize?})` compresses bulky waveform data into `numberOfSamples` bars of `{index, amplitude}` (amplitude 0–1) — ideal for simple volume-bar visualizations. `outputRange` is `'zero-to-one'` (default) or `'minus-one-to-one'`; `normalize` defaults to `true` (scales the peak to 1; it was accidentally `false` between v4.0.267 and v4.0.279).

### Audio duration

`getAudioDurationInSeconds(src)` resolves to the duration (e.g. `33.221`) by loading the file in an invisible `<audio>` tag — and unlike `getAudioData()`, it does not require CORS. **It is deprecated**: prefer `getMediaMetadata()` (Mediabunny), which is faster and supports more formats. To make a composition as long as its audio, feed the duration into `calculateMetadata()` (see [[concepts/compositions-fundamentals]]).

### Synthesizing audio: `audioBufferToDataUrl()`

Converts a Web Audio `AudioBuffer` into a Base64 data URL playable by `<Html5Audio>`. The documented pattern renders a C4 sine tone (261.63 Hz) with an `OfflineAudioContext`, wraps the work in `delayRender()`/`continueRender()`, and calls `cancelRender(err)` on failure.

### Sample rates

Remotion renders all audio at **48000 Hz** by default and resamples every source to the output rate (a 44100 Hz source gets upsampled). Override (v4.0.448+):

- `renderMedia({..., sampleRate: 44100})` or `renderMediaOnWeb({..., sampleRate: 44100})`
- CLI: `npx remotion render MyComp --sample-rate=44100`
- Config file: `Config.setSampleRate(44100)` (Studio/CLI default only)
- Studio render dialog → Audio tab
- Per composition: return `defaultSampleRate` from `calculateMetadata()` (lower priority than CLI/Studio settings)

Preview uses a 48000 Hz `AudioContext`; control it with `Config.setPreviewSampleRate()` or `npx remotion studio --preview-sample-rate=44100`.

## Key Parameters

- `<Html5Audio>`: `src`, `volume` (number or `(frame) => number`), `trimBefore`/`trimAfter`, `loop`, `playbackRate`, `toneFrequency`, `muted`, `audioStreamIndex`, `pauseWhenBuffering`.
- `getAudioData()`: `src`, `{sampleRate = 48000, requestInit}`.
- `getWaveformPortion()`: `numberOfSamples` controls visualization resolution; `channel` defaults to `0`.
- Output sample rate: `48000` default; `--sample-rate`, `sampleRate`, `defaultSampleRate`.

## When To Use

- Background music, voiceover, sound effects → `<Html5Audio>` inside a `<Sequence>` for timing.
- Waveform/volume bars → `getAudioData()` + `getWaveformPortion()`; frequency spectra → `visualizeAudio()`.
- Composition duration matched to a voiceover → media metadata + `calculateMetadata()`.
- Preserving source quality → match output sample rate to the source (`defaultSampleRate` via `calculateMetadata()`).
- Generated tones/procedural audio → `OfflineAudioContext` + `audioBufferToDataUrl()`.

## Risks & Pitfalls

- **CORS**: remote files used with `getAudioData()` must send CORS headers (Remotion's origin is usually `http://localhost:3000`); duration-only reads avoid CORS, or disable web security via Chromium flags during renders.
- **No audio track** → `getAudioData()` throws; pre-check server-side with `getVideoMetadata()` (`audioCodec === null`).
- **`<Html5Audio>` does not work in `@remotion/web-renderer`** (client-side rendering) — use `<Audio>` from `@remotion/media` there.
- **iOS Safari ignores volume** — it is always 1; volumes above 1 are possible since v4.0.279 (the old `allowAmplificationDuringRender` prop is deprecated).
- **Mixed sample rates can't be preserved** — one output rate per file is a container limitation; choose the majority or highest source rate.
- **Pitch/stream props are render-only**: `toneFrequency` and `audioStreamIndex` have no effect in preview.

## Related Concepts

- [[concepts/video-media]] — `staticFile()`, asset importing, media playback errors
- [[concepts/compositions-fundamentals]] — `calculateMetadata()` for duration and sample rate
- [[concepts/animation]] — `interpolate()` for volume ramps and audio-driven animation
- [[concepts/captions]] — transcribing audio into captions
- [[syntheses/media-tag-picker]] — choosing between audio/video components

## Sources

- raw/github_doc-packages-docs-docs-html5-audio-mdx.md — `<Html5Audio>` full prop reference
- raw/github_doc-packages-docs-docs-get-audio-data-mdx.md — `getAudioData()` API, CORS, caching
- raw/github_doc-packages-docs-docs-get-waveform-portion-mdx.md — waveform simplification
- raw/github_doc-packages-docs-docs-get-audio-duration-in-seconds-mdx.md — duration (deprecated API)
- raw/github_doc-packages-docs-docs-sample-rate-mdx.md — output sample rate behavior and overrides
- raw/github_doc-packages-docs-docs-audiobuffertodataurl-mdx.md — AudioBuffer-to-data-URL synthesis



<!-- ===== remotion/wiki/concepts/captions.md ===== -->

---
title: "Captions: Transcribing, Parsing & Display"
type: concept
tags: [captions, subtitles, srt, whisper, tiktok-style]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-captions-api-mdx.md", "raw/github_doc-packages-docs-docs-captions-caption-mdx.md", "raw/github_doc-packages-docs-docs-captions-parse-srt-mdx.md", "raw/github_doc-packages-docs-docs-captions-serialize-srt-mdx.md", "raw/github_doc-packages-docs-docs-captions-create-tiktok-style-captions-mdx.md", "raw/github_doc-packages-docs-docs-captions-importing-mdx.md", "raw/github_doc-packages-docs-docs-captions-transcribing-mdx.md", "raw/github_doc-packages-docs-docs-captions-displaying-mdx.md", "raw/github_doc-packages-docs-docs-captions-ensure-max-characters-per-line-m.md", "raw/github_doc-packages-docs-docs-captions-index-mdx.md"]
---

# Captions: Transcribing, Parsing & Display

## Definition

`@remotion/captions` (v4.0.216+, MIT-licensed — install with the package name `@remotion/captions`) standardizes subtitles around one data structure, the **`Caption`** type, so that transcribing, parsing, formatting, and exporting interoperate. The typical pipeline: transcribe audio (or parse an `.srt`) into `Caption[]`, group words into TikTok-style "pages" with `createTikTokStyleCaptions()`, then render each page in a `<Sequence>` with per-word highlighting.

## How It Works

### The `Caption` type

```tsx
import type {Caption} from '@remotion/captions';
```

Fields: `text` (the caption text), `startMs` / `endMs` (start and end in milliseconds), `timestampMs` (a singular timestamp — the `t_dtw` value when using Whisper.cpp, otherwise possibly the start/end average or undefined), and `confidence` (0–1 transcription confidence).

**Whitespace matters**: include a space in `text` before each word — spaces are the delimiters. When rendering, set `white-space: pre` on the caption container so they survive.

### Getting captions: transcription options

| | `@remotion/install-whisper-cpp` | `@remotion/whisper-web` | `@remotion/openai-whisper` | `@remotion/elevenlabs` |
|---|---|---|---|---|
| Environment | Server (Node.js) | Browser (WASM) | Cloud API | Cloud API |
| Speed | Fast (hardware-dependent) | Slow (WASM overhead) | Fast | Fast |
| Cost | Free | Free | Paid | Paid |
| Offline | Yes | Yes | No | No |
| Convert with | `toCaptions()` | `toCaptions()` | `openaiWhisperApiToCaptions()` | `elevenLabsTranscriptToCaptions()` |

You can also use your own caption format — the `Caption` type is recommended, not required (it also matches the paid Remotion Editor Starter and Animated Captions products).

### Importing and exporting SRT

`parseSrt({input})` takes the contents of a SubRip file as a string and returns `{captions}` — one `Caption` per cue with `confidence: 1` and `timestampMs` as the cue midpoint. Load a file from `public/` with `fetch(staticFile('subtitles.srt'))` inside a `useDelayRender()` flow: `continueRender(handle)` on success, `cancelRender(e)` on failure.

The inverse, `serializeSrt({lines})`, takes a **two-dimensional** array — each top-level item is one SRT line, second-level items are words concatenated without added spaces; the line's timestamps come from the first word's `startMs` and last word's `endMs`. Empty arrays are skipped. (`ensureMaxCharactersPerLine()` exists but is internal/undocumented for now.)

### TikTok-style pages

```tsx
const {pages} = createTikTokStyleCaptions({
  captions,
  combineTokensWithinMilliseconds: 1200,
});
```

Words closer together than `combineTokensWithinMilliseconds` merge into one page — a high value fits many words per page, a low value approaches word-by-word display. Each `TikTokPage` has `text`, `startMs`, `durationMs` (v4.0.261+), and `tokens: [{text, fromMs, toMs}]` with **absolute** millisecond times. Safe in browser, Node.js, and Bun.

### Displaying captions

1. **Fetch** `captions.json` (or parse SRT) under `useDelayRender()`.
2. **Page** them with `createTikTokStyleCaptions()` inside `useMemo`.
3. **Sequence** each page: `startFrame = (page.startMs / 1000) * fps`; end at the next page's start or `startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps`, whichever is sooner; skip pages with non-positive duration.
4. **Highlight the active word** inside the page component: convert the sequence-relative frame back to absolute time (`absoluteTimeMs = page.startMs + (frame / fps) * 1000`) and mark tokens where `token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs` (the example uses highlight color `#39E508` on white text, `fontSize: 80`, `whiteSpace: 'pre'`).

Polish: `fitText()` from `@remotion/layout-utils` auto-scales text to the video width; add enter/exit animation via [[concepts/animation]]; improve legibility with `WebkitTextStroke: '4px black'` plus `paintOrder: 'stroke'`.

## Key Parameters

- `combineTokensWithinMilliseconds` — the single most important knob; controls page-switch cadence (example value `1200`).
- `Caption.text` whitespace — leading space per word; render with `white-space: pre`.
- `parseSrt({input})` / `serializeSrt({lines})` — string in, string out; `lines` is `Caption[][]`.
- Token times (`fromMs`/`toMs`) are absolute; sequence frames are relative — convert deliberately.

## When To Use

- Social-format videos (Reels/TikTok/Shorts) with burned-in word-by-word captions → full pipeline above.
- Existing subtitle files → `parseSrt()` instead of transcribing.
- Generating `.srt` deliverables from edited captions → `serializeSrt()`.
- Choosing a transcription backend: local server and free → Whisper.cpp; zero infrastructure in-browser → whisper-web; fastest setup with budget → OpenAI or ElevenLabs APIs.

## Risks & Pitfalls

- **Omitting spaces before words** makes `createTikTokStyleCaptions()` merge everything into one line/page — the most common formatting bug.
- **Forgetting `white-space: pre`** collapses the spaces you carefully preserved.
- **Mixing absolute and relative time** when highlighting tokens — add `page.startMs` to the sequence-relative time.
- **Fetching captions without `delayRender()`** renders frames before data arrives; always pair with `continueRender`/`cancelRender`.
- **`serializeSrt()` adds no spaces between words** — your `Caption.text` whitespace must already be correct.

## Related Concepts

- [[concepts/compositions-fundamentals]] — `<Sequence>` timing that drives caption pages
- [[concepts/audio]] — the audio being transcribed
- [[concepts/animation]] — entrance/exit effects for caption pages
- [[entities/packages-catalog]] — where `@remotion/captions` and the Whisper packages sit in the ecosystem

## Sources

- raw/github_doc-packages-docs-docs-captions-api-mdx.md / -captions-index-mdx.md — package overview
- raw/github_doc-packages-docs-docs-captions-caption-mdx.md — `Caption` type
- raw/github_doc-packages-docs-docs-captions-parse-srt-mdx.md / -captions-serialize-srt-mdx.md — SRT round-trip
- raw/github_doc-packages-docs-docs-captions-importing-mdx.md — `.srt` import flow
- raw/github_doc-packages-docs-docs-captions-transcribing-mdx.md — transcription option comparison
- raw/github_doc-packages-docs-docs-captions-create-tiktok-style-captions-mdx.md — paging API
- raw/github_doc-packages-docs-docs-captions-displaying-mdx.md — display patterns and full example
- raw/github_doc-packages-docs-docs-captions-ensure-max-characters-per-line-m.md — internal API note



<!-- ===== remotion/wiki/concepts/cli-reference.md ===== -->

---
title: "Remotion CLI and Configuration File"
type: concept
tags: [cli, config, rendering, studio, tooling]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-cli-cli-mdx.md", "raw/github_doc-packages-docs-docs-cli-render-mdx.md", "raw/github_doc-packages-docs-docs-cli-still-mdx.md", "raw/github_doc-packages-docs-docs-cli-studio-mdx.md", "raw/github_doc-packages-docs-docs-cli-bundle-mdx.md", "raw/github_doc-packages-docs-docs-cli-compositions-mdx.md", "raw/github_doc-packages-docs-docs-cli-benchmark-mdx.md", "raw/github_doc-packages-docs-docs-cli-versions-mdx.md", "raw/github_doc-packages-docs-docs-cli-upgrade-mdx.md", "raw/github_doc-packages-docs-docs-cli-gpu-mdx.md", "raw/github_doc-packages-docs-docs-cli-ffmpeg-mdx.md", "raw/github_doc-packages-docs-docs-cli-ffprobe-mdx.md", "raw/github_doc-packages-docs-docs-config-mdx.md", "raw/github_doc-packages-docs-docs-env-variables-mdx.md", "raw/github_doc-packages-docs-docs-chromium-flags-mdx.md"]
---

# Remotion CLI and Configuration File

## Definition

The Remotion CLI (`@remotion/cli`) is the command-line interface for previewing, rendering and managing Remotion projects: `npx remotion <command>`. It is configured per-project through `remotion.config.ts`, with CLI flags taking precedence over config-file options. The config file applies **only** to CLI commands — never to the SSR APIs ([[concepts/rendering-ssr]]).

## How It Works

Run with `npx remotion` (npm), `yarn remotion`, `pnpm exec remotion`, or `bunx remotion`; inside an npm script the prefix is unneeded. `remotionb` runs the Bun version (v4.0.118+); `remotiond` the unsupported Deno experiment. Most commands take an optional entry point or Serve URL as first argument; if omitted, the entry point is auto-determined (or set via `Config.setEntryPoint('./src/index.ts')`).

Core commands:

- `npx remotion render <entry-point|serve-url>? <composition-id> <output-location>` — render video/audio. Omitting `composition-id` shows a picker; default output is the `out` folder. Example: `npx remotion render --codec=vp8 HelloWorld out/video.webm`.
- `npx remotion still <serve-url|entry-point>? [<composition-id>] [<output-location>]` — render one frame (`--frame`, `--image-format`, `--jpeg-quality`).
- `npx remotion studio <entry-point>?` (alias `preview`) — start [[entities/remotion-studio]].
- `npx remotion compositions <serve-url|entry-file>?` — print composition IDs (used for render-all scripts).
- `npx remotion bundle <serve-url|entry-file>?` (v4.0.89+) — create a Remotion Bundle; equivalent to the `bundle()` Node API.
- `npx remotion benchmark src/index.ts [composition-ids]` (v3.2.28+) — time renders across `--runs` and `--concurrencies`; comma-separate multiple IDs.
- `npx remotion versions` — print versions of all installed Remotion packages and check `zod`/`mediabunny` alignment; `npx remotion upgrade` — upgrade all Remotion packages (and compatible `mediabunny`) without touching other deps (preferred over `npm update`); `--version` pins a target.
- `npx remotion gpu --gl=angle` (v4.0.52+) — print how Chrome uses the GPU (e.g. "WebGL: Hardware accelerated"); output not for automated parsing.
- `npx remotion ffmpeg` / `npx remotion ffprobe` (v4.0+) — bundled FFmpeg/FFprobe 7.1 binaries supporting only Remotion's codecs (H.264, H.265, VP8, VP9, ProRes). Example: `npx remotion ffmpeg -i input.mp4 output.mp3`.

## Key Parameters

Render flags (selection): `--props` (file path preferred — inline JSON breaks on Windows shells), `--codec` (`h264` default; `h265`, `av1`, `png`, `vp8`, `vp9`, `mp3`, `aac`, `wav`, `prores`, `h264-mkv`), `--crf` (cannot combine with `--video-bitrate` or hardware acceleration), `--video-bitrate`/`--audio-bitrate`, `--audio-codec`, `--prores-profile`, `--jpeg-quality` (0–100; renamed from `--quality` in v4.0.0), `--scale` (>0 to ≤16, default 1), `--frames`, `--every-nth-frame` + `--number-of-gif-loops` (GIFs, see [[concepts/rendering-ssr]]), `--sequence` (image sequence), `--muted`, `--enforce-audio-track`, `--concurrency`, `--timeout` (delayRender timeout in ms, default `30000` — not the Lambda function timeout), `--log` (`error`/`warn`/`info` default/`verbose`), `--overwrite` (on by default), `--output`, `--gl`, `--hardware-acceleration` (v4.0.228+), `--width`/`--height`/`--fps`/`--duration` overrides.

Chromium flags (since 2.6.5), each available as CLI flag, `chromiumOptions` in Node APIs, and config setter: `--disable-web-security` (`Config.setChromiumDisableWebSecurity(true)`; Remotion auto-appends `--user-data-dir`), `--ignore-certificate-errors` (`Config.setChromiumIgnoreCertificateErrors(true)`), `--gl=swiftshader|angle|...` (`Config.setChromiumOpenGlRenderer()`), deprecated `--disable-headless`.

Config file — create `remotion.config.ts` in the project root, import `{Config}` from `@remotion/cli/config`:

```ts
import {Config} from '@remotion/cli/config';

Config.setConcurrency(8);
Config.setPixelFormat('yuv444p');
Config.setCodec('h265');
```

Other setters: `overrideWebpackConfig()` (custom Webpack), `setCachingEnabled()`, `setStudioPort()`/`setRendererPort()`, `setPublicDir()`, `setBundleOutDir()`, `setEntryPoint()`, `setLogLevel()`, `setMaxTimelineTracks()` (Studio timeline display, default 15), `setKeyboardShortcutsEnabled()`, benchmark setters. Matching CLI flags always take precedence.

Environment variables: CLI-passed vars must be prefixed `REMOTION_` (security: prevents bundling your whole environment); read in components via `process.env.REMOTION_MY_VAR`. The CLI auto-reads `.env` and `.env.local` from the Remotion root (since v4.0.110); Node APIs do **not** — pass `envVariables` to `renderMedia()` (and never use it for AWS credentials). Studio honors `BROWSER`, `BROWSER_ARGS`, `BROWSER=none`.

Studio-specific flags: `--port`, `--no-open`, `--browser`, `--browser-args="--disable-web-security"`, `--beep-on-finish` (v4.0.84+), `--disable-keyboard-shortcuts`, `--webpack-poll`, `--ipv4`, `--disable-ask-ai`, `--force-new`, `--public-license-key`, `--experimental-rspack`.

## When To Use

The CLI is the default dev loop: `studio` while authoring, `render`/`still` for one-off output, `compositions` + shell loop for batch renders, `benchmark` to pick a concurrency, `gpu` to verify acceleration, `versions`/`upgrade` for maintenance. For programmatic or server use, switch to the Node APIs ([[concepts/rendering-ssr]]) — and remember the config file stops applying there. Lambda and Cloud Run have their own subcommands (`npx remotion lambda ...`, `npx remotion cloudrun ...` — see [[concepts/lambda]], [[concepts/cloudrun]]).

## Risks & Pitfalls

- `remotion.config.ts` silently ignored by SSR/Lambda APIs — the single most common configuration confusion.
- Inline `--props='{"json":"..."}'` fails on Windows shells (quote stripping); pass a file path.
- Mixed package versions break projects — `npx remotion versions` to diagnose, `npx remotion upgrade` to fix; avoid blanket `npm update`.
- Two different `--timeout` flags exist (frame delayRender vs Lambda function deploy) — easy to confuse.
- The bundled FFmpeg understands only Remotion-supported codecs; it is not a general-purpose FFmpeg build.
- `--crf` and `--video-bitrate` are mutually exclusive; hardware acceleration forbids CRF entirely.
- Unprefixed env vars are deliberately not bundled — `MY_VAR` works only via `.env`, not the CLI command line.

## Related Concepts

- [[concepts/rendering-ssr]] — Node API equivalents (`bundle()`, `renderMedia()`) and encoding details
- [[entities/remotion-studio]] — what `npx remotion studio` launches
- [[concepts/lambda]] / [[concepts/cloudrun]] — cloud subcommands
- [[concepts/installation-setup]] — scaffolding (`npx create-video@latest`)
- [[syntheses/performance-recipes]] — concurrency, GPU and benchmark workflow
- [[syntheses/troubleshooting-checklist]] — flag-related failure modes

## Sources

- `raw/github_doc-packages-docs-docs-cli-cli-mdx.md` — invocation, runtimes, command list
- `raw/github_doc-packages-docs-docs-cli-render-mdx.md`, `raw/github_doc-packages-docs-docs-cli-still-mdx.md`, `raw/github_doc-packages-docs-docs-cli-studio-mdx.md`, `raw/github_doc-packages-docs-docs-cli-bundle-mdx.md`, `raw/github_doc-packages-docs-docs-cli-compositions-mdx.md`, `raw/github_doc-packages-docs-docs-cli-benchmark-mdx.md`, `raw/github_doc-packages-docs-docs-cli-versions-mdx.md`, `raw/github_doc-packages-docs-docs-cli-upgrade-mdx.md`, `raw/github_doc-packages-docs-docs-cli-gpu-mdx.md`, `raw/github_doc-packages-docs-docs-cli-ffmpeg-mdx.md`, `raw/github_doc-packages-docs-docs-cli-ffprobe-mdx.md` — per-command references
- `raw/github_doc-packages-docs-docs-config-mdx.md`, `raw/github_doc-packages-docs-docs-env-variables-mdx.md`, `raw/github_doc-packages-docs-docs-chromium-flags-mdx.md` — configuration layers



<!-- ===== remotion/wiki/concepts/cloudrun.md ===== -->

---
title: "Remotion Cloud Run: Rendering on GCP (Alpha)"
type: concept
tags: [cloudrun, gcp, cloud-rendering, serverless, alpha]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-cloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-setup-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-status-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-limits-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-permissions-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-region-selection-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-checklist-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-deployservice-mdx.md"]
---

# Remotion Cloud Run: Rendering on GCP (Alpha)

## Definition

Remotion Cloud Run (`@remotion/cloudrun`) renders Remotion videos and stills on GCP Cloud Run. A containerized service (built from a Remotion-published Docker image) opens your deployed Remotion project from a Cloud Storage bucket and renders it. **Status: Alpha, not actively being developed** — critical bugs are fixed, but no new features are added; it was never marked production-ready and lacks many features compared to [[concepts/lambda]]. The plan is to adapt the Lambda runtime to also power Cloud Run in a future package.

## How It Works

- **Deployment**: every Remotion release publishes a new image to a publicly readable GCP Artifact Registry; deploying a service pulls the latest (or a pinned) image. A service is bound to the Remotion version — upgrading Remotion requires deploying a new service.
- **Rendering**: a Cloud Run service and a Cloud Storage bucket are created; your Remotion project is deployed to the bucket as a website; the service gets invoked, opens the project, renders, and uploads the output to Cloud Storage.
- Unlike Lambda's chunked fan-out, a render runs on a single service instance; by default each request gets its own instance (concurrency 0/1).

Architecture: **Cloud Run service** (binaries + JS behind a URL), **Cloud Storage bucket**, **CLI** (`npx remotion cloudrun`), **Node.JS API** (catalog in [[entities/cloudrun-api-catalog]]).

**Setup (verbatim core)**: 1) install `@remotion/cloudrun`; 2) create a GCP project; 3) enable billing; 4) in Cloud Shell run the installer, which provisions APIs/permissions/Service Account via Terraform and generates a `.env`:

```bash
curl -L https://github.com/remotion-dev/remotion/raw/main/packages/cloudrun/src/gcpInstaller/gcpInstaller.tar | tar -x -C . && node install.mjs
```

Copy the printed env vars to your local `.env`, then `rm .env` on the VM. 5) validate with `npx remotion cloudrun permissions`; 6) deploy a service: `npx remotion cloudrun services deploy` or `deployService({projectID, region})`; 7) deploy a site: `npx remotion cloudrun sites create src/index.ts --site-name=my-video` or `getOrCreateBucket()` + `deploySite({bucketName, entryPoint, siteName})` — same `siteName` overwrites on redeploy; 8) render:

```bash
npx remotion cloudrun render <serve-url | site-name> <composition-id> --cloud-run-url=<cloud-run-url>
# or
npx remotion cloudrun render <serve-url | site-name> <composition-id> --service-name=<service-name> --region=<region>
```

Programmatically: `getServices({region, compatibleOnly: true})` then `renderMediaOnCloudrun({serviceName, region, serveUrl, composition, inputProps, codec, updateRenderProgress})` / `renderStillOnCloudrun(...)`. Import from `@remotion/cloudrun/client` to avoid bundling the whole renderer.

## Key Parameters

- **`deployService()`**: `memoryLimit` (default recommendation 2GiB; min `512MiB`, max `32GiB`; cost proportional to RAM), `cpuLimit` (default 1, max 8 vCPUs; min memory/CPU pairings apply), `timeoutSeconds` (must be below 3600), `minInstances` (default 0 — billable even when idle if raised), `maxInstances` (default 100), `projectID`, `region`, `onlyAllocateCpuDuringRequestProcessing` (v4.0.221+, sets `cpu_idle: true` for significant savings). Idempotent like Lambda's `deployFunction()`. Returns `fullName`, `shortName`, `uri`, `alreadyExists`.
- **Limits** (GCP quotas): memory max 32GB; vCPUs max 8; timeout max 60 minutes; instance limit 100 by default (quota increase requestable per region via IAM → Quotas; answer "0" for concurrent-request support). Output file size is constrained by memory (in-memory filesystem), minus Remotion's supporting software.
- **Regions**: default `us-east1`. Select via explicit `region` argument (Node APIs — env var/flag have no effect there), `REMOTION_GCP_REGION` env var, or `--region` flag (flag wins). Keep service and bucket in the same region; regions fall into two pricing tiers, some with low-CO₂ electricity. List with `npx remotion cloudrun regions` / `getRegions()`.
- **Permissions**: a custom role "Remotion API Service Account" is assigned to the Remotion Service Account by the installer; print the version-matched permission list with `npx remotion cloudrun permissions`, or validate programmatically with `testPermissions()`.

## When To Use

Use Cloud Run only if you must stay on GCP and are satisfied with what it currently offers (official guidance). For everything else, prefer [[concepts/lambda]] (faster via parallelization, actively developed) or plain [[concepts/rendering-ssr]]. Decision matrix: [[syntheses/rendering-path-picker]]. One relative advantage: 60-minute timeout and up to 32GB memory on a single instance, versus Lambda's 15-minute/10GB chunked model.

## Risks & Pitfalls

- **Alpha + frozen development** is the headline risk: no new features, feature gap vs Lambda will persist until the planned shared runtime ships.
- Render single-threaded per instance: no chunk concurrency; >100 simultaneous renders returns **503 service unavailable** unless you raise `maxInstances`/quota.
- Production checklist (official): tune memory down to the reliability floor (cost is proportional); renders are **publicly accessible by default** — set `privacy` on `renderMediaOnCloudrun()`/`renderStillOnCloudrun()`; rate-limit user-triggered renders; measure and adjust the timeout; keep Service Account permissions minimal; companies with more than 3 people need cloud rendering seats ([[concepts/licensing]]).
- Raising `minInstances` above 0 bills you for idle instances.
- Changing service concurrency above 1 (via GCP console "Edit and Deploy New Revision") is untested by the Remotion team.
- Version skew: services are version-bound; after upgrading Remotion, redeploy the service or `compatibleOnly: true` will filter it out.

## Related Concepts

- [[entities/cloudrun-api-catalog]] — full API function list
- [[concepts/lambda]] — the recommended, actively developed cloud path
- [[concepts/rendering-ssr]] — self-hosted fallback
- [[concepts/licensing]] — cloud rendering seats
- [[syntheses/rendering-path-picker]], [[syntheses/cost-estimation]]
- [[summaries/casebook-platform]] — GCP deployment issue reports

## Sources

- `raw/github_doc-packages-docs-docs-cloudrun-mdx.md` — overview, architecture, quotas
- `raw/github_doc-packages-docs-docs-cloudrun-status-mdx.md` — alpha status and rationale
- `raw/github_doc-packages-docs-docs-cloudrun-setup-mdx.md` — full setup/deploy/render flow
- `raw/github_doc-packages-docs-docs-cloudrun-deployservice-mdx.md` — service parameters
- `raw/github_doc-packages-docs-docs-cloudrun-limits-mdx.md`, `raw/github_doc-packages-docs-docs-cloudrun-region-selection-mdx.md`, `raw/github_doc-packages-docs-docs-cloudrun-permissions-mdx.md`, `raw/github_doc-packages-docs-docs-cloudrun-checklist-mdx.md` — operations and production guidance



<!-- ===== remotion/wiki/concepts/compositions-fundamentals.md ===== -->

---
title: "Compositions: Timing, Props & Metadata"
type: concept
tags: [composition, sequence, series, props, schemas, metadata, fonts]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-composition-mdx.md", "raw/github_doc-packages-docs-docs-sequence-mdx.md", "raw/github_doc-packages-docs-docs-sequences-mdx.md", "raw/github_doc-packages-docs-docs-series-mdx.md", "raw/github_doc-packages-docs-docs-how-props-flow-mdx.md", "raw/github_doc-packages-docs-docs-calculate-metadata-mdx.md", "raw/github_doc-packages-docs-docs-dynamic-metadata-mdx.md", "raw/github_doc-packages-docs-docs-schemas-mdx.md", "raw/github_doc-packages-docs-docs-parameterized-rendering-mdx.md", "raw/github_doc-packages-docs-docs-passing-props-mdx.md", "raw/github_doc-packages-docs-docs-folder-mdx.md", "raw/github_doc-packages-docs-docs-fonts-mdx.md", "raw/github_doc-packages-docs-docs-font-picker-mdx.md"]
---

# Compositions: Timing, Props & Metadata

## Definition

A **composition** is a renderable video registered with `<Composition>`: a React component plus fixed metadata (`id`, `fps`, `durationInFrames`, `width`, `height`). Inside it, `<Sequence>` time-shifts content and `<Series>` plays scenes back-to-back. Data flows in as **props** — default props, overridable input props, and an optional `calculateMetadata()` transform that can also make duration/dimensions dynamic.

## How It Works

### Registering a composition

```tsx
<Composition component={Component} durationInFrames={300} width={1080} height={1080} fps={30} id="test-render" defaultProps={{}} />
```

Pass either `component` directly **or** `lazyComponent={() => import('./LazyComponent')}` (neither or both is an error; `lazyComponent` requires a default export and uses React Suspense). Wrap a `<Composition>` in `<Folder name="Visuals">` to group it in the Studio sidebar — folders are purely visual, nestable, and names allow only `a-z`, `A-Z`, `0-9` and `-`.

### Time-shifting with `<Sequence>`

A `<Sequence from={30} durationInFrames={30}>` mounts its children only during frames 30–59, and children calling `useCurrentFrame()` see a value shifted by `from` (at absolute frame 30, the child sees frame 0). This is the core reuse mechanism: the same `<Title>` component can appear twice at different times. Patterns:

- **Delay**: `<Sequence from={30}>`
- **Trim end**: finite `durationInFrames` unmounts children afterward
- **Trim start**: negative `from` (e.g. `from={-15}`) skips the first 15 frames of the content
- **Trim and delay**: nest `<Sequence from={30}><Sequence from={-15}>...` — nested sequences cascade (a sequence at 60 inside one at 30 starts at 90)

Children are wrapped in an `<AbsoluteFill>` by default; pass `layout="none"` to opt out (required inside `@remotion/three`'s `<ThreeCanvas>`).

### Sequential scenes with `<Series>`

```tsx
<Series>
  <Series.Sequence durationInFrames={40}>...</Series.Sequence>
  <Series.Sequence durationInFrames={20}>...</Series.Sequence>
</Series>
```

Each `<Series.Sequence>` needs a positive `durationInFrames` (only the last may be `Infinity`). `offset` shifts a segment: positive creates a gap, negative overlaps it with the previous scene and shifts everything after. Since v4.0.443, `<Series>` is a `<Sequence>` under the hood (its `layout` defaults to `"none"`; `<Series.Sequence>` defaults to `"absolute-fill"`).

### How props flow

Three inputs resolve into the final props your component receives:

1. **Default props** — `defaultProps` on `<Composition>`; the design-time fallback, editable in the Studio sidebar.
2. **Input props** — passed at render time via `--props='{"propOne": "Hi", "propTwo": 10}'` (inline JSON or a JSON file path), the `inputProps` option of `renderMedia()`/`renderMediaOnLambda()` (pass it to both `selectComposition()` and `renderMedia()`), or the Studio render dialog. Input props override default props.
3. **`calculateMetadata()`** — may transform the merged props (e.g. data fetching) before they reach the component.

Components remain normal React components: you can still render `<MyComponent propOne="hi" propTwo={10} />` directly, e.g. to chain scenes in a `<Series>` and register the master as another composition. In the root component, use `getInputProps()` to read input props.

### Schemas and parameterized rendering

Install with `npx remotion add @remotion/zod-types zod`, define a Zod schema with `z.object()`, type the component with `React.FC<z.infer<typeof myCompSchema>>`, and attach it via the `schema` prop on `<Composition>` — Remotion then requires matching `defaultProps` and enables visual prop editing in the Studio. The top-level type must be a `z.object()`; `@remotion/zod-types` adds extras like `zColor()`, `zTextarea()`, `zMatrix()`.

### Dynamic metadata with `calculateMetadata()`

Available from v4.0. The callback receives `{props, defaultProps, abortSignal, compositionId, isRendering}` and may return (all optional): `props`, `durationInFrames`, `width`, `height`, `fps`, `defaultCodec`, `defaultOutName`, `defaultVideoImageFormat`, `defaultPixelFormat`, `defaultProResProfile`, `defaultSampleRate`. Typical use — align composition duration with a source video:

```tsx
calculateMetadata={async ({props}) => {
  const {durationInSeconds} = await getMediaMetadata(props.src);
  return {
    durationInFrames: Math.floor(durationInSeconds * 30),
  };
}}
```

It runs **once** per render regardless of concurrency, may be `async`, must resolve within the `delayRender()` timeout, and must return pure JSON-serializable values (plus `Date`, `Map`, `Set`, `staticFile()`). CLI overrides like `--width` beat `calculateMetadata()`; `--scale` has the highest priority.

### Fonts

- **Google Fonts, type-safe**: `import {loadFont} from "@remotion/google-fonts/TitanOne"` then `const {fontFamily} = loadFont("normal", {weights: ["400"], subsets: ["latin"]})`.
- **Google Fonts via CSS**: `@import url("https://fonts.googleapis.com/css2?family=Bangers");` — Remotion waits for fonts automatically since v2.2.
- **Local fonts**: `@remotion/fonts` `loadFont({family, url: staticFile("Inter-Regular.woff2"), weight: "500"})` (v4.0.164+), or the native `FontFace` API wrapped in `delayRender()`/`continueRender()`.
- **Font picker**: `getAvailableFonts()` from `@remotion/google-fonts` (ES Module import only) lists ~1400 fonts; `.load()` then `loadFont()`/`getInfo()` per font. Curate a top-25/100/250 subset to cut bundle size; the font must also be loaded inside the video for rendering.

## Key Parameters

- `<Composition>`: `id` (letters, numbers, `-` only), `fps`, `durationInFrames`, `width`, `height`, `component`/`lazyComponent`, `defaultProps`, `schema`, `calculateMetadata`.
- `<Sequence>`: `from` (default 0), `durationInFrames` (default `Infinity`), `layout`, `name` (timeline label), `width`/`height` (override `useVideoConfig()`), `premountFor` (default changes from `0` to `fps` in v5.0), `postmountFor`, `showInTimeline`, `hidden` (v4.0.462+).
- `<Series.Sequence>`: `durationInFrames` (required-positive except last), `offset`, `layout`, `premountFor`, `ref` (`HTMLDivElement`).

## When To Use

- Multiple renderable videos in one project → one `<Composition>` each; group with `<Folder>`.
- Scenes back-to-back → `<Series>`; overlapping/free-form timing → `<Sequence>`.
- Personalized/templated videos → default props + schema for Studio editing, input props at render time, `calculateMetadata()` for data fetching and duration matched to data. See [[concepts/rendering-ssr]] for the render-side APIs.

## Risks & Pitfalls

- **Props must be JSON-serializable** — functions and classes are silently lost at render (the [[concepts/player]] is the exception). `Date`, `Map`, `Set`, `staticFile()` are safe. Type `defaultProps` with a `type`, not an `interface`; huge `defaultProps` payloads slow things down.
- **The `useEffect()` + `delayRender()` pattern for dynamic duration is deprecated** since v4.0: effects re-run in every render worker, multiplying API calls and risking rate limits. Use `calculateMetadata()` instead.
- **`calculateMetadata()` re-executes on every Studio prop change** — use the provided `abortSignal` to cancel stale requests.
- **Starting the Studio with `--props` overrides sidebar edits** and is not recommended.
- **Only the last `<Series.Sequence>` may have `Infinity` duration**; forgetting this errors.
- **`getAvailableFonts()` from CommonJS throws** on font load — ES Module import only.

## Related Concepts

- [[concepts/installation-setup]] — where compositions get registered (`registerRoot()`)
- [[concepts/animation]] — `useCurrentFrame()` drives animation inside sequences
- [[concepts/video-media]] — embedding media whose duration drives `calculateMetadata()`
- [[concepts/transitions]] — `TransitionSeries` as an alternative to `<Series>`
- [[concepts/player]] — dynamic metadata with the `<Player>`
- [[entities/remotion-studio]] — visual prop editing, timeline, sidebar folders

## Sources

- raw/github_doc-packages-docs-docs-composition-mdx.md — `<Composition>` props
- raw/github_doc-packages-docs-docs-sequence-mdx.md / -sequences-mdx.md — `<Sequence>` API and reuse patterns
- raw/github_doc-packages-docs-docs-series-mdx.md — `<Series>` API
- raw/github_doc-packages-docs-docs-how-props-flow-mdx.md / -passing-props-mdx.md / -parameterized-rendering-mdx.md — props resolution
- raw/github_doc-packages-docs-docs-schemas-mdx.md — Zod schemas
- raw/github_doc-packages-docs-docs-calculate-metadata-mdx.md / -dynamic-metadata-mdx.md — dynamic metadata
- raw/github_doc-packages-docs-docs-folder-mdx.md — `<Folder>`
- raw/github_doc-packages-docs-docs-fonts-mdx.md / -font-picker-mdx.md — fonts



<!-- ===== remotion/wiki/concepts/installation-setup.md ===== -->

---
title: "Installation & Project Setup"
type: concept
tags: [setup, getting-started, project-structure, studio, brownfield]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-getting-started-mdx.md", "raw/github_doc-packages-docs-docs-remotion-mdx.md", "raw/github_doc-packages-docs-docs-register-root-mdx.md", "raw/github_doc-packages-docs-docs-brownfield-installation-mdx.md", "raw/github_doc-readme-md.md"]
---

# Installation & Project Setup

## Definition

Remotion is a framework for creating videos programmatically using React: you express frames as React components and Remotion turns them into video. There are two ways to start — scaffold a fresh project with `npx create-video@latest`, or install Remotion into an existing app ("brownfield"). Either way, every Remotion project boils down to an **entry point** that calls `registerRoot()` with a **root component** that returns one or more `<Composition>` elements.

## How It Works

### Scaffolding a new project

The fastest path, including TailwindCSS, the blank template, and Agent Skills:

```sh
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npx remotion skills add
npm run dev
```

Running `npx create-video@latest` without flags launches a wizard where you pick a template (Hello World is recommended for a first project), and toggle Tailwind and Agent Skills. Package-manager equivalents: `pnpm create video`, `yarn create video`, `bun create video` (Bun as a runtime is mostly supported).

For coding agents (Claude Code, Codex, OpenCode), the official prompt is:

> Ensure Node.js is installed.
> Install Remotion Skills: `npx -y skills@latest add remotion-dev/skills -g -y`
> Then use them to create a video.

### Starting the Studio

For regular templates, `npm run dev` opens [[entities/remotion-studio]]. In the Next.js + React Router 7 templates, `npm run dev` starts the app and `npm run remotion` starts the Studio.

### Project structure: entry point and root

The structure is two files with distinct jobs:

- **Entry point** (e.g. `src/index.ts`) — calls `registerRoot(RemotionRoot)`. This is what CLI commands point at.
- **Root component** (e.g. `src/Root.tsx`) — returns your `<Composition>` list, wrapped in a React Fragment if there is more than one.

```ts
import {registerRoot} from 'remotion';
import {RemotionRoot} from './Root';

registerRoot(RemotionRoot);
```

`registerRoot()` must live in a separate file from the composition list: with React Fast Refresh, all code in a refreshed file re-executes, but `registerRoot()` should only ever run once. If you need to load something first (a dynamic import, WebAssembly), you may defer the call — `loadWebAssembly().then(() => { registerRoot(RemotionRoot); })` — without needing `delayRender()`.

### Brownfield install into an existing app

Remotion installs into Next.js, React Router, Vite, Create React App, and server-only Node.JS projects. Base packages:

```
npm i remotion @remotion/cli
```

Then add by use case: `@remotion/player` to embed videos in your React app (see [[concepts/player]]), `@remotion/renderer` for Node.JS rendering APIs, `@remotion/lambda` for [[concepts/lambda]] rendering.

Create a folder (conventionally `remotion/` at the project root) with three files: `Composition.tsx` (your video component), `Root.tsx` (the `<Composition>` list), and `index.ts` (calls `registerRoot()`). Then point the CLI at your entry point:

```
npx remotion studio remotion/index.ts
npx remotion render remotion/index.ts MyComp out.mp4
```

Optionally install the ESLint plugin (`npm i -D @remotion/eslint-plugin`) and scope its recommended rules to the Remotion files only:

```json
{
  "plugins": ["@remotion"],
  "overrides": [
    {
      "files": ["remotion/*.{ts,tsx}"],
      "extends": ["plugin:@remotion/recommended"]
    }
  ]
}
```

## Key Parameters

- **System requirements**: Node.js (or Bun) at a minimum supported version; macOS 15 (Sequoia) or later; Linux distros need Libc ≥ 2.35 plus additional packages. Alpine Linux and nixOS are unsupported.
- **`create-video` flags**: `--yes` (skip prompts), `--blank` (blank template); positional arg is the directory name.
- **Entry point path**: first argument to `npx remotion studio` / `npx remotion render` — defaults differ per template, always replaceable.
- **Core package**: `npm i remotion` gives the essential building blocks; pure functions like `interpolate()` and `interpolateColors()` work even outside Remotion.

## When To Use

- **New, video-first project** → `npx create-video@latest` with a template.
- **Adding video generation to an existing product** (e.g. a SaaS that renders personalized clips) → brownfield install, then `@remotion/player` for in-app preview or `@remotion/renderer`/`@remotion/lambda` for server rendering. See [[syntheses/rendering-path-picker]] for choosing a render path and [[entities/framework-integrations]] for framework-specific guidance.

## Risks & Pitfalls

- **Calling `registerRoot()` in the same file as compositions** breaks Fast Refresh semantics (it would re-execute on every refresh). Keep it in its own file.
- **TypeScript path aliases**: a `paths` alias without a prefix in `tsconfig.json` can resolve `import {...} from "remotion"` to your local `remotion/` folder instead of the npm package.
- **Unsupported platforms**: older macOS versions, Alpine, and nixOS will not work; Linux requires extra system packages.
- **License**: Remotion has a special license — some companies must obtain a paid company license. See [[concepts/licensing]].

## Related Concepts

- [[concepts/compositions-fundamentals]] — what goes inside the root component
- [[concepts/player]] — embedding videos in an existing React app
- [[concepts/rendering-ssr]] — rendering with `@remotion/renderer`
- [[concepts/cli-reference]] — `npx remotion studio` / `render` and friends
- [[entities/remotion-studio]] — the editor started by `npm run dev`
- [[entities/ai-integration]] — Agent Skills and coding-agent workflows

## Sources

- raw/github_doc-packages-docs-docs-getting-started-mdx.md — scaffolding, wizard, system requirements
- raw/github_doc-packages-docs-docs-brownfield-installation-mdx.md — existing-project install, folder structure, ESLint plugin
- raw/github_doc-packages-docs-docs-register-root-mdx.md — `registerRoot()` contract and deferral
- raw/github_doc-packages-docs-docs-remotion-mdx.md — core package installation
- raw/github_doc-readme-md.md — framework positioning, license note



<!-- ===== remotion/wiki/concepts/lambda.md ===== -->

---
title: "Remotion Lambda: Distributed Rendering on AWS"
type: concept
tags: [lambda, aws, cloud-rendering, serverless, cost, concurrency]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-lambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-setup-mdx.md", "raw/github_doc-packages-docs-docs-lambda-permissions-mdx.md", "raw/github_doc-packages-docs-docs-lambda-region-selection-mdx.md", "raw/github_doc-packages-docs-docs-lambda-limits-mdx.md", "raw/github_doc-packages-docs-docs-lambda-rendermediaonlambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getrenderprogress-mdx.md", "raw/github_doc-packages-docs-docs-lambda-webhooks-mdx.md", "raw/github_doc-packages-docs-docs-lambda-checklist-mdx.md", "raw/github_doc-packages-docs-docs-lambda-concurrency-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cost-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cost-example-mdx.md", "raw/github_doc-packages-docs-docs-lambda-data-transfer-cost-mdx.md", "raw/github_doc-packages-docs-docs-lambda-disk-size-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cli-mdx.md", "raw/github_doc-packages-docs-docs-lambda-authentication-mdx.md", "raw/github_doc-packages-docs-docs-lambda-bucket-security-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deployfunction-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deploysite-mdx.md", "raw/github_doc-packages-docs-docs-lambda-approuterwebhook-mdx.md", "raw/github_doc-packages-docs-docs-lambda-autodelete-mdx.md", "raw/llms_txt-remotion-ai-rules.md"]
---

# Remotion Lambda: Distributed Rendering on AWS

## Definition

Remotion Lambda (`@remotion/lambda`) renders Remotion videos on AWS Lambda by splitting the video across many parallel function invocations. It is the fastest and most scalable official render path — you only pay while rendering. It is the recommended solution whenever you want renders split into chunks across machines, instead of building a distributed renderer yourself.

## How It Works

Verbatim from the official overview:

- A Lambda function and a S3 bucket is created on AWS.
- A Remotion project gets deployed to a S3 bucket as a website.
- The Lambda function gets invoked and opens the Remotion project.
- A lot of Lambda functions are created in parallel which each render a small part of the video.
- The initial Lambda function downloads the videos and stitches them together.
- The final video gets uploaded to S3 and is available for download.

Architecture: one **Lambda function** (with a Remotion-hosted Chromium layer; one function executes different actions), one **S3 bucket** (projects, renders, metadata), the **CLI** (`npx remotion lambda`, installed via `@remotion/lambda`) and an equivalent **Node.JS API**. The full API function catalog lives in [[entities/lambda-api-catalog]].

**IAM setup** (official setup guide, exact names matter): create an IAM **policy named exactly `remotion-lambda-policy`** from the JSON printed by `npx remotion lambda policies role`; create a **role named exactly `remotion-lambda-role`** (use case: Lambda) with that policy; create a user with an inline policy from `npx remotion lambda policies user`; put the access key in `.env` as `REMOTION_AWS_ACCESS_KEY_ID`/`REMOTION_AWS_SECRET_ACCESS_KEY`. Validate with `npx remotion lambda policies validate` (or `simulatePermissions()`; role policies cannot be validated). Why the policies look like they do: the user policy is scoped to `remotionlambda-*` buckets and `remotion-render-*` functions, plus `iam:PassRole` on `remotion-lambda-role` and `lambda:GetLayerVersion` on `arn:aws:lambda:*:678892195805:layer:remotion-binaries-*` — the Chromium/FFmpeg layers in Remotion's own account. The role policy lets the function recursively invoke itself (the first invocation orchestrates the others) and write CloudWatch logs.

**Deploy + render flow**: CLI — `npx remotion lambda functions deploy`, `npx remotion lambda sites create src/index.ts --site-name=my-video`, `npx remotion lambda render <serve-url> <composition-id>`. Node — `deployFunction()`, `getOrCreateBucket()` + `deploySite()`, then `renderMediaOnLambda()` (import from `@remotion/lambda/client`): pass `{region, functionName, serveUrl, composition, codec, inputProps, privacy, framesPerLambda}` and get back `{renderId, bucketName}`. Poll `getRenderProgress({renderId, bucketName, functionName, region})` (~every second) until `progress.done` (read `progress.outputFile`) or `progress.fatalErrorEncountered` (read `progress.errors`); `overallProgress` is 0–1. Both deploys are idempotent: same version/memory/timeout reuses the function; same `siteName` overwrites the site. Redeploy the site whenever code changes; a function is bound to the Remotion version — deploy a new one when upgrading. Recover function names after restarts with `getFunctions({region, compatibleOnly: true})`.

**Authentication**: credentials via `REMOTION_AWS_*` vars (recommended; `AWS_*` is reserved on e.g. Vercel), plain `AWS_*` vars, or `REMOTION_AWS_PROFILE`. `.env` is auto-read by the CLI only, not the Node APIs. Rotating multiple AWS accounts is a documented strategy to scale past concurrency limits.

## Key Parameters

- **`deployFunction()`**: `region`; `timeoutInSeconds` (below 900; recommend ≤120 — raise concurrency, not timeout); `memorySizeInMb` (512–10240, recommend 2048; cost proportional to RAM); `diskSizeInMb` (512–10240MB; default 2048MB <5.0.0, 10240MB ≥5.0.0); `createCloudWatchLogGroup`; `runtimePreference`.
- **`deploySite()`**: `entryPoint`, `bucketName` (from `getOrCreateBucket()` — one bucket per region), `region`, `siteName`, `privacy` (`public` default — the headless browser must reach the site). Returns `serveUrl`.
- **Region**: default `us-east-1`. Node APIs require `region` explicitly per call; `REMOTION_AWS_REGION` env var and `--region` flag affect the **CLI only**. List regions with `getRegions()` / `npx remotion lambda regions`. Function and bucket must be in the **same region**. Pricing varies (most regions $0.0000133334/GB-s; `ap-east-1` $0.0000183, `af-south-1` $0.0000176800); some regions are disabled by default in AWS accounts. Multi-region deploys raise total concurrency and redundancy, at the cost of cold functions.
- **Concurrency**: `framesPerLambda` or `concurrency` (v4.0.322+, = `frameCount / framesPerLambda`; mutually exclusive). Defaults: ≥20 frames per Lambda; concurrency interpolated 75→150 between 0 and 18000 frames. Hard bounds: min `framesPerLambda` 5 (4 until 4.0.331), **max concurrency 200**. AWS account limit: 1000 concurrent executions per region by default, **as low as 10 on new accounts** — check with `npx remotion lambda quotas`, raise with `npx remotion lambda quotas increase` (AWS root accounts only; the limits doc ships answers for AWS's questionnaire).
- **AWS hard limits**: storage ≤10GB, RAM ≤10GB, execution ≤15min ⇒ output ≤ ~5GB ≈ 2h40min of 1080p at 10240MB disk; keep videos under ~80 min Full HD; AV1 not available.
- **`renderMediaOnLambda()` extras**: codecs `h264`/`h265`/`vp8`/`vp9`/`gif`/`prores`; `privacy: "public" | "private" | "no-acl"` (private links via `presignUrl()`); `frameRange` for partial renders; `webhook`; `deleteAfter` (`"1-day"`/`"3-days"`/`"7-days"`/`"30-days"`, needs site deployed with `--enable-folder-expiry`).
- **Cost**: minutes of video for pennies (measured: HelloWorld $0.001; 10-min remote HD ≈$0.10; 10-s 4K $0.013 — 2048MB, us-east-1, v4.0.381) plus S3 egress (billed **even same-region** — mitigate with R2, `@remotion/media` byte-range downloads, VPC endpoints), S3 storage, CloudWatch, and a license for teams of 4+ ([[concepts/licensing]]). Estimate with `estimatePrice()`.
- **Webhooks**: POST on render end with headers `X-Remotion-Status` (`success`/`timeout`/`error`), `X-Remotion-Mode` (`production`/`demo`), `X-Remotion-Signature` (`sha512=...` HMAC-SHA512 of the body, or `NO_SECRET_PROVIDED`). Payload: `{renderId, bucketName, expectedBucketOwner, customData, type}`; success adds `outputUrl`, `outputFile`, `timeToFinish`, `costs`, non-fatal `lambdaErrors`; error adds `errors[]`. `customData` must serialize under 1KB. Verify with `validateWebhookSignature()` or the `appRouterWebhook()`/`pagesRouterWebhook()`/`expressWebhook()` helpers (`secret`, `testing`, `onSuccess`/`onError`/`onTimeout`).

## When To Use

Use Lambda when videos are under ~80 min Full HD, you fit within (or can raise) AWS concurrency limits, and AWS regions work for you. Otherwise fall back to [[concepts/rendering-ssr]] or consider [[concepts/cloudrun]]. See [[syntheses/rendering-path-picker]] and [[syntheses/cost-estimation]].

## Risks & Pitfalls

Production checklist items (official):

- **Memory too high** is the #1 cost mistake — reducing memory 25% cuts cost 25%; redeploy repeatedly to find the floor.
- **Output file size** ≈ half the disk space max; block users from requesting overlong videos.
- **Bucket privacy**: renders are publicly accessible by default — set `privacy` on `renderMediaOnLambda()`/`renderStillOnLambda()`. Buckets created before v4.0.418 used a `public-read` ACL allowing anyone to *list* the bucket; new buckets use a bucket policy restricting public access to `s3:GetObject` only (`s3:PutBucketPolicy`). For existing buckets, remove `List` for `Everyone` in the S3 console.
- **Rate-limit user-triggered renders** — malicious actors can run up your AWS bill.
- **Timeout**: the rendering `--timeout` (delayRender, 30000ms) is a different flag than the function deploy `--timeout`.
- **Unsigned webhooks can't be trusted** — without a secret, authenticity and integrity cannot be verified.
- **License**: companies with more than 3 people need cloud rendering seats before launching.
- Data transfer surprise: same-region S3 asset pulls still bill as egress.

## Related Concepts

- [[entities/lambda-api-catalog]] — full function-by-function API reference
- [[concepts/rendering-ssr]] — the underlying render pipeline and DIY-distribution blueprint
- [[concepts/cloudrun]] — GCP counterpart and status comparison
- [[concepts/licensing]] — cloud rendering seats for 4+ person companies
- [[syntheses/cost-estimation]], [[syntheses/rendering-path-picker]], [[syntheses/troubleshooting-checklist]]
- [[summaries/casebook-rendering]] — field reports from GitHub issues

## Sources

- `raw/github_doc-packages-docs-docs-lambda-mdx.md` — overview, how-it-works
- `raw/github_doc-packages-docs-docs-lambda-setup-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-permissions-mdx.md` — IAM names, policy scopes, validation, full deploy/render walkthrough
- `raw/github_doc-packages-docs-docs-lambda-region-selection-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-limits-mdx.md` — regions, pricing table, AWS quotas, quota increase
- `raw/github_doc-packages-docs-docs-lambda-rendermediaonlambda-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-getrenderprogress-mdx.md` — render kickoff and polling API
- `raw/github_doc-packages-docs-docs-lambda-webhooks-mdx.md` — payloads, headers, HMAC signing
- `raw/github_doc-packages-docs-docs-lambda-checklist-mdx.md` — production checklist
- `raw/github_doc-packages-docs-docs-lambda-concurrency-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-disk-size-mdx.md` — tuning bounds
- `raw/github_doc-packages-docs-docs-lambda-cost-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-cost-example-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-data-transfer-cost-mdx.md` — cost model
- `raw/github_doc-packages-docs-docs-lambda-deployfunction-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-deploysite-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-cli-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-authentication-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-bucket-security-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-approuterwebhook-mdx.md`, `raw/github_doc-packages-docs-docs-lambda-autodelete-mdx.md` — operations
- `raw/llms_txt-remotion-ai-rules.md` — canonical CLI/Node deploy+render flow



<!-- ===== remotion/wiki/concepts/licensing.md ===== -->

---
title: "Remotion Licensing: Free Use vs Company License"
type: concept
tags: [licensing, pricing, compliance, cloud-rendering, business]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-license-mdx.md", "raw/github_doc-readme-md.md", "raw/github_doc-packages-docs-docs-lambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-checklist-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cost-example-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-checklist-mdx.md"]
---

# Remotion Licensing: Free Use vs Company License

## Definition

Remotion is source-available but **not** standard open source: it ships under a special license (LICENSE.md in the repo) that makes it free for individuals and small/non-profit organizations, while larger companies must purchase a company license from remotion.pro. The README warns explicitly: "Be aware of that Remotion has a special license and requires obtaining a company license in some cases."

## How It Works

The official license page states, verbatim:

> Remotion is **free to use** if you are:
>
> - an individual
> - a for-profit organisation with up to 3 employees
> - a non-profit or not-for-profit organisation
> - evaluating whether Remotion is a good fit, and are not yet using it in a commercial way
>
> If you don't qualify for any of the above, you need to acquire a company license. Visit [remotion.pro](https://remotion.pro) for pricing and buying a license.

The authoritative texts are the [LICENSE file](https://github.com/remotion-dev/remotion/blob/main/LICENSE.md) and the [Company License FAQ](https://www.remotion.pro/faq); when in doubt, read those or contact hi@remotion.dev for clarification on free-use eligibility.

For **cloud rendering**, both the Lambda and Cloud Run overview docs say the same thing: "The standard Remotion license applies... Companies needing a license and using cloud rendering must set it up with **Cloud Rendering Units**. Please visit: https://remotion.pro/license". The production checklists for both platforms phrase the threshold as: "Companies with more than 3 people need to buy **cloud rendering seats** in order to use Remotion Lambda [/ Cloud Run]... and buy the necessary cloud seats before launching." The Lambda cost-example doc lists licensing as an explicit cost line item: "Remotion Licensing: Teams of 4+ people also need to acquire a Remotion Company License in addition to the AWS cost."

## Key Parameters

- **Free-use threshold**: for-profit organisation with **up to 3 employees** (the cloud-rendering docs equivalently say "more than 3 people" / "teams of 4+" need to pay).
- **Evaluation carve-out**: evaluating fit, *not yet using it in a commercial way*, is free regardless of company size.
- **Non-profits**: free.
- **Company license**: bought at remotion.pro; cloud rendering additionally requires **Cloud Rendering Units** (also called cloud rendering seats in the checklists), set up via remotion.pro/license.
- **Where it surfaces in tooling**: the Studio accepts a `--public-license-key` flag (`npx remotion studio --public-license-key="your-license-key"`), indicating license keys are wired into the toolchain.
- **Pricing figures**: actual dollar amounts, seat counts, and Cloud Rendering Unit pricing are **not contained in this KB's sources** — they live on remotion.pro. Do not quote prices from this page; check remotion.pro for current numbers. (Everything else on this page is verbatim or near-verbatim from official docs — confidence high; pricing structure beyond "company license + cloud units exist" — unknown here.)

## When To Use

Consult this page whenever deciding:

- **"Can we use Remotion for free?"** — yes if you are an individual, a ≤3-employee for-profit, a non-profit, or still evaluating non-commercially. Otherwise buy a company license before production use.
- **"Does Lambda/Cloud Run change the math?"** — yes: a 4+-person company using [[concepts/lambda]] or [[concepts/cloudrun]] needs the company license *plus* Cloud Rendering Units, on top of AWS/GCP infrastructure costs. Both production checklists make "Valid Company license" a pre-launch gate. Factor this into [[syntheses/cost-estimation]].
- **"We're growing past 3 employees"** — the free tier lapses at employee #4; plan the license purchase as part of scaling.

## Risks & Pitfalls

- **Counting renders, not employees**: the threshold is organisation size (employees/people), not render volume or revenue — a 4-person company rendering one video a month still needs a license.
- **Forgetting the cloud add-on**: a company license alone may not cover cloud rendering; the docs consistently require Cloud Rendering Units/seats for Lambda and Cloud Run use.
- **Treating Remotion as MIT/OSS**: the repo is on GitHub but the README and license page explicitly negate standard open-source assumptions; vendor/compliance reviews should read LICENSE.md, not assume from the GitHub presence.
- **Terminology drift in docs**: "Cloud Rendering Units", "cloud rendering seats" and "cloud seats" all appear; they refer to the same remotion.pro licensing mechanism for cloud rendering. "Up to 3 employees" (license page) vs "more than 3 people" (checklists) vs "teams of 4+" (cost page) are consistent statements of one threshold.
- **Evaluation creep**: the free evaluation clause ends once usage becomes commercial; shipping to production while "still evaluating" is the gray zone the FAQ exists for — ask hi@remotion.dev if in doubt.
- Pricing quoted from third-party sources may be stale; only remotion.pro is authoritative.

## Related Concepts

- [[concepts/lambda]] — cloud rendering path that triggers the Cloud Rendering Units requirement
- [[concepts/cloudrun]] — same license terms apply
- [[concepts/installation-setup]] — where new users first hit the license notice
- [[syntheses/cost-estimation]] — license cost as a line item alongside compute
- [[syntheses/rendering-path-picker]] — license implications per rendering path
- [[summaries/casebook-platform]] — ecosystem context

## Sources

- `raw/github_doc-packages-docs-docs-license-mdx.md` — the authoritative free-use list (verbatim above)
- `raw/github_doc-readme-md.md` — "special license" warning
- `raw/github_doc-packages-docs-docs-lambda-mdx.md`, `raw/github_doc-packages-docs-docs-cloudrun-mdx.md` — Cloud Rendering Units requirement
- `raw/github_doc-packages-docs-docs-lambda-checklist-mdx.md`, `raw/github_doc-packages-docs-docs-cloudrun-checklist-mdx.md` — "more than 3 people" pre-launch gate
- `raw/github_doc-packages-docs-docs-lambda-cost-example-mdx.md` — "Teams of 4+ people" as a cost line item

_Gap note: the LICENSE.md full text, the remotion.pro FAQ, and concrete pricing are not in `raw/`; this page reports only what the docs state._



<!-- ===== remotion/wiki/concepts/player.md ===== -->

---
title: "Remotion Player: Embedding Compositions in Apps"
type: concept
tags: [player, embedding, react, interactivity, video-apps]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-player-api-mdx.md", "raw/github_doc-packages-docs-docs-player-index-mdx.md", "raw/github_doc-packages-docs-docs-player-best-practices-mdx.md", "raw/github_doc-packages-docs-docs-player-autoplay-mdx.md", "raw/github_doc-packages-docs-docs-player-current-time-mdx.md", "raw/github_doc-packages-docs-docs-player-buffer-state-mdx.md", "raw/github_doc-packages-docs-docs-player-premounting-mdx.md", "raw/github_doc-packages-docs-docs-player-thumbnail-mdx.md", "raw/github_doc-packages-docs-docs-player-into-remotion-project-mdx.md", "raw/github_doc-packages-docs-docs-building-a-timeline-mdx.md", "raw/github_doc-packages-docs-docs-interactive-mdx.md", "raw/github_issue-audio-not-stoping-in-the-player.md", "raw/github_issue-experiencing-issues-with-remotion-player-on-mobile-safari.md", "raw/github_issue-error-message-for-composition-outside-player-is-bad.md"]
---

# Remotion Player: Embedding Compositions in Apps

## Definition

The Remotion Player (`<Player>` from `@remotion/player`) is a React component that plays a Remotion composition inside any React app (Next.js, Vite, CRA) — without rendering a video file. It gives users an instant, interactive preview: the same component code that later gets rendered to MP4 plays live in the browser, driven by React state. It is the foundation for video editors, personalized-video preview UIs, and timeline tools. The package also ships `<Thumbnail>` (v3.2.41+) to display a single frame (`frameToDisplay`).

## How It Works

The Player mounts your composition component directly in the DOM and advances a virtual frame clock. It does **not** use `<Composition>` — pass the component and metadata as props:

```tsx
import {Player} from '@remotion/player';

<Player component={MyVideo} durationInFrames={120} compositionWidth={1920} compositionHeight={1080} fps={30} />;
```

`compositionWidth`/`compositionHeight` are the video's render dimensions; size the on-screen player separately with `style={{width: 400}}`. Pass either `component` or `lazyComponent` (a dynamic-import function, wrapped in `useCallback()`) — neither or both is an error. Interactivity comes from React state flowing through `inputProps` (memoized with `useMemo`), the documented timeline-editor pattern: state updates re-render the video live, with items placed via `<Sequence>` per track and layered with `<AbsoluteFill>`.

The Player only previews — rendering a file happens server-side via [[concepts/rendering-ssr]] or [[concepts/lambda]]. Official templates (Next.js App/Pages dir, React Router 7) ship Player + Lambda pre-wired — see [[entities/framework-integrations]].

## Key Parameters

**Playback props**: `loop` (default `false`), `autoPlay` (default `false`; discouraged if the video has audio — browsers block it), `playbackRate` (-10 to 10, excluding 0; negative = reverse, but media tags can't play in reverse), `initialFrame`, `inFrame`/`outFrame` (limit playback to a range), `moveToBeginningWhenEnded`, `initiallyMuted`, `initialVolume` (0–1, v4.0.453+; bypasses `localStorage`) / `volumePersistenceKey` (default key `"remotion.volumePreference"`).

**Controls props**: `controls` (seek bar + play/pause; default `false`), `showVolumeControls`, `allowFullscreen`, `clickToPlay`, `doubleClickToFullscreen` (not on mobile), `spaceKeyToPlayOrPause`, `initiallyShowControls`, `alwaysShowControls`, `hideControlsWhenPointerDoesntMove` (default 3000ms), `showPlaybackRateControl` (`true` = `[0.5, 0.8, 1, 1.2, 1.5, 1.8, 2, 2.5, 3]`), `browserMediaControlsBehavior` (media keys).

**Custom UI callbacks**: `errorFallback`, `renderLoading`, `renderPoster` + `showPosterWhenUnplayed`/`...Paused`/`...Ended`/`...Buffering`/`...BufferingAndPaused`, `posterFillMode` (`player-size`/`composition-size`), `renderPlayPauseButton` (receives `{playing, isBuffering}`), `renderFullscreenButton`, `renderMuteButton`, `renderVolumeSlider`, `renderCustomControls` (v4.0.418+, slot in the control bar). `bufferStateDelayInMilliseconds` (default 300) delays the buffering UI; `waiting`/`resume` events still fire immediately.

**Audio**: `numberOfSharedAudioTags` (default 5) pre-mounts silent audio tags so `<Html5Audio>` survives iOS Safari autoplay policies; `sampleRate` (default 48000, v4.0.470+). `acknowledgeRemotionLicense` silences the console message.

**`PlayerRef` methods**: `play(e?)`, `pause()`, `toggle(e?)`, `pauseAndReturnToPlayStart()`, `seekTo(frame)`, `getCurrentFrame()`, `isPlaying()`, `mute()`/`unmute()`/`isMuted()`, `getVolume()`/`setVolume(0–1)`, `requestFullscreen()`/`exitFullscreen()`/`isFullscreen()` (no fullscreen on iOS Safari), `getScale()`, `getContainerNode()`, `addEventListener()`/`removeEventListener()`.

**Events** (via ref): `play`, `pause`, `ended`, `seeked` (every frame while seeking, `e.detail.frame`), `timeupdate` (throttled to ≥250ms during playback), `frameupdate` (every frame change, playback + seeking), `ratechange`, `volumechange`, `mutechange`, `scalechange`, `fullscreenchange`, `error`, `waiting`/`resume` (buffer state).

## When To Use

- Video editors and customization UIs (timeline + Player is the documented architecture; remotion.pro sells a `<Timeline>` component); SaaS previews of parameterized videos before paying for a render.
- To show video frames as thumbnails without playback → `<Thumbnail>`.
- To sync external UI (timeline cursor, time display) with playback, use the official `useCurrentPlayerFrame()` hook: `useSyncExternalStore` subscribed to the ref's `frameupdate` event, reading `getCurrentFrame()`. Never call `useCurrentFrame()` outside the composition.
- Adding local rendering/Studio to a Player app: create `remotion/Root.tsx` registering a `<Composition>` with the same component, `index.ts` calling `registerRoot()`, then `npx remotion studio` / `npx remotion render`; apply the same Webpack overrides your app uses.

## Risks & Pitfalls

- **Re-render bottlenecks** (official best practices): render controls/UI as a *sibling* of the component that renders `<Player>`, sharing a `playerRef` — putting frequently-updating state (current time) in the Player's parent re-renders the Player constantly. Always memoize `inputProps`.
- **Autoplay policy**: Mobile Safari is the strictest browser — if it plays there, it plays everywhere. Avoid `autoPlay` with audio; trigger playback from a user gesture and **pass the event** to `play(e)`/`toggle(e)` (use `onClickCapture` for Safari propagation), or use `initiallyMuted` for must-autoplay cases.
- **Buffering**: assets may not be loaded when their frame arrives. Add `pauseWhenBuffering` to `<Html5Video>`/`<OffthreadVideo>`/`<Html5Audio>` (`pauseWhenLoading` for `<Img>`; on by default for `@remotion/media` tags), or call `useBufferState().delayPlayback()` manually (clear with `.unblock()` on unmount). Premount upcoming assets: from v5.0 every `<Sequence>` premounts for 1 second (`premountFor={0}` opts out); in v4 set `premountFor` explicitly.
- **No client-side file export** — render server-side and serve the file.
- **Crashes are contained**: errors in the render function hit an error boundary — the video unmounts and shows error UI (customizable via `errorFallback`), the host app survives; re-mount by changing `key`. Errors in event handlers/async code are *not* caught.
- **Known field issues**: audio kept playing in unfocused tabs (issue #2005, Chrome pauses `requestAnimationFrame()`); mobile/desktop Safari stutter with rapid pause/unpause or multiple `<Audio>` tags (issue #4662 — Player verbose logging exists to debug this); `useVideoConfig()` errors mention `<Composition />` even in Player contexts (issue #703) — if Lambda render fails with that message, fix the render-side registration, not the Player.

## Related Concepts

- [[concepts/compositions-fundamentals]] — the component model the Player plays
- [[concepts/rendering-ssr]] — turning the previewed composition into a file
- [[concepts/lambda]] — cloud rendering behind a Player-based app
- [[entities/remotion-studio]] — the dev-time counterpart to the Player
- [[entities/framework-integrations]] — Next.js / React Router templates with Player preinstalled
- [[syntheses/rendering-path-picker]] — choosing the render backend for your Player app

## Sources

- `raw/github_doc-packages-docs-docs-player-api-mdx.md` — full `<Player>` prop, `PlayerRef`, and event reference
- `raw/github_doc-packages-docs-docs-player-index-mdx.md` — package overview, Player+Lambda templates
- `raw/github_doc-packages-docs-docs-player-best-practices-mdx.md` — sibling-controls pattern, event passing, memoization
- `raw/github_doc-packages-docs-docs-player-autoplay-mdx.md` — browser autoplay policy handling
- `raw/github_doc-packages-docs-docs-player-current-time-mdx.md` — `useCurrentPlayerFrame()` sync hook
- `raw/github_doc-packages-docs-docs-player-buffer-state-mdx.md`, `raw/github_doc-packages-docs-docs-player-premounting-mdx.md` — buffering and premounting
- `raw/github_doc-packages-docs-docs-player-thumbnail-mdx.md` — `<Thumbnail>`
- `raw/github_doc-packages-docs-docs-player-into-remotion-project-mdx.md` — converting a Player app into a full Remotion project
- `raw/github_doc-packages-docs-docs-building-a-timeline-mdx.md` — canonical Player + timeline editor architecture
- `raw/github_doc-packages-docs-docs-interactive-mdx.md` — `Interactive.*` elements and Player compatibility
- `raw/github_issue-audio-not-stoping-in-the-player.md`, `raw/github_issue-experiencing-issues-with-remotion-player-on-mobile-safari.md`, `raw/github_issue-error-message-for-composition-outside-player-is-bad.md` — real-world pitfalls



<!-- ===== remotion/wiki/concepts/rendering-ssr.md ===== -->

---
title: "Server-Side Rendering (SSR) with @remotion/renderer"
type: concept
tags: [rendering, ssr, nodejs, encoding, docker, batch-rendering]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-render-mdx.md", "raw/github_doc-packages-docs-docs-bundle-mdx.md", "raw/github_doc-packages-docs-docs-renderer-mdx.md", "raw/github_doc-packages-docs-docs-encoding-mdx.md", "raw/github_doc-packages-docs-docs-docker-mdx.md", "raw/github_doc-packages-docs-docs-distributed-rendering-mdx.md", "raw/github_doc-packages-docs-docs-dataset-render-mdx.md", "raw/github_doc-packages-docs-docs-render-all-mdx.md", "raw/github_doc-packages-docs-docs-render-as-gif-mdx.md", "raw/github_doc-packages-docs-docs-cancel-render-mdx.md", "raw/github_doc-packages-docs-docs-continue-render-mdx.md"]
---

# Server-Side Rendering (SSR) with @remotion/renderer

## Definition

Server-side rendering is producing video, audio, stills, image sequences or GIFs from a Remotion project on a machine you control, using the Node.JS APIs of `@remotion/renderer` (the same package that powers the CLI and Remotion Lambda). The pipeline is: bundle once with `bundle()` from `@remotion/bundler`, resolve a composition with `selectComposition()`, then render with `renderMedia()`.

## How It Works

The canonical script (verbatim from the official Docker guide):

```tsx
import {bundle} from '@remotion/bundler';
import {renderMedia, selectComposition} from '@remotion/renderer';

const bundled = await bundle({
  entryPoint: require.resolve('./src/index.ts'),
  // If you have a webpack override in remotion.config.ts, pass it here as well.
  webpackOverride: (config) => config,
});

const inputProps = {};

const composition = await selectComposition({
  serveUrl: bundled,
  id: 'MyComp',
  inputProps,
});

await renderMedia({
  codec: 'h264',
  composition,
  serveUrl: bundled,
  outputLocation: `out/${composition.id}.mp4`,
  chromiumOptions: {enableMultiProcessOnLinux: true},
  inputProps,
});
```

`bundle()` packs the project with Webpack and returns a serve URL (a directory path). **Call it only when source code changes** — render many videos from one bundle, parameterized via `inputProps`; calling `bundle()` per render is an anti-pattern, and `bundle()` cannot be called in a serverless function. `renderMedia()` (added in Remotion 3.0) combines the older `renderFrames()` + `stitchFramesToVideo()` into one faster step — prefer it. A headless Chrome renders each frame; FFmpeg encodes. Components can defer frames with `delayRender()`/`continueRender()` (or the preferred `useDelayRender()` hook) and abort the whole render with `cancelRender(err)` — pass an `Error` for best stack traces; note `cancelRender()` throws, so wrap in `try/catch` where needed.

## Key Parameters

- **`bundle()`**: `entryPoint` (absolute path, usually `src/index.ts`), `webpackOverride` (reducer-style; pass the same override as `remotion.config.ts`), `outDir`, `onProgress` (0–100), `rootDir`, `publicDir`, `rspack` (use Rspack instead of Webpack, default `false`). Returns a promise resolving to the output directory.
- **Important:** the `remotion.config.ts` configuration file has **no effect** when using `@remotion/renderer` APIs — pass options explicitly.
- **Codec** (encoding guide): `h264` (default, .mp4/.mov/.mkv, very fast, best compatibility), `h265`, `vp8`/`vp9` (.webm), `av1` (very small, very slow; **not available on Lambda or Linux ARM64 GNU**), `prores` (.mov, alpha via `"4444"`/`"4444-xq"` profiles). Audio-only: pass `mp3`, `wav` or `aac` as codec.
- **Quality**: CRF — lower is better quality; defaults/ranges per codec: H264 default 18 (1–51), H265 23 (0–51), VP8 9 (4–63), VP9 28 (0–63), AV1 30 (0–63). Alternatively `videoBitrate`/`audioBitrate` (incompatible with other quality options). With hardware acceleration (from 4.0.228) you cannot set CRF.
- **Concurrency**: `renderMedia()` accepts `concurrency`; for dataset renders, do **not** render more than one video at a time — each render already saturates the machine.
- **GIFs**: `codec: "gif"`; lower the frame rate with `everyNthFrame` (e.g. `2` turns 30 FPS into a 15 FPS GIF); `numberOfGifLoops` (`null` = infinite, `0` = no loop); transparent GIFs need `imageFormat: "png"`.

## When To Use

- **Dataset / batch renders**: loop over JSON entries, call `selectComposition()` + `renderMedia()` per entry with the entry as `inputProps`; optionally vary duration/size via `calculateMetadata()`. Render all compositions with `getCompositions(bundled)` and a loop, or via CLI: `compositions=($(npx remotion compositions src/index.ts -q))`.
- **Docker deployment**: official Dockerfile uses `FROM node:22-bookworm-slim`, installs Chrome shared libraries (libnss3, libgbm-dev, libasound2, …), then `RUN npx remotion browser ensure` to install Chrome Headless Shell. Set `chromiumOptions.enableMultiProcessOnLinux: true` (v4.0.42+). Install `fonts-noto-color-emoji` for emoji and `fonts-noto-cjk` for CJK. **Don't use Alpine Linux** (slow Rust startup, unpinnable Chrome). Give the container CPUs: `--cpus=16 --cpuset-cpus=0-15`.
- **Distributed rendering** (advanced): split frames into equal-size chunks (`frameRange`), render each chunk with identical options, codec `h264-ts` instead of `h264`, `compositionStart` = first frame of overall range, `forSeamlessAacConcatenation: true` for AAC, then merge with `combineChunks()` (final codec `h264`). Lambda follows this same blueprint — the docs explicitly recommend [[concepts/lambda]] instead of building your own (it handles orchestration, retries, Chrome bundling, webhooks, clients for Node/Go/Ruby/Python/PHP).
- GitHub Actions renders are also supported via the SSR API.

## Risks & Pitfalls

- Re-bundling per render wastes time and is called out as an anti-pattern; `bundle()` in a serverless function fails.
- Forgetting to pass your Webpack override to `bundle()`/`deploySite()` when one exists in `remotion.config.ts` breaks Tailwind/SCSS/alias setups silently.
- Expecting `remotion.config.ts` to apply to SSR — it doesn't.
- Wrong CRF intuition across codecs: `23` looks very good on H264 but terrible on WebM.
- Chunked DIY distribution: unequal chunk sizes or wrong `compositionStart`/audio codec settings cause audio artifacts on concatenation.
- Alpine images and missing Linux shared libraries are the top Docker failure modes; pinning Debian package versions breaks builds later (old packages get removed from repos).
- `cancelRender()` throws — unhandled in client-side rendering unless caught.

## Related Concepts

- [[concepts/lambda]] — managed distributed rendering on AWS
- [[concepts/cloudrun]] — GCP alternative (alpha)
- [[concepts/cli-reference]] — same renders via `npx remotion render`
- [[concepts/compositions-fundamentals]] — what `selectComposition()` resolves
- [[syntheses/rendering-path-picker]] — Studio vs CLI vs SSR vs Lambda vs Cloud Run
- [[syntheses/performance-recipes]] — concurrency and speed tuning

## Sources

- `raw/github_doc-packages-docs-docs-render-mdx.md` — overview of all render paths
- `raw/github_doc-packages-docs-docs-bundle-mdx.md`, `raw/github_doc-packages-docs-docs-renderer-mdx.md` — `bundle()` / `@remotion/renderer` APIs
- `raw/github_doc-packages-docs-docs-encoding-mdx.md` — codecs, CRF, ProRes profiles, audio codecs
- `raw/github_doc-packages-docs-docs-docker-mdx.md` — Dockerfile and render script
- `raw/github_doc-packages-docs-docs-distributed-rendering-mdx.md`, `raw/github_doc-packages-docs-docs-dataset-render-mdx.md`, `raw/github_doc-packages-docs-docs-render-all-mdx.md`, `raw/github_doc-packages-docs-docs-render-as-gif-mdx.md` — batch, distributed and GIF techniques
- `raw/github_doc-packages-docs-docs-cancel-render-mdx.md`, `raw/github_doc-packages-docs-docs-continue-render-mdx.md` — render lifecycle control



<!-- ===== remotion/wiki/concepts/transitions.md ===== -->

---
title: "Transitions: TransitionSeries, Presentations & Timings"
type: concept
tags: [transitions, transition-series, presentations, timings]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-transitions-index-mdx.md", "raw/github_doc-packages-docs-docs-transitions-transitionseries-mdx.md", "raw/github_doc-packages-docs-docs-transitions-audio-transitions-mdx.md", "raw/github_doc-packages-docs-docs-transitions-use-transition-progress-mdx.md", "raw/github_doc-packages-docs-docs-transitions-make-html-in-canvas-presentat.md", "raw/llms_txt-remotion-ai-rules.md", "raw/github_doc-packages-docs-docs-cli-add-mdx.md", "raw/github_doc-packages-docs-docs-5-0-migration-mdx.md", "raw/github_release-v4-0-465.md", "raw/github_release-v4-0-466.md", "raw/github_release-v4-0-467.md"]
---

# Transitions: TransitionSeries, Presentations & Timings

## Definition

`@remotion/transitions` (available from v4.0.53) provides `<TransitionSeries>`, a variant of `<Series>` that plays scenes one after another **with an animated transition in between**. Each transition combines a **presentation** (the visual effect, e.g. `fade()`, `wipe()`) with a **timing** (how the progress is animated, e.g. `springTiming()`, `linearTiming()`). Since v4.0.415 it also supports **overlays** — children rendered on top of a cut point without affecting timing.

## How It Works

Install version-matched with your other Remotion packages: `npx remotion add @remotion/transitions` (pins to your existing Remotion version, avoiding mismatches).

The canonical structure, verbatim from the official `<TransitionSeries>` doc:

```tsx
import {linearTiming, springTiming, TransitionSeries} from '@remotion/transitions';
import {fade} from '@remotion/transitions/fade';
import {wipe} from '@remotion/transitions/wipe';

export const TransitionExample: React.FC = () => {
  return (
    <TransitionSeries>
      <TransitionSeries.Sequence durationInFrames={60}>
        <Fill color="#0b84f3" />
      </TransitionSeries.Sequence>
      <TransitionSeries.Transition timing={springTiming({config: {damping: 200}})} presentation={fade()} />
      <TransitionSeries.Sequence durationInFrames={60}>
        <Fill color="pink" />
      </TransitionSeries.Sequence>
      <TransitionSeries.Transition timing={linearTiming({durationInFrames: 30})} presentation={wipe()} />
      <TransitionSeries.Sequence durationInFrames={60}>
        <Fill color="#2ecc71" />
      </TransitionSeries.Sequence>
    </TransitionSeries>
  );
};
```

**Duration math**: during a transition both scenes render simultaneously, so the total duration **shrinks** by each transition's length — `40 + 60 - 30 = 70` frames for two scenes with a 30-frame transition; with three scenes sum all sequences and subtract all transitions (`40+60+90-30-45 = 115`). Get a transition's length with `timing.getDurationInFrames({fps})` — e.g. `springTiming({config: {damping: 200}}).getDurationInFrames({fps: 30}) // 23`. Overlays do **not** shorten the timeline.

**Enter/exit animations**: a transition placed first or last in the series (with only one adjacent sequence) animates a scene's entrance or exit.

**Official rules**: (1) a transition must not be longer than the previous or next sequence; (2) two transitions cannot be adjacent; (3) two overlays cannot be adjacent; (4) a transition and an overlay cannot be adjacent — they occupy the same slot; (5) at least one sequence must come before or after a transition or overlay.

### Presentations

Imported from subpaths (`@remotion/transitions/fade`, `/wipe`, `/slide`, `/none`); timings come from the package root. Confirmed in this corpus: `fade()`, `wipe()`, `slide()` (the **default** if `presentation` is omitted), and `none()` (no visual — pair with `useTransitionProgress()`). The v4.0.465–467 releases added `dissolve()`, `ripple()`, `crosswarp()`, `bookFlip()`, `linearBlur()` (HTML-in-canvas presentations) and `swap()`, `dreamyZoom()`, `crossZoom()`, `filmBurn()`. Custom shader presentations: `makeHtmlInCanvasPresentation()` (v4.0.456) takes a WebGL2 `HtmlInCanvasShader` exposing `{clear, cleanup, draw({prevImage, nextImage, width, height, time})}`. Each presentation has a doc page under `/docs/transitions/presentations/<name>`; their individual option objects are not reproduced here.

### Timings

- `springTiming({config: {damping: 200}})` — physics-based progress; same spring config shape as [[concepts/animation]] (`damping: 200` = no bounce).
- `linearTiming({durationInFrames: 30})` — constant-speed progress over an explicit frame count.

### Reading progress in a scene

`useTransitionProgress()` (v4.0.177), called inside a `<TransitionSeries.Sequence>` child, returns `{entering, exiting, isInTransitionSeries}`: the outgoing scene sees `exiting` go 0→1 (`entering` stays 1), the incoming scene sees `entering` go 0→1 (`exiting` stays 0); outside a series both are constant and `isInTransitionSeries` is `false`. Meant for `none()` but works with any presentation.

### Audio behavior

Transitions are silent by default. The official `addSound()` pattern wraps any presentation: it re-wraps `transition.component` and mounts `<Html5Audio src={src} />` only when `presentationDirection === 'entering'` (so the sound plays once, not twice — both scenes render the presentation during the overlap). Works from v4.0.58; customize volume/offset/playback rate on the audio tag.

## Key Parameters

- `<TransitionSeries>`: inherits `from`, `name`, `className`, `style` from `<Sequence>`; may only contain `Sequence`, `Transition`, `Overlay` children.
- `<TransitionSeries.Sequence>`: `durationInFrames` (required); inherits `name`, `className`, `style`, `showInTimeline`, `premountFor`, `postmountFor`, `layout` — but **no `offset`**.
- `<TransitionSeries.Transition>`: `timing` (a `TransitionTiming`), `presentation?` (a `TransitionPresentation`, default `slide()`).
- `<TransitionSeries.Overlay>` (v4.0.415): `durationInFrames` (positive integer), `offset?` (shifts relative to the cut point's center — half before, half after by default; positive = later). Children animate independently; no progress context. Must not extend before frame 0 or beyond adjacent sequences.

## When To Use

- Slideshow-style videos where scenes hand off with a visual effect → `<TransitionSeries>`.
- Flashes/light leaks over a hard cut without changing timing → `<TransitionSeries.Overlay>` (e.g. `<LightLeak>` from `@remotion/light-leaks`).
- Animating objects *inside* scenes during the handoff → `none()` + `useTransitionProgress()`.
- Scenes that simply cut back-to-back → plain `<Series>` ([[concepts/compositions-fundamentals]]); use `offset` there for manual overlaps.

## Risks & Pitfalls

- **Transitions consume scene time** — budget `durationInFrames` knowing total = sum of sequences − sum of transitions; a transition longer than a neighboring sequence is invalid.
- **Forgetting the default**: omitting `presentation` gives you `slide()`, not a crossfade.
- **Double audio**: naively adding audio to a presentation plays it in both the entering and exiting copy — gate on `presentationDirection === 'entering'`.
- **5.0 breaking change**: `<TransitionSeries layout="none">` is no longer supported — transitioned elements must be absolutely positioned.
- **5.0 behavior change**: `<TransitionSeries.Sequence>` (like all sequences) auto-premounts for 1 second (`fps` frames); opt out with `premountFor={0}`.
- **Misplaced tags**: adjacent transitions, adjacent overlays, or a transition next to an overlay all violate the structure rules above.

## Related Concepts

- [[concepts/compositions-fundamentals]] — `<Series>`, the transition-less sibling
- [[concepts/animation]] — springs and easing that power timings
- [[concepts/video-media]] — media inside transitioned scenes (premounting matters for heavy content)
- [[concepts/player]] — transitions play live in the Player like any composition
- [[summaries/release-digest]] — the v4.0.465–467 presentation additions
- [[summaries/official-ai-rules]] — source of the canonical snippet

## Sources

- `raw/github_doc-packages-docs-docs-transitions-transitionseries-mdx.md` — `<TransitionSeries>`/`Transition`/`Overlay` API, duration math, rules, `getDurationInFrames()`
- `raw/github_doc-packages-docs-docs-transitions-index-mdx.md` — package overview (v4.0.53+)
- `raw/github_doc-packages-docs-docs-transitions-audio-transitions-mdx.md` — `addSound()` wrapper, `presentationDirection`
- `raw/github_doc-packages-docs-docs-transitions-use-transition-progress-mdx.md` — `useTransitionProgress()` and `none()`
- `raw/github_doc-packages-docs-docs-transitions-make-html-in-canvas-presentat.md` — custom shader presentations
- `raw/llms_txt-remotion-ai-rules.md` — canonical usage and structural rules
- `raw/github_doc-packages-docs-docs-cli-add-mdx.md` — `npx remotion add @remotion/transitions`
- `raw/github_doc-packages-docs-docs-5-0-migration-mdx.md` — `layout="none"` removal, auto-premounting
- `raw/github_release-v4-0-465.md` / `-466.md` / `-467.md` — new presentations



<!-- ===== remotion/wiki/concepts/video-media.md ===== -->

---
title: "Video & Media: Tags, Assets & Playback"
type: concept
tags: [video, offthreadvideo, images, assets, prefetch, troubleshooting]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-offthreadvideo-mdx.md", "raw/github_doc-packages-docs-docs-html5-video-mdx.md", "raw/github_doc-packages-docs-docs-img-mdx.md", "raw/github_doc-packages-docs-docs-iframe-mdx.md", "raw/github_doc-packages-docs-docs-animatedimage-mdx.md", "raw/github_doc-packages-docs-docs-importing-assets-mdx.md", "raw/github_doc-packages-docs-docs-get-static-files-mdx.md", "raw/github_doc-packages-docs-docs-prefetch-mdx.md", "raw/github_doc-packages-docs-docs-media-playback-error-mdx.md", "raw/github_doc-packages-docs-docs-non-seekable-media-mdx.md", "raw/github_doc-packages-docs-docs-media-fragments-mdx.md"]
---

# Video & Media: Tags, Assets & Playback

## Definition

Remotion replaces native media tags with timeline-aware components: `<OffthreadVideo>`, `<Html5Video>` (previously `<Video>`) and the newer `<Video>` from `@remotion/media` for video; `<Img>`, `<AnimatedImage>` and `<IFrame>` for images and embeds. They guarantee assets are fully loaded before a frame renders and stay synchronized with Remotion's time. Assets live in the `public/` folder and are referenced via `staticFile()`.

## How It Works

### Choosing a video tag

- **`<OffthreadVideo>`** (v3.0.11+): during rendering, extracts the exact frame outside the browser using FFmpeg and shows it in an `<Img>`; during preview it uses a `<video>` tag. Built to overcome `<Html5Video>` limitations — it renders non-seekable sources fine and avoids "too many video tags" errors. Reads H.264, H.265/HEVC, VP8/VP9, AV1 (v4.0.6+), and ProRes. It does **not** implement `loop` (wrap in `<Loop durationInFrames={...}>` after fetching the duration, or fall back to `<Html5Video loop>` in preview).
- **`<Html5Video>`**: wraps the native `<video>` element (all native props except `autoplay`/`controls` forwarded). Supports `loop`. The docs recommend preferring the other tags for performance. When a video ends, its last frame stays visible (`currentTime` past duration shows the last frame).
- **`<Video>` from `@remotion/media`**: experimental successor; the **only** video tag supported in `@remotion/web-renderer` (client-side rendering) — neither `<OffthreadVideo>` nor `<Html5Video>` works there.

Shared props (both core tags): `src`, `trimBefore`/`trimAfter` (frames; v4.0.319+, replacing deprecated `startFrom`/`endAt` — at 30 fps, `trimBefore={60} trimAfter={120}` plays the 2s–4s range), `volume` (number or per-frame function), `playbackRate` (reverse unsupported; Chrome errors outside `0.0625`–`16`), `preservePitch` (preview-only; render pitch via `toneFrequency` `0.01`–`2`), `muted` (on `<Html5Video>` this also skips downloading the file to mix audio — faster renders), `audioStreamIndex` (render-only), `pauseWhenBuffering` (default `false`, `true` in 5.0), `acceptableTimeShiftInSeconds` (seek threshold, default `0.45`), `onError`, `onAutoPlayError`, `onVideoFrame`, `crossOrigin`, `name`, `showInTimeline`. `<OffthreadVideo>` extras: `transparent` (PNG extraction for alpha — slower; default BMP) and `toneMapped` (default `true` since v4.0.117; HDR→sRGB correction, disable for speed).

### Images, animated images, iframes

- **`<Img>`** waits for the image before rendering the frame (no flicker). Retries failed loads (`maxRetries`, default `2`, exponential backoff from 1000ms); from v4.0.0 exhausted retries call `cancelRender()` unless you pass `onError`. From v4.0.465 it inherits `from`, `durationInFrames`, `name`, `showInTimeline`, `hidden` from `<Sequence>`. The `effects` prop (v4.0.469+, e.g. `effects={[blur({radius: 8})]}` from `@remotion/effects/blur`) switches rendering to a `<canvas>`, disabling `<img>`-only props. Max resolution: Chrome's 2^29 px limit. **Don't use `<Img>` for GIFs** — use `@remotion/gif`'s `<Gif>`.
- **`<AnimatedImage>`** (v4.0.246+) renders animated GIF, APNG, AVIF, or WebP synced to the timeline via the `ImageDecoder` API — Chrome and Firefox only (no Safari). Props: `width`/`height`, `fit` (`'fill'` default, `'contain'`, `'cover'`), `loopBehavior` (`'loop'` default, `'pause-after-finish'`, `'clear-after-finish'`), `playbackRate`, `effects`, `requestInit` (auth headers; `signal` is managed internally).
- **`<IFrame>`** wraps `delayRender()` around an `<iframe>` so the page loads before the frame renders. The embedded site should not animate on its own — only `useCurrentFrame()`-driven animation renders correctly.

### Importing assets

Put files in `public/` and reference with `staticFile('logo.png')`. Image sequences work via interpolated paths: `staticFile(`/frame${frame}.png`)`. Webpack `import` statements also work for listed extensions (images, `.webm`/`.mov`/`.mp4`, `.mp3`/`.wav`/`.aac`/`.m4a`, fonts) but are discouraged: 2GB max, limited extensions, funky dynamic imports. Remotion runs in the browser, so arbitrary filesystem paths and `fs` are unavailable — enumerate `public/` with `getStaticFiles()` (Studio/render only; returns `{name, src, sizeInBytes, lastModified}`, first 10000 files; pass `src`, never `name`, to media tags). Assets added to `public/` after `bundle()` are not accessible during render.

### `prefetch()` and media fragments

`prefetch(src, {method: 'blob-url'})` (v3.2.23+) downloads an asset into memory for the [[concepts/player]]; returns `{free, waitUntilDone}`. Once fetched, Remotion media tags using the same URL automatically switch to the Blob URL. Options: `method` (`'blob-url'` fast default; `'base64'` if Safari audio stutters), `contentType` (set e.g. `video/mp4` if the server's header is wrong — blob URLs lose the file extension; bites in Safari), `credentials`, `onProgress`, `logLevel`. Alternative: `@remotion/preload`.

Remotion automatically appends W3C media-fragment hashes to video URLs — a video in `<Sequence from={2 * fps} durationInFrames={4 * fps}>` mounts as `<video src="https://example.com/bbb.mp4#t=2.0,4.0" />`, so browsers load only that range (important for Safari mobile). Append `#disable` to the src to opt out — do this when `from`/`durationInFrames`, `trimBefore`/`trimAfter`, or `playbackRate` change dynamically, since every fragment change makes the browser treat it as a new source and reload.

## Key Parameters

- Tag choice: `<OffthreadVideo>` for render robustness; `<Html5Video>` for `loop`; `@remotion/media` `<Video>` for web-renderer.
- `transparent`, `toneMapped` — the two `<OffthreadVideo>` render-speed levers.
- `staticFile()` — the only correct way to reference `public/` files.
- `prefetch()` `method`/`contentType` — Safari playback levers.

## When To Use

- Compositing source footage → `<OffthreadVideo>` by default; see [[syntheses/media-tag-picker]].
- Stills/logos → `<Img>`; meme GIFs/animated stickers → `<AnimatedImage>` or `@remotion/gif`.
- Embedding live web pages → `<IFrame>` (static pages only).
- Player apps swapping media at runtime → `prefetch()` before mounting the new src.

## Risks & Pitfalls

- **"Could not play video/audio with src" (`MediaError`)**: usually a Chrome-unsupported codec (HEVC on Linux, `.avi`, `.flv`) or a 404 — a plain `"/my-video.mp4"` path fails because Remotion serves `public/` under a prefix; use `staticFile('my-video.mp4')`. Also check 200 status, `Content-Type`, and `Content-Range` headers; Internet Download Manager corrupts media traffic. "error creating media player" = too many `<video>` tags — often a `key={uuidv4()}` recreating tags every frame; fix the key or switch to `<OffthreadVideo>`.
- **"The media [src] cannot be seeked"**: the source was swapped without preloading (fix: `prefetch().waitUntilDone()` first), or the server omits `Content-Range`/`Content-Length`/Faststart, or headers like `X-Frame-Options`/`Content-Security-Policy: frame-ancestors`/`Cross-Origin-Resource-Policy: same-origin` block loading. Fixes: a Range-supporting host, importing the file locally, or `<OffthreadVideo>` (renders fine; preview may still struggle).
- **CORS** is required for remote assets used with `prefetch()` / `<AnimatedImage>`; Remotion's origin is usually `http://localhost:3000`.
- **`<AnimatedImage>` fails in Safari** (no `ImageDecoder`).
- **Unhandled `<Img>` error stalls the render** until timeout — unmount or replace `src` in `onError`.

## Related Concepts

- [[concepts/audio]] — the audio counterpart (`<Html5Audio>`, volume, sample rates)
- [[concepts/compositions-fundamentals]] — `calculateMetadata()` to match composition duration to a video
- [[concepts/player]] — where `prefetch()` matters
- [[syntheses/media-tag-picker]] — decision table for media components
- [[syntheses/troubleshooting-checklist]] — broader render debugging

## Sources

- raw/github_doc-packages-docs-docs-offthreadvideo-mdx.md / -html5-video-mdx.md — video tags, codecs, looping
- raw/github_doc-packages-docs-docs-img-mdx.md / -animatedimage-mdx.md / -iframe-mdx.md — image and iframe components
- raw/github_doc-packages-docs-docs-importing-assets-mdx.md / -get-static-files-mdx.md — `public/`, `staticFile()`, `getStaticFiles()`
- raw/github_doc-packages-docs-docs-prefetch-mdx.md — prefetching
- raw/github_doc-packages-docs-docs-media-playback-error-mdx.md / -non-seekable-media-mdx.md — troubleshooting
- raw/github_doc-packages-docs-docs-media-fragments-mdx.md — `#t=` fragment behavior



<!-- ===== remotion/wiki/entities/ai-integration.md ===== -->

---
title: "AI Integration"
type: entity
tags: [ai, agents, llms-txt, skills, claude-code, prompting]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/llms_txt-remotion-ai-rules.md", "raw/github_doc-packages-docs-docs-cli-skills-mdx.md", "raw/github_doc-packages-docs-docs-lovable-for-motion-graphics-mdx.md", "raw/github_doc-packages-docs-docs-getting-started-mdx.md", "raw/github_doc-packages-docs-docs-schemas-mdx.md", "raw/github_doc-packages-docs-docs-cli-create-video-mdx.md", "raw/github_doc-packages-docs-docs-html-in-canvas-guide-mdx.md", "raw/github_doc-packages-docs-docs-cli-studio-mdx.md"]
---

# AI Integration

## Overview

Remotion treats AI coding agents as first-class users. It publishes official AI rules at `https://www.remotion.dev/llms.txt` (a system-prompt-ready description of how to write Remotion code), distributes **Agent Skills** from `remotion-dev/skills` installable via the CLI, embeds agent-friendly flags (`npx create-video@latest --yes`), ships an "Ask AI" modal in the Studio, and trains "Remotion AI" on public help conversations. Strategically, Remotion has stated it will **not** build a "Lovable for motion graphics" consumer tool — it builds the video tech backbone and licenses it to companies building prompt-to-video products, betting that agents like Claude Code are the better chat interface.

## Characteristics

**The official llms.txt rules** — the canonical instructions a code-generating agent should follow:

- All output is valid React in TypeScript. Scaffold with `npx create-video@latest --blank`. Entry file (`src/index.ts`) calls `registerRoot(Root)`; `src/Root.tsx` registers `<Composition>`s.
- Composition defaults: `fps` 30, `width` 1920, `height` 1080, `id` "MyComp"; `defaultProps` must match the component's prop shape. Frames start at 0 via `useCurrentFrame()`.
- Media tags: `<Video>` and `<Audio>` from `@remotion/media` (props `trimBefore`, `trimAfter`, `volume` 0–1); `<Img>` from `remotion` for stills; `<Gif>` from `@remotion/gif` for animated GIFs. `public/` assets go through `staticFile()`.
- Layering with `<AbsoluteFill>`; timing with `<Sequence from durationInFrames>` (negative `from` cuts off the start; child `useCurrentFrame()` restarts at 0); sequential scenes with `<Series>` (`Series.Sequence` has `offset`, no `from`); transitions with `<TransitionSeries>` from `@remotion/transitions` (`TransitionSeries.Transition` with `timing={springTiming(...)}`/`linearTiming(...)` and `presentation={fade()}`/`wipe()` must sit *between* `TransitionSeries.Sequence` tags).
- **Determinism rule**: `Math.random()` is forbidden — use `random('my-seed')` from `remotion`.
- Animation: `interpolate(frame, inputRange, outputRange, {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})` (clamps by default per the rules); `spring({fps, frame, config: {damping: 200}})` animates 0→1; read `fps`/`durationInFrames`/`width`/`height` from `useVideoConfig()`.
- Rendering: `npx remotion render [id]`, `npx remotion still [id]`. Lambda: complete `/docs/lambda/setup`, then CLI `npx remotion lambda functions deploy`, `npx remotion lambda sites create` (first arg = entry point), `npx remotion lambda render [comp-id]`; or Node APIs `deployFunction()`, `deploySite()`, `renderMediaOnLambda()`, and progress **must** be polled with `getRenderProgress()`.

**Agent Skills** — instructions defining best practices for Remotion projects, "useful for AI agents like Claude Code, Codex, or Cursor". Installed to `.agents/skills`; Claude Code compatibility via per-skill symlinks in `.claude/skills`. Skills also teach component-specific rules (e.g. `<HtmlInCanvas>`'s `onInit`/`onPaint` lifecycle, the `--gl=angle` flag, the no-nesting rule).

**Strategy ("Lovable for Motion Graphics")** — Remotion will not build a consumer prompt-to-video product: it self-assesses as bad at B2C, licenses its tech via the company license to video editors / prompt-to-video tools / ad generators, and argues a homegrown chat UI would lose to Claude Code, which composes with the OS (CLI, filesystem, subagents, skills).

## How to Use

The official "Coding Agent Prompt" from the getting-started doc (paste into Claude Code, Codex or OpenCode):

> Ensure Node.js is installed.
> Install Remotion Skills: `npx -y skills@latest add remotion-dev/skills -g -y`
> Then use them to create a video.

Install or update skills inside a project:

```bash
npx remotion skills add
npx remotion skills update
```

Agent-friendly scaffolding (skips all prompts; note skills are NOT installed by `--yes` — add them after):

```sh
npx create-video@latest --yes --blank my-video
cd my-video
npm i
npx remotion skills add
npm run dev
```

Reusable task prompt from the schemas doc, for making an existing composition editable in the Studio (verbatim):

```txt
Make this Remotion composition parameterizable in Remotion Studio.

Find the component that is passed to <Composition> and the file where the composition is registered.
Define a z.object() schema that describes the props the component accepts.
Use z.infer<typeof schema> as the React component prop type.
Attach the schema to the <Composition> using the schema prop.
Add defaultProps to the <Composition> that match the schema and preserve the current rendered output.

If zod or @remotion/zod-types are missing, install them with npx remotion add @remotion/zod-types zod.
Keep the existing composition behavior unchanged except for making the props editable in Remotion Studio.
```

In the Studio, the Ask AI modal is on by default; disable with `npx remotion studio --disable-ask-ai` (config `setAskAiEnabled()`). Deeper agent onboarding lives at `/docs/ai/coding-agents` and `/docs/ai/skills` (not yet ingested).

## Related Entities

- [[summaries/official-ai-rules]] — full summary of the llms.txt source
- [[entities/remotion-studio]] — Ask AI modal; the Studio the agent prompts target
- [[entities/packages-catalog]] — the packages the rules instruct agents to import (`@remotion/media`, `@remotion/gif`, `@remotion/transitions`)
- [[entities/lambda-api-catalog]] — the Lambda flow the rules prescribe
- [[concepts/animation]] and [[concepts/compositions-fundamentals]] — the concepts the rules compress into prompt form



<!-- ===== remotion/wiki/entities/cloudrun-api-catalog.md ===== -->

---
title: "Cloud Run API Catalog (@remotion/cloudrun)"
type: entity
tags: [cloudrun, gcp, catalog, api, serverless-rendering]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-cloudrun-api-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-status-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-deployservice-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-deploysite-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-deleteservice-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-deletesite-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-getorcreatebucket-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-getregions-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-getserviceinfo-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-getservices-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-getsites-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-rendermediaoncloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-renderstilloncloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-speculateservicename-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-testpermissions-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-light-client-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-generate-env-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-setup-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-cli-mdx.md"]
---

# Cloud Run API Catalog (@remotion/cloudrun)

## Overview

This is a CATALOG page mapping the Node.js API of `@remotion/cloudrun` — rendering Remotion videos on GCP Cloud Run. **Status caveat that colors every row**: Cloud Run support is in **Alpha and not actively being developed**; critical bugs are fixed but no new features are added, and Remotion plans to eventually share a runtime with Lambda. Rely on it only if satisfied with what it currently offers (`/docs/cloudrun/status`).

Unlike Lambda's chunked concurrency, a Cloud Run render runs on a single service instance; GCP autoscales by spinning up one instance per request (default concurrency 0, instance cap 100, quota-raisable).

## Characteristics

### Service and site lifecycle

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `deployService()` | Create the Cloud Run rendering service in your GCP project; idempotent for same Remotion version / memory limit / CPU limit / timeout in a region | `/docs/cloudrun/deployservice` |
| `deploySite()` | Bundle the project and upload to a Cloud Storage bucket; returns a serve URL; reuse `siteName` to overwrite on redeploy; create a bucket first via `getOrCreateBucket()` | `/docs/cloudrun/deploysite` |
| `getOrCreateBucket()` | Create (or return existing) Cloud Storage bucket — only 1 bucket per region is necessary | `/docs/cloudrun/getorcreatebucket` |
| `getServices()` | List deployed Remotion services; `compatibleOnly` filters to those matching the installed version | `/docs/cloudrun/getservices` |
| `getServiceInfo()` | Info about one service by name + region; throws if it does not exist (use to probe existence) | `/docs/cloudrun/getserviceinfo` |
| `deleteService()` | Delete a deployed service by name (list via `getServices()` first) | `/docs/cloudrun/deleteservice` |
| `getSites()` | List Remotion projects in the bucket's `sites/` subdirectory (no bucket name needed — one bucket per region) | `/docs/cloudrun/getsites` |
| `deleteSite()` | Remove a project (deletes all files under its `sites/` subfolder) | `/docs/cloudrun/deletesite` |
| `speculateServiceName()` | Predict the service name `deployService()` / `npx remotion cloudrun services deploy` would create from a known config | `/docs/cloudrun/speculateservicename` |

### Rendering

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `renderMediaOnCloudrun()` | Kick off a media render. Requires a deployed service and a site/serve URL. Pass `serviceName` *or* `cloudRunUrl` (not both) + `region`, `serveUrl`, `composition`, `codec`. Returns `{type: 'success', bucketName, renderId, ...}` | `/docs/cloudrun/rendermediaoncloudrun` |
| `renderStillOnCloudrun()` | Same for a single still image | `/docs/cloudrun/renderstilloncloudrun` |
| `getRegions()` | Array of GCP regions supported by this release | `/docs/cloudrun/getregions` |
| `testPermissions()` | Calls GCP's Test IAM Permissions API and validates the Service Account's permissions against what this Remotion version requires; missing permissions are reported in the return value (no throw). CLI: `npx remotion cloudrun permissions` | `/docs/cloudrun/testpermissions` |

### Light client

From v4.0.84, import renderer-independent functions from `@remotion/cloudrun/client` — bundleable with ESBuild/Webpack (e.g. Next.js serverless endpoints): `deleteService, deleteSite, getOrCreateBucket, getRegions, getServiceInfo, getServices, getSites, renderMediaOnCloudrun, renderStillOnCloudrun, speculateServiceName` plus types `RenderMediaOnCloudrunInput`, `RenderStillOnCloudrunInput`. Edge runtimes (Vercel Edge, Cloudflare Workers) are not supported, and calling from the browser leaks GCP credentials — don't. (`/docs/cloudrun/light-client`)

## How to Use

Setup (`/docs/cloudrun/setup`): install `@remotion/cloudrun`, create a GCP project, then generate credentials. Authentication uses a Service Account key in a `.env` file; GCP Cloud Shell can generate it via Remotion's script (requires owner role; GCP caps keys at 10 per service account — delete stale keys, keep the `.env` out of source control).

Minimal render call:

```tsx
import {renderMediaOnCloudrun} from '@remotion/cloudrun/client';

const result = await renderMediaOnCloudrun({
  region: 'us-east1',
  serviceName: 'remotion-render-bds9aab',
  composition: 'MyVideo',
  serveUrl: 'https://storage.googleapis.com/remotioncloudrun-123asd321/sites/abcdefgh',
  codec: 'h264',
});

if (result.type === 'success') {
  console.log(result.bucketName);
  console.log(result.renderId);
}
```

CLI command groups exist under `npx remotion cloudrun` (`sites`, `services`, `render`, `still`, `permissions`; see `/docs/cloudrun/cli`). Operations docs: region selection (deploy service and bucket in the same region), instance count (min instances default 0 — scale-to-zero; raise to cut cold starts), limits (standard GCP quotas), production checklist, upgrading (bump all packages, optionally delete old services), uninstall.

## Related Entities

- [[concepts/cloudrun]] — concept-level guide and trade-offs
- [[entities/lambda-api-catalog]] — the actively-developed AWS sibling; prefer it for new projects
- [[entities/packages-catalog]] — `@remotion/cloudrun` in the package space
- [[syntheses/rendering-path-picker]] — choosing between Lambda, Cloud Run, SSR and Studio renders



<!-- ===== remotion/wiki/entities/framework-integrations.md ===== -->

---
title: "Framework Integrations"
type: entity
tags: [integrations, angular, electron, runtimes, design-tools, react-versions]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-angular-mdx.md", "raw/github_doc-packages-docs-docs-react-native-mdx.md", "raw/github_doc-packages-docs-docs-figma-mdx.md", "raw/github_doc-packages-docs-docs-after-effects-mdx.md", "raw/github_doc-packages-docs-docs-spline-mdx.md", "raw/github_doc-packages-docs-docs-electron-mdx.md", "raw/github_doc-packages-docs-docs-bun-mdx.md", "raw/github_doc-packages-docs-docs-deno-mdx.md", "raw/github_doc-packages-docs-docs-react-18-mdx.md", "raw/github_doc-packages-docs-docs-react-19-mdx.md", "raw/github_doc-packages-docs-docs-jsx-support-mdx.md", "raw/github_doc-packages-docs-docs-maps-mdx.md", "raw/github_doc-packages-docs-docs-shaders-mdx.md"]
---

# Framework Integrations

## Overview

Remotion is React at its core, but it is routinely used beyond a plain React app: embedded into Angular apps via the Player, fed designs from Figma, After Effects and Spline, packaged inside Electron desktop apps, and run on alternative runtimes like Bun and Deno. This page maps what is officially supported, what is experimental, and what is explicitly not planned.

Note: the raw doc named "solid" covers Remotion's `<Solid>` canvas component (a solid-color rectangle for effects), **not** a SolidJS integration. Svelte and Vue integration guides exist officially (`/docs/svelte`, `/docs/vue`) but are not yet ingested into this KB.

## Characteristics

| Integration | Status | Mechanism |
|---|---|---|
| Angular | Supported guide | Embed `@remotion/player` via a React `createRoot()` wrapper component |
| Svelte / Vue | Official guides exist (not yet ingested) | Same Player-embedding pattern |
| React Native | **Not planned** — per-frame re-rendering model performs poorly; App.js experimental renderer and an Expo DOM components experiment exist but were not pursued | — |
| Figma | Import workflow | Copy design as SVG → convert to React component (e.g. SVGR) → animate `<g>` groups with `spring()`/`interpolate()` |
| After Effects | Import workflow | Export composition as Lottie JSON via Bodymovin plugin → play with `<Lottie>` from `@remotion/lottie` |
| Spline | Import workflow (reported out of date) | Export 3D model as React Three Fiber code → render in `<ThreeCanvas>` from `@remotion/three` |
| Maps | Guide | MapLibre GL JS + Turf.js, gated with `useDelayRender()` |
| WebGL shaders | Guide | Render to `<canvas>`; drive uniforms from `useCurrentFrame()` for determinism |
| Electron | Experimental, official template | Render in the main process via `@remotion/renderer`; prebuild bundle at package time |
| Bun | Mostly supported (from v1.0.3) | `remotionb` CLI variant; known issues: `lazyComponent` disabled, SSR scripts may not auto-quit (as of Bun 1.0.24 / Remotion 4.0.88) |
| Deno | **Not supported**, experimental escape hatch | `remotiond` CLI variant (from v2.0.227) with explicit permission flags |
| React 18 / 19 | Supported | Remotion ≥3.0.0 for React 18; ≥4.0.0 for React 19 |
| Plain JavaScript | Supported since 1.3 | Rename entry files to `.jsx`, drop types |

## How to Use

**Angular** — install the Player stack, then bridge React into Angular:

```bash
npm i remotion @remotion/player @remotion/cli @remotion/zod-types react react-dom zod
npm i --save-dev @types/react @types/react-dom
```

Keep Remotion files in `src/app/remotion`, copy `remotion.config.ts` next to `package.json`, set `"jsx": "react"` (plus recommended `"skipLibCheck": true`) in `tsconfig.json`, then write a wrapper `@Component` that calls `createRoot()` in `ngAfterViewInit()` and renders a `<Player>` with a `PlayerRef`. Use it as `<app-player-view [data]="data" (onPaused)="playerPaused()"></app-player-view>`. Reference: `remotion-dev/angular-starter`.

**After Effects** — install the Bodymovin ZXP plugin, enable `Allow Scripts to Write Files and Access Network` under `Preferences -> Scripting & Expressions...`, export the composition as JSON, put it in `public/`, and load via `staticFile()` into `<Lottie>` with a `delayRender()`/`continueRender()` pair.

**Figma** — right-click a design, **Copy/Paste as** SVG, convert to a React component, register a `<Composition>`, and animate grouped `<g>` elements (set `transformOrigin: "center center"`, `transformBox: "fill-box"`).

**Spline** — export as **Code (Experimental)** → react-three-fiber, `npm install @splinetools/r3f-spline`, scaffold with `npx create-video@latest` (Three template), wrap in `<ThreeCanvas width={width} height={height}>`.

**Electron** — use the official Electron template (Electron Forge + Vite): keep the Remotion project in `remotion/`, trigger renders over IPC, run `selectComposition()` and `renderMedia()` in the main process, and build the bundle during packaging — never call `bundle()` at packaged runtime. Point `binariesDirectory` at a compositor package inside `app.asar.unpacked` (binaries must not load from inside `app.asar`). Linux needs the libc-matching compositor package (`@remotion/compositor-linux-x64-gnu` vs `-musl`). For offline renders set `REMOTION_ELECTRON_PACKAGE_BROWSER=true` during packaging (not supported for macOS universal builds — call `ensureBrowser()` at runtime there).

**Bun** — `bun create video` scaffolds with scripts set to `bunx remotionb`; use `remotionb` instead of `remotion` for the Bun runtime (e.g. `npx remotionb render`).

**Deno** — `npx remotiond`, which requires: `--allow-env --allow-read --allow-write --allow-net --allow-run --allow-sys`.

**React upgrades** — React 18: bump `remotion`, `@remotion/bundler`, `@remotion/cli`, `@remotion/renderer` to `3.0.0`, `react`/`react-dom` to `18.2.0`, `@types/react` to `18.0.0`; `React.FC` no longer includes `children`; `createRoot()` is adopted automatically. React 19: Remotion ≥`4.0.0`, ref type errors fixed in v4.0.236; upgrade React Three Fiber to `9.1.2` + `three` `0.171.0`, `styled-components` v6, Next.js 15; React Native Skia has no React 19 support — stay on React 18.

## Related Entities

- [[entities/packages-catalog]] — `@remotion/player`, `@remotion/lottie`, `@remotion/three`, compositor packages
- [[entities/remotion-studio]] — the dev environment regardless of host framework
- [[entities/ai-integration]] — agents scaffolding projects across these setups
- [[concepts/player]] — the embedding primitive all framework integrations rely on
- [[concepts/installation-setup]] — base project setup the integrations adapt
- [[concepts/rendering-ssr]] — `bundle()` / `renderMedia()` used by the Electron flow



<!-- ===== remotion/wiki/entities/lambda-api-catalog.md ===== -->

---
title: "Lambda API Catalog (@remotion/lambda)"
type: entity
tags: [lambda, aws, catalog, api, serverless-rendering]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-lambda-api-mdx.md", "raw/github_doc-packages-docs-docs-lambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-setup-mdx.md", "raw/github_doc-packages-docs-docs-lambda-rendermediaonlambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-renderstillonlambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getrenderprogress-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getfunctions-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getfunctioninfo-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getsites-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getorcreatebucket-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getcompositionsonlambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-speculatefunctionname-mdx.md", "raw/github_doc-packages-docs-docs-lambda-presignurl-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getawsclient-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getregions-mdx.md", "raw/github_doc-packages-docs-docs-lambda-simulatepermissions-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getrolepolicy-mdx.md", "raw/github_doc-packages-docs-docs-lambda-getuserpolicy-mdx.md", "raw/github_doc-packages-docs-docs-lambda-webhooks-mdx.md", "raw/github_doc-packages-docs-docs-lambda-pagesrouterwebhooks-mdx.md", "raw/github_doc-packages-docs-docs-lambda-validatewebhooksignature-mdx.md", "raw/github_doc-packages-docs-docs-lambda-rendervideoonlambda-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deployfunction-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deploysite-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deletefunction-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deleterender-mdx.md", "raw/github_doc-packages-docs-docs-lambda-deletesite-mdx.md", "raw/github_doc-packages-docs-docs-lambda-downloadmedia-mdx.md", "raw/github_doc-packages-docs-docs-lambda-downloadvideo-mdx.md", "raw/github_doc-packages-docs-docs-lambda-estimateprice-mdx.md", "raw/github_doc-packages-docs-docs-lambda-approuterwebhook-mdx.md", "raw/github_doc-packages-docs-docs-lambda-expresswebhook-mdx.md", "raw/github_doc-packages-docs-docs-lambda-authentication-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cli-mdx.md", "raw/llms_txt-remotion-ai-rules.md"]
---

# Lambda API Catalog (@remotion/lambda)

## Overview

This is a CATALOG page mapping the Node.js API surface of `@remotion/lambda` (AWS Lambda distributed rendering — "the fastest and most scalable way to render Remotion videos; you only pay while you are rendering"). One line per function: purpose, signature essence, official doc path. Prefer importing rendering-path functions from **`@remotion/lambda/client`** (the light client) to avoid bundling problems inside serverless functions.

## Characteristics

### Deployment lifecycle

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `deployFunction()` | Create the rendering Lambda in your AWS account; idempotent if same version/memory/timeout exists. `deployFunction({region, timeoutInSeconds, memorySizeInMb, createCloudWatchLogGroup?, diskSizeInMb?, ...}) → {functionName}` | `/docs/lambda/deployfunction` |
| `deploySite()` | Bundle a Remotion project and upload to S3 so Lambdas can render it; redeploy after local changes (reuse `siteName` to overwrite). `deploySite({entryPoint, bucketName, region, siteName?}) → {serveUrl}` | `/docs/lambda/deploysite` |
| `getOrCreateBucket()` | Ensure the per-region Remotion S3 bucket exists (only 1 per region needed); call before `deploySite()`. `getOrCreateBucket({region, enableFolderExpiry?}) → {bucketName}` | `/docs/lambda/getorcreatebucket` |
| `getFunctions()` | List deployed functions; functions are version-bound, so after a Remotion upgrade `compatibleOnly: true` may return `[]` until you redeploy. `getFunctions({region, compatibleOnly}) → [{functionName, memorySizeInMb, timeoutInSeconds, diskSizeInMb, version}]` | `/docs/lambda/getfunctions` |
| `getFunctionInfo()` | Inspect a single function; throws if it doesn't exist. `getFunctionInfo({region, functionName}) → {functionName, memorySizeInMb, diskSizeInMb, timeoutInSeconds, version}` | `/docs/lambda/getfunctioninfo` |
| `deleteFunction()` | Delete a deployed Lambda by name (list via `getFunctions()` first). `deleteFunction({region, functionName})` | `/docs/lambda/deletefunction` |
| `getSites()` | List deployed sites in the `sites/` S3 subdirectory. `getSites({region, forceBucketName?, compatibleOnly?}) → {sites: [{id, bucketName, serveUrl, sizeInBytes, lastModified, version}], buckets}` | `/docs/lambda/getsites` |
| `deleteSite()` | Remove a project from S3 (deletes everything under that site's `sites/` subfolder). `deleteSite({bucketName, siteName, region})` | `/docs/lambda/deletesite` |
| `speculateFunctionName()` | Predict a function name from its config without an API call (synchronous). `speculateFunctionName({memorySizeInMb, diskSizeInMb, timeoutInSeconds}) → "remotion-render-<version>-mem<x>mb-disk<y>mb-<z>sec"` | `/docs/lambda/speculatefunctionname` |
| `getRegions()` | List AWS regions supported by this release (synchronous). `getRegions({enabledByDefaultOnly?}) → string[]`; CLI: `npx remotion lambda regions` | `/docs/lambda/getregions` |

### Rendering and progress

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `renderMediaOnLambda()` | Kick off a distributed video/audio render. `renderMediaOnLambda({region, functionName, serveUrl, composition, codec, inputProps?, privacy?, framesPerLambda?\|concurrency?, frameRange?, maxRetries?, webhook?, outName?, downloadBehavior?, deleteAfter?, ...}) → {bucketName, renderId}`. Codecs: `h264`/`h265`/`vp8`/`vp9`/`gif`/`prores`; `privacy`: `public`/`private`/`no-acl`; `framesPerLambda` and `concurrency` are mutually exclusive, max 200 functions | `/docs/lambda/rendermediaonlambda` |
| `getRenderProgress()` | Poll progress of a `renderMediaOnLambda()` render (each call = one Lambda invocation unless `skipLambdaInvocation: true`, which reads S3 directly — cheaper/faster but requires the standard naming convention). `getRenderProgress({renderId, bucketName, functionName, region, customCredentials?, skipLambdaInvocation?}) → {overallProgress: 0–1, chunks, done, encodingStatus, fatalErrorEncountered, errors, outputFile, renderMetadata, bucket}` | `/docs/lambda/getrenderprogress` |
| `renderStillOnLambda()` | Render a single still frame on Lambda; result returns immediately — do **not** poll `getRenderProgress()`. `renderStillOnLambda({region, functionName, serveUrl, composition, inputProps, imageFormat, frame?, privacy, maxRetries, envVariables?}) → {estimatedPrice, url, sizeInBytes, renderId}` | `/docs/lambda/renderstillonlambda` |
| `getCompositionsOnLambda()` | List compositions of a serve URL via Lambda — for machines that cannot run Chrome (otherwise `getCompositions()` works too). `getCompositionsOnLambda({region, functionName, serveUrl, inputProps}) → compositions[]` (v3.3.2+) | `/docs/lambda/getcompositionsonlambda` |
| `estimatePrice()` | Estimate AWS Lambda cost from region, total execution duration (main + worker + helper functions) and memory size, using the AWS pricing matrix | `/docs/lambda/estimateprice` |
| `renderVideoOnLambda()` | Old name; doc page redirects to `renderMediaOnLambda()` | `/docs/lambda/rendervideoonlambda` |

### Artifacts and storage

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `downloadMedia()` | Download a rendered video/audio/still to the calling machine's disk. `downloadMedia({bucketName, region, renderId, outPath}) → {outputPath, sizeInBytes}`. For end-user downloads use `renderMediaOnLambda()`'s `downloadBehavior` instead | `/docs/lambda/downloadmedia` |
| `downloadVideo()` | Deprecated/moved alias of `downloadMedia()` | `/docs/lambda/downloadvideo` |
| `deleteRender()` | Delete a render and associated metadata. `deleteRender({bucketName, region, renderId}) → {freedBytes}` | `/docs/lambda/deleterender` |
| `presignUrl()` | Turn a private S3 object into a time-limited public URL. `presignUrl({region, bucketName, objectKey, expiresInSeconds, checkIfObjectExists?}) → string` (or `null` if `checkIfObjectExists: true` and missing) | `/docs/lambda/presignurl` |
| `getAwsClient()` | Escape hatch to the underlying AWS SDK v3. `getAwsClient({region, service}) → {client, sdk}` — e.g. `client.send(new sdk.GetObjectCommand(...))` to stream a render, or `PutBucketCorsCommand` to set CORS | `/docs/lambda/getawsclient` |

### Webhooks

| Function | Purpose / signature essence | Docs |
|---|---|---|
| Webhooks overview | POST on render end; headers `X-Remotion-Status` (`success`/`timeout`/`error`), `X-Remotion-Mode` (`production`/`demo`), `X-Remotion-Signature` (HMAC-SHA512 `sha512=<hex>`, or `NO_SECRET_PROVIDED`). Payload: `{renderId, bucketName, expectedBucketOwner, customData (<1KB), type}` + on success `outputUrl`, `outputFile`, `timeToFinish`, `costs`, `lambdaErrors`; on error `errors[]` | `/docs/lambda/webhooks` |
| `appRouterWebhook()` | Webhook endpoint factory for Next.js App Router (v4.0.246+): `appRouterWebhook({secret, testing, extraHeaders?, onSuccess, onError, onTimeout})` → export as `POST` (and `OPTIONS` for the endpoint tester) | `/docs/lambda/approuterwebhook` |
| `pagesRouterWebhook()` | Same options for Next.js Pages Router (v4.0.246+); returns the API-route handler | `/docs/lambda/pagesrouterwebhook` |
| `expressWebhook()` | Same options for an Express.js server; mount on `POST` + `OPTIONS` | `/docs/lambda/expresswebhook` |
| `validateWebhookSignature()` | Manual verification: `validateWebhookSignature({secret, body (parsed JSON, not string), signatureHeader: req.header('X-Remotion-Signature')})` — throws if invalid (v3.2.30+) | `/docs/lambda/validatewebhooksignature` |

### Permissions and policies

| Function | Purpose / signature essence | Docs |
|---|---|---|
| `getUserPolicy()` | Returns the inline JSON policy for the Remotion AWS **user** (CLI: `npx remotion lambda policies user`) | `/docs/lambda/getuserpolicy` |
| `getRolePolicy()` | Returns the inline JSON policy for the **`remotion-lambda-role`** role, i.e. the Lambda function itself (CLI: `npx remotion lambda policies role`) | `/docs/lambda/getrolepolicy` |
| `simulatePermissions()` | Validate the **user** policy (not the role policy) against the AWS Policy Simulator; missing permissions are reported in the result, not thrown. `simulatePermissions({region, onSimulation?}) → {results: [{decision, name}]}`; CLI: `npx remotion lambda policies validate` | `/docs/lambda/simulatepermissions` |

## How to Use

Install and authenticate (env vars in `.env` are picked up by the CLI but **not** by the Node.js APIs; `REMOTION_`-prefixed variants are recommended and take priority):

```
REMOTION_AWS_ACCESS_KEY_ID / REMOTION_AWS_SECRET_ACCESS_KEY
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY
REMOTION_AWS_PROFILE / AWS_PROFILE
```

Typical flow (per the official setup guide, `/docs/lambda/setup`): create IAM policy/role/user (`getUserPolicy()`/`getRolePolicy()` or the `policies` CLI), validate (`simulatePermissions()`), then

1. `deployFunction()` — or CLI: `npx remotion lambda functions deploy`
2. `getOrCreateBucket()` + `deploySite()` — or CLI: `npx remotion lambda sites create src/index.ts --site-name=my-video`
3. `renderMediaOnLambda()` — or CLI: `npx remotion lambda render <serve-url> <composition-id>`
4. Poll with `getRenderProgress()` until `done` or `fatalErrorEncountered`

CLI command groups: `sites`, `functions`, `render`, `still`, `policies`, `compositions`, `regions`, `quotas` (see `/docs/lambda/cli`). Output lands at `renders/${renderId}/out.{extension}` in the site bucket by default; customize with `outName` or a different/custom S3-compatible bucket. Operational guardrails live in the production checklist (`/docs/lambda/checklist`), concurrency (`/docs/lambda/concurrency`), disk size (default 2048MB before 5.0, 10240MB from 5.0), and bucket security (private ACLs default from v4.0.418).

## Related Entities

- [[concepts/lambda]] — concept-level guide (setup, IAM, regions, concurrency, cost, limits, webhooks)
- [[entities/cloudrun-api-catalog]] — the GCP sibling API
- [[entities/packages-catalog]] — where `@remotion/lambda` sits in the package space
- [[entities/ai-integration]] — the official AI rules' prescribed Lambda flow
- [[syntheses/rendering-path-picker]] and [[syntheses/cost-estimation]] — when to choose Lambda and what it costs



<!-- ===== remotion/wiki/entities/packages-catalog.md ===== -->

---
title: "Packages Catalog (@remotion/*)"
type: entity
tags: [packages, catalog, npm, reference-map]
created: 2026-06-11
updated: 2026-06-11
confidence: medium
sources: ["raw/github_doc-packages-docs-docs-bundler-mdx.md", "raw/github_doc-packages-docs-docs-renderer-mdx.md", "raw/github_doc-packages-docs-docs-captions-api-mdx.md", "raw/github_doc-packages-docs-docs-effects-mdx.md", "raw/github_doc-packages-docs-docs-fonts-mdx.md", "raw/github_doc-packages-docs-docs-noise-visualization-mdx.md", "raw/github_doc-packages-docs-docs-light-leaks-guide-mdx.md", "raw/github_doc-packages-docs-docs-get-audio-data-mdx.md", "raw/github_doc-packages-docs-docs-lambda-api-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-api-mdx.md", "raw/github_doc-packages-docs-docs-electron-mdx.md", "raw/github_doc-packages-docs-docs-angular-mdx.md", "raw/llms_txt-remotion-ai-rules.md", "raw/github_release-v4-0-461.md", "raw/github_release-v4-0-470.md", "raw/github_doc-packages-docs-docs-cli-skills-mdx.md", "raw/github_doc-packages-docs-docs-schemas-mdx.md"]
---

# Packages Catalog (@remotion/*)

## Overview

This is a CATALOG page: it maps the `@remotion/*` package space so the KB can answer "does package X exist and where are its docs" without ingesting every package's reference. One line per package; doc paths are on remotion.dev. Packages marked **(not yet ingested)** are referenced in raw sources but have no dedicated raw doc in this KB — treat their rows as low-confidence pointers.

## Characteristics

### Core authoring and tooling

| Package | What it does / key exports | Docs |
|---|---|---|
| `remotion` | Core: `<Composition>`, `<Sequence>`, `<Series>`, `<AbsoluteFill>`, `<Img>`, `useCurrentFrame()`, `useVideoConfig()`, `interpolate()`, `spring()`, `random()`, `staticFile()`, `registerRoot()`, `delayRender()` | `/docs/remotion` |
| `@remotion/cli` | The `npx remotion` CLI: `studio`, `render`, `still`, `compositions`, `bundle`, `benchmark`, `add`, `skills`, `upgrade`, `versions`, `ffmpeg`, `ffprobe`, `gpu` | `/docs/cli` |
| `@remotion/bundler` | `bundle()` — Webpack-bundles a project for SSR functions like `getCompositions()` / `renderMedia()` | `/docs/bundler` |
| `@remotion/renderer` | Server-side rendering: `renderMedia()`, `renderStill()`, `selectComposition()`, `ensureBrowser()`; used internally by CLI and Lambda; config file has no effect on these APIs | `/docs/renderer` |
| `@remotion/player` | `<Player>` + `PlayerRef` — embed previews in your own app | `/docs/player` |
| `@remotion/studio` | Studio APIs (not usable in read-only/static Studio deployments) | `/docs/studio/api` |
| `@remotion/studio-server` (not yet ingested) | Backend for deployed Studio | `/docs/studio/deploy-server` |
| `@remotion/zod-types` | Remotion-specific Zod types (e.g. `zColor`) for visual props editing; install via `npx remotion add @remotion/zod-types zod` | `/docs/zod-types` |
| `@remotion/eslint-config` / `@remotion/eslint-plugin` (not yet ingested) | Lint rules for Remotion projects | `/docs/brownfield-installation` mentions |
| `@remotion/babel-loader` (not yet ingested) | Legacy Babel webpack loader | `/docs/legacy-babel-loader` |
| `@remotion/enable-scss` / `@remotion/tailwind-v4` (not yet ingested) | Webpack overrides for SCSS / Tailwind | `/docs/webpack` area |

### Media, assets, and visuals

| Package | What it does / key exports | Docs |
|---|---|---|
| `@remotion/media` | New `<Video>` and `<Audio>` tags (with `trimBefore`, `trimAfter`, `volume`) — the tags the official AI rules tell agents to use | `/docs/media` |
| `@remotion/media-utils` | Helpers: `getAudioData()`, `getAudioDurationInSeconds()`, `getVideoMetadata()`, `getWaveformPortion()`, `audioBufferToDataUrl()`, `getImageDimensions()` | `/docs/media-utils` |
| `@remotion/gif` | `<Gif>` component for frame-synced animated GIFs | `/docs/gif` |
| `@remotion/google-fonts` | Type-safe Google Fonts loading: `loadFont()` (from v3.2.40) | `/docs/google-fonts` |
| `@remotion/fonts` (not yet ingested) | Load local/custom font files | `/docs/fonts` |
| `@remotion/lottie` | `<Lottie>`, `LottieAnimationData`, `getLottieMetadata()` — plays After Effects/Bodymovin exports | `/docs/lottie` |
| `@remotion/three` | `<ThreeCanvas>` — React Three Fiber inside Remotion | `/docs/three` |
| `@remotion/noise` (not yet ingested as API page) | `noise2D()`/`noise3D()` deterministic noise (usage guide ingested) | `/docs/noise` |
| `@remotion/paths` (not yet ingested) | SVG path utilities | `/docs/paths` |
| `@remotion/shapes` (not yet ingested) | Ready-made SVG shape components | `/docs/shapes` |
| `@remotion/effects` | `effects` arrays for canvas-based components (`<Solid>`, `<HtmlInCanvas>`, `<Video>`, `<Img>`, `<CanvasImage>`); from v4.0.464 | `/docs/effects/api` |
| `@remotion/light-leaks` | `<LightLeak>` component + `lightLeak()` effect (from v4.0.415) | `/docs/light-leaks/api` |
| `@remotion/starburst` (not yet ingested) | `starburst()` effect, accepts CSS color strings | `/docs/starburst/starburst-effect` |
| `@remotion/sfx` (not yet ingested) | Bundled sound effects (e.g. `recordScratch`) | `/docs/sfx` (inferred) |
| `@remotion/motion-blur` (not yet ingested) | Motion blur components | `/docs/motion-blur` |
| `@remotion/animation-utils` (not yet ingested) | Animation helpers (e.g. style interpolation) | `/docs/animation-utils` |
| `@remotion/layout-utils` (not yet ingested) | Text measurement / layout (`fillTextBox` proposed in issues) | `/docs/layout-utils` |
| `@remotion/timeline-utils` (not yet ingested) | Timeline-building helpers: audio waveform utils, `drawRepeatingImageThumbnail()` | `/docs/building-a-timeline` mentions |
| `@remotion/preload` (not yet ingested) | `preloadVideo()`/`preloadAudio()` alternatives to `prefetch()` | `/docs/preload` |

### Captions and transcription

| Package | What it does / key exports | Docs |
|---|---|---|
| `@remotion/captions` | `Caption` type + `parseSrt()`, `serializeSrt()`, `createTikTokStyleCaptions()`, `ensureMaxCharactersPerLine()` (from v4.0.216) | `/docs/captions/api` |
| `@remotion/install-whisper-cpp` (not yet ingested) | Local Whisper.cpp install/transcribe; `toCaptions()` | `/docs/install-whisper-cpp` |
| `@remotion/whisper-web` (not yet ingested) | In-browser Whisper; `toCaptions()` | `/docs/whisper-web` |
| `@remotion/openai-whisper` (not yet ingested) | `openAiWhisperApiToCaptions()` | `/docs/openai-whisper` |
| `@remotion/elevenlabs` (not yet ingested) | `elevenLabsTranscriptToCaptions()` | `/docs/elevenlabs` |

### Rendering at scale and platforms

| Package | What it does / key exports | Docs |
|---|---|---|
| `@remotion/lambda` | AWS Lambda distributed rendering — see [[entities/lambda-api-catalog]] | `/docs/lambda/api` |
| `@remotion/cloudrun` | GCP Cloud Run rendering (alpha, not actively developed) — see [[entities/cloudrun-api-catalog]] | `/docs/cloudrun/api` |
| `@remotion/web-renderer` (not yet ingested) | Client-side (in-browser) rendering | `/docs/miscellaneous/render-in-browser` mentions |
| `@remotion/compositor-*` (not yet ingested) | Platform-specific native compositor binaries, e.g. `@remotion/compositor-linux-x64-gnu`, `-musl`, `@remotion/compositor-darwin-arm64`; needed for Electron packaging | `/docs/electron` |
| `@remotion/transitions` | `<TransitionSeries>`, `linearTiming()`, `springTiming()`, presentations `fade()`, `wipe()` | `/docs/transitions` |
| `@remotion/skills` / `@remotion/skills-evals` (not yet ingested) | Agent Skills distribution and visual eval runner | `/docs/ai/skills` |
| `@remotion/skia` / `@remotion/rive` / `@remotion/vue` (not yet ingested) | Skia renderer, Rive animations, Vue integration | `/docs/skia`, `/docs/rive`, `/docs/vue` |

## How to Use

Install any package alongside the matching `remotion` version — versions must stay in sync across `remotion`, `@remotion/cli`, `@remotion/bundler`, `@remotion/renderer`, etc. (the upgrade guides bump them together). The CLI provides a helper that picks your package manager:

```bash
npx remotion add @remotion/zod-types zod
```

For a new project: `npx create-video@latest`. To find a package's full API, follow the docs path in the table on remotion.dev.

## Related Entities

- [[entities/lambda-api-catalog]] — the function-level map of `@remotion/lambda`
- [[entities/cloudrun-api-catalog]] — the function-level map of `@remotion/cloudrun`
- [[entities/remotion-studio]] — `@remotion/studio` / `@remotion/cli` in practice
- [[entities/framework-integrations]] — which packages each integration pulls in
- [[entities/ai-integration]] — packages the official AI rules instruct agents to use
- [[concepts/captions]], [[concepts/transitions]], [[concepts/player]], [[concepts/rendering-ssr]] — concept pages for the major package families



<!-- ===== remotion/wiki/entities/remotion-studio.md ===== -->

---
title: "Remotion Studio"
type: entity
tags: [studio, preview, cli, rendering, props-editing]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-cli-studio-mdx.md", "raw/github_doc-packages-docs-docs-preview-mdx.md", "raw/github_doc-packages-docs-docs-render-mdx.md", "raw/github_doc-packages-docs-docs-schemas-mdx.md", "raw/github_doc-packages-docs-docs-config-mdx.md", "raw/github_doc-packages-docs-docs-get-remotion-environment-mdx.md", "raw/github_release-v4-0-461.md"]
---

# Remotion Studio

## Overview

The Remotion Studio is the browser-based development environment for Remotion projects. It is what you see when you "preview your video": a timeline-based editor served from a local dev server where you scrub through compositions, edit props visually, trigger renders from a UI, and (since v4.0.461) even make code edits. It is distinct from the [[concepts/player]] (`@remotion/player`), which embeds video previews into *your* app — the Studio is the tool *you* work in while building compositions.

The Studio ships as part of the standard project setup: the `@remotion/studio` package backs the UI, and the `@remotion/cli` package exposes it as the `studio` command (alias: `preview`).

## Characteristics

- **Launch model**: a server starts on port `3000` (or the next free port) and the Studio opens in your browser. `npm run dev` is the conventional script in regular templates; Next.js and React Router 7 templates use `npm run remotion` (older projects used `npm start`).
- **Visual props editing**: if you attach a Zod schema to a `<Composition>` via the `schema` prop, the Studio lets you edit props visually — useful for quickly trying values (official doc: `/docs/visual-editing`, `/docs/schemas`).
- **Render UI**: clicking the **Render** button in the Studio opens a settings dialog; confirm with **Render video**. This is the no-CLI rendering path (official doc: `/docs/render`).
- **Code edits**: enabled in Studio as of v4.0.461 (official doc: `/docs/studio/code-edits`).
- **Ask AI modal**: the Studio includes an Ask AI feature; disable it with `--disable-ask-ai` (config: `setAskAiEnabled()`). See [[entities/ai-integration]].
- **Deployable**: the Studio can be deployed to a long-running cloud server so non-technical team members can render videos via a URL (official doc: `/docs/studio/deploy-server`), or deployed statically (`/docs/studio/deploy-static`). In a statically deployed Studio, `getRemotionEnvironment().isReadOnlyStudio` is `true` and the `@remotion/studio` APIs cannot be used (available from v4.0.238).
- **Configurable via `remotion.config.ts`**: e.g. `Config.setStudioPort(3003)`, max timeline tracks shown (default `15`), keyboard shortcuts, Rspack instead of Webpack (`setRspackEnabled` equivalent flag), buffering UI delay (default `300` ms). CLI flags take precedence over config file options.

## How to Use

Start the Studio (an entry point may be passed as argument, otherwise it is auto-determined):

```bash
npx remotion studio <entry-point>?
```

Or via the template scripts:

```bash
npm run dev        # regular templates
npm run remotion   # Next.js / React Router 7 templates
```

Key flags of `npx remotion studio` (verbatim, with version availability):

| Flag | Purpose |
|---|---|
| `--props` | Pass input props (inline JSON not supported on Windows shells — use a file name) |
| `--config` (v1.2.0) | Custom config file |
| `--env-file` (v2.2.0) | Custom .env location |
| `--log` | `error`, `warn`, `info` (default), `verbose` |
| `--port` | Studio port |
| `--public-dir` (v3.2.13) | Custom public directory |
| `--disable-keyboard-shortcuts` (v3.2.11) | Turn off shortcuts |
| `--enable-experimental-client-side-rendering` (v4.0.387) | Experimental client-side rendering |
| `--allow-html-in-canvas` (v4.0.447) | Allow `<HtmlInCanvas>` |
| `--experimental-rspack` (v4.0.426) | Rspack bundler instead of Webpack |
| `--webpack-poll` (v3.3.11) | Polling instead of file watching |
| `--no-open` (v3.3.19) | Don't auto-open browser |
| `--browser` / `--browser-args` (v3.3.79) | Browser selection, e.g. `npx remotion studio --browser-args="--disable-web-security"` |
| `--beep-on-finish` (v4.0.84) | Beep when a render finishes |
| `--ipv4` (v4.0.125) | Force IPv4 |
| `--number-of-shared-audio-tags` (v3.3.2) | e.g. `--number-of-shared-audio-tags=5` |
| `--preview-sample-rate` | e.g. `--preview-sample-rate=44100` |
| `--cross-site-isolation` (v4.0.364) | Enable Cross-Site Isolation |
| `--disable-ask-ai` (v4.0.407) | Disable the Ask AI modal |
| `--force-new` (v4.0.421) | Force a new Studio instance |
| `--public-license-key` (v4.0.398) | e.g. `--public-license-key="your-license-key"` |

Environment variables `BROWSER`, `BROWSER_ARGS` work like the corresponding flags; `BROWSER=none` is equivalent to `--no-open`.

To render from the Studio: click the **Render** button, choose settings, confirm with **Render video**. To make props editable in the render dialog and sidebar, define a Zod schema and `defaultProps` on the `<Composition>` (install with `npx remotion add @remotion/zod-types zod`).

## Related Entities

- [[entities/ai-integration]] — the Studio's Ask AI modal and the agent prompt that makes compositions parameterizable for Studio editing
- [[entities/packages-catalog]] — `@remotion/studio`, `@remotion/studio-server`, `@remotion/cli` package boundaries
- [[entities/framework-integrations]] — the Studio works alongside the Player when Remotion is embedded in other frameworks
- [[concepts/cli-reference]] — `studio` is one command of the Remotion CLI
- [[concepts/compositions-fundamentals]] — what the Studio previews
- [[concepts/rendering-ssr]] — the CLI/SSR alternatives to the Studio render button



<!-- ===== remotion/wiki/log.md ===== -->

---
title: "Activity Log"
type: log
---

# Activity Log

Append-only record of all wiki changes.

## Format

Each entry follows this format:
```
### YYYY-MM-DD HH:MM — [Action Type]
- **Source/Trigger**: what initiated the action
- **Pages created**: list of new pages
- **Pages updated**: list of updated pages
- **Notes**: any contradictions flagged, decisions made
```

---

### 2026-04-08 00:00 — Setup

- **Source/Trigger**: Repository initialized
- **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md
- **Pages updated**: none
- **Notes**: Empty knowledge base ready for first source ingestion

---

### 2026-06-11 — [Initial compilation]
- **Source/Trigger**: KB created via source-pipeline (create_kb.py + agent curation per RECIPE Phase 3, MEDIUM retention ring)
- **Pages created**: full initial set — see index.md (13 concepts, 6 entities incl. 3 catalog pages, 4 summaries incl. solved-issue casebooks, 5 decision syntheses)
- **Sources**: 343 provenance-stamped files in raw/ (repo docs tree incl. lambda/player/cli/cloudrun/transitions/captions subdirs, 15 releases, 40 solved issues, official llms.txt AI-rules doc)
- **Notes**: subdir gather initially capped at 80 and cut off the core Lambda/Player docs alphabetically — re-gathered at max 260 and integrated (lesson recorded); remaining gaps in index.md Gaps/TODO



<!-- ===== remotion/wiki/summaries/casebook-platform.md ===== -->

---
title: "Casebook: Platform, Cloud & Player Issues"
type: summary
tags: [troubleshooting, lambda, cloudrun, windows, safari, player, casebook]
created: 2026-06-11
updated: 2026-06-11
confidence: medium
sources: ["raw/github_issue-getting-error-while-deploying-remotion-in-google-cloud.md", "raw/github_issue-remotion-lambda-client-too-large-to-be-used-in-supabase-edge.md", "raw/github_issue-npm-start-error-no-available-ports-found-on-windows-wsl.md", "raw/github_issue-experiencing-issues-with-remotion-player-on-mobile-safari.md", "raw/github_issue-audio-not-stoping-in-the-player.md", "raw/github_issue-bun-support.md", "raw/github_issue-serverless-example.md"]
---

# Casebook: Platform, Cloud & Player Issues

Solved (or diagnosed) platform-specific problems from real GitHub issues: cloud deployment, Windows/WSL, runtimes, and Player embedding. Confidence is medium — community threads, not all officially confirmed.

## Key Points

### Case 1 — Cloud Run service deploy fails on a new GCP account

- **Symptom:** `npx remotion cloudrun` deployment fails; user tried multiple regions (full output of `npx remotion cloudrun regions`), tried changing max instances to 10 and lowering CPU limit — "value didn't override".
- **Cause:** Remotion does not pass `maxScale` at all and passes `cpu: "1.0"`; the failure traced to **GCP quota limits on new accounts** (user's console showed a per-Job-execution task limit of 10). Newer GCP accounts get lower Cloud Run quotas.
- **Fix/workaround:** check https://cloud.google.com/run/quotas for account limitations and request quota increases via IAM → Quotas (the "Instance limit per region" quota under the Cloud Run Admin API). No code-side fix exists. Thread ended unresolved for the reporter.
- **Issue ref:** remotion-dev/remotion#4970

### Case 2 — `@remotion/lambda/client` too large for Supabase Edge Functions

- **Symptom (verbatim):**
  ```
  Deploying Function: start-render (script size: 34.9MB)
  unexpected status 413: {"message":"request entity too large"}
  ```
  Supabase Edge Functions (Deno) have a 20MB limit; importing `npm:@remotion/lambda@4.0.260/client` produces a ~31-35MB bundle.
- **Cause:** with Deno's `npm:` specifier the whole package gets bundled, pulling in `@remotion/renderer` and AWS SDKs (bundled properly, the client is only ~6MB). Trying `esm.sh/@remotion/lambda@4.0.260/client` instead yields a 300KB bundle but fails at runtime with `[unenv] fs.readFile is not implemented yet!` (browser build, missing Node globals).
- **Fix/workaround:** use the dedicated lightweight client package created for this (PR remotion-dev/remotion#4871, `@remotion/lambda-client`) instead of `@remotion/lambda/client`, or pre-bundle the client yourself so tree-shaking applies.
- **Issue ref:** remotion-dev/remotion#4862

### Case 3 — `npm start` fails on Windows WSL: "No available ports found"

- **Symptom (verbatim):** `Error: No available ports found` when starting Remotion Studio on WSL2 (Ubuntu 24.04, Remotion 4.0.212), even though ports 3000/3001 are free and other dev servers (Next/Vite) bind fine.
- **Cause:** Remotion's `get-port.ts` probes `127.0.0.1` and `0.0.0.0`, which in WSL cause socket connect timeouts; WSL needs the real adapter IP.
- **Fix/workaround:** the WSL host IP can be obtained with:
  ```
  ip route show | grep -i default | awk '{ print $3}'
  ```
  Removing the IPv4 probe locally also fixed it for the reporter. Upstream fix tracked as a $150 bounty to copy Vite's port-probing logic.
- **Issue ref:** remotion-dev/remotion#4315

### Case 4 — Player stutters and glitches on (mobile) Safari

- **Symptom:** rapid pause/unpause causes stuttering and the video snapping back to a previous frame; reproduced on iPhones and desktop Safari, especially with multiple `<Audio>` elements (soundtrack + voiceovers in `<Sequence>`).
- **Diagnosis path:** enable the Player's verbose playback logging (docs: /docs/player/playback-issues). The telltale log spam is repeated seeks:
  ```
  [seek] from 0.6178 to 1.2666. Reason: because time shift is too big. ... timeShift = 0.6489
  ```
- **Cause:** Safari falls behind Remotion's internal clock (CPU-bound; worsens under load), triggering constant re-seeks. Top-level `<Audio>` was fine; `<Audio>` inside `<Sequence>` stuttered. `pauseWhenBuffering` had no significant effect. React strict mode also double-mounts the Player (rule that out when reading logs).
- **Fix/workaround:** no complete fix in-thread; mitigations are reducing simultaneous media elements, simplifying per-frame CSS work, and collecting verbose logs for upstream reports. Treat heavy multi-audio compositions in Safari as a known risk.
- **Issue ref:** remotion-dev/remotion#4662

### Case 5 — Player audio keeps playing after switching browser tabs

- **Symptom:** play a Player video, switch to another tab — audio continues even after the video timeline finishes.
- **Cause:** Chrome pauses `requestAnimationFrame()` for unfocused tabs; the Player's visual timeline stops advancing while the audio elements keep playing.
- **Fix/workaround:** handled in the Player package via the `visibilitychange` event (pausing/muting when hidden). If embedding an old Player version, pause the Player on `document.visibilitychange` yourself.
- **Issue ref:** remotion-dev/remotion#2005

### Case 6 — Runtime support: Deno/Bun are not first-class

- **Symptom (verbatim, Deno):** `error: Uncaught TypeError: Cannot read property 'ReactCurrentDispatcher' of undefined` when importing Remotion via jspm; later `error: Uncaught TypeError: The "original" argument must be of type Function` for `@remotion/renderer`.
- **Cause:** Remotion targets Node.js; native Node modules (path, os, child_process) and TS import conventions block Deno. Bun was noted as the more promising alternative runtime.
- **Status:** long-running issue; strategy is reducing npm dependencies to become more runtime-agnostic. For serverless rendering use Lambda (official) rather than alternative runtimes — see Case 2 for the Deno edge-function caveat.
- **Issue ref:** remotion-dev/remotion#50

### Case 7 — "Can I render serverless?" (origin of Remotion Lambda)

- **Context:** the original request for serverless rendering guidance became Remotion Lambda (first shipped as a beta at v3). Maintainer guidance from the thread that still holds: only AWS Lambda is officially supported as the distributed serverless path; from Vercel/Next.js functions you *invoke* a Lambda render rather than rendering in-function.
- **Issue ref:** remotion-dev/remotion#191

## Relevant Concepts

- [[concepts/lambda]] — the supported serverless path (cases 2, 7)
- [[concepts/cloudrun]] — alpha status and quota caveats (case 1)
- [[concepts/player]] — embedding pitfalls (cases 4, 5)
- [[concepts/installation-setup]] — WSL/port quirks (case 3)
- [[syntheses/rendering-path-picker]] — choosing between Lambda, Cloud Run, SSR
- [[syntheses/troubleshooting-checklist]] — ordered diagnosis sequence
- [[summaries/casebook-rendering]] — companion casebook for render/encode failures

## Source Metadata

- **Type of source:** GitHub issues (community + maintainer responses) on `remotion-dev/remotion`
- **Issue numbers:** #4970, #4862, #4315, #4662, #2005, #50, #191
- **Fetched:** 2026-06-11
- **Caveat:** several threads ended without an officially confirmed fix (cases 1, 4); treat the workarounds as community-validated, not guaranteed.



<!-- ===== remotion/wiki/summaries/casebook-rendering.md ===== -->

---
title: "Casebook: Rendering & Encoding Failures"
type: summary
tags: [troubleshooting, rendering, timeout, flickering, performance, casebook]
created: 2026-06-11
updated: 2026-06-11
confidence: medium
sources: ["raw/github_issue-timeouterror-waiting-for-function-failed-timeout-30000ms-exc.md", "raw/github_issue-error-message.md", "raw/github_issue-loop-component-will-re-mount-a-component-due-to-key-change.md", "raw/github_issue-parallel-frame-capturing-and-encoding-for-better-performance.md", "raw/github_doc-packages-docs-docs-flickering-mdx.md", "raw/github_doc-packages-docs-docs-enametoolong-mdx.md"]
---

# Casebook: Rendering & Encoding Failures

Solved (or diagnosed) rendering problems from real GitHub issues. Each case: symptom with the verbatim error, the cause, and the fix or workaround. Confidence is medium — these are community threads, not all officially confirmed resolutions.

## Key Points

### Case 1 — Render hangs then dies at ~50%: Puppeteer timeout with bundled video

- **Symptom (verbatim):**
  ```
  TimeoutError: waiting for function failed: timeout 30000ms exceeded
      at new WaitTask (.../puppeteer-core/lib/cjs/puppeteer/common/DOMWorld.js:509:34)
  ```
  Render progress stalls mid-render (e.g. `51% | ETA: 43s | 801/1560`) with a `<Video>` in the background. Failing frame index varies between runs.
- **Cause:** a `delayRender()` call is made and never cleared, so Remotion waits forever until the Puppeteer timeout fires. In this case, webpack had trouble loading a large MP4 imported via an `import` statement; reducing `--concurrency=2` did NOT help.
- **Fix/workaround:** do not `import` large videos through the bundler. Serve the asset over HTTP (`cd assets && npx serve`) and pass a plain URL as `src` (e.g. `src="http://localhost:5000/dev-video.mp4"`) — or today, put it in `public/` and use `staticFile()`. Note: passing the URL to webpack `externals` instead produces `The target environment doesn't support EcmaScriptModule syntax so it's not possible to use external type 'module'` — pass the URL string directly as `src`, don't import anything.
- **Issue ref:** remotion-dev/remotion#214

### Case 2 — delayRender timeout while fetching Google Fonts (version regression)

- **Symptom (verbatim):**
  ```
  Render error: A delayRender() "Fetching Inter font {"style":"normal","weight":"100","subset":"cyrillic-ext"}" was called but not cleared after 58000ms. See https://remotion.dev/docs/timeout for help
  ```
- **Cause:** reported as appearing "very recently" with no project changes, around v4.0.280; multiple users reproduced on 4.0.272 and 4.0.265. Suspected regression interacting with long source videos / font fetching.
- **Fix/workaround:** one user resolved it by pinning to **Remotion 4.0.269**; another could not reproduce the fix on 4.0.269 (difference possibly `<Video>` vs `<OffthreadVideo>`). No confirmed root-cause fix in the thread — treat as: pin/downgrade to bisect the regression, and raise the `delayRender` timeout (`delayRenderTimeoutInMilliseconds`, `--timeout`) while diagnosing.
- **Issue ref:** remotion-dev/remotion#5071

### Case 3 — Video flickers / goes black at loop boundaries with `<Loop>`

- **Symptom:** wrapping a video in a loop re-mounts it every iteration, causing a visible flicker:
  ```tsx
  <Loop durationInFrames={100}>
    <Video src={staticFile("video.mp4")}>
  </Loop>
  ```
- **Cause:** `<Loop>` sets `key={"loop" + i}` on its children; the key change re-mounts the `<video>` element each cycle. The same gap also reproduces with back-to-back `<Sequence>` blocks each mounting their own `<Video>` — a sequence that is not current does not render its children, so the video element mounts late. `preloadVideo` does not help.
- **Fix/workaround:** keep the video mounted across the loop — use a single always-mounted `<Sequence>`/component and derive the looped time from `useCurrentFrame()` instead of relying on `<Loop>`-driven remounts. (Tracked upstream as a `<Loop>` refactor to avoid `key`-based remounting.)
- **Issue ref:** remotion-dev/remotion#2207

### Case 4 — Render is slow, CPU underutilized regardless of `--concurrency`

- **Symptom:** rendering a trivial animation is ~2-3x slower than a vanilla headless-Chrome pipeline; raising `--concurrency` (even to 24 on a 12-core 5900X) doesn't increase CPU utilization.
- **Cause:** (historical, Remotion ~v2 era) Remotion used a single browser instance with multiple tabs; Chrome effectively kept one foreground tab, serializing work. Benchmarks in the issue: 1 browser/6 tabs = 67,088ms vs 6 browsers = 43,183ms frame rendering on a 6-core MBP; 39,739ms → 22,189ms on a 5900X.
- **Fix/workaround:** fixed upstream by parallelizing capture and encoding. Today's levers: tune concurrency with `npx remotion benchmark` (too high AND too low are both counterproductive), prefer JPEG screenshots over PNG when no alpha is needed. See [[syntheses/performance-recipes]].
- **Issue ref:** remotion-dev/remotion#584

### Case 5 — Choppy/flickering output during rendering (multi-threading)

- **Symptom:** animations stutter or flicker only in the rendered file, not in Studio preview.
- **Cause:** Remotion renders frames in parallel browser tabs that share no state; any animation not driven purely by `useCurrentFrame()` (CSS animations, `requestAnimationFrame`, state accumulating over time, `Math.random()`) breaks.
- **Fix/workaround:** make components a pure function of frame: same frame in → same image out, no order dependence, `random()` with a static seed instead of `Math.random()`. Escape hatch: `--concurrency=1` fixes many cases but is slow, timing is still not guaranteed, and it blocks rendering via Lambda.
- **Source:** official flickering doc (raw/github_doc-packages-docs-docs-flickering-mdx.md)

### Case 6 — `ENAMETOOLONG` on Windows with many audio layers

- **Symptom (verbatim):**
  ```
  Command failed with ENAMETOOLONG: ffmpeg ...
  ```
- **Cause:** Windows caps command length at 8192 characters; many audio layers generate an FFmpeg command longer than that. FFmpeg has no alternative input mechanism, so Remotion cannot fix it.
- **Fix/workaround:** (1) add `muted` to videos with no sound so they are excluded from the audio mix; (2) render on macOS/Linux/WSL which allow much longer commands; (3) render portions with `--frames` and concatenate with an FFmpeg concat command.
- **Source:** official ENAMETOOLONG doc (raw/github_doc-packages-docs-docs-enametoolong-mdx.md)

## Relevant Concepts

- [[concepts/rendering-ssr]] — where these failures occur
- [[concepts/video-media]] — video tags involved in cases 1, 3
- [[concepts/animation]] — determinism rules behind case 5
- [[syntheses/troubleshooting-checklist]] — ordered diagnosis sequence built from this casebook
- [[syntheses/performance-recipes]] — concurrency and screenshot-format levers
- [[summaries/casebook-platform]] — companion casebook for Lambda/cloud/platform issues

## Source Metadata

- **Type of source:** GitHub issues (community + maintainer responses) on `remotion-dev/remotion`, plus two official troubleshooting docs
- **Issue numbers:** #214, #5071, #2207, #584
- **Fetched:** 2026-06-11
- **Caveat:** issue threads reflect the Remotion version at the time of filing; cases 1 and 4 predate v4 and are partly historical context.



<!-- ===== remotion/wiki/summaries/official-ai-rules.md ===== -->

---
title: "Official AI Rules (remotion.dev/llms.txt)"
type: summary
tags: [ai-integration, llms-txt, code-generation, authoring-rules]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/llms_txt-remotion-ai-rules.md"]
---

# Official AI Rules (remotion.dev/llms.txt)

Remotion publishes an official `llms.txt` at https://www.remotion.dev/llms.txt — system rules for AI assistants generating Remotion code. This page summarizes the rules it mandates.

## Key Points

- **Output contract:** all generated output must be valid React code written in TypeScript.
- **Project structure:** a project = entry file + Root file + components. Scaffold with `npx create-video@latest --blank`. Entry file (`src/index.ts`) calls `registerRoot(Root)`; Root file (`src/Root.tsx`) returns `<Composition>` elements.
- **Composition defaults the rules mandate:** `fps` 30, `width` 1920, `height` 1080, `id` "MyComp"; `defaultProps` must match the shape of the component's React props.
- **Time model:** use `useCurrentFrame()` inside components; frames start at 0. Inside a `<Sequence>`, `useCurrentFrame()` restarts at 0 from the sequence's first visible frame. For `fps`/`durationInFrames`/`width`/`height`, use `useVideoConfig()`.
- **Mandated media tags** (not raw HTML tags):
  - Video → `<Video>` from `@remotion/media`
  - Audio → `<Audio>` from `@remotion/media`
  - Non-animated image → `<Img>` from `remotion`
  - Animated GIF → `<Gif>` from `@remotion/gif` (install the package)
  - All accept regular CSS via `style`.
- **Media props:** `trimBefore` (trim left side by N frames), `trimAfter` (limit duration), `volume` (0–1) on both `<Video>` and `<Audio>`.
- **Assets:** remote URLs, or files in `public/` referenced via `staticFile('audio.mp3')` — never plain paths.
- **Layering:** stack elements with `<AbsoluteFill>`; later children render in front.
- **Timing components:**
  - `<Sequence from={10} durationInFrames={20}>` — shift content in time; negative `from` starts immediately but cuts off the first frames.
  - `<Series>` with `<Series.Sequence durationInFrames={...} offset={...}>` — sequential scenes (no `from`; `offset` shifts start).
  - `<TransitionSeries>` from `@remotion/transitions` with `linearTiming`/`springTiming` and presentations like `fade()`, `wipe()`. **Order matters:** `TransitionSeries.Transition` must sit between `TransitionSeries.Sequence` tags. `TransitionSeries.Sequence` has no `offset`.
- **Determinism rule:** `Math.random()` is forbidden. Use `random('my-seed')` from `remotion` with a static seed (returns 0–1).
- **Animation rules:**
  - `interpolate(frame, inputRange, outputRange, options)` — code should add `extrapolateLeft: 'clamp'` and `extrapolateRight: 'clamp'` by default.
  - `spring({fps, frame, config: {damping: 200}})` — animates 0→1; duration not fixed in advance.
- **Rendering commands:** `npx remotion render MyComp` (video), `npx remotion still MyComp` (still image).
- **Lambda rules:** complete the setup at /docs/lambda/setup; rendering requires a Lambda function + a site on S3.
  - CLI: `npx remotion lambda functions deploy`, `npx remotion lambda sites create` (first arg = entry point), `npx remotion lambda render [comp-id]`.
  - Node APIs: `deployFunction()`, `deploySite()`, `renderMediaOnLambda()`, and **progress must be polled with `getRenderProgress()`**.

## Relevant Concepts

- [[concepts/compositions-fundamentals]] — Composition, Sequence, Series defaults the rules encode
- [[concepts/animation]] — interpolate/spring conventions
- [[concepts/video-media]] — the mandated media tags
- [[concepts/transitions]] — TransitionSeries ordering rules
- [[concepts/lambda]] — the Lambda command sequence
- [[entities/ai-integration]] — how Remotion positions these rules for agents
- [[syntheses/media-tag-picker]] — why `@remotion/media` tags are the default recommendation

## Source Metadata

- **Type of source:** official `llms.txt` published by Remotion
- **Author:** Remotion team
- **URL:** https://www.remotion.dev/llms.txt
- **Fetched:** 2026-06-11
- **Note:** this is normative guidance (what Remotion wants AI to generate), notably preferring the newer `@remotion/media` tags over `<OffthreadVideo>`/`<Html5Video>`.



<!-- ===== remotion/wiki/summaries/release-digest.md ===== -->

---
title: "Release Digest (v4.0.461 – v4.0.475)"
type: summary
tags: [releases, versioning, studio, effects, changelog]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_release-v4-0-461.md", "raw/github_release-v4-0-462.md", "raw/github_release-v4-0-463.md", "raw/github_release-v4-0-464.md", "raw/github_release-v4-0-465.md", "raw/github_release-v4-0-466.md", "raw/github_release-v4-0-467.md", "raw/github_release-v4-0-468.md", "raw/github_release-v4-0-469.md", "raw/github_release-v4-0-470.md", "raw/github_release-v4-0-471.md", "raw/github_release-v4-0-472.md", "raw/github_release-v4-0-473.md", "raw/github_release-v4-0-474.md", "raw/github_release-v4-0-475.md"]
---

# Release Digest (v4.0.461 – v4.0.475)

**CURRENT LATEST VERSION: v4.0.475** (published 2026-06-10).

## Key Points

- **The current latest Remotion version is v4.0.475**, released 2026-06-10. The 15 releases covered here span 2026-05-14 (v4.0.461) to 2026-06-10 (v4.0.475).
- **Release cadence: roughly one release every 2 days.** Remotion ships small, frequent patch releases on the 4.0.x line; pinning an exact version and upgrading deliberately (e.g. `npx remotion upgrade`) is the practical workflow.
- **Two headline features dominate this window:**
  - **The effects system** (`@remotion/effects`), launched in v4.0.465 and expanded in nearly every release since: `blur()`, `grayscale()`, `invert()`, `hue()`, `brightness()`, `scale()`, `halftone()`, `tint()`, `saturation()`, `mirror()`, `barrelDistortion()`, `chromaticAberration()`, `contrast()`, `duotone()`, `glow()`, `vignette()`, `shine()`, `colorKey()`, `linearProgressiveBlur()`, `noiseDisplacement()`, `fisheye()`, and more. Effects apply during video rendering as of v4.0.470.
  - **Studio interactivity**, released in v4.0.475: click/drag items on the canvas, drag effects and assets onto elements, set keyframes for CSS/component/effect props, drag layers in the timeline. Built-in interactive components: `<Img>`, `<AnimatedImage>`, `<Video>`, `<Sequence>`, `<HtmlInCanvas>`, `@remotion/shapes`, `<Gif>`, `<Solid>`; regular HTML opts in via `<Interactive.Div>` (`<div>` → `<Interactive.Div>`). Opt out with the Studio "Outline Toggle" or `showInTimeline={false}`.
- Notable changes per release:
  - **v4.0.461** (2026-05-14): Enable Code Edits in Studio; fix easing overshoot in `interpolate()`.
  - **v4.0.462** (2026-05-15): Allow an array for `Easing` in `interpolate()`; bundler symlinks public dir for ephemeral CLI render bundles; stable Chrome now suffices for HTML-in-canvas (Canary no longer required).
  - **v4.0.463** (2026-05-19): `preservesPitch` prop support; `hidden` prop on `<Sequence>`; fix browser download on Node 26; fix Studio localStorage quota errors.
  - **v4.0.464** (2026-05-20): New `<Solid>` component; `@remotion/sfx` gains 20 more sound effects; many Studio fixes.
  - **v4.0.465** (2026-05-22): **Effects system launch**; `<Img>` inherits from `<Sequence layout="none">`; `dissolve()` transition presentation.
  - **v4.0.466** (2026-05-25): Keyframe interval option in renderer; effect avalanche (grayscale, invert, hue, brightness, scale, halftone, tint, saturation, mirror, barrelDistortion); new transition presentations `ripple()`, `swap()`, `crosswarp()`, `bookFlip()`, `linearBlur()`, `dreamyZoom()`; Studio Composition menu and keyframe markers.
  - **v4.0.467** (2026-05-26): New `<CanvasImage>` component; restored CSS Modules support in bundler; `requestInit` prop in `@remotion/media`; `crossZoom()` and `filmBurn()` presentations.
  - **v4.0.468** (2026-05-27): Fix `<Audio>` volume callback not starting at 0; `duotone()`, `glow()`, `vignette()`, `shine()` effects; new `@remotion/light-leaks` and `@remotion/starburst` effect packages.
  - **v4.0.469** (2026-05-29): Fix wrong interpretation of CLI boolean flags; `@remotion/dockerfiles` installs `util-linux` in Linux images; `dropShadow()`, speckle, dot-grid effects; Vercel `getRenderProgress()` detach + polling.
  - **v4.0.470** (2026-05-31): `posterize` option on interpolation APIs; fix stacked WebGL effects; effects now applied during video rendering; configurable Studio preview sample rate.
  - **v4.0.471** (2026-06-01): `requestInit` for animated images and `<Gif>`; `pixelDissolve()`, `rings()`, `zigzag()`, `waves()` effects; Zed editor support fix.
  - **v4.0.472** (2026-06-04): `usePixelDensity` API; `pixelDensity` prop on `<Solid>` and `<HtmlInCanvas>`; transform strings supported in `interpolate()`; stabilized Lambda render completion progress; HLS support info updated in video-tag comparison.
  - **v4.0.473** (2026-06-05): Fix `Series.Sequence` from schema; Studio audio asset imports; auto-install packages before drop codemods.
  - **v4.0.474** (2026-06-08): Preserve subframe media durations; `noiseDisplacement()` effect; source alpha masking option; `@remotion/shapes` gains effects/schemas/outline/sequence support; fix frame cache duration check in `@remotion/media`.
  - **v4.0.475** (2026-06-10): **Studio interactivity release**; new `Interactive` components; transform-origin keywords in `interpolate()`; easing in `interpolateColors()`; prevent initial double seek in `@remotion/media`.
- Ongoing investment themes: `@remotion/media` (the new `<Video>`/`<Audio>` tags) gets buffering/seek/premount fixes nearly every release; Studio timeline/keyframe editing is in heavy active development; AI-related tooling (`@remotion/skills`, skills-evals) is being built out internally.

## Relevant Concepts

- [[concepts/installation-setup]] — upgrading and version pinning
- [[concepts/animation]] — `interpolate()` easing array, posterize, transform strings
- [[entities/remotion-studio]] — code edits, keyframes, interactivity
- [[entities/packages-catalog]] — `@remotion/effects`, `@remotion/media`, `@remotion/sfx`, `@remotion/shapes`
- [[syntheses/media-tag-picker]] — `@remotion/media` tags receiving the most fixes
- [[summaries/casebook-rendering]] — version-specific regressions worth knowing before upgrading

## Source Metadata

- **Type of source:** GitHub release notes (official), repository `remotion-dev/remotion`
- **Author:** Remotion team (primarily @JonnyBurger, @samohovets)
- **Date range:** 2026-05-14 to 2026-06-10; fetched 2026-06-11
- **Identifiers:** https://github.com/remotion-dev/remotion/releases/tag/v4.0.461 through v4.0.475



<!-- ===== remotion/wiki/syntheses/cost-estimation.md ===== -->

---
title: "Cost Estimation: What Rendering Actually Costs"
type: synthesis
tags: [cost, lambda, licensing, data-transfer, decision-guide, infrastructure]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-lambda-cost-mdx.md", "raw/github_doc-packages-docs-docs-lambda-cost-example-mdx.md", "raw/github_doc-packages-docs-docs-lambda-data-transfer-cost-mdx.md", "raw/github_doc-packages-docs-docs-lambda-estimateprice-mdx.md", "raw/github_doc-packages-docs-docs-lambda-disk-size-mdx.md", "raw/github_doc-packages-docs-docs-license-mdx.md", "raw/github_doc-packages-docs-docs-lambda-mdx.md", "raw/github_doc-packages-docs-docs-compare-mdx.md"]
---

# Cost Estimation: What Rendering Actually Costs

The Lambda cost model, measured price points, the hidden line items (egress, storage, logs), and how the Remotion license stacks on top of infrastructure cost.

## Comparison

### Measured Lambda price points (official, 2048MB RAM, 10GB disk, default concurrency, us-east-1, Remotion 4.0.381)

| Workload | Cold Lambda | Warm Lambda |
|---|---|---|
| HelloWorld template | $0.001 / 11.02s | $0.001 / 7.56s |
| 1-min video w/ embedded video (same S3 bucket) | $0.021 / 15.52s | $0.017 / 18.91s |
| 10-min remote HD video | $0.108 / 60.98s | $0.103 / 56.09s |
| 10-sec remote 4K video | $0.014 / 53.09s | $0.013 / 45.28s |

Takeaways from the official examples: embedding video inside your video increases cost significantly; 4K resolution significantly increases render time and therefore cost.

### Cost line items per render path

| Line item | Lambda | Cloud Run | Own server (SSR) |
|---|---|---|---|
| Compute | Most expensive per second, but only while rendering | Cheaper than Lambda (no distributed-rendering overhead, no idle billing) | Cheapest compute, but you pay for idle |
| Data transfer | S3 egress on every asset pull — **even same-region**, because it goes over HTTP | GCP egress applies | Your bandwidth |
| Storage | S3 (sites + renders) | Cloud Storage | Your disk |
| Logs | CloudWatch (on by default) | GCP logging | Yours |
| Remotion license | Required for companies (Cloud Rendering Units) | Required for companies (Cloud Rendering Units) | Company license (no cloud units for non-cloud rendering) |

## Analysis

- **`estimatePrice()` makes Lambda cost programmable.** Verbatim example:
  ```ts
  import { estimatePrice } from "@remotion/lambda";

  estimatePrice({
    region: "us-east-1",
    durationInMilliseconds: 20000,
    memorySizeInMb: 2048,
    diskSizeInMb: 2048,
    lambdasInvoked: 1,
  }); // 0.00067
  ```
  The duration is the **sum across all spawned functions** (main orchestrator + chunk renderers + short-lived helpers). It covers AWS Lambda compute only — not S3, not licensing. Disk size is factored in. The CLI also shows an estimate per render.
- **Memory is the linear dial; concurrency is the overhead dial.** Reducing memory linearly reduces cost — tune it down until renders crash, then step back. Lower concurrency means fewer cold starts/browser launches/asset downloads (less total overhead → cheaper) at the price of slower renders. Many users overprovision memory and overpay (per Remotion's distributed-rendering notes).
- **Disk is effectively free — max it.** 10240MB costs <1% more than the default and raises max video length (~8 min at 512MB → ~2h40min at 10240MB, 1080p). Default is 2048MB before v5, 10240MB from v5.
- **Egress is the surprise bill.** Same-region S3 asset pulls still count as egress because the headless browser loads them over HTTP. Three official mitigations: (1) host big assets on Cloudflare R2 (free egress; disable "Bot fight mode" under Security → Settings and use your own domain so the headless browser isn't blocked); (2) use `@remotion/media` `<Video>`/`<Audio>` — byte-range partial downloads fetch only the needed parts, unlike `<OffthreadVideo>` which downloads the entire file (see [[syntheses/media-tag-picker]]); (3) VPC endpoints (delete + redeploy the function for settings to apply; flat per-request fee remains).
- **The license is part of the infrastructure cost equation.** Remotion is free for individuals, for-profit orgs up to 3 employees, and non-profits (and for evaluation). Beyond that, a company license from remotion.pro is required, and **companies using cloud rendering (Lambda or Cloud Run) must additionally set it up with Cloud Rendering Units** (remotion.pro/license). Budget license + AWS together — the cost-example doc explicitly lists "Remotion Licensing: Teams of 4+ people" as an additional cost.
- **Volume flips the calculus.** Lambda's pay-per-render wins at low/spiky volume; a dedicated server's idle cost amortizes at high steady volume ("the more videos you render, the more a long-running server might be worth"). See [[syntheses/rendering-path-picker]].

## Recommendations

- **Before launching anything billed:** run `estimatePrice()` against a representative render and multiply by expected volume; always measure your own composition — official numbers vary by region, bundle weight, and latency.
- **Default config for cost-sane Lambda:** lowest stable memory, `diskSizeInMb: 10240`, default `framesPerLambda` (set it to `null` rather than guessing), cheaper region if latency allows.
- **Big media assets:** move to R2 or switch to `@remotion/media` tags before optimizing anything else — egress often dwarfs compute for media-heavy comps.
- **Faster = cheaper:** every performance recipe ([[syntheses/performance-recipes]]) that cuts render seconds cuts Lambda dollars; pre-compute data once and pass via input props instead of recomputing in every Lambda.
- **Don't forget the license check:** >3 employees and rendering in the cloud → company license + Cloud Rendering Units, in addition to AWS charges.

## Pages Compared

- [[concepts/lambda]] — the platform being priced
- [[concepts/licensing]] — license tiers and Cloud Rendering Units
- [[concepts/cloudrun]] — the cheaper-but-alpha alternative
- [[entities/lambda-api-catalog]] — `estimatePrice()`, `deployFunction()` options
- [[syntheses/rendering-path-picker]] — volume-based path choice
- [[syntheses/performance-recipes]] — speed levers that double as cost levers
- [[syntheses/media-tag-picker]] — partial downloads vs whole-file egress



<!-- ===== remotion/wiki/syntheses/media-tag-picker.md ===== -->

---
title: "Media Tag Picker: Video, OffthreadVideo, Html5Video, Img, Gif & Friends"
type: synthesis
tags: [video-media, components, decision-guide, player, rendering]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-offthreadvideo-mdx.md", "raw/github_doc-packages-docs-docs-html5-video-mdx.md", "raw/github_doc-packages-docs-docs-img-mdx.md", "raw/github_doc-packages-docs-docs-iframe-mdx.md", "raw/github_doc-packages-docs-docs-animatedimage-mdx.md", "raw/github_doc-packages-docs-docs-media-playback-error-mdx.md", "raw/github_doc-packages-docs-docs-flickering-mdx.md", "raw/github_doc-packages-docs-docs-performance-mdx.md", "raw/github_doc-packages-docs-docs-lambda-data-transfer-cost-mdx.md", "raw/llms_txt-remotion-ai-rules.md", "raw/github_issue-loop-component-will-re-mount-a-component-due-to-key-change.md"]
---

# Media Tag Picker: Video, OffthreadVideo, Html5Video, Img, Gif & Friends

Which media component to use when — and the pitfalls of each. Naming history matters: **`<Video>` from `remotion` was renamed `<Html5Video>`; the modern `<Video>` lives in `@remotion/media`.**

## Comparison

### Video tags

| | `<Video>` (`@remotion/media`) | `<OffthreadVideo>` (`remotion`) | `<Html5Video>` (`remotion`, ex-`<Video>`) | Raw HTML5 `<video>` |
|---|---|---|---|---|
| **Render mechanism** | New optimized pipeline (Mediabunny-based) | FFmpeg extracts the exact frame outside the browser, shown via `<Img>`; `<video>` tag in preview | Native `<video>`, `currentTime = frame / fps` | Native, unsynchronized |
| **Performance** | **Optimal — Remotion's recommendation** | Good; frame-perfect during render | "Not optimized"; many tags cause stutters/flicker | n/a |
| **Partial downloads** | **Yes — byte-range requests** (big Lambda egress savings) | No — downloads the entire file to extract a frame | Downloads whole file to mix audio (unless `muted`) | — |
| **Client-side rendering (`@remotion/web-renderer`)** | **Yes (only option)** | No | No | No |
| **`loop` prop** | (use current docs) | **No** — wrap in `<Loop>` with measured duration (`LoopableOffthreadVideo` pattern) | Yes (`loop`, v3.2.29+) | — |
| **Transparency** | — | `transparent` prop (PNG extraction, slower) | No | — |
| **Codecs (render)** | Broad | H.264, H.265, VP8/VP9, AV1 (v4.0.6+), ProRes | Whatever Chrome plays (no HEVC on Linux, no AVI/FLV) | Whatever the browser plays |
| **Official AI rules say** | **Use this one** | Legacy alternative | Legacy alternative | Never |

### Image / embed tags

| Component | Use for | Key pitfalls |
|---|---|---|
| `<Img>` (`remotion`) | Static images; waits for load before screenshotting a frame | Don't use for GIFs; max Chrome resolution 2^29 px; with `effects` (v4.0.469+) it becomes a `<canvas>` and drops `<img>`-only props (`ref`, `srcSet`, `onLoad`, `alt`, ...); unmount or swap `src` on error or the render times out; from v4.0.465 inherits `from`/`durationInFrames` from `<Sequence>` |
| `<IFrame>` (`remotion`) | Embedding webpages; wraps `delayRender()` until loaded | Site animations won't sync — only `useCurrentFrame()`-driven animation renders correctly (flicker risk) |
| `<AnimatedImage>` (`remotion`, v4.0.246+) | Animated GIF/APNG/AVIF/WebP synced to the timeline | Uses `ImageDecoder` API: **Chrome/Firefox only, no Safari** (Player implication!); remote sources need CORS; no `onLoad` |
| `<Gif>` (`@remotion/gif`) | GIFs when Safari support matters or you need `onLoad` | GIF only (no AVIF/APNG/WebP); the official AI rules mandate it for GIFs |

## Analysis

- **The whole tag family exists to solve one problem: deterministic frames.** Raw `<img>`/`<video>` don't tell Remotion to wait, so renders screenshot loading states — the #1 cause of flicker. Every Remotion media tag wraps `delayRender()`/load-waiting.
- **`<OffthreadVideo>` vs `<Html5Video>` is reliability vs features.** FFmpeg frame extraction gives frame-perfect renders and survives "too many video tags" (`error creating media player`) scenarios, but costs: full-file download (egress on Lambda), no `loop`, `transparent` extraction is slower (PNG vs BMP). `<Html5Video>` keeps native behaviors (`loop`) but suffers when many tags mount.
- **`@remotion/media`'s `<Video>` wins on two axes simultaneously:** performance and Lambda data-transfer cost (byte ranges fetch only what the composition uses — see [[syntheses/cost-estimation]]). It's also the only video tag supported in client-side rendering (`@remotion/web-renderer`). It still receives frequent buffering/seek fixes (see [[summaries/release-digest]]) — pin recent versions.
- **Remount = flicker.** `<Loop>` historically re-mounted children via a changing `key`, flickering videos at loop boundaries (issue #2207); back-to-back `<Sequence>` blocks remount video elements the same way. Keep video elements mounted and derive time instead.
- **"Could not play video with src ... [object MediaError]"** is almost always one of: unsupported codec in Chrome (HEVC on Linux, `.avi`, `.flv`), a 404 because a `public/` file was referenced as `"/my-video.mp4"` instead of `staticFile('my-video.mp4')`, missing `Content-Type`/`Content-Range` headers, or an infinite remount loop (e.g. `key={uuidv4()}`). See [[syntheses/troubleshooting-checklist]].

## Recommendations

- **Default: `<Video>`/`<Audio>` from `@remotion/media`** — best performance, partial downloads, web-renderer support, and what the official AI rules mandate ([[summaries/official-ai-rules]]).
- **Pick `<OffthreadVideo>`** when you need its FFmpeg codec coverage (ProRes, AV1), transparency via `transparent`, or you're hitting `<video>`-tag limits — and accept full-file downloads and the `<Loop>` wrapper pattern for looping.
- **Pick `<Html5Video>`** only for legacy code or when you specifically need native `loop` semantics with a single, small video. Add `muted` to silent videos so Remotion skips downloading them for audio mixing.
- **Never use raw `<video>`/`<img>`/`<iframe>`** — use the Remotion wrappers so frames wait for assets.
- **Images:** `<Img>` (with `maxRetries`, default 2, exponential backoff from 1000ms). **GIFs:** `<Gif>` if Safari playback matters, `<AnimatedImage>` if you need WebP/AVIF/APNG and control (`loopBehavior`, `playbackRate`, `fit`) and Chrome/Firefox-only is acceptable.
- **In the Player**, prefetch remote media with `prefetch()` (`blob-url` method; `base64` for Safari audio hiccups) — see [[syntheses/performance-recipes]].

## Pages Compared

- [[concepts/video-media]] — video/audio fundamentals
- [[concepts/player]] — preview-side behavior of these tags
- [[concepts/rendering-ssr]] — render-side behavior
- [[summaries/official-ai-rules]] — the normative tag choices
- [[summaries/casebook-rendering]] — Loop-remount flicker case
- [[syntheses/performance-recipes]] — transparent/toneMapped performance flags
- [[syntheses/cost-estimation]] — partial downloads vs Lambda egress



<!-- ===== remotion/wiki/syntheses/performance-recipes.md ===== -->

---
title: "Performance Recipes: Concurrency, GPU, Prefetch & Encoding"
type: synthesis
tags: [performance, concurrency, gpu, hardware-acceleration, rendering, decision-guide]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-performance-mdx.md", "raw/github_doc-packages-docs-docs-gpu-mdx.md", "raw/github_doc-packages-docs-docs-hardware-acceleration-mdx.md", "raw/github_doc-packages-docs-docs-scaling-mdx.md", "raw/github_doc-packages-docs-docs-slow-method-to-extract-frame-mdx.md", "raw/github_doc-packages-docs-docs-quality-mdx.md", "raw/github_doc-packages-docs-docs-prefetch-mdx.md", "raw/github_issue-parallel-frame-capturing-and-encoding-for-better-performance.md"]
---

# Performance Recipes: Concurrency, GPU, Prefetch & Encoding

The levers that actually move render speed (and Player smoothness), with verbatim flags and values.

## Comparison

| Lever | How | Effect | Applies to |
|---|---|---|---|
| Concurrency | `--concurrency` flag; find optimum with `npx remotion benchmark` | Too high AND too low are both counterproductive | CLI/SSR render |
| Image format | default JPEG (quality 80); `--image-format=png` only for transparency; tune `--jpeg-quality` | PNG screenshots are significantly slower than JPEG | Render |
| GPU (`--gl`) | enable an OpenGL backend during rendering (headless Chrome disables GPU by default) | Big speedup ONLY for GPU content: WebGL (Three.js/Skia/P5/Mapbox), 2D canvas, `box-shadow`, `text-shadow`, `linear-gradient`/`radial-gradient`, `filter: blur()`, `filter: drop-shadow()`, `transform` | Render on GPU machines; **not Lambda (no GPU)** |
| Hardware-accelerated encoding | `--hardware-acceleration if-possible` (CLI) or `hardwareAcceleration: 'if-possible'` in `renderMedia()`; also `Config.setHardwareAcceleration('if-possible')` | Faster encoding; **macOS only (VideoToolbox)**; ProRes from v4.0.228, H.264/H.265 from v4.0.236; not supported on Lambda/Cloud Run | Encoding step |
| Bitrate w/ HW accel | `--video-bitrate=8M` | HW-encoded files are much larger by default; 8M ≈ software-encoded size for H.264 Full HD; `crf` is incompatible with HW encoders | Encoding |
| Codec choice | avoid `vp8`/`vp9` (WebM) unless needed | WebM codecs are very slow to encode | Encoding |
| Resolution | `--scale` (e.g. `--scale=0.5`; max 16; since 4.0.328 non-integer/odd values auto-round) | Lower resolution = faster; higher scale = sharper text on hi-DPI but slower | Render |
| Video tag choice | use `<Video>` from `@remotion/media` | `<Html5Video>` and `<OffthreadVideo>` are "not optimized" per official docs | Render + Player |
| OffthreadVideo flags | leave `transparent` off; set `toneMapped={false}` if color accuracy is secondary | PNG extraction (~40% slower) and tone mapping both cost time | Render |
| Slow frame extraction (pre-v4) | re-encode: `npx remotion ffmpeg -i inputvideo.mp4 outputvideo.mp4`; or prefer VP9 over VP8 / JPEG over PNG | Eliminates "Using a slow method to extract the frame at 1000ms of [video]" | Render (Remotion < 4.0 only) |
| Asset prefetch (Player) | `prefetch(src, {method: 'blob-url'})`; `free()` to release; `base64` for Safari audio hiccups; set `contentType` if server headers are wrong | Media ready before playback; Player-only (no-op when rendering) | Player/Studio |
| Slow JS / data fetching | `--log=verbose` lists slowest frames; `console.time`; `useMemo`/`useCallback`; pre-compute and pass as input props; cache in localStorage | Removes per-frame bottlenecks | Everything |
| Silent video audio | add `muted` to videos without sound | Skips downloading the file for audio mixing | Render |

## Analysis

- **Concurrency is empirical, not "more is better."** The benchmark command exists precisely because the optimum depends on composition and hardware. History: Remotion once ran one browser with many tabs, which serialized rendering (issue #584 measured 67s → 43s frame time by switching to multiple browser instances; 39.7s → 22.2s on a 5900X). Modern Remotion parallelizes, but the lesson stands — measure with `npx remotion benchmark`.
- **Studio/Player feel fast, renders feel slow — because the GPU disappears.** In Studio and Player the GPU is on; headless Chromium disables it. That's why a composition full of `box-shadow`, gradients, and blurs renders far slower than it previews. Options: enable `--gl` on a GPU machine, or replace GPU-heavy CSS with precomputed images. Note what the GPU does NOT accelerate: `<Html5Video>`, `<OffthreadVideo>`, canvas pixel manipulation, and video encoding itself.
- **Two different "hardware" levers get conflated:** GPU rendering of frames (`--gl`, content-dependent) vs hardware-accelerated *encoding* (VideoToolbox on macOS only). They're independent; on Lambda you get neither.
- **Quality and speed share knobs.** CRF controls quality for software encoding; `--video-bitrate` replaces it under hardware acceleration (mutually exclusive with `--crf`). `--x264-preset` trades speed/compression. Sharp text on hi-DPI displays needs output scaling (`--scale=2`), which multiplies render cost — and canvas/WebGL content won't upscale unless components support `pixelDensity` (`<Solid>`, `<HtmlInCanvas>` with `usePixelDensity()`).
- **Cloud renders pay for everything twice:** GPU effects render slowly on CPU-only Lambda AND big assets cost egress. Performance work and cost work overlap heavily — see [[syntheses/cost-estimation]].

## Recommendations

- **Always start with `npx remotion benchmark`** before hand-tuning `--concurrency`.
- **Rendering locally on a Mac with H.264/H.265/ProRes output:** add `--hardware-acceleration if-possible --video-bitrate=8M`.
- **Composition is CSS-effect heavy (shadows/gradients/blur):** either render on a GPU machine with `--gl`, or bake effects into images before rendering on Lambda.
- **Slow renders with embedded videos:** switch to `<Video>` from `@remotion/media` ([[syntheses/media-tag-picker]]); mute silent videos; keep `transparent` off.
- **Player startup jank with remote media:** `prefetch()` assets on mount with `blob-url`; switch to `base64` only if Safari audio stutters.
- **Diagnose before tuning:** `--log=verbose` to find the slowest frames; if early frames are slow that's thread initialization, not your code.
- **Need 4K output of a 1080p comp:** `--scale=2` and accept the slowdown; don't redesign the composition.

## Pages Compared

- [[concepts/rendering-ssr]] — render pipeline these levers act on
- [[concepts/cli-reference]] — `benchmark`, `render` flags
- [[concepts/lambda]] — what's unavailable there (GPU, HW encoding)
- [[concepts/player]] — prefetch applies here only
- [[syntheses/media-tag-picker]] — tag choice as a performance lever
- [[syntheses/cost-estimation]] — speed savings = cost savings on Lambda
- [[summaries/casebook-rendering]] — the multi-tab concurrency history (issue #584)



<!-- ===== remotion/wiki/syntheses/rendering-path-picker.md ===== -->

---
title: "Rendering Path Picker: CLI vs SSR vs Lambda vs Cloud Run"
type: synthesis
tags: [rendering, lambda, cloudrun, ssr, decision-guide, infrastructure]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-compare-mdx.md", "raw/github_doc-packages-docs-docs-render-mdx.md", "raw/github_doc-packages-docs-docs-renderer-mdx.md", "raw/github_doc-packages-docs-docs-lambda-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-mdx.md", "raw/github_doc-packages-docs-docs-cloudrun-limits-mdx.md", "raw/github_doc-packages-docs-docs-lambda-concurrency-mdx.md", "raw/github_doc-packages-docs-docs-lambda-disk-size-mdx.md", "raw/github_doc-packages-docs-docs-distributed-rendering-mdx.md"]
---

# Rendering Path Picker: CLI vs SSR vs Lambda vs Cloud Run

How to choose where a Remotion render runs. Remotion's own comparison adds a fifth option (Vercel Sandbox), included below for completeness.

## Comparison

| | Local CLI (`npx remotion render`) | SSR (`renderMedia()` on your server) | Remotion Lambda | Cloud Run | Vercel Sandbox |
|---|---|---|---|---|---|
| **What it is** | One-off render on your machine (also via Studio render button) | `@remotion/renderer` Node.js/Bun APIs on infra you run | Distributed render across many AWS Lambda functions | Single-instance render on GCP Cloud Run | VM-based render on Vercel |
| **Distributed rendering** | No | No (DIY possible via `combineChunks()`, complex) | **Yes — fastest option** | No | No |
| **Speed** | Bound by one machine | Bound by one machine | Fastest (chunks render in parallel) | One machine | One machine; long cold starts (VM provision + browser download) |
| **Compute cost** | Free (your hardware) | **Cheapest compute**, but you pay for idle | Most expensive compute, but pay only while rendering | Cheaper than Lambda; no idle cost | Usage-based (VM runtime) |
| **Ops burden** | None | **Highest**: queueing, traffic spikes, progress/error handling, logging, server provisioning | Low (deploy function + site; SaaS templates exist) | Low-medium (alpha caveats) | **Lowest** (Vercel account + Blob store, push to deploy) |
| **Key limits** | Machine resources | Whatever you provision | 15-min AWS timeout (~80 min FHD video); 10GB disk → output ≤ ~5GB ≈ 2h FHD; default 1000 concurrent lambdas/region; max concurrency 200, min `framesPerLambda` 5; no AV1 | Max 32GB RAM, 8 vCPU, 60-min timeout, 100 instances (quota-raisable); new GCP accounts get lower quotas | Functions ≤ 800s; longer via `detached: true` + `getRenderProgress()` polling |
| **GPU** | Yes if your machine has one (`--gl`) | Possible (cloud-GPU guide, not officially supported) | **No GPU** | Untested (attachable) | No GPU |
| **Maturity** | Stable | Stable, long-term committed | Stable, long-term committed; most high-volume customers use it | **Alpha, not actively developed**; may be re-based on Lambda's code | New, actively improving |
| **Extra features** | — | Full flexibility, build anything | Webhooks, Apple Emoji, cost estimation, render expiry, PHP/Go/Python clients | — | Detached-render progress polling |

## Analysis

- **Lambda's speed advantage is structural:** it is the only path with built-in distributed rendering — the video is split into chunks rendered in parallel, then stitched. Concurrency is `frameCount / framesPerLambda`; defaults choose 20–∞ frames per Lambda and never exceed 200 functions ("Too many functions" error fires past that, with diminishing returns anyway).
- **Cost and speed trade against each other twice:** Lambda compute is pricier per second but bills only during renders; a server is the cheapest per render but bills while idle. Remotion's own conclusion: *the more videos you render, the more a long-running server might be worth*.
- **Cloud Run's position is precarious:** alpha status, only essential changes being made, and a planned re-architecture to share Lambda's runtime. Real-world deploys also hit new-account GCP quota walls (see [[summaries/casebook-platform]] case 1).
- **DIY distributed SSR is documented but discouraged:** the distributed-rendering guide lists everything Lambda already handles (chunk orchestration, seamless AAC concatenation via `h264-ts`, retries, log symbolication). Build it only if the compute-cost savings clearly beat the engineering cost.
- **GPU rarely matters:** most renders do not speed up with a GPU, and Lambda/Vercel have none. If your content is WebGL-heavy, that pushes you toward a GPU server (SSR path) — see [[syntheses/performance-recipes]].

## Recommendations

- **Pick the local CLI** if: you render occasionally, during development, or in CI (GitHub Actions render is supported). Zero infra.
- **Pick Lambda** if: you build a product where users trigger renders, videos are under ~80 min FHD, and you want the fastest turnaround with minimal ops. This is Remotion's recommendation "for most people" and what its highest-volume customers use.
- **Pick SSR on your own server** if: you render at very high, steady volume (idle cost amortizes), need videos longer than Lambda's limits, need a GPU, need AV1, or need full control over queueing/infra — and you're committed to building queue/progress/logging yourself.
- **Pick Cloud Run** only if: you are GCP-bound and accept alpha software with possible breaking re-architecture. Otherwise prefer Lambda or SSR.
- **Pick Vercel Sandbox** if: you're already on Vercel and want the absolute simplest setup, and cold-start latency is acceptable.
- **Whatever you pick for the cloud:** estimate cost first with `estimatePrice()` — see [[syntheses/cost-estimation]] — and max out Lambda disk (10240MB) since it costs <1% more and lifts the video-length ceiling to ~2h40min at 1080p.

## Pages Compared

- [[concepts/rendering-ssr]] — SSR APIs (`renderMedia()`, `@remotion/renderer`)
- [[concepts/lambda]] — Remotion Lambda
- [[concepts/cloudrun]] — Cloud Run (alpha)
- [[concepts/cli-reference]] — `npx remotion render`
- [[syntheses/cost-estimation]] — what each path actually costs
- [[syntheses/performance-recipes]] — making any path faster
- [[summaries/casebook-platform]] — real failures on Lambda/Cloud Run/edge runtimes



<!-- ===== remotion/wiki/syntheses/troubleshooting-checklist.md ===== -->

---
title: "Troubleshooting Checklist: Ordered Diagnosis for Failed Renders"
type: synthesis
tags: [troubleshooting, flickering, timeout, cors, decision-guide, rendering]
created: 2026-06-11
updated: 2026-06-11
confidence: high
sources: ["raw/github_doc-packages-docs-docs-flickering-mdx.md", "raw/github_doc-packages-docs-docs-media-playback-error-mdx.md", "raw/github_doc-packages-docs-docs-cors-issues-mdx.md", "raw/github_doc-packages-docs-docs-enametoolong-mdx.md", "raw/github_issue-timeouterror-waiting-for-function-failed-timeout-30000ms-exc.md", "raw/github_issue-error-message.md", "raw/github_doc-packages-docs-docs-lambda-concurrency-mdx.md", "raw/github_issue-npm-start-error-no-available-ports-found-on-windows-wsl.md", "raw/github_issue-experiencing-issues-with-remotion-player-on-mobile-safari.md"]
---

# Troubleshooting Checklist: Ordered Diagnosis for Failed Renders

Work top to bottom: identify the error class by its verbatim signature, then apply the checks in order. Built from the official troubleshooting docs plus the [[summaries/casebook-rendering]] and [[summaries/casebook-platform]] casebooks.

## Comparison

| Error signature (verbatim fragment) | Class | Go to step |
|---|---|---|
| `A delayRender() ... was called but not cleared after ...ms` | Timeout | 1 |
| `TimeoutError: waiting for function failed: timeout 30000ms exceeded` | Timeout (legacy Puppeteer) | 1 |
| `Error: Could not play video with src [source] [object MediaError]` | Media playback | 2 |
| `error creating media player` | Media playback (too many tags) | 2.5 |
| `...has been blocked by CORS policy: ...` | CORS | 3 |
| Output flickers / animations choppy (no error) | Determinism | 4 |
| `Command failed with ENAMETOOLONG: ffmpeg ...` | Windows command length | 5 |
| `Too many functions: This render would cause [X] functions to spawn.` | Lambda concurrency | 6 |
| `Error: No available ports found` | Environment (WSL) | 7 |
| Player stutters in Safari, `[seek] from x to y ... time shift is too big` in logs | Player playback | 8 |

## Analysis

### Step 1 — Timeouts: find the uncleared `delayRender()`

1. The message names the handle (e.g. `"Fetching Inter font {...}"`) — that tells you *which* call never cleared. Fix the underlying load (font, data fetch) and ensure every `delayRender()` has a matching `continueRender()` (or `cancelRender()` on error).
2. Embedded media: never `import` large videos through webpack — put them in `public/` + `staticFile()`, or serve over HTTP (issue #214's fix).
3. Only after the cause is understood, raise the timeout (`delayRenderTimeoutInMilliseconds` on media tags, `--timeout` flag) — raising it blindly just delays the failure.
4. If it appeared after upgrading with no code changes, bisect Remotion versions (issue #5071: one user fixed by pinning 4.0.269).

### Step 2 — Media playback errors, in check order

1. **Codec:** does Chrome play it at all? (No HEVC on Linux, no `.avi`/`.flv`.) Convert if not.
2. **Path:** `public/` assets must use `staticFile('my-video.mp4')` — a plain `"/my-video.mp4"` 404s because Remotion serves statics under a prefix.
3. **Network tab:** open the asset URL directly — expect 200 status, a suitable `Content-Type`, and a `Content-Range` header (required for seeking).
4. **Local interference:** disable Internet Download Manager if installed.
5. **Too many tags / remount loop:** a frequently-changing `key` (e.g. `key={uuidv4()}`) recreates the video element every frame → `error creating media player`. Fix the keys, or switch to `<OffthreadVideo>` / `@remotion/media` `<Video>` ([[syntheses/media-tag-picker]]).
6. **Recoverable?** Pass `onError()` to swap in a fallback source (v3.3.89+).

### Step 3 — CORS: read the second half of the error

The first half of a CORS error is always the same; the diagnosis is in the second half. Map message → header:

- `No 'Access-Control-Allow-Origin' header is present` → send `Access-Control-Allow-Origin: *`
- `Response to preflight request doesn't pass access control check` → also return CORS headers on the `OPTIONS` request (note: adding `Content-Type: application/json` to a POST triggers preflight)
- `Method PUT is not allowed by Access-Control-Allow-Methods` → send `Access-Control-Allow-Methods: *`
- `No 'Access-Control-Allow-Private-Network' header` → send `Access-Control-Allow-Private-Network: true`

If nothing makes sense: DevTools → Network → "Disable cache" (stale cached responses lie).

### Step 4 — Flicker/choppiness: determinism audit

1. All animation must derive from `useCurrentFrame()` — a component is a pure function frame → image. No CSS animations, no `requestAnimationFrame`, no accumulated state.
2. Randomness only via `random(seed)` — never `Math.random()`.
3. Assets must block rendering: use `<Img>`, `<Video>`, `<OffthreadVideo>`, `<Audio>`, `<IFrame>`, `<Gif>`; wrap data loading in `delayRender()`; wait for fonts before `fitText()`/`measureText()`; avoid `background-image`/`mask-image` CSS (they don't wait).
4. Loop-boundary flicker: `<Loop>`/back-to-back `<Sequence>` remounts (casebook case 3) — keep media mounted.
5. Last resort: `--concurrency=1` — slower, timing still not guaranteed, and it blocks Lambda rendering.

### Step 5 — `ENAMETOOLONG` (Windows)

In order: add `muted` to silent videos (removes them from the FFmpeg audio mix) → render on macOS/Linux/WSL (8192-char Windows limit doesn't apply) → render in parts with `--frames` and FFmpeg-concat.

### Step 6 — Lambda "Too many functions"

You set `framesPerLambda` too low (max concurrency is 200; minimum `framesPerLambda` is 5). Set `framesPerLambda: null` and let Remotion choose; beyond 200 functions returns diminish anyway.

### Step 7 — Environment: Studio won't start on WSL

`Error: No available ports found` on WSL2 is the `get-port.ts` 127.0.0.1/0.0.0.0 probe issue — get the real adapter IP with `ip route show | grep -i default | awk '{ print $3}'` (casebook-platform case 3).

### Step 8 — Player stutter (especially Safari)

Enable verbose Player logging per /docs/player/playback-issues and look for repeated `[seek] ... time shift is too big` lines = the browser can't keep up. Reduce simultaneous `<Audio>`/`<Video>` elements (audio inside `<Sequence>` is the worst offender), `prefetch()` media, and rule out React strict-mode double-mounting when reading logs.

## Recommendations

- **Triage by verbatim signature first** (table above) — most Remotion errors name their own fix.
- **Fix causes before raising timeouts or dropping concurrency** — `--concurrency=1` and bigger timeouts mask determinism and loading bugs that will resurface on Lambda.
- **Make the determinism audit (step 4) part of code review** for every composition; it prevents the two most common failure classes (flicker and timeouts) before they happen.
- **For cloud-specific failures** (quota walls, bundle-size limits, egress surprises) continue with [[summaries/casebook-platform]] and [[syntheses/rendering-path-picker]].
- **For slow-but-successful renders**, this page is the wrong tool — use [[syntheses/performance-recipes]].

## Pages Compared

- [[summaries/casebook-rendering]] — rendering failures feeding this checklist
- [[summaries/casebook-platform]] — platform/cloud failures feeding this checklist
- [[concepts/rendering-ssr]] — where steps 1–6 occur
- [[concepts/player]] — where step 8 occurs
- [[concepts/video-media]] — media-tag behavior behind steps 2 and 4
- [[syntheses/media-tag-picker]] — tag swaps as fixes
- [[syntheses/performance-recipes]] — the non-failure performance path