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.

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

Effects

• 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 — @remotion/light-leaks overlays.
• rules/transparent-videos.md — alpha-channel render output.
• rules/lottie.md — embedded Lottie JSON animations.

Audio & narration

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

Captions & subtitles

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

Media handling

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

Composition & metadata

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

Typography

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

Specialty

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

Composition shape

The canonical frame-driven fade-in. Memorize this shape — every other animation is a variation.

import { AbsoluteFill, Easing, interpolate, useCurrentFrame, useVideoConfig } from "remotion";

export const FadeIn: React.FC = () => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const opacity = interpolate(frame, [0, 2 * fps], [0, 1], {
    extrapolateRight: "clamp",
    extrapolateLeft: "clamp",
    easing: Easing.bezier(0.16, 1, 0.3, 1),
  });

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <h1 style={{ opacity, fontSize: 120 }}>Hello</h1>
    </AbsoluteFill>
  );
};

Width / height / fps / duration belong on the <Composition> in src/Root.tsx. For dynamic durations (e.g., audio-driven length), use calculateMetadata — see rules/calculate-metadata.md.

Render pipeline

# Preview interactively
npx remotion studio

# One-frame sanity check (always do this first)
npx remotion still MyComposition --frame=30 --scale=0.25 --output=out/check.png

# Full render
npx remotion render MyComposition out/video.mp4

# WebGL effects (HtmlInCanvas + WebGL, shaders, Three.js)
npx remotion render MyComposition out/video.mp4 --gl=angle

Set --gl=angle as the default in remotion.config.ts once a project uses WebGL anywhere — it avoids "blank frames in render but fine in Studio" surprises.

import { Config } from "@remotion/cli/config";
Config.setChromiumOpenGlRenderer("angle");

HtmlInCanvas — the user-asked feature

<HtmlInCanvas> renders DOM children into a <canvas> so you can post-process them with the Canvas 2D API or WebGL. This is how you build CRT terminals, glitch effects, video shaders, and other "DOM but with a filter on top" looks.

Constraints:

• Chrome 149+ with chrome://flags/#canvas-draw-element enabled. Tell the user this once.
• Non-Chromium machines cannot render — flag it before starting work.
• Do NOT nest <HtmlInCanvas> inside another <HtmlInCanvas>. Remotion throws.
• Use --gl=angle whenever the inner effect uses WebGL.

Working 2D blur example (frame-driven blur radius via onPaint):

import {
  AbsoluteFill,
  HtmlInCanvas,
  type HtmlInCanvasOnPaint,
  useCurrentFrame,
  useVideoConfig,
} from "remotion";
import { useCallback } from "react";

export const Blur: React.FC = () => {
  const frame = useCurrentFrame();
  const { width, height, fps } = useVideoConfig();

  const onPaint: HtmlInCanvasOnPaint = useCallback(
    ({ canvas, element, elementImage }) => {
      const ctx = canvas.getContext("2d");
      if (!ctx) throw new Error("Failed to acquire 2D context");

      const blurPx = 4 + 18 * (0.5 + 0.5 * Math.sin((frame / fps) * Math.PI));

      ctx.reset();
      ctx.filter = `blur(${blurPx}px)`;
      const transform = ctx.drawElementImage(elementImage, 0, 0);
      element.style.transform = transform.toString();
    },
    [frame, fps],
  );

  return (
    <HtmlInCanvas width={width} height={height} onPaint={onPaint}>
      <AbsoluteFill style={{ justifyContent: "center", alignItems: "center", fontSize: 120 }}>
        <h1>Hello</h1>
      </AbsoluteFill>
    </HtmlInCanvas>
  );
};

For the full WebGL pattern (texture upload via gl.texElementImage2D, shader programs, async multi-pass), see rules/html-in-canvas.md.

For a complete CRT terminal scene with scanlines, phosphor glow, and chromatic aberration, see the /cmo-remotion skill's templates/CRTComposition.tsx.

Anti-Patterns

Checking for upstream updates

This skill mirrors content from remotion-dev/skills (primary) and remotion-dev/remotion .claude (secondary). To check for drift:

./skills/remotion-best-practices/scripts/check-upstream.sh

The script compares pinned SHAs in upstream.json against the latest commits in both upstream repos and reports added/changed rule files. Owned by ironmint — do not edit upstream.json or scripts/ from this skill.

How this composes

Three sibling skills overlap. Pick the right entry point — they are not interchangeable.

remotion-best-practices is the shared knowledge layer under /cmo-remotion and /video-content (Remotion tier). Skills do not call it directly — they chain in the rules they need by file path.

Attribution

Mirrored from:

• Primary: remotion-dev/skills — skills/remotion/SKILL.md and the full skills/remotion/rules/ tree (35 files).
• Secondary: remotion-dev/remotion — .claude/ patterns referenced in references/upstream-internal/MAP.md.

Snapshot SHAs and pinned tags live in upstream.json. Curated and adapted via /mktg-steal on 2026-05-04.

Credit to @JonnyBurger and the Remotion contributors. Upstream is MIT-licensed; see each upstream repo for the canonical license text. The mktg adaptation only changes the entry-point SKILL.md (this file) and adds provenance scaffolding — the rule corpus is mirrored verbatim.