Remotion Best Practices

When to use

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

New project setup

When in an empty folder or workspace with no existing Remotion project, scaffold one using:

npx create-video@latest --yes --blank --no-tailwind my-video

Replace my-video with a suitable project name.

Designing a video

Animate properties using useCurrentFrame() and interpolate(). Use Easing to customize the timing of the animation.

import { useCurrentFrame, Easing } from "remotion";

export const FadeIn = () => {
  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 <div style={{ opacity }}>Hello World!</div>;
};

CSS transitions or animations are FORBIDDEN - they will not render correctly. Tailwind animation class names are FORBIDDEN - they will not render correctly.

Place assets in the public/ folder at your project root.

Use staticFile() to reference files from the public/ folder.

Add images using the <Img> component:

import { Img, staticFile } from "remotion";

export const MyComposition = () => {
  return <Img src={staticFile("logo.png")} style={{ width: 100, height: 100 }} />;
};

Add videos using the <Video> component from @remotion/media:

import { Video } from "@remotion/media";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Video src={staticFile("video.mp4")} style={{ opacity: 0.5 }} />;
};

Add audio using the <Audio> component from @remotion/media:

import { Audio } from "@remotion/media";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Audio src={staticFile("audio.mp3")} />;
};

Assets can be also referenced as remote URLs:

import { Video } from "@remotion/media";

export const MyComposition = () => {
  return <Video src="https://remotion.media/video.mp4" />
};

To delay content wrap it in <Sequence> and use from. To limit the duration of an element, use durationInFrames of <Sequence>. <Sequence> by default is an absolute fill. For inline content, use layout="none".

import { Sequence } from "remotion";

export const Title = () => {
  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 <div style={{ opacity }}>Title</div>;
};

export const Subtitle = () => {
  return <div>Subtitle</div>;
};

const Main = () => {
  const {fps} = useVideoConfig();

  return (
    <AbsoluteFill>
      <Sequence>
        <Background />
      </Sequence>
      <Sequence from={1 * fps} durationInFrames={2 * fps} layout="none">
        <Title />
      </Sequence>
      <Sequence from={2 * fps} durationInFrames={2 * fps} layout="none">
        <Subtitle />
      </Sequence>
    </AbsoluteFill>
  );
}

The width, height, fps, and duration of a video is defined in src/Root.tsx:

import { Composition } from "remotion";
import { MyComposition } from "./MyComposition";

export const RemotionRoot = () => {
  return (
    <Composition
      id="MyComposition"
      component={MyComposition}
      durationInFrames={100}
      fps={30}
      width={1080}
      height={1080}
    />
  );
};

Metadata can also be calculated dynamically:

import { Composition, CalculateMetadataFunction } from "remotion";
import { MyComposition, MyCompositionProps } from "./MyComposition";

const calculateMetadata: CalculateMetadataFunction<
  MyCompositionProps
> = async ({ props, abortSignal }) => {
  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
    signal: abortSignal,
  }).then((res) => res.json());

  return {
    durationInFrames: Math.ceil(data.duration * 30),
    props: {
      ...props,
      videoUrl: data.url,
    },
    width: 1080,
    height: 1080,
  };
};

export const RemotionRoot = () => {
  return (
    <Composition
      id="MyComposition"
      component={MyComposition}
      fps={30}
      width={1080}
      height={1080}
      defaultProps={{ videoId: "abc123" }}
      calculateMetadata={calculateMetadata}
    />
  );
};

Starting preview

Start the Remotion Studio to preview a video:

npx remotion studio

Optional: one-frame render check

You can render a single frame with the CLI to sanity-check layout, colors, or timing. Skip it for trivial edits, pure refactors, or when you already have enough confidence from Studio or prior renders.

npx remotion still [composition-id] --scale=0.25 --frame=30

At 30 fps, --frame=30 is the one-second mark (--frame is zero-based).

Captions

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

Using FFmpeg

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

Silence detection

When needing to detect and trim silent segments from video or audio files, load the ./rules/silence-detection.md file.

Audio visualization

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

Sound effects

When needing to use sound effects, load the ./rules/sfx.md file for more information.

3D content

See rules/3d.md for 3D content in Remotion using Three.js and React Three Fiber.

Advanced audio

See rules/audio.md for advanced audio features like trimming, volume, speed, pitch.

Dynamic duration, dimensions and data

See rules/calculate-metadata.md for dynamically set composition duration, dimensions, and props.

Advanced compositions

See rules/compositions.md for how to define stills, folders, default props and for how to nest compositions.

Google Fonts

Is the recommended way to load fonts in Remotion. See rules/google-fonts.md for how to load Google Fonts.

Local fonts

See rules/local-fonts.md for how to load local fonts.

Getting audio duration

See rules/get-audio-duration.md for getting the duration of an audio file in seconds with Mediabunny.

Getting video dimensions

See rules/get-video-dimensions.md for getting the width and height of a video file with Mediabunny.

Getting video duration

See rules/get-video-duration.md for getting the duration of a video file in seconds with Mediabunny.

GIFs

See rules/gifs.md for how to display GIFs synchronized with Remotion's timeline.

Advanced Images

See rules/images.md for sizing and positioning images, dynamic image paths, and getting image dimensions.

Light leaks

See rules/light-leaks.md for light leak overlay effects using @remotion/light-leaks.

Lottie animations

See rules/lottie.md for embedding Lottie animations in Remotion.

HTML in canvas

See rules/html-in-canvas.md if you need to render HTML into a <canvas> to apply 2D or WebGL effects via <HtmlInCanvas>.

Measuring DOM nodes

See rules/measuring-dom-nodes.md for measuring DOM element dimensions in Remotion.

Measuring text

See rules/measuring-text.md for measuring text dimensions, fitting text to containers, and checking overflow.

Advanced sequencing

See rules/sequencing.md for more sequencing patterns - delay, trim, limit duration of items.

TailwindCSS

See rules/tailwind.md for using TailwindCSS in Remotion.

Text animations

See rules/text-animations.md for typography and text animation patterns.

Advanced timing

See rules/timing.md for advanced timing with interpolate and Bézier easing, and springs.

Transitions

See rules/transitions.md for scene transition patterns.

Transparent videos

See rules/transparent-videos.md for rendering out a video with transparency.

Trimming

See rules/trimming.md for trimming patterns - cutting the beginning or end of animations.

Advanced Videos

See rules/videos.md for advanced knowledge about embedding videos - trimming, volume, speed, looping, pitch.

Parameterized videos

See rules/parameters.md for making a composition parametrizable by adding a Zod schema.

Maps

For simple maps with little flyovers, consider using static map images. For complex maps with animated routes or flyovers, load the maps rule: rules/maplibre.md

Voiceover

See rules/voiceover.md for adding AI-generated voiceover to Remotion compositions using ElevenLabs TTS.

Using Three.js and React Three Fiber in Remotion

Follow React Three Fiber and Three.js best practices. Only the following Remotion-specific rules need to be followed:

Prerequisites

First, the @remotion/three package needs to be installed. If it is not, use the following command:

npx remotion add @remotion/three # If project uses npm
bunx remotion add @remotion/three # If project uses bun
yarn remotion add @remotion/three # If project uses yarn
pnpm exec remotion add @remotion/three # If project uses pnpm

Using ThreeCanvas

You MUST wrap 3D content in <ThreeCanvas> and include proper lighting. <ThreeCanvas> MUST have a width and height prop.

import { ThreeCanvas } from "@remotion/three";
import { useVideoConfig } from "remotion";

const { width, height } = useVideoConfig();

<ThreeCanvas width={width} height={height}>
  <ambientLight intensity={0.4} />
  <directionalLight position={[5, 5, 5]} intensity={0.8} />
  <mesh>
    <sphereGeometry args={[1, 32, 32]} />
    <meshStandardMaterial color="red" />
  </mesh>
</ThreeCanvas>;

No animations not driven by useCurrentFrame()

Shaders, models etc MUST NOT animate by themselves. No animations are allowed unless they are driven by useCurrentFrame(). Otherwise, it will cause flickering during rendering.

Using useFrame() from @react-three/fiber is forbidden.

Animate using useCurrentFrame()

Use useCurrentFrame() to perform animations.

const frame = useCurrentFrame();
const rotationY = frame * 0.02;

<mesh rotation={[0, rotationY, 0]}>
  <boxGeometry args={[2, 2, 2]} />
  <meshStandardMaterial color="#4a9eff" />
</mesh>;

Using <Sequence> inside <ThreeCanvas>

The layout prop of any <Sequence> inside a <ThreeCanvas> must be set to none.

import { Sequence } from "remotion";
import { ThreeCanvas } from "@remotion/three";

const { width, height } = useVideoConfig();

<ThreeCanvas width={width} height={height}>
  <Sequence layout="none">
    <mesh>
      <boxGeometry args={[2, 2, 2]} />
      <meshStandardMaterial color="#4a9eff" />
    </mesh>
  </Sequence>
</ThreeCanvas>;

Audio Visualization in Remotion

Prerequisites

npx remotion add @remotion/media-utils

Loading Audio Data

Use useWindowedAudioData() (https://www.remotion.dev/docs/use-windowed-audio-data) to load audio data:

import { useWindowedAudioData } from "@remotion/media-utils";
import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
  src: staticFile("podcast.wav"),
  frame,
  fps,
  windowInSeconds: 30,
});

Spectrum Bar Visualization

Use visualizeAudio() (https://www.remotion.dev/docs/visualize-audio) to get frequency data for bar charts:

import { useWindowedAudioData, visualizeAudio } from "@remotion/media-utils";
import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
  src: staticFile("music.mp3"),
  frame,
  fps,
  windowInSeconds: 30,
});

if (!audioData) {
  return null;
}

const frequencies = visualizeAudio({
  fps,
  frame,
  audioData,
  numberOfSamples: 256,
  optimizeFor: "speed",
  dataOffsetInSeconds,
});

return (
  <div style={{ display: "flex", alignItems: "flex-end", height: 200 }}>
    {frequencies.map((v, i) => (
      <div
        key={i}
        style={{
          flex: 1,
          height: `${v * 100}%`,
          backgroundColor: "#0b84f3",
          margin: "0 1px",
        }}
      />
    ))}
  </div>
);

• numberOfSamples must be power of 2 (32, 64, 128, 256, 512, 1024)
• Values range 0-1; left of array = bass, right = highs
• Use optimizeFor: "speed" for Lambda or high sample counts

Important: When passing audioData to child components, also pass the frame from the parent. Do not call useCurrentFrame() in each child - this causes discontinuous visualization when children are inside <Sequence> with offsets.

Waveform Visualization

