remotion-video

Remotion Video

Creates production-grade videos using Remotion — a React framework where video is code. Every frame is a React component. Animations use spring physics and frame-based interpolation.

Reference Files

File	Purpose
references/rules/fundamentals.md	useCurrentFrame, useVideoConfig, interpolate, spring, core hooks
references/rules/animations.md	Easing, spring config, interpolateColors, timing patterns
references/rules/compositions.md	Composition, registerRoot, Folder, calculateMetadata
references/rules/media.md	Img, Video, OffthreadVideo, Audio, staticFile, async loading
references/rules/text-and-fonts.md	Google Fonts, local fonts, text measurement, typography
references/rules/tailwind.md	TailwindCSS integration, utility-first styling in Remotion
references/rules/audio.md	Audio component, volume curves, trimming, frame-synced audio
references/rules/subtitles.md	Caption system, SRT/VTT parsing, word-level timing
references/rules/three-d.md	@remotion/three, ThreeCanvas, React Three Fiber integration
references/rules/charts.md	Bar, pie, line chart animation patterns
references/rules/rendering.md	CLI render, renderMedia API, quality presets
references/rules/data-driven.md	Dataset rendering, batch generation, parametric compositions
references/templates/explainer.tsx	Parametric tech explainer template
references/templates/product-demo.tsx	Product showcase template
references/templates/data-viz.tsx	Animated chart composition template
scripts/scaffold_project.sh	Bootstrap a new Remotion project with TailwindCSS
scripts/render.sh	Render wrapper with quality presets and format options

Why Remotion

Remotion treats video as a React application. Each frame is a pure function of time — given frame N and total frames F, your component renders deterministically. This means:

• Component composition: Nest scenes, reuse components, apply CSS.
• Spring physics: spring() gives natural motion without hand-tweaking cubic beziers.
• Asset pipeline: Import images, audio, video — the same way you import in React.
• Iterative workflow: Edit code → hot-reload preview → render final. The .tsx file IS the editable intermediate.
• Data-driven at scale: Render thousands of personalized videos by passing different props to the same composition.

Workflow

Scaffold → Compose → Preview → Iterate → Render

1. Scaffold the project (once per video project)
2. Interpret the user's concept — choose the right template and rule files
3. Compose React components for each scene
4. Preview in Remotion Studio (npm run dev)
5. Iterate based on user feedback
6. Render final video via scripts/render.sh

Step 0: Ensure Dependencies

Node.js 18+ is required. Check before scaffolding:

node --version   # Must be >= 18.0.0
npm --version

If Node.js is not available, inform the user — Remotion cannot run without it.

Step 1: Scaffold the Project

Run scripts/scaffold_project.sh to create a new Remotion project. The script is idempotent — it detects an existing project and skips re-initialization.

bash scripts/scaffold_project.sh my-video-project
cd my-video-project
npm run dev   # Opens Remotion Studio at localhost:3000

Step 2: Interpret the Concept

Determine the best approach. Read the relevant rule file for detailed patterns.

Content type	Rule file	Template
Explainer / educational	fundamentals.md	explainer.tsx
Product demo / marketing	animations.md	product-demo.tsx
Data visualization / animated chart	charts.md	data-viz.tsx
Video with voiceover / narration	audio.md + subtitles.md	explainer.tsx
Social media clip (short, looping)	animations.md	product-demo.tsx
3D scene / abstract motion graphics	three-d.md	(custom)
Personalized / batch generation	data-driven.md	any
Video with embedded media	media.md	any

Step 3: Compose the Components

Core rules for writing Remotion components:

• One composition per video: registerRoot points to one root composition.
• Sequences for timing: Use <Sequence from={30} durationInFrames={60}> to place scenes at specific frames.
• AbsoluteFill for layering: Use <AbsoluteFill> as the base for any full-screen element.
• Frame-based math only: Derive all animation state from useCurrentFrame(). Never use Date.now() or setTimeout.
• Spring over easing: Prefer spring({ frame, fps }) for natural motion.
• Props for everything variable: Hardcoded values → props. This enables data-driven rendering.

Component structure pattern

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

type MySceneProps = {
  title: string;
  accentColor: string;
};

