environment-setup

name	Environment Setup
description	Automatically detects and configures the Remotion video generation environment. Use when user requests video creation and dependencies (Node.js, FFmpeg, Remotion packages) need verification or installation. Checks system requirements, installs missing tools, initializes Remotion project structure, and validates the setup is ready for video generation.

Remotion Environment Setup

You are responsible for ensuring the user's system has all required dependencies to generate videos with Remotion. This skill automatically detects, installs, and validates the complete environment.

When This Skill Activates

This skill should activate automatically when:

• The video-generator skill detects a video creation request
• The user explicitly mentions environment setup or dependencies
• Any Remotion command fails due to missing dependencies

System Requirements

Required Software

1. Node.js (v16 or higher)

   • Check: node --version
   • Required for running Remotion and React

2. FFmpeg (any recent version)

   • Check: ffmpeg -version
   • Required for video encoding and frame stitching

3. npm or yarn or pnpm

   • Comes with Node.js installation
   • Package manager for installing dependencies

4. Chromium/Chrome

   • Remotion downloads its own bundled Chromium
   • No manual installation needed
   • Used for rendering React components to frames

Recommended (Optional)

• Git: For version control of video projects
• Visual Studio Code: For editing Remotion code
• 2-4GB free RAM: For rendering process
• 500MB free disk space: For project and output files

Environment Detection Process

Step 1: Check Node.js

Run this command:

node --version

Expected output: v16.x.x or higher (e.g., v18.17.0, v20.5.1)

If missing:

• Detect platform (macOS, Linux, Windows)
• Provide platform-specific installation instructions
• Do NOT attempt auto-install (Node.js requires user consent)

Installation Instructions by Platform:

macOS:

# Using Homebrew (recommended)
brew install node

# Or download from nodejs.org

Linux (Ubuntu/Debian):

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows: Download installer from https://nodejs.org/ and run it.

---

Step 2: Check FFmpeg

Run this command:

ffmpeg -version

Expected output: FFmpeg version information (any recent version is fine)

If missing:

macOS:

brew install ffmpeg

Linux (Ubuntu/Debian):

sudo apt-get update
sudo apt-get install ffmpeg

Windows:

1. Download from https://ffmpeg.org/download.html
2. Extract to C:\ffmpeg
3. Add to PATH environment variable

Automatic Installation Decision:

• On macOS/Linux: Ask user permission, then run install command
• On Windows: Provide manual instructions (auto-install not reliable)

---

Step 3: Verify Package Manager

Run this command:

npm --version

Expected output: Version number (e.g., 9.8.1)

If npm is missing: This indicates Node.js wasn't installed correctly. Return to Step 1.

Alternative package managers:

• yarn: yarn --version
• pnpm: pnpm --version

Use whichever is available (prefer npm as default).

---

Project Initialization

Step 4: Determine Project Directory

The Remotion project directory (referred to as PROJECT_DIR below) is selected using the following priority:

1. User-specified path: If the user explicitly provides a path, use that
2. Environment variable: If REMOTION_PROJECT_DIR is set, use its value
3. Current working directory (recommended): ./remotion-videos/ — keeps the project co-located with the user's workspace
4. Home directory fallback: ~/remotion-videos/ — only if the current directory is not writable or not suitable

Determine and create the directory:

# Use environment variable if set, otherwise default to ./remotion-videos
PROJECT_DIR="${REMOTION_PROJECT_DIR:-./remotion-videos}"
mkdir -p "$PROJECT_DIR"
cd "$PROJECT_DIR"

Why this strategy:

• Works in sandboxed environments where ~ may not be predictable
• Keeps video projects close to the user's working context
• Can be overridden externally via environment variable
• Falls back gracefully to home directory if needed