Use visualizeAudioWaveform() (https://www.remotion.dev/docs/media-utils/visualize-audio-waveform) with createSmoothSvgPath() (https://www.remotion.dev/docs/media-utils/create-smooth-svg-path) for oscilloscope-style displays:

import {
  createSmoothSvgPath,
  useWindowedAudioData,
  visualizeAudioWaveform,
} from "@remotion/media-utils";
import { staticFile, useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { width, fps } = useVideoConfig();
const HEIGHT = 200;

const { audioData, dataOffsetInSeconds } = useWindowedAudioData({
  src: staticFile("voice.wav"),
  frame,
  fps,
  windowInSeconds: 30,
});

if (!audioData) {
  return null;
}

const waveform = visualizeAudioWaveform({
  fps,
  frame,
  audioData,
  numberOfSamples: 256,
  windowInSeconds: 0.5,
  dataOffsetInSeconds,
});

const path = createSmoothSvgPath({
  points: waveform.map((y, i) => ({
    x: (i / (waveform.length - 1)) * width,
    y: HEIGHT / 2 + (y * HEIGHT) / 2,
  })),
});

return (
  <svg width={width} height={HEIGHT}>
    <path d={path} fill="none" stroke="#0b84f3" strokeWidth={2} />
  </svg>
);

Bass-Reactive Effects

Extract low frequencies for beat-reactive animations:

const frequencies = visualizeAudio({
  fps,
  frame,
  audioData,
  numberOfSamples: 128,
  optimizeFor: "speed",
  dataOffsetInSeconds,
});

const lowFrequencies = frequencies.slice(0, 32);
const bassIntensity =
  lowFrequencies.reduce((sum, v) => sum + v, 0) / lowFrequencies.length;

const scale = 1 + bassIntensity * 0.5;
const opacity = Math.min(0.6, bassIntensity * 0.8);

Volume-Based Waveform

Use getWaveformPortion() (https://www.remotion.dev/docs/get-waveform-portion) when you need simplified volume data instead of frequency spectrum:

import { getWaveformPortion } from "@remotion/media-utils";
import { useCurrentFrame, useVideoConfig } from "remotion";

const frame = useCurrentFrame();
const { fps } = useVideoConfig();
const currentTimeInSeconds = frame / fps;

const waveform = getWaveformPortion({
  audioData,
  startTimeInSeconds: currentTimeInSeconds,
  durationInSeconds: 5,
  numberOfSamples: 50,
});

// Returns array of { index, amplitude } objects (amplitude: 0-1)
waveform.map((bar) => (
  <div key={bar.index} style={{ height: bar.amplitude * 100 }} />
));

Postprocessing

Low frequencies naturally dominate. Apply logarithmic scaling for visual balance:

const minDb = -100;
const maxDb = -30;

const scaled = frequencies.map((value) => {
  const db = 20 * Math.log10(value);
  return (db - minDb) / (maxDb - minDb);
});

Using audio in Remotion

Prerequisites

First, the @remotion/media package needs to be installed. If it is not installed, use the following command:

npx remotion add @remotion/media

Importing Audio

Use <Audio> from @remotion/media to add audio to your composition.

import { Audio } from "@remotion/media";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Audio src={staticFile("audio.mp3")} />;
};

Remote URLs are also supported:

<Audio src="https://remotion.media/audio.mp3" />

By default, audio plays from the start, at full volume and full length. Multiple audio tracks can be layered by adding multiple <Audio> components.

Trimming

Use trimBefore and trimAfter to remove portions of the audio. Values are in frames.

const { fps } = useVideoConfig();

return (
  <Audio
    src={staticFile("audio.mp3")}
    trimBefore={2 * fps} // Skip the first 2 seconds
    trimAfter={10 * fps} // End at the 10 second mark
  />
);

The audio still starts playing at the beginning of the composition - only the specified portion is played.

Delaying

Wrap the audio in a <Sequence> to delay when it starts:

import { Sequence, staticFile } from "remotion";
import { Audio } from "@remotion/media";

const { fps } = useVideoConfig();

return (
  <Sequence from={1 * fps}>
    <Audio src={staticFile("audio.mp3")} />
  </Sequence>
);

The audio will start playing after 1 second.

Volume

Set a static volume (0 to 1):

<Audio src={staticFile("audio.mp3")} volume={0.5} />

Or use a callback for dynamic volume based on the current frame:

import { interpolate } from "remotion";

const { fps } = useVideoConfig();

return (
  <Audio
    src={staticFile("audio.mp3")}
    volume={(f) =>
      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
    }
  />
);

The value of f starts at 0 when the audio begins to play, not the composition frame.

Muting

Use muted to silence the audio. It can be set dynamically:

const frame = useCurrentFrame();
const { fps } = useVideoConfig();

return (
  <Audio
    src={staticFile("audio.mp3")}
    muted={frame >= 2 * fps && frame <= 4 * fps} // Mute between 2s and 4s
  />
);

Speed

Use playbackRate to change the playback speed:

<Audio src={staticFile("audio.mp3")} playbackRate={2} /> {/* 2x speed */}
<Audio src={staticFile("audio.mp3")} playbackRate={0.5} /> {/* Half speed */}

Reverse playback is not supported.

Looping

Use loop to loop the audio indefinitely:

<Audio src={staticFile("audio.mp3")} loop />

Use loopVolumeCurveBehavior to control how the frame count behaves when looping:

• "repeat": Frame count resets to 0 each loop (default)
• "extend": Frame count continues incrementing

<Audio
  src={staticFile("audio.mp3")}
  loop
  loopVolumeCurveBehavior="extend"
  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
/>

Pitch

Use toneFrequency to adjust the pitch without affecting speed. Values range from 0.01 to 2:

<Audio
  src={staticFile("audio.mp3")}
  toneFrequency={1.5} // Higher pitch
/>
<Audio
  src={staticFile("audio.mp3")}
  toneFrequency={0.8} // Lower pitch
/>

Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the <Player />.

Using calculateMetadata

Use calculateMetadata on a <Composition> to dynamically set duration, dimensions, and transform props before rendering.

<Composition
  id="MyComp"
  component={MyComponent}
  durationInFrames={300}
  fps={30}
  width={1920}
  height={1080}
  defaultProps={{ videoSrc: "https://remotion.media/video.mp4" }}
  calculateMetadata={calculateMetadata}
/>

Setting duration based on a video

Use the `getVideoDuration` and `getVideoDimensions` skills to get the video duration and dimensions:

import { CalculateMetadataFunction } from "remotion";
import { getVideoDuration } from "./get-video-duration";

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  const durationInSeconds = await getVideoDuration(props.videoSrc);

  return {
    durationInFrames: Math.ceil(durationInSeconds * 30),
  };
};

Matching dimensions of a video

Use the `getVideoDimensions` skill to get the video dimensions:

import { CalculateMetadataFunction } from "remotion";
import { getVideoDuration } from "./get-video-duration";
import { getVideoDimensions } from "./get-video-dimensions";

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  const dimensions = await getVideoDimensions(props.videoSrc);

  return {
    width: dimensions.width,
    height: dimensions.height,
  };
};

Setting duration based on multiple videos

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  const metadataPromises = props.videos.map((video) =>
    getVideoDuration(video.src),
  );
  const allMetadata = await Promise.all(metadataPromises);

  const totalDuration = allMetadata.reduce(
    (sum, durationInSeconds) => sum + durationInSeconds,
    0,
  );

  return {
    durationInFrames: Math.ceil(totalDuration * 30),
  };
};

Setting a default outName

Set the default output filename based on props:

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  return {
    defaultOutName: `video-${props.id}`, // .mp4 is added automatically
  };
};

Transforming props

Fetch data or transform props before rendering:

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
  abortSignal,
}) => {
  const response = await fetch(props.dataUrl, { signal: abortSignal });
  const data = await response.json();

  return {
    props: {
      ...props,
      fetchedData: data,
    },
  };
};

The abortSignal cancels stale requests when props change in the Studio.

Return value

All fields are optional. Returned values override the <Composition> props:

• durationInFrames: Number of frames
• width: Composition width in pixels
• height: Composition height in pixels
• fps: Frames per second
• props: Transformed props passed to the component
• defaultOutName: Default output filename
• defaultCodec: Default codec for rendering

A <Composition> defines the component, width, height, fps and duration of a renderable video.

Default Props

Pass defaultProps to provide initial values for your component. Values must be JSON-serializable (Date, Map, Set, and staticFile() are supported).

import { Composition } from "remotion";
import { MyComposition, MyCompositionProps } from "./MyComposition";

export const RemotionRoot = () => {
  return (
    <Composition
      id="MyComposition"
      component={MyComposition}
      durationInFrames={100}
      fps={30}
      width={1080}
      height={1080}
      defaultProps={
        {
          title: "Hello World",
          color: "#ff0000",
        } satisfies MyCompositionProps
      }
    />
  );
};

Use type declarations for props rather than interface to ensure defaultProps type safety.

Folders

Use <Folder> to organize compositions in the sidebar. Folder names can only contain letters, numbers, and hyphens.

import { Composition, Folder } from "remotion";

export const RemotionRoot = () => {
  return (
    <>
      <Folder name="Marketing">
        <Composition id="Promo" /* ... */ />
        <Composition id="Ad" /* ... */ />
      </Folder>
      <Folder name="Social">
        <Folder name="Instagram">
          <Composition id="Story" /* ... */ />
          <Composition id="Reel" /* ... */ />
        </Folder>
      </Folder>
    </>
  );
};

Stills

Use <Still> for single-frame images. It does not require durationInFrames or fps.

import { Still } from "remotion";
import { Thumbnail } from "./Thumbnail";

export const RemotionRoot = () => {
  return (
    <Still id="Thumbnail" component={Thumbnail} width={1280} height={720} />
  );
};

Calculate Metadata

Use calculateMetadata to make dimensions, duration, or props dynamic based on data.

import { Composition, CalculateMetadataFunction } from "remotion";
import { MyComposition, MyCompositionProps } from "./MyComposition";

const calculateMetadata: CalculateMetadataFunction<
  MyCompositionProps
> = async ({ props, abortSignal }) => {
  const data = await fetch(`https://api.example.com/video/${props.videoId}`, {
    signal: abortSignal,
  }).then((res) => res.json());

  return {
    durationInFrames: Math.ceil(data.duration * 30),
    props: {
      ...props,
      videoUrl: data.url,
    },
  };
};

export const RemotionRoot = () => {
  return (
    <Composition
      id="MyComposition"
      component={MyComposition}
      fps={30}
      width={1080}
      height={1080}
      defaultProps={{ videoId: "abc123" }}
      calculateMetadata={calculateMetadata}
    />
  );
};

The function can return props, durationInFrames, width, height, fps, and codec-related defaults. It runs once before rendering begins.

Nesting compositions within another

To add a composition within another composition, you can use the <Sequence> component with a width and height prop to specify the size of the composition.

<AbsoluteFill>
  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
    <CompositionComponent />
  </Sequence>
</AbsoluteFill>

Displaying captions in Remotion

This guide explains how to display captions in Remotion, assuming you already have captions in the `Caption` format.

Prerequisites

Read Transcribing audio for how to generate captions.

First, the `@remotion/captions` package needs to be installed. If it is not installed, use the following command:

npx remotion add @remotion/captions

Fetching captions

First, fetch your captions JSON file. Use `useDelayRender()` to hold the render until the captions are loaded:

import { useState, useEffect, useCallback } from "react";
import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
import type { Caption } from "@remotion/captions";

