name: remotion description: AI video production workflow using Remotion. Use when creating videos, short films, commercials, or motion graphics. Triggers on requests to make promotional videos, product demos, social media videos, animated explainers, or any programmatic video content. Produces polished motion graphics, not slideshows.

Video Generator (Remotion)

Workflow

1. Scaffold the project in output/<project-name>/:

   cd output && npx --yes create-video@latest <project-name> --template blank
   cd <project-name> && npm install && npm install lucide-react @remotion/google-fonts
   

2. Copy the template library into the project:

   cp -r <skill-dir>/templates/src/lib/ src/lib/
   

   This gives the project src/lib/utils.ts, palette.ts, backgrounds.tsx, text.tsx, ui.tsx, effects.tsx, transitions.tsx, and themes/ — all ready to import.
3. Fix package.json scripts — replace any bun references with npx remotion:

   {
     "prepare:tts": "node scripts/generate-tts-manifest.mjs",
     "dev": "npx remotion studio",
     "build": "npx remotion bundle"
   }
   

4. Choose a theme based on the video's tone (see Theme Guide below), then customize src/lib/palette.ts to match.
5. Write the narration script — one sentence per scene, sentence order = scene order.
6. Generate TTS — copy scripts/generate-tts-manifest.mjs from references/inworld-tts.md, update the SENTENCES array, then:

   npm run prepare:tts
   

   This produces public/audio/tts/*.mp3 and src/tts-manifest.json with measured durations.
7. Build all scenes — each scene imports from src/lib/ and src/tts-manifest.json. Never hardcode durations.
8. Start Remotion Studio:

   cd output/<project-name> && npm run dev
   

   User opens http://localhost:3000 to preview. Hot-reloads on save.

Fast iteration

REUSE_EXISTING_AUDIO=1 npm run prepare:tts   # skip re-synthesis

Render (only when user explicitly asks)

npx remotion render CompositionName out/video.mp4

Template Library (src/lib/)

Every project gets these files copied in at scaffold time. Import from them — do not rewrite the code inline.

Theme Guide

Choose one theme per video based on the content's tone. Import from src/lib/themes/. Each theme accepts { startDelay?: number }.

Usage: Themes define the visual identity — background, typography treatment, color palette, decorative elements. Use a theme's style to inform scene design, or render the theme component directly as a background/intro layer.

import { ThemeCyberpunk } from "./lib/themes";

// As a background layer in a scene:
<AbsoluteFill>
  <ThemeCyberpunk startDelay={0} />
  {/* Scene content overlaid on top */}
</AbsoluteFill>

Layout Guide

Every scene needs a layout — the spatial arrangement of elements on screen. Choose a layout before choosing text/UI components.

All layouts accept frame, startDelay, and handle their own entrance animations. They render full-screen (AbsoluteFill) and include backgrounds.

Usage: Import a layout, pass content props, and layer additional components (text animations, effects) on top if needed.

import { GiantNumber } from "./lib/layouts";

<GiantNumber
  frame={frame}
  number="4.2M"
  label="MONTHLY ACTIVE USERS"
  heading="Growing Fast"
  accentWord="Fast"
  startDelay={0}
/>

Layout selection rules

• No two adjacent scenes should use the same layout
• Match layout to the sentence archetype (see mapping below)
• Layouts handle backgrounds — don't stack a layout inside another background

For archetypes not listed (list, code, CTA), use a neutral dark background and layer content components from ui.tsx and text.tsx directly.

Scene Architecture

Timing from TTS manifest

import manifest from "./tts-manifest.json";
const sceneDurationFrames = (i: number, fps: number) =>
  Math.ceil((manifest[i].durationMs / 1000) * fps);

Set durationInFrames on the Composition from the manifest sum. Never hardcode frame counts.

Video structure

<AbsoluteFill>
  <Audio src={staticFile("audio/bg-music.mp3")} volume={0.35} />
  <BokehBackground frame={frame} baseHue={220} />

  <Series>
    <Series.Sequence durationInFrames={d0}>
      <Scene00 />
    </Series.Sequence>
    <Series.Sequence offset={-12} durationInFrames={d1}>
      <Scene01 />
    </Series.Sequence>
  </Series>
</AbsoluteFill>

Use Series with negative offset for overlapping scene transitions.

Scene component pattern

Every scene should:

1. Import from src/lib/ — not reimplement animation logic
2. Accept timing from the manifest — not hardcode durations
3. Include its own <Audio> tag for narration
4. Use lerp for exit fade: lerp(frame, [totalFrames - 15, totalFrames], [1, 0])

Scene Content Design

For each narration sentence, decide before coding:

1. What is the single key idea? One concept per scene.
2. Which archetype? (see table below)
3. Which layout? (see Layout Guide — match archetype to layout)
4. Which 2–3 words trigger animation beats? Time component entrances to land on those words.

Scene archetypes → component mapping

Audio-visual sync rules

• Don't front-load. Spread animation beats across the full duration — not all in the first second.
• Key word = animation beat. Time component entrances to land as key words are spoken.
• Post-entrance motion. After elements enter, they should float/pulse/breathe — never static for >30 frames.
• Exit early. Start fade-out ~15 frames before audio ends.

