Remotion setup

remotion-setup: Install, Configure & Update Remotion

Full lifecycle skill for Remotion: fresh install, AI skill rules setup, and updates.

Step 1: Detect Current State

Determine what already exists before taking any action.

Check for Remotion installation:

# Look for remotion in package.json (current dir and remotion/ subdir)
cat package.json 2>/dev/null | grep -E '"remotion|@remotion' | head -5
cat remotion/package.json 2>/dev/null | grep -E '"remotion|@remotion' | head -5

Check for AI skill rules:

# Look for skill files in project-level .claude/skills/remotion/
ls .claude/skills/remotion/SKILL.md 2>/dev/null
ls .claude/skills/remotion/rules/*.md 2>/dev/null | wc -l

Based on results, branch to:

• Nothing found → Go to Step 2 (Fresh Install) then Step 3 (Skills)
• Remotion installed, no skills → Skip to Step 3 (Install Skills)
• Both installed → Skip to Step 4 (Update)
• Skills only, no Remotion → Go to Step 2 (Install Remotion)

Report what was detected and which path you're taking.

Step 2: Install Remotion (if not already installed)

Ask the user which approach they want:

Option A: New standalone project

npx create-video@latest

Recommend: Blank template, TailwindCSS enabled, install AI skills when prompted.

If npx create-video fails on Windows (spawn ENOENT), fall back to manual setup:

mkdir remotion && cd remotion
npm init -y
npm i --save-exact remotion@latest @remotion/cli@latest @remotion/player@latest

Option B: Add to existing project

npm i --save-exact remotion@latest @remotion/cli@latest

Only add the core packages. Ask user which extras they need:

• @remotion/player — embed videos in React apps
• @remotion/transitions — transition effects
• @remotion/google-fonts — Google Fonts support
• @remotion/media — media utilities
• @remotion/tailwind — TailwindCSS integration

Step 3: Install AI Skill Rules (if not present)

These are Claude Code rule files from the remotion-dev/skills GitHub repo. They go into the project-level .claude/skills/remotion/ directory.

Try the CLI first:

npx remotion skills add remotion-dev/skills

Windows fallback (spawn EINVAL):

If the CLI fails, manually fetch from GitHub:

1. Fetch the SKILL.md: URL: https://raw.githubusercontent.com/remotion-dev/skills/main/skills/remotion/SKILL.md Write to: .claude/skills/remotion/SKILL.md

2. Get the rules directory listing: URL: https://github.com/remotion-dev/skills/tree/main/skills/remotion/rules Extract all .md filenames from the page.

3. Fetch each rule file: Raw URL pattern: https://raw.githubusercontent.com/remotion-dev/skills/main/skills/remotion/rules/{filename} Write each to: .claude/skills/remotion/rules/{filename}

4. Report how many files were installed.

Step 4: Update (if already installed)

4a: Upgrade Remotion packages

cd <remotion-dir>
npm view remotion version        # latest on npm
cat package.json | grep -E '"remotion|@remotion' | head -10  # currently installed

Report current vs latest version. If already up to date, skip.

Try npx remotion upgrade first. On Windows this commonly fails with spawn npm ENOENT. If it fails:

1. Read package.json to find all remotion / @remotion/* packages
2. Run manual install with the latest version:

npm i --save-exact --no-fund --no-audit [email protected] @remotion/[email protected] @remotion/[email protected] ...

Only include packages already in the project's package.json — don't add new ones.

4b: Update AI skill rule files

Try npx remotion skills update first. On Windows this commonly fails with spawn EINVAL. If it fails:

1. Fetch the rules directory listing from GitHub: https://github.com/remotion-dev/skills/tree/main/skills/remotion/rules

2. Compare with local files using Glob on .claude/skills/remotion/rules/*.md

3. For new files not present locally, fetch raw content from: https://raw.githubusercontent.com/remotion-dev/skills/main/skills/remotion/rules/{filename} and write them to the local rules directory.

4. Note: Existing files may have upstream changes too. Mention this to the user and offer to re-pull specific files if needed.

Step 5: Voice & Music Setup (optional)

Set up ElevenLabs text-to-speech and background music for walkthrough videos.

5a: Install dependencies

cd <remotion-dir>
npm i --save-dev @elevenlabs/elevenlabs-js dotenv

5b: Create .env.local

Create remotion/.env.local with:

ELEVENLABS_API_KEY=
ELEVENLABS_VOICE_ID=

5c: Add to .gitignore

Ensure .env.local is in .gitignore (it usually is by default, but verify):

echo ".env.local" >> .gitignore

5d: Pick a voice

Browse the ElevenLabs Voice Library at https://elevenlabs.io/voice-library to find a voice that fits your project. Copy the Voice ID and paste it into .env.local as ELEVENLABS_VOICE_ID.

5e: Get background music

Browse https://pixabay.com/music/ for royalty-free background music. Download a track and place it at:

remotion/public/audio/bg-music.mp3

Choose something upbeat but not distracting — it will be ducked (volume lowered) during voiceover.

Step 6: Verify

cd <remotion-dir>
cat package.json | grep -E '"remotion|@remotion' | head -10

Count local skill rule files:

ls .claude/skills/remotion/rules/*.md 2>/dev/null | wc -l

Optionally test the setup works:

cd <remotion-dir>
npx remotion compositions

Step 7: Update memory (if applicable)

If the project has a memory file tracking the Remotion version or skill count (e.g. in .claude/projects/*/memory/remotion.md), update it with the new version number and skill file count.

Reference: What a Complete Setup Looks Like

A properly configured Remotion project in a brownfield codebase (e.g. Remotion living inside a larger app):

Directory structure:

project-root/
├── remotion/                  # Remotion lives in its own subdirectory
│   ├── package.json           # Separate package.json with Remotion deps
│   ├── remotion.config.ts
│   ├── tsconfig.json
│   ├── src/                   # Compositions, components, utilities
│   ├── public/                # Static assets (images, audio, fonts)
│   ├── scripts/               # Helper scripts (e.g. ElevenLabs TTS)
│   └── out/                   # Rendered output (gitignored)
├── .claude/
│   └── skills/
│       └── remotion/          # AI skill rules (project-level)
│           ├── SKILL.md
│           └── rules/         # ~35+ rule .md files
└── ...

Typical package.json dependencies:

{
  "dependencies": {
    "remotion": "4.x.x",
    "@remotion/cli": "4.x.x",
    "@remotion/player": "4.x.x",
    "@remotion/transitions": "4.x.x",
    "@remotion/google-fonts": "4.x.x",
    "@remotion/media": "4.x.x",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  },
  "devDependencies": {
    "@types/react": "^18.3.0",
    "typescript": "^5.0.0"
  }
}

All remotion and @remotion/* packages must be on the same exact version (use --save-exact).

Key Reference URLs

• Skills GitHub repo: https://github.com/remotion-dev/skills
• Raw SKILL.md: https://raw.githubusercontent.com/remotion-dev/skills/main/skills/remotion/SKILL.md
• Rules directory listing: https://github.com/remotion-dev/skills/tree/main/skills/remotion/rules
• Raw rule file pattern: https://raw.githubusercontent.com/remotion-dev/skills/main/skills/remotion/rules/{filename}