export const MyComponent: React.FC = () => {
  const [captions, setCaptions] = useState<Caption[] | null>(null);
  const { delayRender, continueRender, cancelRender } = useDelayRender();
  const [handle] = useState(() => delayRender());

  const fetchCaptions = useCallback(async () => {
    try {
      // Assuming captions.json is in the public/ folder.
      const response = await fetch(staticFile("captions123.json"));
      const data = await response.json();
      setCaptions(data);
      continueRender(handle);
    } catch (e) {
      cancelRender(e);
    }
  }, [continueRender, cancelRender, handle]);

  useEffect(() => {
    fetchCaptions();
  }, [fetchCaptions]);

  if (!captions) {
    return null;
  }

  return <AbsoluteFill>{/* Render captions here */}</AbsoluteFill>;
};

Creating pages

Use createTikTokStyleCaptions() to group captions into pages. The combineTokensWithinMilliseconds option controls how many words appear at once:

import { useMemo } from "react";
import { createTikTokStyleCaptions } from "@remotion/captions";
import type { Caption } from "@remotion/captions";

// How often captions should switch (in milliseconds)
// Higher values = more words per page
// Lower values = fewer words (more word-by-word)
const SWITCH_CAPTIONS_EVERY_MS = 1200;

const { pages } = useMemo(() => {
  return createTikTokStyleCaptions({
    captions,
    combineTokensWithinMilliseconds: SWITCH_CAPTIONS_EVERY_MS,
  });
}, [captions]);

Rendering with Sequences

Map over the pages and render each one in a <Sequence>. Calculate the start frame and duration from the page timing:

import { Sequence, useVideoConfig, AbsoluteFill } from "remotion";
import type { TikTokPage } from "@remotion/captions";

const CaptionedContent: React.FC = () => {
  const { fps } = useVideoConfig();

  return (
    <AbsoluteFill>
      {pages.map((page, index) => {
        const nextPage = pages[index + 1] ?? null;
        const startFrame = (page.startMs / 1000) * fps;
        const endFrame = Math.min(
          nextPage ? (nextPage.startMs / 1000) * fps : Infinity,
          startFrame + (SWITCH_CAPTIONS_EVERY_MS / 1000) * fps,
        );
        const durationInFrames = endFrame - startFrame;

        if (durationInFrames <= 0) {
          return null;
        }

        return (
          <Sequence
            key={index}
            from={startFrame}
            durationInFrames={durationInFrames}
          >
            <CaptionPage page={page} />
          </Sequence>
        );
      })}
    </AbsoluteFill>
  );
};

White-space preservation

The captions are whitespace sensitive. You should include spaces in the text field before each word. Use whiteSpace: "pre" to preserve the whitespace in the captions.

Separate component for captions

Put captioning logic in a separate component. Make a new file for it.

Word highlighting

A caption page contains tokens which you can use to highlight the currently spoken word:

import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
import type { TikTokPage } from "@remotion/captions";

const HIGHLIGHT_COLOR = "#39E508";

const CaptionPage: React.FC<{ page: TikTokPage }> = ({ page }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  // Current time relative to the start of the sequence
  const currentTimeMs = (frame / fps) * 1000;
  // Convert to absolute time by adding the page start
  const absoluteTimeMs = page.startMs + currentTimeMs;

  return (
    <AbsoluteFill style={{ justifyContent: "center", alignItems: "center" }}>
      <div style={{ fontSize: 80, fontWeight: "bold", whiteSpace: "pre" }}>
        {page.tokens.map((token) => {
          const isActive =
            token.fromMs <= absoluteTimeMs && token.toMs > absoluteTimeMs;

          return (
            <span
              key={token.fromMs}
              style={{ color: isActive ? HIGHLIGHT_COLOR : "white" }}
            >
              {token.text}
            </span>
          );
        })}
      </div>
    </AbsoluteFill>
  );
};

Display captions alongside video content

By default, put the captions alongside the video content, so the captions are in sync. For each video, make a new captions JSON file.

<AbsoluteFill>
  <Video src={staticFile("video.mp4")} />
  <CaptionPage page={page} />
</AbsoluteFill>

FFmpeg in Remotion

ffmpeg and ffprobe do not need to be installed. They are available via the npx remotion ffmpeg and npx remotion ffprobe:

npx remotion ffmpeg -i input.mp4 output.mp3
npx remotion ffprobe input.mp4

Trimming videos

You have 2 options for trimming videos:

1. Preferred: Use the trimBefore and trimAfter props of the <Video> component. This is non-destructive, requires no re-encoding, and you can change the trim at any time.

import {Video} from '@remotion/media';

<Video src={staticFile('video.mp4')} trimBefore={5 * fps} trimAfter={10 * fps} />;

2. Use the FFmpeg command line. You MUST re-encode the video to avoid frozen frames at the start of the video. Only use this if you need a standalone trimmed file (e.g. for upload or external use).

# Re-encodes from the exact frame
npx remotion ffmpeg -ss 00:00:05 -i public/input.mp4 -to 00:00:10 -c:v libx264 -c:a aac public/output.mp4

Getting audio duration with Mediabunny

Mediabunny can extract the duration of an audio file. It works in browser, Node.js, and Bun environments.

Getting audio duration