If directory already exists: Use existing directory (don't overwrite).

---

Step 5: Initialize npm Project

If package.json doesn't exist:

npm init -y

This creates a basic package.json file.

If package.json exists: Check if Remotion dependencies are installed (next step).

---

Step 6: Install Remotion Dependencies

Install the core Remotion packages:

cd "$PROJECT_DIR"
npm install remotion@^4.0.0 @remotion/cli@^4.0.0 react@^19.0.0 react-dom@^19.0.0

Additional useful packages (install if time permits):

npm install @remotion/tailwind@^4.0.0 @remotion/transitions@^4.0.0 @remotion/google-fonts@^4.0.0

Why these packages:

• remotion: Core framework
• @remotion/cli: Command-line tools for rendering
• react + react-dom: Required peer dependencies
• @remotion/tailwind: For Tailwind CSS styling (optional)
• @remotion/transitions: Pre-built transition effects (optional)
• @remotion/google-fonts: Easy font loading (optional)

Installation timing:

• This may take 1-2 minutes
• Show progress indicator to user
• If installation fails, check error messages and retry

Common installation errors:

• Network timeout: Retry with longer timeout
• Permission errors: User may need sudo (Linux/macOS)
• Disk space: Check available space

---

Step 7: Create Project Structure

Create the standard Remotion project structure:

cd "$PROJECT_DIR"
mkdir -p src/compositions public/assets output

Directory purposes:

• src/: React components and video compositions
• src/compositions/: Individual video project folders
• public/: Static assets (images, fonts, audio)
• public/assets/: User-provided assets
• output/: Rendered MP4 files

---

Step 8: Create Configuration Files

Create remotion.config.ts:

import { Config } from "@remotion/cli/config";

Config.setVideoImageFormat("jpeg");
Config.setOverwriteOutput(true);

Why these settings:

• jpeg: Faster rendering than png
• overwriteOutput: Automatically replace existing output files

Create src/index.ts (entry point):

import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";

registerRoot(RemotionRoot);

Create basic src/Root.tsx:

import React from "react";

export const RemotionRoot: React.FC = () => {
  return (
    <>
      {/* Video compositions will be added here */}
    </>
  );
};

Create package.json scripts (if not present):

{
  "scripts": {
    "dev": "remotion studio",
    "build": "remotion bundle",
    "render": "remotion render"
  }
}

---

Step 9: Validate Installation

Run validation checks:

Check 1: Remotion CLI

npx remotion --version

Expected: Version number (e.g., 4.0.409)

Check 2: Project structure

ls -la "$PROJECT_DIR"

Expected: src/, public/, node_modules/, package.json directories exist

Check 3: TypeScript

npx tsc --version

Expected: Version number (TypeScript is a Remotion dependency)

If all checks pass: Environment is ready! ✓

---

Error Handling

Common Issues and Solutions

Issue: "command not found: node"

• Cause: Node.js not installed or not in PATH
• Solution: Install Node.js or add to PATH

Issue: "command not found: ffmpeg"

• Cause: FFmpeg not installed or not in PATH
• Solution: Install FFmpeg or add to PATH

Issue: "npm ERR! EACCES: permission denied"

• Cause: Insufficient permissions
• Solution: Use sudo npm install (Linux/macOS) or run as administrator (Windows)

Issue: "npm ERR! network timeout"

• Cause: Network issues or slow connection
• Solution: Retry with npm install --timeout=60000

Issue: "npm ERR! ENOSPC: no space left on device"

• Cause: Insufficient disk space
• Solution: Free up disk space (need at least 500MB)

Issue: Module not found errors

• Cause: Dependencies not fully installed
• Solution: Delete node_modules/ and re-run npm install

---

Output to User

Success Message

When environment is ready, inform user:

✓ Environment setup complete!

✓ Node.js: v18.17.0
✓ FFmpeg: version 6.0
✓ Remotion: 4.0.409
✓ Project directory: $PROJECT_DIR

You're ready to create videos! The video-generator skill will now proceed.

Partial Success Message

If some optional components are missing:

✓ Core environment ready!

✓ Node.js: v18.17.0
✓ FFmpeg: version 6.0
✓ Remotion: 4.0.409

⚠ Optional: Consider installing Git for version control

Project directory: $PROJECT_DIR

Failure Message

If critical components are missing and cannot be auto-installed:

❌ Environment setup incomplete

Missing requirements:
❌ Node.js: Not installed
   Install from: https://nodejs.org/

Current status:
✓ FFmpeg: version 6.0

Please install the missing requirements and try again.

---

Platform-Specific Considerations

macOS

Homebrew availability: Check if Homebrew is installed

which brew

If Homebrew exists, use it for FFmpeg installation:

brew install ffmpeg

If Homebrew doesn't exist:

• Suggest installing Homebrew first: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
• Or provide direct FFmpeg download link

Linux

Distribution detection:

• Ubuntu/Debian: Use apt-get
• Fedora/RedHat: Use yum or dnf
• Arch: Use pacman

Sudo requirement: Most installations require sudo

• Ask user permission before running sudo commands
• Explain what the command does

Windows

Installation challenges:

• FFmpeg requires manual PATH setup
• npm may require administrator rights

Provide clear instructions:

1. Download FFmpeg from official site
2. Extract to C:\ffmpeg
3. Add C:\ffmpeg\bin to PATH
4. Restart terminal

Alternative: Suggest using WSL2 (Windows Subsystem for Linux) for easier setup

---

Verification Checklist

Before proceeding to video generation, confirm:

• Node.js v16+ is installed and accessible
• FFmpeg is installed and in PATH
• npm/yarn/pnpm is available
• Remotion packages are installed in $PROJECT_DIR
• Project structure exists (src/, public/, output/)
• Configuration files are created
• remotion studio command works (optional: test by running it)

---

Integration with Other Skills

Called by video-generator

The video-generator skill invokes this skill first to ensure environment is ready before generating videos.

Output to video-generator

Return status:

• Ready: All requirements met, proceed with video generation
• Pending: User needs to install something manually, wait for confirmation
• Failed: Critical requirements missing, cannot proceed

---

Best Practices

User Communication

Be transparent: Explain what you're installing and why Ask permission: Don't run installation commands without user consent Provide alternatives: If auto-install fails, give manual instructions Show progress: Indicate when installations are running (may take time)

Error Recovery

Graceful degradation: If optional packages fail, continue with core setup Clear diagnostics: Explain error causes in simple terms Actionable solutions: Provide exact commands to fix issues Support links: Include official documentation URLs

Performance

Parallel checks: Run Node.js and FFmpeg checks simultaneously Cached validation: If environment was validated recently, skip re-check Minimal installs: Only install what's needed, offer optional packages separately

---

Example Workflow

User request: "Create a video showing our product features"

Environment setup flow:

1. Detect video creation request
2. Check if environment exists
   • If yes: Quick validation, then proceed
   • If no: Full setup process
3. Check Node.js → ✓ Found v18.17.0
4. Check FFmpeg → ✗ Not found
5. Ask user: "FFmpeg is required for video rendering. Install it now? (will run: brew install ffmpeg)"
6. User confirms → Run installation
7. FFmpeg installed → ✓
8. Check Remotion project → Not found
9. Create project directory at $PROJECT_DIR
10. Run npm install remotion @remotion/cli react react-dom
11. Create project structure
12. Validate installation → ✓ All checks pass
13. Report success → Hand off to video-generator skill

Total time: 2-3 minutes (mostly npm installation)

---

Security Considerations

Don't run arbitrary code: Only execute well-known package installations Verify package sources: Install from official npm registry User consent: Always ask before running sudo or admin commands No credential storage: Don't save API keys or passwords Safe defaults: Create project in current working directory or user's home directory (not system folders)

---

Troubleshooting Guide

Provide this if user encounters issues:

Problem: Remotion Studio won't start Diagnosis: Run npm run dev and check error message Common causes:

• Port 3000 already in use → Use different port: remotion studio --port=3001
• TypeScript errors → Run npm install typescript

Problem: Rendering fails Diagnosis: Run npx remotion render with verbose flag Common causes:

• FFmpeg not found → Verify with which ffmpeg
• Out of memory → Close other applications
• Missing composition → Check src/Root.tsx

Problem: Slow installation Diagnosis: Check network speed Solutions:

• Use npm mirror: npm install --registry=https://registry.npmmirror.com
• Clear npm cache: npm cache clean --force
• Update npm: npm install -g npm@latest

---

This skill ensures a smooth, automated environment setup experience while maintaining user control and providing clear feedback at every step.