Content reduction rules

• Show less than the narrator says — the visual is an anchor, not a transcript.
• One headline per scene. If you need two, split into two scenes.
• On-screen text is a 2–5 word distillation, never the full narration sentence.
• Empty space is intentional. Don't fill it.

Motion Graphics Rules

NEVER

• Set startDelay > 15% of a scene's total frames — layouts have built-in stagger, adding a large scene-level delay creates blank screen while narration plays
• Use rotated divs to create non-rectangular zone boundaries — use clipPath: polygon() containers instead, with content as a child of its zone (rotated div visual boundaries are unpredictable from CSS)
• Reference theme objects directly in scenes (darkTheme.accent, darkTheme.bg) — this bypasses context. Let layouts read t.accent from useTheme(). Scene-level <ThemeProvider> overrides put the right tokens in context automatically.
• Render background: t.bg in custom scene code without checking useThemeConfig()?.opaqueLayouts — this covers the atmosphere in atmospheric themes
• Fade to black between scenes
• Centered text on solid backgrounds with no animation
• Same transition for every scene
• Linear/robotic animations — always use spring() or EASE curves
• Static screens — every element must move
• Emoji icons — always Lucide React
• Math.random() — always random() from Remotion (deterministic)
• Inline hex colors — always use C from palette

ALWAYS

• Overlapping transitions via Series with negative offsets
• Layered compositions: background → effects → content
• Spring physics for entrances, EASE curves for continuous motion
• Staggered group entrances (8–15 frames between items)
• Post-entrance float/pulse on every visible element
• Varied scene layouts — no two adjacent scenes should look the same

Visual Style

Typography

• One display font + one body font max
• Minimum 32px for any text — nothing smaller
• Body: 36–48px. Labels: 32px minimum. Headlines: 64px+

Layout

• Safe zone: 160px horizontal padding, 100px vertical padding on every scene root
• AbsoluteFill is flex-direction: column — use justifyContent: "center" for vertical centering
• Three valid states: centred, balanced L/R, or intentionally asymmetric → resolves

Critique Checklist

After all scenes are built, audit every scene file:

• Every fontSize ≥ 32
• Root padding ≥ 160px horizontal, ≥ 100px vertical
• Vertical centering uses justifyContent: "center" not just alignItems: "center"
• Animation delays spread across full frame count, not clustered in first 30 frames
• Exit fade starts ≥ 15 frames before end
• No two adjacent scenes use the same layout
• Each scene uses a layout from layouts.tsx or has a clear reason not to
• All colors use C from palette
• All text animations use components from src/lib/text.tsx
• All group entrances are staggered, not simultaneous
• No element is static for >30 frames after entrance

Implementation Steps

1. Director's treatment — vibe, emotional arc
2. Visual direction — customize palette.ts, choose theme
3. Write narration — one sentence per scene
4. Generate TTS — npm run prepare:tts
5. Scene breakdown — match each sentence to an archetype
6. Layout design — assign a layout from layouts.tsx to each scene (no two adjacent scenes share a layout)
7. Build persistent layer — background + music outside sequences
8. Build scenes — import layouts and components from src/lib/, wire up timing from manifest
9. Start Remotion Studio — npm run dev
10. Critique — run checklist above, fix all failures
11. Iterate — edit source, hot-reload; use REUSE_EXISTING_AUDIO=1
12. Render — only when user says to export

File Structure

my-video/
├── src/
│   ├── Root.tsx              # Composition definitions
│   ├── index.ts              # Entry point
│   ├── index.css             # Global styles
│   ├── MyVideo.tsx           # Main video component
│   ├── tts-manifest.json     # Generated by prepare:tts
│   ├── lib/                  # Copied from templates — DO NOT MODIFY
│   │   ├── utils.ts          # lerp, EASE, SPRING
│   │   ├── palette.ts        # Centralized colors (customize this one)
│   │   ├── backgrounds.tsx   # BokehBackground, WaveBackground, Starfield, FloatingShapes
│   │   ├── text.tsx          # TextReveal, WordReveal, NeonFlickerText, GlitchText, Typewriter
│   │   ├── ui.tsx            # FeatureCard, StatsDisplay, CTAButton, TerminalWindow, StaggeredList
│   │   ├── layouts.tsx        # FullscreenType, MultiColumn, SplitContrast, GiantNumber, Asymmetric, FrameInFrame
│   │   ├── effects.tsx        # RadialExplosion, Blob, Scanlines, GridBackground, PerspectiveGrid
│   │   └── transitions.tsx    # CircleReveal, ColorWipe
│   └── scenes/               # Scene components (you write these)
├── scripts/
│   └── generate-tts-manifest.mjs
├── public/
│   ├── images/
│   └── audio/
│       ├── bg-music.mp3
│       └── tts/              # Generated TTS clips
├── remotion.config.ts
└── package.json

References

• references/inworld-tts.md — TTS API spec, script implementation, manifest schema