```tsx title="get-audio-duration.ts" import { Input, ALL_FORMATS, UrlSource } from "mediabunny";

export const getAudioDuration = async (src: string) => { const input = new Input({ formats: ALL_FORMATS, source: new UrlSource(src, { getRetryDelay: () => null, }), });

const durationInSeconds = await input.computeDuration(); return durationInSeconds; };

## Usage

const duration = await getAudioDuration("https://remotion.media/audio.mp3"); console.log(duration); // e.g. 180.5 (seconds)

## Using with staticFile in Remotion

Make sure to wrap the file path in `staticFile()`:

import { staticFile } from "remotion";

const duration = await getAudioDuration(staticFile("audio.mp3"));

## In Node.js and Bun

Use `FileSource` instead of `UrlSource`:

import { Input, ALL_FORMATS, FileSource } from "mediabunny";

const input = new Input({ formats: ALL_FORMATS, source: new FileSource(file), // File object from input or drag-drop });

Getting video dimensions with Mediabunny

Mediabunny can extract the width and height of a video file. It works in browser, Node.js, and Bun environments.

Getting video dimensions

import { Input, ALL_FORMATS, UrlSource } from "mediabunny";

export const getVideoDimensions = async (src: string) => {
  const input = new Input({
    formats: ALL_FORMATS,
    source: new UrlSource(src, {
      getRetryDelay: () => null,
    }),
  });

  const videoTrack = await input.getPrimaryVideoTrack();
  if (!videoTrack) {
    throw new Error("No video track found");
  }

  return {
    width: videoTrack.displayWidth,
    height: videoTrack.displayHeight,
  };
};

Usage

const dimensions = await getVideoDimensions("https://remotion.media/video.mp4");
console.log(dimensions.width); // e.g. 1920
console.log(dimensions.height); // e.g. 1080

Using with local files

For local files, use FileSource instead of UrlSource:

import { Input, ALL_FORMATS, FileSource } from "mediabunny";

const input = new Input({
  formats: ALL_FORMATS,
  source: new FileSource(file), // File object from input or drag-drop
});

const videoTrack = await input.getPrimaryVideoTrack();
const width = videoTrack.displayWidth;
const height = videoTrack.displayHeight;

Using with staticFile in Remotion

import { staticFile } from "remotion";

const dimensions = await getVideoDimensions(staticFile("video.mp4"));

Getting video duration with Mediabunny

Mediabunny can extract the duration of a video file. It works in browser, Node.js, and Bun environments.

Getting video duration

import { Input, ALL_FORMATS, UrlSource } from "mediabunny";

export const getVideoDuration = async (src: string) => {
  const input = new Input({
    formats: ALL_FORMATS,
    source: new UrlSource(src, {
      getRetryDelay: () => null,
    }),
  });

  const durationInSeconds = await input.computeDuration();
  return durationInSeconds;
};

Usage

const duration = await getVideoDuration("https://remotion.media/video.mp4");
console.log(duration); // e.g. 10.5 (seconds)

Video files from the public/ directory

Make sure to wrap the file path in staticFile():

import { staticFile } from "remotion";

const duration = await getVideoDuration(staticFile("video.mp4"));

In Node.js and Bun

Use FileSource instead of UrlSource:

import { Input, ALL_FORMATS, FileSource } from "mediabunny";

const input = new Input({
  formats: ALL_FORMATS,
  source: new FileSource(file), // File object from input or drag-drop
});

const durationInSeconds = await input.computeDuration();

Using Animated images in Remotion

Basic usage

Use <AnimatedImage> to display a GIF, APNG, AVIF or WebP image synchronized with Remotion's timeline:

import { AnimatedImage, staticFile } from "remotion";

export const MyComposition = () => {
  return (
    <AnimatedImage src={staticFile("animation.gif")} width={500} height={500} />
  );
};

Remote URLs are also supported (must have CORS enabled):

<AnimatedImage
  src="https://example.com/animation.gif"
  width={500}
  height={500}
/>

Sizing and fit

Control how the image fills its container with the fit prop:

// Stretch to fill (default)
<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="fill" />

// Maintain aspect ratio, fit inside container
<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="contain" />

// Fill container, crop if needed
<AnimatedImage src={staticFile("animation.gif")} width={500} height={300} fit="cover" />

Playback speed

Use playbackRate to control the animation speed:

<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={2} /> {/* 2x speed */}
<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} playbackRate={0.5} /> {/* Half speed */}

Looping behavior

Control what happens when the animation finishes:

// Loop indefinitely (default)
<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="loop" />

// Play once, show final frame
<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="pause-after-finish" />

// Play once, then clear canvas
<AnimatedImage src={staticFile("animation.gif")} width={500} height={500} loopBehavior="clear-after-finish" />

Styling

Use the style prop for additional CSS (use width and height props for sizing):

<AnimatedImage
  src={staticFile("animation.gif")}
  width={500}
  height={500}
  style={{
    borderRadius: 20,
    position: "absolute",
    top: 100,
    left: 50,
  }}
/>

Getting GIF duration

Use getGifDurationInSeconds() from @remotion/gif to get the duration of a GIF.

npx remotion add @remotion/gif

import { getGifDurationInSeconds } from "@remotion/gif";
import { staticFile } from "remotion";

const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
console.log(duration); // e.g. 2.5

This is useful for setting the composition duration to match the GIF:

import { getGifDurationInSeconds } from "@remotion/gif";
import { staticFile, CalculateMetadataFunction } from "remotion";

const calculateMetadata: CalculateMetadataFunction = async () => {
  const duration = await getGifDurationInSeconds(staticFile("animation.gif"));
  return {
    durationInFrames: Math.ceil(duration * 30),
  };
};

Alternative

If <AnimatedImage> does not work (only supported in Chrome and Firefox), you can use <Gif> from @remotion/gif instead.

npx remotion add @remotion/gif # If project uses npm
bunx remotion add @remotion/gif # If project uses bun
yarn remotion add @remotion/gif # If project uses yarn
pnpm exec remotion add @remotion/gif # If project uses pnpm

import { Gif } from "@remotion/gif";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Gif src={staticFile("animation.gif")} width={500} height={500} />;
};

The <Gif> component has the same props as <AnimatedImage> but only supports GIF files.

Using fonts in Remotion

Google Fonts with @remotion/google-fonts

The recommended way to use Google Fonts. It's type-safe and automatically blocks rendering until the font is ready.

Prerequisites

First, the @remotion/google-fonts package needs to be installed. If it is not installed, use the following command:

npx remotion add @remotion/google-fonts # If project uses npm
bunx remotion add @remotion/google-fonts # If project uses bun
yarn remotion add @remotion/google-fonts # If project uses yarn
pnpm exec remotion add @remotion/google-fonts # If project uses pnpm

import { loadFont } from "@remotion/google-fonts/Lobster";

const { fontFamily } = loadFont();

export const MyComposition = () => {
  return <div style={{ fontFamily }}>Hello World</div>;
};

Preferrably, specify only needed weights and subsets to reduce file size:

import { loadFont } from "@remotion/google-fonts/Roboto";

const { fontFamily } = loadFont("normal", {
  weights: ["400", "700"],
  subsets: ["latin"],
});

Using in components

Call loadFont() at the top level of your component or in a separate file that's imported early:

import { loadFont } from "@remotion/google-fonts/Montserrat";

const { fontFamily } = loadFont("normal", {
  weights: ["400", "700"],
  subsets: ["latin"],
});

export const Title: React.FC<{ text: string }> = ({ text }) => {
  return (
    <h1
      style={{
        fontFamily,
        fontSize: 80,
        fontWeight: "bold",
      }}
    >
      {text}
    </h1>
  );
};

Using <HtmlInCanvas> in Remotion

Renders children into a <canvas> so you can post-process them with the Canvas 2D API or WebGL.

Only works in Chrome 149+ with the chrome://flags/#canvas-draw-element flag enabled. Give the user a notice.

Nesting

Do not nest <HtmlInCanvas> inside another <HtmlInCanvas>. Remotion throws:

<HtmlInCanvas> effects cannot be nested together. Chrome will only display the outer effect. Consider merging the effects into one if you can.

Enabling WebGL during renders

If you make use of WebGL during renders, you need to enable it:

From the CLI:

npx remotion render --gl=angle

Set it as the default for Studio and CLI (advised):

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

Config.setChromiumOpenGlRenderer("angle");

Basic usage

By default, draws to canvas with no effect applied:

import { HtmlInCanvas } from "remotion";

export const MyComp = () => {
  return (
    <HtmlInCanvas width={1280} height={720}>
      <div style={{ fontSize: 80 }}>Hello</div>
    </HtmlInCanvas>
  );
};

2D effect with onPaint

onPaint runs whenever the content updates. Call ctx.drawElementImage(elementImage, 0, 0) to draw the captured DOM, and assign the returned transform to element.style.transform so DOM selection still aligns with the painted output.

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

export const Blur = () => {
  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>
  );
};

WebGL effects

For WebGL, set up the context, program, and texture in onInit and return a cleanup function. Inside onPaint, upload the captured DOM with gl.texElementImage2D(...) and draw.

const onInit: HtmlInCanvasOnInit = useCallback(({ canvas }) => {
  const gl = canvas.getContext("webgl2", { alpha: true, premultipliedAlpha: true });
  if (!gl) {
    throw new Error(
      "WebGL2 unavailable. Try rendering with the --gl=angle option. See https://remotion.dev/docs/gl-options.",
    );
  }
  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
  // compile program, create texture, set up VAO...
  return () => {
    // delete program, texture, buffers...
  };
}, []);

const onPaint: HtmlInCanvasOnPaint = useCallback(({ elementImage }) => {
  gl.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, elementImage);
  gl.drawArrays(gl.TRIANGLES, 0, 6);
}, []);

For a fully working minimal example, see https://github.com/remotion-dev/remotion/blob/main/packages/docs/components/demos/HtmlInCanvasDocsDemoWebGL.tsx.

Async onPaint

onPaint may be async. Remotion holds the frame open via delayRender() until the promise resolves. Useful for multi-pass effects with createImageBitmap.

Sizing and positioning

Use the style prop to control size and position:

<Img
  src={staticFile("photo.png")}
  style={{
    width: 500,
    height: 300,
    position: "absolute",
    top: 100,
    left: 50,
    objectFit: "cover",
  }}
/>

Dynamic image paths

Use template literals for dynamic file references:

import { Img, staticFile, useCurrentFrame } from "remotion";

const frame = useCurrentFrame();

// Image sequence
<Img src={staticFile(`frames/frame${frame}.png`)} />

// Selecting based on props
<Img src={staticFile(`avatars/${props.userId}.png`)} />

// Conditional images
<Img src={staticFile(`icons/${isActive ? "active" : "inactive"}.svg`)} />

This pattern is useful for:

• Image sequences (frame-by-frame animations)
• User-specific avatars or profile images
• Theme-based icons
• State-dependent graphics

Getting image dimensions

Use getImageDimensions() to get the dimensions of an image:

import { getImageDimensions, staticFile } from "remotion";

const { width, height } = await getImageDimensions(staticFile("photo.png"));

This is useful for calculating aspect ratios or sizing compositions:

import {
  getImageDimensions,
  staticFile,
  CalculateMetadataFunction,
} from "remotion";

const calculateMetadata: CalculateMetadataFunction = async () => {
  const { width, height } = await getImageDimensions(staticFile("photo.png"));
  return {
    width,
    height,
  };
};

Importing .srt subtitles into Remotion

If you have an existing .srt subtitle file, you can import it into Remotion using parseSrt() from @remotion/captions.

If you don't have a .srt file, read Transcribing audio for how to generate captions instead.

Prerequisites

First, the @remotion/captions package needs to be installed. If it is not installed, use the following command:

npx remotion add @remotion/captions # If project uses npm
bunx remotion add @remotion/captions # If project uses bun
yarn remotion add @remotion/captions # If project uses yarn
pnpm exec remotion add @remotion/captions # If project uses pnpm

Reading an .srt file

Use staticFile() to reference an .srt file in your public folder, then fetch and parse it:

import { useState, useEffect, useCallback } from "react";
import { AbsoluteFill, staticFile, useDelayRender } from "remotion";
import { parseSrt } from "@remotion/captions";
import type { Caption } from "@remotion/captions";

export const MyComponent: React.FC = () => {
  const [captions, setCaptions] = useState<Caption[] | null>(null);
  const { delayRender, continueRender, cancelRender } = useDelayRender();
  const [handle] = useState(() => delayRender());

  const fetchCaptions = useCallback(async () => {
    try {
      const response = await fetch(staticFile("subtitles.srt"));
      const text = await response.text();
      const { captions: parsed } = parseSrt({ input: text });
      setCaptions(parsed);
      continueRender(handle);
    } catch (e) {
      cancelRender(e);
    }
  }, [continueRender, cancelRender, handle]);

  useEffect(() => {
    fetchCaptions();
  }, [fetchCaptions]);

  if (!captions) {
    return null;
  }

  return <AbsoluteFill>{/* Use captions here */}</AbsoluteFill>;
};

Remote URLs are also supported - you can fetch() a remote file via URL instead of using staticFile().

Using imported captions

Once parsed, the captions are in the Caption format and can be used with all @remotion/captions utilities.

Light Leaks

This only works from Remotion 4.0.415 and up. Use npx remotion versions to check your Remotion version and npx remotion upgrade to upgrade your Remotion version.

<LightLeak> from @remotion/light-leaks renders a WebGL-based light leak effect. It reveals during the first half of its duration and retracts during the second half.

Typically used inside a <TransitionSeries.Overlay> to play over the cut point between two scenes. See the transitions rule for <TransitionSeries> and overlay usage.

Prerequisites

npx remotion add @remotion/light-leaks

Basic usage with TransitionSeries

import { TransitionSeries } from "@remotion/transitions";
import { LightLeak } from "@remotion/light-leaks";

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneA />
  </TransitionSeries.Sequence>
  <TransitionSeries.Overlay durationInFrames={30}>
    <LightLeak />
  </TransitionSeries.Overlay>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneB />
  </TransitionSeries.Sequence>
</TransitionSeries>;

Props

• durationInFrames? — defaults to the parent sequence/composition duration. The effect reveals during the first half and retracts during the second half.
• seed? — determines the shape of the light leak pattern. Different seeds produce different patterns. Default: 0.
• hueShift? — rotates the hue in degrees (0–360). Default: 0 (yellow-to-orange). 120 = green, 240 = blue.

Customizing the look

import { LightLeak } from "@remotion/light-leaks";

// Blue-tinted light leak with a different pattern
<LightLeak seed={5} hueShift={240} />;

// Green-tinted light leak
<LightLeak seed={2} hueShift={120} />;

Standalone usage

<LightLeak> can also be used outside of <TransitionSeries>, for example as a decorative overlay in any composition:

import { AbsoluteFill } from "remotion";
import { LightLeak } from "@remotion/light-leaks";

const MyComp: React.FC = () => (
  <AbsoluteFill>
    <MyContent />
    <LightLeak durationInFrames={60} seed={3} />
  </AbsoluteFill>
);

For local font files, use the @remotion/fonts package.

Prerequisites

First, install @remotion/fonts:

npx remotion add @remotion/fonts # If project uses npm
bunx remotion add @remotion/fonts # If project uses bun
yarn remotion add @remotion/fonts # If project uses yarn
pnpm exec remotion add @remotion/fonts # If project uses pnpm

Loading a local font

Place your font file in the public/ folder and use loadFont():

import { loadFont } from "@remotion/fonts";
import { staticFile } from "remotion";

await loadFont({
  family: "MyFont",
  url: staticFile("MyFont-Regular.woff2"),
});

export const MyComposition = () => {
  return <div style={{ fontFamily: "MyFont" }}>Hello World</div>;
};

Loading multiple weights

Load each weight separately with the same family name:

import { loadFont } from "@remotion/fonts";
import { staticFile } from "remotion";

await Promise.all([
  loadFont({
    family: "Inter",
    url: staticFile("Inter-Regular.woff2"),
    weight: "400",
  }),
  loadFont({
    family: "Inter",
    url: staticFile("Inter-Bold.woff2"),
    weight: "700",
  }),
]);

Available options

loadFont({
  family: "MyFont", // Required: name to use in CSS
  url: staticFile("font.woff2"), // Required: font file URL
  format: "woff2", // Optional: auto-detected from extension
  weight: "400", // Optional: font weight
  style: "normal", // Optional: normal or italic
  display: "block", // Optional: font-display behavior
});

Using Lottie Animations in Remotion

Prerequisites

First, the @remotion/lottie package needs to be installed. If it is not, use the following command:

npx remotion add @remotion/lottie # If project uses npm
bunx remotion add @remotion/lottie # If project uses bun
yarn remotion add @remotion/lottie # If project uses yarn
pnpm exec remotion add @remotion/lottie # If project uses pnpm

Displaying a Lottie file

To import a Lottie animation:

• Fetch the Lottie asset
• Wrap the loading process in delayRender() and continueRender()
• Save the animation data in a state
• Render the Lottie animation using the Lottie component from the @remotion/lottie package

import { Lottie, LottieAnimationData } from "@remotion/lottie";
import { useEffect, useState } from "react";
import { cancelRender, continueRender, delayRender } from "remotion";

export const MyAnimation = () => {
  const [handle] = useState(() => delayRender("Loading Lottie animation"));

  const [animationData, setAnimationData] =
    useState<LottieAnimationData | null>(null);

  useEffect(() => {
    fetch("https://assets4.lottiefiles.com/packages/lf20_zyquagfl.json")
      .then((data) => data.json())
      .then((json) => {
        setAnimationData(json);
        continueRender(handle);
      })
      .catch((err) => {
        cancelRender(err);
      });
  }, [handle]);

  if (!animationData) {
    return null;
  }

  return <Lottie animationData={animationData} />;
};

Styling and animating

Lottie supports the style prop to allow styles and animations:

return (
  <Lottie animationData={animationData} style={{ width: 400, height: 400 }} />
);

Use MapLibre GL JS for rendering maps in Remotion. Use Turf for geospatial operations such as great-circle routes, distances, slicing lines, and positions along routes.

Core rules

• Prefer @turf/turf for geospatial work. Do not hand-roll distance, great-circle, route slicing, or coordinate interpolation unless the user explicitly needs a custom non-geodesic effect.
• Use GeoJSON sources and MapLibre layers for lines, markers, and labels. Avoid DOM Marker elements unless the user specifically asks for HTML markers.
• Disable non-deterministic map behavior: interactive: false, fadeDuration: 0.
• Use delayRender() / continueRender() around map loading and per-frame map updates.
• Before continuing the initial render, add sources/layers, apply the frame-0 camera with jumpTo(), then wait for idle.
• Do not add a mapInstance.remove() cleanup function; it can interfere with Remotion's render lifecycle.
• Use standard MapLibre style JSON URLs and layer/source APIs.
• Do not install @types/maplibre-gl; MapLibre ships its own types.

Coordinates in MapLibre, Turf, and GeoJSON are [longitude, latitude].

const zurich: [number, number] = [8.5417, 47.3769];
const newYork: [number, number] = [-74.006, 40.7128];

Prerequisites

Install MapLibre and Turf with the project's package manager.

npm i maplibre-gl @turf/turf

bun i maplibre-gl @turf/turf

yarn add maplibre-gl @turf/turf

pnpm i maplibre-gl @turf/turf

Import the MapLibre CSS once in the component or an app-level stylesheet:

import 'maplibre-gl/dist/maplibre-gl.css';

Basic map example

import {useEffect, useRef, useState} from 'react';
import {AbsoluteFill, useDelayRender, useVideoConfig} from 'remotion';
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const zurich: [number, number] = [8.5417, 47.3769];

export const MyComposition = () => {
	const containerRef = useRef<HTMLDivElement>(null);
	const {delayRender, continueRender} = useDelayRender();
	const {width, height} = useVideoConfig();
	const [loadingHandle] = useState(() => delayRender('Loading map'));

	useEffect(() => {
		if (!containerRef.current) {
			return;
		}

		const mapInstance = new maplibregl.Map({
			container: containerRef.current,
			style: 'https://demotiles.maplibre.org/style.json',
			center: zurich,
			zoom: 7,
			interactive: false,
			attributionControl: false,
			fadeDuration: 0,
			canvasContextAttributes: {
				preserveDrawingBuffer: true,
			},
		});

		mapInstance.on('load', () => {
			mapInstance.jumpTo({center: zurich, zoom: 7});
			mapInstance.once('idle', () => {
				continueRender(loadingHandle);
			});
		});
	}, [continueRender, loadingHandle]);

	return (
		<AbsoluteFill>
			<div ref={containerRef} style={{width, height, position: 'absolute'}} />
		</AbsoluteFill>
	);
};

Animated examples should keep the loaded map in React state and skip per-frame updates until that state is set.

Animated flight route example

This example shows the recommended pattern for route animations:

• Turf creates the route and markers.
• Turf slices the route for line reveal animation.
• The camera has a separate route from the target route.
• MapLibre's calculateCameraOptionsFromTo() is used for camera movement.
• Frame 0 is prepared before continueRender().

import * as turf from '@turf/turf';
import {useEffect, useRef, useState} from 'react';
import {
	AbsoluteFill,
	Easing,
	interpolate,
	useCurrentFrame,
	useDelayRender,
	useVideoConfig,
} from 'remotion';
import maplibregl, {type GeoJSONSource, type Map} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const zurich: [number, number] = [8.5417, 47.3769];
const newYork: [number, number] = [-74.006, 40.7128];

const greatCircleLine = (from: [number, number], to: [number, number]) => {
	const route = turf.greatCircle(from, to, {npoints: 100});

	if (route.geometry.type === 'LineString') {
		return turf.lineString(route.geometry.coordinates);
	}

	// Great-circle routes crossing the antimeridian can become MultiLineString.
	// Keep the example valid by choosing the longest segment.
	const longestSegment = route.geometry.coordinates.reduce((longest, segment) => {
		return segment.length > longest.length ? segment : longest;
	});

	return turf.lineString(longestSegment);
};

const targetRoute = greatCircleLine(zurich, newYork);
const targetRouteDistance = turf.length(targetRoute);

const cameraRoute = greatCircleLine(zurich, newYork);
const cameraRouteDistance = turf.length(cameraRoute);

const cityMarkers = turf.featureCollection([
	turf.point(zurich, {name: 'Zurich'}),
	turf.point(newYork, {name: 'New York'}),
]);

const clampProgress = (progress: number) => Math.min(1, Math.max(0, progress));

const distanceAlong = (totalDistance: number, progress: number) => {
	// Keep the route non-empty at progress 0; Turf can error on zero-length slices.
	return Math.max(0.001, totalDistance * clampProgress(progress));
};

const getPartialTargetRoute = (progress: number) => {
	return turf.lineSliceAlong(
		targetRoute,
		0,
		distanceAlong(targetRouteDistance, progress),
	);
};

const getCameraOptions = (
	map: Map,
	progress: number,
	cameraAltitudeMeters: number,
	cameraLatitudeOffset: number,
) => {
	const target = turf.along(
		targetRoute,
		distanceAlong(targetRouteDistance, progress),
	).geometry.coordinates;
	const camera = turf.along(
		cameraRoute,
		distanceAlong(cameraRouteDistance, progress),
	).geometry.coordinates;

	return map.calculateCameraOptionsFromTo(
		new maplibregl.LngLat(camera[0], camera[1] - cameraLatitudeOffset),
		cameraAltitudeMeters,
		new maplibregl.LngLat(target[0], target[1]),
	);
};

export const MyComposition = () => {
	const containerRef = useRef<HTMLDivElement>(null);
	const frame = useCurrentFrame();
	const {delayRender, continueRender} = useDelayRender();
	const {durationInFrames, height, width} = useVideoConfig();
	const [map, setMap] = useState<Map | null>(null);
	const [loadingHandle] = useState(() => delayRender('Loading MapLibre map'));

	useEffect(() => {
		if (!containerRef.current) {
			return;
		}

		const mapInstance = new maplibregl.Map({
			container: containerRef.current,
			style: 'https://demotiles.maplibre.org/style.json',
			center: zurich,
			zoom: 7,
			interactive: false,
			attributionControl: false,
			fadeDuration: 0,
			canvasContextAttributes: {
				preserveDrawingBuffer: true,
			},
		});

		mapInstance.on('load', () => {
			mapInstance.addSource('trace', {
				type: 'geojson',
				data: getPartialTargetRoute(0),
			});

			mapInstance.addLayer({
				id: 'trace-line',
				type: 'line',
				source: 'trace',
				layout: {
					'line-cap': 'round',
					'line-join': 'round',
				},
				paint: {
					'line-color': '#111111',
					'line-width': 7,
				},
			});

			mapInstance.addSource('city-markers', {
				type: 'geojson',
				data: cityMarkers,
			});

			mapInstance.addLayer({
				id: 'city-marker-dots',
				type: 'circle',
				source: 'city-markers',
				paint: {
					'circle-color': '#f03b20',
					'circle-radius': 12,
					'circle-stroke-color': '#ffffff',
					'circle-stroke-width': 4,
				},
			});

			mapInstance.addLayer({
				id: 'city-marker-labels',
				type: 'symbol',
				source: 'city-markers',
				layout: {
					'text-allow-overlap': true,
					'text-anchor': 'top',
					'text-field': ['get', 'name'],
					'text-offset': [0, 0.9],
					'text-size': 28,
				},
				paint: {
					'text-color': '#111111',
					'text-halo-color': '#ffffff',
					'text-halo-width': 3,
				},
			});

			mapInstance.jumpTo(getCameraOptions(mapInstance, 0, 180000, 1.1));
			mapInstance.once('idle', () => {
				setMap(mapInstance);
				continueRender(loadingHandle);
			});
		});
	}, [continueRender, loadingHandle]);

	useEffect(() => {
		if (!map) {
			return;
		}

		const handle = delayRender('Rendering MapLibre frame');
		const timelineProgress = interpolate(frame, [0, durationInFrames - 1], [0, 1], {
			extrapolateLeft: 'clamp',
			extrapolateRight: 'clamp',
		});
		const travelProgress = interpolate(timelineProgress, [0.2, 0.82], [0, 1], {
			extrapolateLeft: 'clamp',
			extrapolateRight: 'clamp',
			easing: Easing.inOut(Easing.cubic),
		});
		const cameraAltitudeMeters = interpolate(
			timelineProgress,
			[0, 0.28, 0.74, 1],
			[180000, 2200000, 2200000, 180000],
			{
				extrapolateLeft: 'clamp',
				extrapolateRight: 'clamp',
				easing: Easing.inOut(Easing.cubic),
			},
		);
		const cameraLatitudeOffset = interpolate(
			timelineProgress,
			[0, 0.28, 0.74, 1],
			[1.1, 8, 8, 1.1],
			{
				extrapolateLeft: 'clamp',
				extrapolateRight: 'clamp',
				easing: Easing.inOut(Easing.cubic),
			},
		);
		const trace = map.getSource('trace') as GeoJSONSource | undefined;

		trace?.setData(getPartialTargetRoute(travelProgress));
		map.jumpTo(
			getCameraOptions(
				map,
				travelProgress,
				cameraAltitudeMeters,
				cameraLatitudeOffset,
			),
		);

		map.once('idle', () => continueRender(handle));
		// Force an idle event even if the camera parameters are unchanged from the previous frame.
		map.triggerRepaint();
	}, [continueRender, delayRender, durationInFrames, frame, map]);

	return (
		<AbsoluteFill style={{backgroundColor: '#e8eef3'}}>
			<div ref={containerRef} style={{height, position: 'absolute', width}} />
		</AbsoluteFill>
	);
};

Camera guidance

Use MapLibre's camera helper for camera movement:

map.calculateCameraOptionsFromTo(cameraLngLat, cameraAltitudeMeters, targetLngLat);

A good pattern is to keep two concepts separate:

• targetRoute: where the animated line is and where the camera looks.
• cameraRoute: where the camera moves.

Then use Turf to read positions from both routes for the same progress value:

const target = turf.along(targetRoute, targetDistance * progress).geometry.coordinates;
const camera = turf.along(cameraRoute, cameraDistance * progress).geometry.coordinates;

map.jumpTo(
	map.calculateCameraOptionsFromTo(
		new maplibregl.LngLat(camera[0], camera[1]),
		cameraAltitudeMeters,
		new maplibregl.LngLat(target[0], target[1]),
	),
);

For zoom-out / travel / zoom-in animations, animate travel progress separately from camera altitude. Camera altitude is measured in meters. This avoids heavy custom camera math.

Lines

Use GeoJSON sources for lines. Unless the user asks, do not add glow effects or extra decorative points.

For geodesic flight routes, use Turf:

const line = greatCircleLine(start, end);
const distance = turf.length(line);
const partialLine = turf.lineSliceAlong(
	line,
	0,
	// Keep the route non-empty at progress 0.
	Math.max(0.001, distance * progress),
);

For a visually straight line on the map, use a simple GeoJSON LineString between the two points instead of greatCircle().

Markers and labels

Use map-native GeoJSON layers for markers and labels:

mapInstance.addSource('markers', {
	type: 'geojson',
	data: turf.featureCollection([
		turf.point([-118.2437, 34.0522], {name: 'Los Angeles'}),
	]),
});

mapInstance.addLayer({
	id: 'marker-dots',
	type: 'circle',
	source: 'markers',
	paint: {
		'circle-color': '#f03b20',
		'circle-radius': 12,
		'circle-stroke-color': '#ffffff',
		'circle-stroke-width': 4,
	},
});

mapInstance.addLayer({
	id: 'marker-labels',
	type: 'symbol',
	source: 'markers',
	layout: {
		'text-allow-overlap': true,
		'text-anchor': 'top',
		'text-field': ['get', 'name'],
		'text-offset': [0, 0.9],
		'text-size': 28,
	},
	paint: {
		'text-color': '#111111',
		'text-halo-color': '#ffffff',
		'text-halo-width': 3,
	},
});

Make marker sizes and label font sizes large enough for the composition resolution.

Styles

Default to the stock MapLibre demo style:

style: 'https://demotiles.maplibre.org/style.json'

If the user requests another style, use any valid MapLibre style JSON URL.

Rendering

For WebGL map renders, prefer single concurrency and ANGLE:

bunx remotion render [composition-id] out/video.mp4 --gl=angle --concurrency=1

Use the equivalent package runner for the project. In npm projects, use npx; in Bun projects, use bunx.

Measuring DOM nodes in Remotion

Remotion applies a scale() transform to the video container, which affects values from getBoundingClientRect(). Use useCurrentScale() to get correct measurements.

Measuring element dimensions

import { useCurrentScale } from "remotion";
import { useRef, useEffect, useState } from "react";

export const MyComponent = () => {
  const ref = useRef<HTMLDivElement>(null);
  const scale = useCurrentScale();
  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });

  useEffect(() => {
    if (!ref.current) return;
    const rect = ref.current.getBoundingClientRect();
    setDimensions({
      width: rect.width / scale,
      height: rect.height / scale,
    });
  }, [scale]);

  return <div ref={ref}>Content to measure</div>;
};

Measuring text in Remotion

Prerequisites

Install @remotion/layout-utils if it is not already installed:

npx remotion add @remotion/layout-utils

Measuring text dimensions

Use measureText() to calculate the width and height of text:

import { measureText } from "@remotion/layout-utils";

const { width, height } = measureText({
  text: "Hello World",
  fontFamily: "Arial",
  fontSize: 32,
  fontWeight: "bold",
});

Results are cached - duplicate calls return the cached result.

Fitting text to a width

Use fitText() to find the optimal font size for a container:

import { fitText } from "@remotion/layout-utils";

const { fontSize } = fitText({
  text: "Hello World",
  withinWidth: 600,
  fontFamily: "Inter",
  fontWeight: "bold",
});

return (
  <div
    style={{
      fontSize: Math.min(fontSize, 80), // Cap at 80px
      fontFamily: "Inter",
      fontWeight: "bold",
    }}
  >
    Hello World
  </div>
);

Checking text overflow

Use fillTextBox() to check if text exceeds a box:

import { fillTextBox } from "@remotion/layout-utils";

const box = fillTextBox({ maxBoxWidth: 400, maxLines: 3 });

const words = ["Hello", "World", "This", "is", "a", "test"];
for (const word of words) {
  const { exceedsBox } = box.add({
    text: word + " ",
    fontFamily: "Arial",
    fontSize: 24,
  });
  if (exceedsBox) {
    // Text would overflow, handle accordingly
    break;
  }
}

Best practices

Load fonts first: Only call measurement functions after fonts are loaded.

import { loadFont } from "@remotion/google-fonts/Inter";

const { fontFamily, waitUntilDone } = loadFont("normal", {
  weights: ["400"],
  subsets: ["latin"],
});

waitUntilDone().then(() => {
  // Now safe to measure
  const { width } = measureText({
    text: "Hello",
    fontFamily,
    fontSize: 32,
  });
});

Use validateFontIsLoaded: Catch font loading issues early:

measureText({
  text: "Hello",
  fontFamily: "MyCustomFont",
  fontSize: 32,
  validateFontIsLoaded: true, // Throws if font not loaded
});

Match font properties: Use the same properties for measurement and rendering:

const fontStyle = {
  fontFamily: "Inter",
  fontSize: 32,
  fontWeight: "bold" as const,
  letterSpacing: "0.5px",
};

const { width } = measureText({
  text: "Hello",
  ...fontStyle,
});

return <div style={fontStyle}>Hello</div>;

Avoid padding and border: Use outline instead of border to prevent layout differences:

<div style={{ outline: "2px solid red" }}>Text</div>

To make a video parametrizable, a Zod schema can be added to a composition.

First, zod must be installed .

Search the project for lockfiles and run the correct command depending on the package manager:

If package-lock.json is found, use the following command:

npm i zod

If bun.lockb is found, use the following command:

bun i zod

If yarn.lock is found, use the following command:

yarn add zod

If pnpm-lock.yaml is found, use the following command:

pnpm i zod

Then, a Zod schema can be defined alongside the component:

```tsx title="src/MyComposition.tsx" import { z } from "zod";

