mathews-tom/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.