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

Scaffold the project (once per video project)
Interpret the user's concept — choose the right template and rule files
Compose React components for each scene
Preview in Remotion Studio (npm run dev)
Iterate based on user feedback
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.

remotion-video

Remotion Video

Reference Files