export const MyCompositionSchema = z.object({ title: z.string(), });

const MyComponent: React.FC<z.infer<typeof MyCompositionSchema>> = () => { return ( <div> <h1>{props.title}</h1> </div> ); };

In the root file, the schema can be passed to the composition:

import { Composition } from "remotion"; import { MycComponent, MyCompositionSchema } from "./MyComposition";

export const RemotionRoot = () => { return ( <Composition id="MyComposition" component={MyComponent} durationInFrames={100} fps={30} width={1080} height={1080} defaultProps={{ title: "Hello World" }} schema={MyCompositionSchema} /> ); };

Now, the user can edit the parameter visually in the sidebar.

All schemas that are supported by Zod are supported by Remotion.

Remotion requires that the top-level type is a z.object(), because the collection of props of a React component is always an object.

## Color picker

For adding a color picker, use `zColor()` from `@remotion/zod-types`.

If it is not installed, use the following command:

npx remotion add @remotion/zod-types # If project uses npm bunx remotion add @remotion/zod-types # If project uses bun yarn remotion add @remotion/zod-types # If project uses yarn pnpm exec remotion add @remotion/zod-types # If project uses pnpm

Then import `zColor` from `@remotion/zod-types`:

import { zColor } from "@remotion/zod-types";

Then use it in the schema:

