Remotion

Remotion

Build and maintain Remotion projects while preserving user changes. If a file changed unexpectedly, treat it as intentional unless the user confirms otherwise.

Workflow

1. Inspect package.json, the lockfile, existing compositions, the current diff, and npx remotion versions. Reuse the package manager and project shape; keep every remotion / @remotion/* package on one exact version.
2. Confirm the requested output: composition/source changes, Studio preview, rendered media, an embedded Player, or a rendering service.
3. Implement deterministic, frame-driven visuals and keep render inputs serializable.
4. Preview in Studio. Render only when the user requests a media file.
5. Verify rendered media with ffprobe and inspect representative frames.
6. Report changed files, preview/render evidence, and the delivery receipt. In Prismer, a loose sandbox path is not a delivered result.

Prismer artifact and delivery contract

When the user requests rendered media, write the final file under $PRISMER_ARTIFACTS_DIR (the dispatch <artifacts_dir>). Put project scaffolds, frames, probes, and other intermediates under $PRISMER_SCRATCH_DIR or the existing project tree. Then deliver each requested final file exactly once:

cloud deliver "$PRISMER_ARTIFACTS_DIR/launch-video.mp4"

Writing or rendering a file does not attach it. A successful cloud deliver receipt is the delivery oracle. Do not deliver preview frames, temporary audio, or duplicate encodes unless the user requested them. If no dispatch artifact directory exists, keep the result in the user-approved project output path and report that delivery was unavailable rather than inventing a receipt.

Project creation and compositions

Do not scaffold over a non-empty project. When no suitable project exists, confirm Node.js and Git are available, then run:

npx create-video@latest --yes --blank --no-tailwind my-video
cd my-video
npm install

Use a meaningful directory name. Add Tailwind only when the user asks for it or the project already uses it. Inspect the generated manifest, config, and global CSS before continuing: generator releases can still emit Tailwind dependencies and imports when --no-tailwind was requested. Remove those only when the project does not use them, and keep the Remotion package versions aligned.

In Prismer sandbox images, use a command-scoped writable npm cache for every command that may install or invoke a missing package, including scaffolding, npm ci, remotion add, probes, and renders:

npm_config_cache="${PRISMER_SCRATCH_DIR:-/tmp}/npm-cache" npm ci

Do not change the user's global npm configuration to work around a sandbox ownership mismatch.

Keep static composition metadata inline:

<Composition
  id="LaunchVideo"
  component={LaunchVideo}
  durationInFrames={300}
  fps={30}
  width={1920}
  height={1080}
  defaultProps={{title: 'Launch day'}}
/>

Use calculateMetadata() only when duration, dimensions, or props genuinely depend on inputs, remote data, or media inspection. Keep defaultProps inline so Studio can save prop edits back to code. For multi-scene videos, use named <Sequence> boundaries and derive all timing from one fps-aware plan.

Frame-driven animation

Drive rendered animation from useCurrentFrame(), interpolate(), springs, or easing. Do not use CSS transitions, CSS animations, wall-clock timers, or Tailwind animation utilities; they are not deterministic renders.

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

export const Hero = () => {
  const frame = useCurrentFrame();
  const {fps} = useVideoConfig();

  return (
    <AbsoluteFill style={{justifyContent: 'center', alignItems: 'center'}}>
      <Interactive.Div
        name="Hero title"
        style={{
          opacity: interpolate(frame, [0, fps], [0, 1], {
            extrapolateLeft: 'clamp',
            extrapolateRight: 'clamp',
            easing: Easing.bezier(0.16, 1, 0.3, 1),
          }),
          scale: interpolate(frame, [0, fps], [0.9, 1], {
            extrapolateLeft: 'clamp',
            extrapolateRight: 'clamp',
            easing: Easing.spring({damping: 200}),
            output: 'perceptual-scale',
          }),
          fontSize: 88,
        }}
      >
        Launch day
      </Interactive.Div>
    </AbsoluteFill>
  );
};

Prefer the individual scale, translate, and rotate CSS properties over a composed transform string. Clamp both ends of finite animations unless extrapolation is intentional.

Studio-editable markup

Use Interactive.* for HTML and SVG elements that should be selectable, draggable, resized, rotated, styled, or keyframed in Studio. <Img> is already interactive.

• Give each interactive element a short, hard-coded, descriptive name.
• Keep one-off text directly inside the element.
• Keep style objects, interpolate() ranges, outputs, easing, and extrapolation inline when Studio write-back matters.
• Destructure only supported values such as fps, width, height, and durationInFrames from useVideoConfig().
• Avoid extracted style constants, object spreading, computed effect arrays, and arbitrary variables inside editable keyframe ranges.

For custom components, look up the current make-component-interactive API in the official Remotion documentation before implementing it.

Assets, media, and timing

Put local assets in public/ and reference them with staticFile():

import {Audio, Video} from '@remotion/media';
import {AnimatedImage, CanvasImage, staticFile} from 'remotion';

export const MediaLayer = () => (
  <>
    <Video src={staticFile('clip.mp4')} />
    <Audio src={staticFile('music.mp3')} />
    <CanvasImage src={staticFile('logo.png')} />
    <AnimatedImage src={staticFile('sticker.gif')} />
  </>
);

Use @remotion/gif when the Chrome-backed animated-image path is unsuitable. Install ecosystem packages with npx remotion add <package> so Remotion package versions stay aligned.

Prefer local or content-addressed media for reproducible sandbox renders. Do not bake cookies, bearer tokens, signed URLs, or map credentials into source or composition props. For asynchronous assets, fonts, captions, and map tiles, pair delayRender() / continueRender() with cancelRender() on failure so a missing dependency fails explicitly instead of hanging until timeout.

Use from, durationInFrames, and trimBefore on supported components. Wrap unsupported components in <Sequence>:

<Sequence name="Product demo" from={2 * fps} durationInFrames={6 * fps}>
  <Video src={staticFile('demo.mp4')} trimBefore={1 * fps} />
</Sequence>

Match media duration to the intended usable segment. Keep scene timing in one plan so transitions neither overlap accidentally nor leave blank frames.

For effects, use the least complex technique that produces the shot:

1. HTML, SVG, and CSS.
2. A Remotion effect on the element or an HtmlInCanvas wrapper.
3. A custom effect or shader only when the first two cannot produce it.

Keep effect arrays stable. Render separate elements instead of conditionally changing an effect array's shape.

Captions and multimedia inspection

Normalize captions to Remotion's Caption[] shape and keep ingestion timestamps in milliseconds:

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

const caption: Caption = {
  text: 'Hello',
  startMs: 0,
  endMs: 800,
  timestampMs: null,
  confidence: null,
};

Convert milliseconds to frames only at the composition boundary using the composition fps. Preserve word timing when available, group captions into readable pages, animate from the frame clock, and verify wrapping and safe areas at the actual output dimensions.

Use the current @remotion/captions parser for SRT rather than writing a timestamp parser. Before implementing captions, confirm the current APIs for parse-srt, createTikTokStyleCaptions, and the chosen transcription provider.

For audio visualization, use @remotion/media-utils with frame-windowed audio data; never drive bars or waveforms from a realtime analyser. For charts and text animation, compute the final geometry first and reveal it with frame-based clipping, opacity, or transforms so bars, labels, and glyph layout stay stable.

Use Mediabunny for browser-side duration, dimensions, trimming, cropping, metadata, and container handling. Read https://mediabunny.dev/llms.txt before using unfamiliar APIs. Keep mediabunny and @mediabunny/* versions compatible with the project's Remotion version.

Maps

Choose one technique for the shot:

Never commit map credentials. Confirm licensing and attribution for imagery, tiles, and styles. Before frame capture, wait for tiles, imagery, fonts, and camera initialization. Drive camera movement from the Remotion frame clock, keep geographic inputs local or content-addressed when repeatability matters, and verify headless Chromium/WebGL in the actual render environment.