remotion-best-practices

Remotion Best Practices

Domain-specific knowledge for writing, animating, and rendering Remotion videos in React. Mirrored from the upstream remotion-dev/skills and remotion-dev/remotion .claude snapshots — see upstream.json for SHAs and scripts/check-upstream.sh for drift detection.

This is a knowledge skill. Other skills (/cmo-remotion, /video-content, /tiktok-slideshow) chain into it for the rules. Don't invoke it directly to render a video — invoke it to ground yourself before you touch composition code.

On Activation

Read brand files in this order. Each is a soft input — every section below works at L0 with no brand at all:

1. brand/creative-kit.md — colors, typography, visual brand style. Drives palette, font choice, and the look of any composition you scaffold.
2. brand/voice-profile.md — tone, vocabulary. Drives any visible text (titles, captions, subtitle phrasing).
3. brand/audience.md — who watches. Drives pacing (tight cuts for B2C scroll feeds, longer holds for B2B explainers).
4. brand/positioning.md — what the video is selling. Drives narrative beats and CTA copy.

If any file is missing or template, fall back to neutral defaults: 1920×1080 @ 30fps, system font stack, 6-second hold per beat. Tell the user once: "Brand files thin — using neutral defaults. Run /cmo foundation to ground future videos."

When to use

• User mentions Remotion, useCurrentFrame, interpolate, spring, <Sequence>, <Composition>, staticFile.
• User wants to scaffold a programmatic React video (npx create-video@latest).
• User wants HtmlInCanvas, CRT terminal, glitch, video shader, or WebGL post-processing.
• User is debugging captions, subtitles, voiceover, audio visualization, or ffmpeg-piped Remotion work.
• User is rendering with npx remotion render and hitting WebGL / GPU / fps issues.

Do not use for: assembling a finished MP4 from existing slide PNGs (/video-content), inspiration-to-MP4 from a reference URL (/cmo-video), or TikTok slideshow chains (/tiktok-slideshow).

Hard Rules

These are non-negotiable. Violating them produces black frames, stuttered playback, or render failures.

| Rule | Why | |---|---| | CSS transitions / @keyframes are FORBIDDEN. | Remotion renders frame-by-frame. CSS animations are time-based and will not advance during a still or video render. | | **Tailwind animation classes (animate-*) are FORBIDDEN. | Same reason — they compile to CSS animations. Tailwind for layout/colors is fine; Tailwind for motion is broken. | | Drive every motion off useCurrentFrame() + interpolate() or spring(). | Frame is the only source of truth Remotion can serialize across the render worker pool. | | Use <Img>, <Video>, <Audio> from @remotion/media — never native <img> / <video> / <audio>. | Native elements don't participate in Remotion's frame-locking, so video frames desync from the timeline and audio drifts. | | Reference public assets via staticFile("path") — never hardcoded /path or ./path. | staticFile resolves correctly in Studio, in the renderer, and in deployed Lambda functions. Hardcoded paths break in Lambda. | | Render-then-inspect. | A composition that looks right in Studio can still ship broken frames. Render a still or short clip and look at it before declaring done. | | One-frame sanity check before any long render.** | npx remotion still <id> --frame=30 --scale=0.25 is ~2 seconds. Catches missing assets, font fallbacks, layout overflow, and Tailwind misconfigs before you burn 20 minutes on a 30-second render. |

New project setup

When in an empty folder or a workspace with no existing Remotion project:

npx create-video@latest --yes --blank --no-tailwind my-video
cd my-video
npx remotion studio

Flags:

• --yes — skip the interactive prompt.
• --blank — minimal scaffold, no demo composition.
• --no-tailwind — Tailwind ships with animate-* utilities that will tempt the next agent to use forbidden CSS animations. Skip it. Add Tailwind later only if you need its layout utilities and you're disciplined about animation.

For mktg projects, scaffold under marketing/video/<name>/ so renders land alongside the rest of the marketing artifacts.