export const MyCompositionSchema = z.object({ color: zColor(), });

Use <Sequence> to delay when an element appears in the timeline.

import { Sequence } from "remotion";

export const Title = () => {
  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 <div style={{ opacity }}>Title</div>;
};

export const Subtitle = () => {
  return <div>Subtitle</div>;
};

const Main = () => {
  const {fps} = useVideoConfig();

  return (
    <AbsoluteFill>
      <Sequence>
        <Background />
      </Sequence>
      <Sequence from={1 * fps} durationInFrames={2 * fps} layout="none">
        <Title />
      </Sequence>
      <Sequence from={2 * fps} durationInFrames={2 * fps} layout="none">
        <Subtitle />
      </Sequence>
    </AbsoluteFill>
  );
}

This will by default wrap the component in an absolute fill element. If the items should not be wrapped, use the layout prop:

<Sequence layout="none">
  <Title />
</Sequence>

Premounting

This loads the component in the timeline before it is actually played. Always premount any <Sequence>!

<Sequence premountFor={1 * fps}>
  <Title />
</Sequence>

Series

Use <Series> when elements should play one after another without overlap.

import { Series } from "remotion";

<Series>
  <Series.Sequence durationInFrames={45}>
    <Intro />
  </Series.Sequence>
  <Series.Sequence durationInFrames={60}>
    <MainContent />
  </Series.Sequence>
  <Series.Sequence durationInFrames={30}>
    <Outro />
  </Series.Sequence>
</Series>;

Same as with <Sequence>, the items will be wrapped in an absolute fill element by default when using <Series.Sequence>, unless the layout prop is set to none.

Series with overlaps

Use negative offset for overlapping sequences:

<Series>
  <Series.Sequence durationInFrames={60}>
    <SceneA />
  </Series.Sequence>
  <Series.Sequence offset={-15} durationInFrames={60}>
    {/* Starts 15 frames before SceneA ends */}
    <SceneB />
  </Series.Sequence>
</Series>

Frame References Inside Sequences

Inside a Sequence, useCurrentFrame() returns the local frame (starting from 0):

<Sequence from={60} durationInFrames={30}>
  <MyComponent />
  {/* Inside MyComponent, useCurrentFrame() returns 0-29, not 60-89 */}
</Sequence>

Nested Sequences

Sequences can be nested for complex timing:

<Sequence from={0} durationInFrames={120}>
  <Background />
  <Sequence from={15} durationInFrames={90} layout="none">
    <Title />
  </Sequence>
  <Sequence from={45} durationInFrames={60} layout="none">
    <Subtitle />
  </Sequence>
</Sequence>

Nesting compositions within another

To add a composition within another composition, you can use the <Sequence> component with a width and height prop to specify the size of the composition.

<AbsoluteFill>
  <Sequence width={COMPOSITION_WIDTH} height={COMPOSITION_HEIGHT}>
    <CompositionComponent />
  </Sequence>
</AbsoluteFill>

To include a sound effect, use the <Audio> tag:

import { Audio } from "@remotion/sfx";

<Audio src={"https://remotion.media/whoosh.wav"} />;

The following sound effects are available:

• https://remotion.media/whoosh.wav
• https://remotion.media/whip.wav
• https://remotion.media/page-turn.wav
• https://remotion.media/switch.wav
• https://remotion.media/mouse-click.wav
• https://remotion.media/shutter-modern.wav
• https://remotion.media/shutter-old.wav
• https://remotion.media/ding.wav
• https://remotion.media/bruh.wav
• https://remotion.media/vine-boom.wav
• https://remotion.media/windows-xp-error.wav