export const MyScene: React.FC<MySceneProps> = ({ title, accentColor }) => {
  const frame = useCurrentFrame();
  const { fps, durationInFrames } = useVideoConfig();

  const opacity = interpolate(frame, [0, 30], [0, 1], {
    extrapolateRight: "clamp",
  });
  const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100 } });

  return (
    <AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>
      <div
        style={{ opacity, transform: `scale(${scale})`, color: accentColor }}
      >
        {title}
      </div>
    </AbsoluteFill>
  );
};

Step 4: Preview

Remotion Studio provides hot-reload preview. Start it with:

npm run dev

Studio opens at http://localhost:3000. The timeline scrubber lets you inspect any frame.

Use <Still> component for frame-accurate screenshots during iteration.

Step 5: Iterate

Request	Action
"Slower/faster"	Adjust durationInFrames on <Sequence> or change FPS
"Different color"	Update props passed to composition
"Add a section"	Add new <Sequence> block with incremented from offset
"Change font"	Load via @remotion/google-fonts, apply as CSS fontFamily
"Add background music"	Add <Audio src={staticFile('audio.mp3')} /> to root composition
"Make it loop"	Set durationInFrames and design matching first/last frame state
"Add captions"	See subtitles.md for SRT parsing and word-level timing

Step 6: Render

Use scripts/render.sh to render the final video:

bash scripts/render.sh --composition MyComposition --quality final --format mp4

Quality presets

Preset	Resolution	FPS	Use case
preview	480p	15	Fast layout check
draft	720p	30	Client draft review
final	1080p	30	Standard delivery
4k	2160p	60	Presentation / cinema

Format options

Format	Use case
mp4	Standard delivery (H.264)
webm	Web-optimized
gif	Embeddable in docs, social media

Error Handling

Error	Cause	Resolution
node: command not found	Node.js not installed	Install Node.js 18+ from nodejs.org
Cannot find module 'remotion'	Dependencies not installed	Run npm install in the project directory
Composition not found	Wrong composition ID	Check registerRoot and <Composition id= match
delayRender timed out	Async asset load > 30s	Increase timeout via delayRender('reason', { timeoutInMilliseconds: 60000 })
OffthreadVideo failed	Video codec not supported	Convert to H.264 MP4 with ffmpeg first
ENOMEM during render	Out of memory on large compositions	Reduce --concurrency flag, or lower resolution
Port 3000 already in use	Another dev server running	Kill existing process or set --port 3001
Spring animation goes past 1.0	Missing { extrapolateRight: 'clamp' }	Add extrapolation clamp to interpolate calls
Fonts not loading in render	Font not loaded before render starts	Use @remotion/google-fonts or delayRender for font face load

Limitations

• Node.js required — Remotion is a Node.js framework. Cannot run in Python-only or headless container environments.
• Chromium dependency — Remotion renders via Chromium. The npx remotion render command downloads it automatically, but it requires ~300MB disk space.
• No server-side Lambda in v1 — Cloud rendering via @remotion/lambda is deferred to a future skill version. Local rendering only.
• Large renders are slow — A 60-second 1080p video at 30fps = 1800 frames rendered through Chromium. Plan for 10-30 minutes on a typical laptop.
• GIF size — GIFs at full resolution are large. Limit to 480p and <10 seconds for embeddable GIFs.
• Audio in preview — Remotion Studio supports audio playback in preview. Rendered audio requires ffmpeg.

Design Principles

• Frame-based thinking: Every visual state is a function of the current frame number. No timers, no intervals.
• Composition-first: Split video into logical <Sequence> blocks. Each scene is its own component.
• Spring over easing: spring() gives physically accurate motion. Only use interpolate with easing when spring doesn't fit.
• Props for content: Never hardcode strings, colors, or data inside components. Pass via props to enable reuse.
• Type everything: All composition props have TypeScript types enforced via z.infer<typeof schema> (Zod) or explicit interfaces.

Cross-Reference

For mathematical animations, algorithm visualizations, or when Node.js is unavailable, use concept-to-video (Manim/Python) instead. Manim runs in any Python environment and excels at geometric proofs, equation animations, and LaTeX rendering.