Rule Index — load on demand

The full rule corpus lives in rules/. Load only what you need for the current task — don't preload everything.

Animation core

• [rules/timing.md](rules/timing.md) — interpolate ranges, Bézier easing, spring() configuration.
• [rules/sequencing.md](rules/sequencing.md) — <Sequence from> / durationInFrames, layout="none" for inline content.
• [rules/transitions.md](rules/transitions.md) — <TransitionSeries> for scene-to-scene transitions.
• [rules/trimming.md](rules/trimming.md) — cutting the head or tail of an animation cleanly.
• [rules/text-animations.md](rules/text-animations.md) — typography motion patterns.

Effects

• [rules/html-in-canvas.md](rules/html-in-canvas.md) — <HtmlInCanvas> for 2D/WebGL post-processing of DOM. The user-asked feature. See dedicated section below.
• [rules/light-leaks.md](rules/light-leaks.md) — @remotion/light-leaks overlays.
• [rules/transparent-videos.md](rules/transparent-videos.md) — alpha-channel render output.
• [rules/lottie.md](rules/lottie.md) — embedded Lottie JSON animations.

Audio & narration

• [rules/audio.md](rules/audio.md) — trimming, volume curves, speed, pitch.
• [rules/voiceover.md](rules/voiceover.md) — ElevenLabs TTS into a Remotion composition.
• [rules/sfx.md](rules/sfx.md) — sound effects, layering.
• [rules/audio-visualization.md](rules/audio-visualization.md) — spectrum bars, waveforms, bass-reactive visuals.
• [rules/get-audio-duration.md](rules/get-audio-duration.md) — Mediabunny audio duration.
• [rules/silence-detection.md](rules/silence-detection.md) — auto-trim silent segments via ffmpeg.

Captions & subtitles

• [rules/subtitles.md](rules/subtitles.md) — basic subtitle rendering.
• [rules/display-captions.md](rules/display-captions.md) — caption styling and positioning.
• [rules/import-srt-captions.md](rules/import-srt-captions.md) — load .srt files into a composition.
• [rules/transcribe-captions.md](rules/transcribe-captions.md) — whisper-style transcription into captions.

Media handling

• [rules/images.md](rules/images.md) — sizing, dynamic paths, dimension queries.
• [rules/videos.md](rules/videos.md) — embedding videos with trimming, volume, speed, looping.
• [rules/gifs.md](rules/gifs.md) — GIFs synchronized to the Remotion timeline.
• [rules/get-video-dimensions.md](rules/get-video-dimensions.md) — Mediabunny dimensions.
• [rules/get-video-duration.md](rules/get-video-duration.md) — Mediabunny duration.
• [rules/ffmpeg.md](rules/ffmpeg.md) — pipeline-side video operations (encoding, format conversion, trimming).

Composition & metadata

• [rules/compositions.md](rules/compositions.md) — stills, folders, default props, nested compositions.
• [rules/calculate-metadata.md](rules/calculate-metadata.md) — dynamic durationInFrames / dimensions / props from async data.
• [rules/parameters.md](rules/parameters.md) — Zod schemas for parametrizable compositions.

Typography

• [rules/google-fonts.md](rules/google-fonts.md) — recommended font path. Use this first.
• [rules/local-fonts.md](rules/local-fonts.md) — fallback when a font isn't on Google Fonts.
• [rules/measuring-text.md](rules/measuring-text.md) — fitting text to containers, overflow detection.
• [rules/measuring-dom-nodes.md](rules/measuring-dom-nodes.md) — measure rendered DOM dimensions.

Specialty

• [rules/3d.md](rules/3d.md) — Three.js / React Three Fiber inside Remotion.
• [rules/mapbox.md](rules/mapbox.md) — animated Mapbox flyovers (use static images for trivial maps).
• [rules/tailwind.md](rules/tailwind.md) — Tailwind setup notes if you must use it. Animation classes still forbidden.

Composition shape

The canonical frame-driven