For more sound effects, search the internet. A good resource is https://github.com/kapishdima/soundcn/tree/main/assets.

Adaptive Silence Detection

Detect silent segments in video or audio files.

Requires FFmpeg — see ffmpeg.md for how to invoke it in Remotion projects.

Step 1: Measure loudness with loudnorm

Use the loudnorm filter in JSON mode to get the EBU R128 integrated loudness and gating threshold for each file:

npx remotion ffmpeg -i public/video.mov -map 0:a -af loudnorm=print_format=json -f null /dev/null

As output you will get:

• input_i: Integrated loudness (dB) — the overall perceived volume
• input_thresh: EBU R128 gating threshold (dB) — the level below which audio is considered too quiet to count toward loudness measurement

Step 2: Detect silences using adaptive threshold

Pass the input_thresh value from step 1 as the noise parameter to silencedetect:

npx remotion ffmpeg -i public/video.mov -map 0:a -af "silencedetect=noise=${THRESH}dB:d=0.5" -f null /dev/null

Parameters:

• noise: The threshold below which audio is considered silent. Use input_thresh from step 1.
• d: Minimum silence duration in seconds. 0.5 is a good default.

Interpreting the output

The filter outputs pairs of silence_start and silence_end timestamps:

[silencedetect] silence_start: 0
[silencedetect] silence_end: 2.241021 | silence_duration: 2.241021
[silencedetect] silence_start: 38.77425
[silencedetect] silence_end: 39.619604 | silence_duration: 0.845354

Identifying leading and trailing silence

• Leading silence: Consecutive silence segments starting at or near 0. If the first silence_start is > 0.5s, there is no leading silence.
• Trailing silence: The last silence segment that extends to (or near) the end of the file. Compare the last silence_end with the file's total duration.

When multiple silences are nearly contiguous at the start or end (gap < 0.2s), treat them as a single leading/trailing silence block.

Using with Remotion's <Video> component

Apply the detected trim points using trimBefore and trimAfter (values are in frames):

import { Video } from "@remotion/media";
import { staticFile, useVideoConfig } from "remotion";

const { fps } = useVideoConfig();

<Video
  src={staticFile("video.mov")}
  trimBefore={Math.floor(leadingEnd * fps)}
  trimAfter={Math.ceil(trailingStart * fps)}
/>

All captions must be processed in JSON. The captions must use the Caption type which is the following:

import type { Caption } from "@remotion/captions";

This is the definition:

type Caption = {
  text: string;
  startMs: number;
  endMs: number;
  timestampMs: number | null;
  confidence: number | null;
};

Generating captions

To transcribe video and audio files to generate captions, load the ./transcribe-captions.md file for more instructions.

Displaying captions

To display captions in your video, load the ./display-captions.md file for more instructions.

Importing captions

To import captions from a .srt file, load the ./import-srt-captions.md file for more instructions.

You can and should use TailwindCSS in Remotion, if TailwindCSS is installed in the project.

Don't use transition-* or animate-* classes - always animate using the useCurrentFrame() hook.

Tailwind must be installed and enabled first in a Remotion project - fetch https://www.remotion.dev/docs/tailwind using WebFetch for instructions.

Text animations

Based on useCurrentFrame(), reduce the string character by character to create a typewriter effect.

Typewriter Effect

See Typewriter for an advanced example with a blinking cursor and a pause after the first sentence.

Always use string slicing for typewriter effects. Never use per-character opacity.

Word Highlighting

See Word Highlight for an example for how a word highlight is animated, like with a highlighter pen.

Drive motion with interpolate() over explicit frame range. To customize timing, use `Easing.bezier`. The four parameters are the same as CSS cubic-bezier(x1, y1, x2, y2).

A simple linear interpolation is done using the interpolate function.

```ts title="Going from 0 to 1 over 100 frames" import { interpolate } from "remotion";

const opacity = interpolate(frame, [0, 100], [0, 1]);

By default, the values are not clamped, so the value can go outside the range [0, 1].  
Here is how they can be clamped:

const opacity = interpolate(frame, [0, 100], [0, 1], { extrapolateRight: "clamp", extrapolateLeft: "clamp", });

## Bézier easing

Use `Easing.bezier(x1, y1, x2, y2)` inside the `interpolate` options object. The curve is identical in spirit to CSS animations and transitions, which helps when you are stealing timing from the web or from a designer’s spec.

import { interpolate, Easing } from "remotion";

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

### Examples (copy-paste curves)

**1. Crisp UI entrance (strong ease-out, no overshoot)** — slows nicely into the rest value; similar to many system “deceleration” curves.

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

**2. Editorial / slow fade (balanced ease-in-out)** — symmetric acceleration and deceleration over a hold-friendly move.

const progress = interpolate(frame, [0, 90], [0, 1], { easing: Easing.bezier(0.45, 0, 0.55, 1), extrapolateLeft: "clamp", extrapolateRight: "clamp", });

**3. Playful overshoot (control point y > 1)** — a little past the target then settles; use sparingly for emphasis.

const pop = interpolate(frame, [0, 30], [0, 1], { easing: Easing.bezier(0.34, 1.56, 0.64, 1), extrapolateLeft: "clamp", extrapolateRight: "clamp", });

## Preset easings (`Easing.in` / `Easing.out` / named curves)

Easing can be added to the `interpolate` function without a custom cubic:

import { interpolate, Easing } from "remotion";

const value1 = interpolate(frame, [0, 100], [0, 1], { easing: Easing.inOut(Easing.cubic), extrapolateLeft: "clamp", extrapolateRight: "clamp", });

The default easing is `Easing.linear`.  
Convexities:

- `Easing.in` — starting slow and accelerating
- `Easing.out` — starting fast and slowing down
- `Easing.inOut`

Named curves (from most linear to most curved):

- `Easing.quad`
- `Easing.cubic` (good default when you do not need a custom cubic)
- `Easing.sin`
- `Easing.exp`
- `Easing.circle`

### Easing direction for enter/exit animations

Use `Easing.out` for enter animations (starts fast, decelerates into place) and `Easing.in` for exit animations (starts slow, accelerates away). This feels natural because elements arrive with momentum and leave with gravity. When you need a specific curve from design, prefer a single `Easing.bezier(...)` instead of stacking presets.

## Composing interpolations

When multiple properties share the same timing (e.g. a slide-in panel and a video shift), avoid duplicating the full interpolation for each property. Instead, create a single normalized progress value (0 to 1) and derive each property from it:

const slideIn = interpolate( frame, [slideInStart, slideInStart + slideInDuration], [0, 1], { easing: Easing.bezier(0.22, 1, 0.36, 1), extrapolateLeft: "clamp", extrapolateRight: "clamp", }, ); const slideOut = interpolate( frame, [slideOutStart, slideOutStart + slideOutDuration], [0, 1], { easing: Easing.in(Easing.cubic), extrapolateLeft: "clamp", extrapolateRight: "clamp" }, ); const progress = slideIn - slideOut;

// Derive multiple properties from the same progress const overlayX = interpolate(progress, [0, 1], [100, 0]); const videoX = interpolate(progress, [0, 1], [0, -20]); const opacity = interpolate(progress, [0, 1], [0, 1]);

The key idea: separate **timing** (when and how fast) from **mapping** (what values to animate between).

Transcribing audio

To transcribe audio to generate captions in Remotion, you can use the `transcribe()` function from the `@remotion/install-whisper-cpp` package.

Prerequisites

First, the @remotion/install-whisper-cpp package needs to be installed. If it is not installed, use the following command:

npx remotion add @remotion/install-whisper-cpp

Transcribing

Make a Node.js script to download Whisper.cpp and a model, and transcribe the audio.

import path from "path";
import {
  downloadWhisperModel,
  installWhisperCpp,
  transcribe,
  toCaptions,
} from "@remotion/install-whisper-cpp";
import fs from "fs";

const to = path.join(process.cwd(), "whisper.cpp");

await installWhisperCpp({
  to,
  version: "1.5.5",
});

await downloadWhisperModel({
  model: "medium.en",
  folder: to,
});

// Convert the audio to a 16KHz wav file first if needed:
// import {execSync} from 'child_process';
// execSync('ffmpeg -i /path/to/audio.mp4 -ar 16000 /path/to/audio.wav -y');

const whisperCppOutput = await transcribe({
  model: "medium.en",
  whisperPath: to,
  whisperCppVersion: "1.5.5",
  inputPath: "/path/to/audio123.wav",
  tokenLevelTimestamps: true,
});

// Optional: Apply our recommended postprocessing
const { captions } = toCaptions({
  whisperCppOutput,
});

// Write it to the public/ folder so it can be fetched from Remotion
fs.writeFileSync("captions123.json", JSON.stringify(captions, null, 2));

Transcribe each clip individually and create multiple JSON files.

See Displaying captions for how to display the captions in Remotion.

TransitionSeries

<TransitionSeries> arranges scenes and supports two ways to enhance the cut point between them:

• Transitions (<TransitionSeries.Transition>) — crossfade, slide, wipe, etc. between two scenes. Shortens the timeline because both scenes play simultaneously during the transition.
• Overlays (<TransitionSeries.Overlay>) — render an effect (e.g. a light leak) on top of the cut point without shortening the timeline.

Children are absolutely positioned.

Prerequisites

npx remotion add @remotion/transitions

Transition example

import { TransitionSeries, linearTiming } from "@remotion/transitions";
import { fade } from "@remotion/transitions/fade";

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneA />
  </TransitionSeries.Sequence>
  <TransitionSeries.Transition
    presentation={fade()}
    timing={linearTiming({ durationInFrames: 15 })}
  />
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneB />
  </TransitionSeries.Sequence>
</TransitionSeries>;

Overlay example

Any React component can be used as an overlay. For a ready-made effect, see the light-leaks rule.

import { TransitionSeries } from "@remotion/transitions";
import { LightLeak } from "@remotion/light-leaks";

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneA />
  </TransitionSeries.Sequence>
  <TransitionSeries.Overlay durationInFrames={20}>
    <LightLeak />
  </TransitionSeries.Overlay>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneB />
  </TransitionSeries.Sequence>
</TransitionSeries>;

Mixing transitions and overlays

Transitions and overlays can coexist in the same <TransitionSeries>, but an overlay cannot be adjacent to a transition or another overlay.

import { TransitionSeries, linearTiming } from "@remotion/transitions";
import { fade } from "@remotion/transitions/fade";
import { LightLeak } from "@remotion/light-leaks";

<TransitionSeries>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneA />
  </TransitionSeries.Sequence>
  <TransitionSeries.Overlay durationInFrames={30}>
    <LightLeak />
  </TransitionSeries.Overlay>
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneB />
  </TransitionSeries.Sequence>
  <TransitionSeries.Transition
    presentation={fade()}
    timing={linearTiming({ durationInFrames: 15 })}
  />
  <TransitionSeries.Sequence durationInFrames={60}>
    <SceneC />
  </TransitionSeries.Sequence>
</TransitionSeries>;

Transition props

<TransitionSeries.Transition> requires:

• presentation — the visual effect (e.g. fade(), slide(), wipe()).
• timing — controls speed and easing (e.g. linearTiming(), springTiming()).

Overlay props

<TransitionSeries.Overlay> accepts:

• durationInFrames — how long the overlay is visible (positive integer).
• offset? — shifts the overlay relative to the cut point center. Positive = later, negative = earlier. Default: 0.

Available transition types

Import transitions from their respective modules:

import { fade } from "@remotion/transitions/fade";
import { slide } from "@remotion/transitions/slide";
import { wipe } from "@remotion/transitions/wipe";
import { flip } from "@remotion/transitions/flip";
import { clockWipe } from "@remotion/transitions/clock-wipe";

Slide transition with direction

import { slide } from "@remotion/transitions/slide";

<TransitionSeries.Transition
  presentation={slide({ direction: "from-left" })}
  timing={linearTiming({ durationInFrames: 20 })}
/>;

Directions: "from-left", "from-right", "from-top", "from-bottom"

Timing options

import { linearTiming, springTiming } from "@remotion/transitions";

// Linear timing - constant speed
linearTiming({ durationInFrames: 20 });

// Spring timing - organic motion
springTiming({ config: { damping: 200 }, durationInFrames: 25 });

Duration calculation

Transitions overlap adjacent scenes, so the total composition length is shorter than the sum of all sequence durations. Overlays do not affect the total duration.

For example, with two 60-frame sequences and a 15-frame transition:

• Without transitions: 60 + 60 = 120 frames
• With transition: 60 + 60 - 15 = 105 frames

Adding an overlay between two other sequences does not change the total.

Getting the duration of a transition

Use the getDurationInFrames() method on the timing object:

import { linearTiming, springTiming } from "@remotion/transitions";

const linearDuration = linearTiming({
  durationInFrames: 20,
}).getDurationInFrames({ fps: 30 });
// Returns 20

const springDuration = springTiming({
  config: { damping: 200 },
}).getDurationInFrames({ fps: 30 });
// Returns calculated duration based on spring physics

For springTiming without an explicit durationInFrames, the duration depends on fps because it calculates when the spring animation settles.

Calculating total composition duration

import { linearTiming } from "@remotion/transitions";

const scene1Duration = 60;
const scene2Duration = 60;
const scene3Duration = 60;

const timing1 = linearTiming({ durationInFrames: 15 });
const timing2 = linearTiming({ durationInFrames: 20 });

const transition1Duration = timing1.getDurationInFrames({ fps: 30 });
const transition2Duration = timing2.getDurationInFrames({ fps: 30 });

const totalDuration =
  scene1Duration +
  scene2Duration +
  scene3Duration -
  transition1Duration -
  transition2Duration;
// 60 + 60 + 60 - 15 - 20 = 145 frames

Rendering Transparent Videos

Remotion can render transparent videos in two ways: as a ProRes video or as a WebM video.

Transparent ProRes

Ideal for when importing into video editing software.

CLI:

npx remotion render --image-format=png --pixel-format=yuva444p10le --codec=prores --prores-profile=4444 MyComp out.mov

Default in Studio (restart Studio after changing):

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

Config.setVideoImageFormat("png");
Config.setPixelFormat("yuva444p10le");
Config.setCodec("prores");
Config.setProResProfile("4444");

Setting it as the default export settings for a composition (using calculateMetadata):

import { CalculateMetadataFunction } from "remotion";

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  return {
    defaultCodec: "prores",
    defaultVideoImageFormat: "png",
    defaultPixelFormat: "yuva444p10le",
    defaultProResProfile: "4444",
  };
};

<Composition
  id="my-video"
  component={MyVideo}
  durationInFrames={150}
  fps={30}
  width={1920}
  height={1080}
  calculateMetadata={calculateMetadata}
/>;

Transparent WebM (VP9)

Ideal for when playing in a browser.

CLI:

npx remotion render --image-format=png --pixel-format=yuva420p --codec=vp9 MyComp out.webm

Default in Studio (restart Studio after changing):

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

Config.setVideoImageFormat("png");
Config.setPixelFormat("yuva420p");
Config.setCodec("vp9");

Setting it as the default export settings for a composition (using calculateMetadata):

import { CalculateMetadataFunction } from "remotion";

const calculateMetadata: CalculateMetadataFunction<Props> = async ({
  props,
}) => {
  return {
    defaultCodec: "vp8",
    defaultVideoImageFormat: "png",
    defaultPixelFormat: "yuva420p",
  };
};

<Composition
  id="my-video"
  component={MyVideo}
  durationInFrames={150}
  fps={30}
  width={1920}
  height={1080}
  calculateMetadata={calculateMetadata}
/>;

Use <Sequence> with a negative from value to trim the start of an animation.

Trim the Beginning

A negative from value shifts time backwards, making the animation start partway through:

import { Sequence, useVideoConfig } from "remotion";

const fps = useVideoConfig();

<Sequence from={-0.5 * fps}>
  <MyAnimation />
</Sequence>;

The animation appears 15 frames into its progress - the first 15 frames are trimmed off. Inside <MyAnimation>, useCurrentFrame() starts at 15 instead of 0.

Trim the End

Use durationInFrames to unmount content after a specified duration:

<Sequence durationInFrames={1.5 * fps}>
  <MyAnimation />
</Sequence>

The animation plays for 45 frames, then the component unmounts.

Trim and Delay

Nest sequences to both trim the beginning and delay when it appears:

<Sequence from={30}>
  <Sequence from={-15}>
    <MyAnimation />
  </Sequence>
</Sequence>

The inner sequence trims 15 frames from the start, and the outer sequence delays the result by 30 frames.

Using videos in Remotion

Prerequisites

First, the @remotion/media package needs to be installed. If it is not, use the following command:

npx remotion add @remotion/media # If project uses npm
bunx remotion add @remotion/media # If project uses bun
yarn remotion add @remotion/media # If project uses yarn
pnpm exec remotion add @remotion/media # If project uses pnpm

Use <Video> from @remotion/media to embed videos into your composition.

import { Video } from "@remotion/media";
import { staticFile } from "remotion";

export const MyComposition = () => {
  return <Video src={staticFile("video.mp4")} />;
};

Remote URLs are also supported:

<Video src="https://remotion.media/video.mp4" />

Trimming

Use trimBefore and trimAfter to remove portions of the video. Values are in seconds.

const { fps } = useVideoConfig();

return (
  <Video
    src={staticFile("video.mp4")}
    trimBefore={2 * fps} // Skip the first 2 seconds
    trimAfter={10 * fps} // End at the 10 second mark
  />
);

Delaying

Wrap the video in a <Sequence> to delay when it appears:

import { Sequence, staticFile } from "remotion";
import { Video } from "@remotion/media";

const { fps } = useVideoConfig();

return (
  <Sequence from={1 * fps}>
    <Video src={staticFile("video.mp4")} />
  </Sequence>
);

The video will appear after 1 second.

Sizing and Position

Use the style prop to control size and position:

<Video
  src={staticFile("video.mp4")}
  style={{
    width: 500,
    height: 300,
    position: "absolute",
    top: 100,
    left: 50,
    objectFit: "cover",
  }}
/>

Volume

Set a static volume (0 to 1):

<Video src={staticFile("video.mp4")} volume={0.5} />

Or use a callback for dynamic volume based on the current frame:

import { interpolate } from "remotion";

const { fps } = useVideoConfig();

return (
  <Video
    src={staticFile("video.mp4")}
    volume={(f) =>
      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
    }
  />
);

Use muted to silence the video entirely:

<Video src={staticFile("video.mp4")} muted />

Speed

Use playbackRate to change the playback speed:

<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}

Reverse playback is not supported.

Looping

Use loop to loop the video indefinitely:

<Video src={staticFile("video.mp4")} loop />

Use loopVolumeCurveBehavior to control how the frame count behaves when looping:

• "repeat": Frame count resets to 0 each loop (for volume callback)
• "extend": Frame count continues incrementing

<Video
  src={staticFile("video.mp4")}
  loop
  loopVolumeCurveBehavior="extend"
  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
/>

Pitch

Use toneFrequency to adjust the pitch without affecting speed. Values range from 0.01 to 2:

<Video
  src={staticFile("video.mp4")}
  toneFrequency={1.5} // Higher pitch
/>
<Video
  src={staticFile("video.mp4")}
  toneFrequency={0.8} // Lower pitch
/>

Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the <Player />.

Adding AI voiceover to a Remotion composition

Use ElevenLabs TTS to generate speech audio per scene, then use `calculateMetadata` to dynamically size the composition to match the audio.

Prerequisites

By default this guide uses ElevenLabs as the TTS provider (ELEVENLABS_API_KEY environment variable). Users may substitute any TTS service that can produce an audio file.

If the user has not specified a TTS provider, recommend ElevenLabs and ask for their API key.

Ensure the environment variable is available when running the generation script:

node --strip-types generate-voiceover.ts

Generating audio with ElevenLabs

Create a script that reads the config, calls the ElevenLabs API for each scene, and writes MP3 files to the public/ directory so Remotion can access them via staticFile().

The core API call for a single scene:

``ts title="generate-voiceover.ts" const response = await fetch( https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`, { method: "POST", headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY!, "Content-Type": "application/json", Accept: "audio/mpeg", }, body: JSON.stringify({ text: "Welcome to the show.", model_id: "eleven_multilingual_v2", voice_settings: { stability: 0.5, similarity_boost: 0.75, style: 0.3, }, }), }, );

const audioBuffer = Buffer.from(await response.arrayBuffer()); writeFileSync(public/voiceover/${compositionId}/${scene.id}.mp3, audioBuffer);

## Dynamic composition duration with calculateMetadata

Use [`calculateMetadata`](./calculate-metadata.md) to measure the [audio durations](./get-audio-duration.md) and set the composition length accordingly.

import { CalculateMetadataFunction, staticFile } from "remotion"; import { getAudioDuration } from "./get-audio-duration";

const FPS = 30;

const SCENE_AUDIO_FILES = [ "voiceover/my-comp/scene-01-intro.mp3", "voiceover/my-comp/scene-02-main.mp3", "voiceover/my-comp/scene-03-outro.mp3", ];

export const calculateMetadata: CalculateMetadataFunction<Props> = async ({ props, }) => { const durations = await Promise.all( SCENE_AUDIO_FILES.map((file) => getAudioDuration(staticFile(file))), );

const sceneDurations = durations.map((durationInSeconds) => { return durationInSeconds * FPS; });

return { durationInFrames: Math.ceil(sceneDurations.reduce((sum, d) => sum + d, 0)), }; };

The computed `sceneDurations` are passed into the component via a `voiceover` prop so the component knows how long each scene should be.

If the composition uses [`<TransitionSeries>`](./transitions.md), subtract the overlap from total duration: [./transitions.md#calculating-total-composition-duration](./transitions.md#calculating-total-composition-duration)

## Rendering audio in the component

See [audio.md](./audio.md) for more information on how to render audio in the component.

## Delaying audio start

See [audio.md#delaying](./audio.md#delaying) for more information on how to delay the audio start.