Remotion Video

Remotion Video Skill

Specialized knowledge base for mapping creative video concepts to Remotion compositions. Covers template selection, storyboard-to-composition translation, timing and pacing rules, animation and transition catalogs, platform-specific constraints, brand integration, retention psychology, and anti-patterns. This skill is consumed by the video-producer agent and integrates with the copywriting, video-production, and platform-mastery skills.

Trigger Conditions

Use this skill when the user asks to:

• Create a video, reel, short, or explainer
• Produce an animated carousel from existing slide content
• Map a storyboard to a Remotion composition
• Select the right video template for a given topic
• Calculate frame timing for video scenes
• Choose animations or transitions for video content
• Optimize video pacing for retention
• Convert carousel slides into animated video format
• Render a video using Remotion
• Review or improve an existing video storyboard

Template Registry

Six composition templates are available, each with specific constraints and scene flow patterns.

1. ReelTips

Props Schema:

typescriptCopy code
{
  template: "ReelTips",
  fps: 30,
  width: 1080,
  height: 1920,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, point, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

2. ReelBeforeAfter

Props Schema:

typescriptCopy code
{
  template: "ReelBeforeAfter",
  fps: 30,
  width: 1080,
  height: 1920,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, comparison, point, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

3. ReelNumbers

Props Schema:

typescriptCopy code
{
  template: "ReelNumbers",
  fps: 30,
  width: 1080,
  height: 1920,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, number, point, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

4. ExplainerSteps

Props Schema:

typescriptCopy code
{
  template: "ExplainerSteps",
  fps: 30,
  width: 1920,
  height: 1080,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, step, point, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

5. ExplainerDemo

Props Schema:

typescriptCopy code
{
  template: "ExplainerDemo",
  fps: 30,
  width: 1920,
  height: 1080,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, point, demo, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

6. CarouselAnimated

Props Schema:

typescriptCopy code
{
  template: "CarouselAnimated",
  fps: 30,
  width: 1080,
  height: 1350,
  brand: BrandProps,
  scenes: SceneProps[],  // types: hook, point, cta
  showProgressBar: boolean,
  showWatermark: boolean
}

Storyboard-to-Composition Mapping

Mapping Rules

The storyboard YAML produced by the video-producer agent must be translated into a Remotion composition JSON. Follow these rules exactly.

Scene Type Mapping

Frame Calculation

Copy code
For each scene in storyboard.scenes:
  scene.durationFrames = scene.duration * storyboard.fps
  scene.startFrame = sum of all previous scenes' durationFrames

Total composition frames:
  totalFrames = sum of all scene durationFrames

Example calculation (30fps):

Copy code
Scene 1 (hook, 3s):     startFrame=0,    durationFrames=90
Scene 2 (point, 5s):    startFrame=90,   durationFrames=150
Scene 3 (point, 5s):    startFrame=240,  durationFrames=150
Scene 4 (point, 5s):    startFrame=390,  durationFrames=150
Scene 5 (cta, 4s):      startFrame=540,  durationFrames=120
Total:                   totalFrames=660  (22 seconds)

Brand Injection

Map brand-voice.yaml colors to Remotion BrandProps:

yamlCopy code
# Input: brand-voice.yaml
visual_identity:
  colors:
    primary: "#6c5ce7"
    secondary: "#00cec9"
    background: "#0a0a0a"
    text: "#ffffff"
    accent: "#fd79a8"
  handle: "@myhandle"
  name: "My Brand"

# Output: BrandProps
brand:
  name: "My Brand"
  handle: "@myhandle"
  colors:
    primary: "#6c5ce7"
    secondary: "#00cec9"
    background: "#0a0a0a"
    text: "#ffffff"
    accent: "#fd79a8"
  watermark_position: "bottom-right"

Composition Assembly

jsonCopy code
{
  "template": "<from storyboard.template>",
  "fps": 30,
  "width": "<from template spec>",
  "height": "<from template spec>",
  "totalFrames": "<calculated sum>",
  "brand": "<BrandProps from brand-voice.yaml>",
  "scenes": [
    {
      "type": "<mapped scene type>",
      "startFrame": "<calculated>",
      "durationFrames": "<scene.duration * fps>",
      "text": "<from storyboard scene>",
      "subtext": "<from storyboard scene, optional>",
      "icon": "<from storyboard scene, optional>",
      "animation": "<from storyboard scene>",
      "transition": "<from storyboard scene, default crossfade>"
    }
  ],
  "showProgressBar": true,
  "showWatermark": true
}

Timing and Pacing

Duration Rules by Scene Type

Pacing by Platform

Pacing Rules

1. 3-5 second visual change rule: No scene should go more than 5 seconds without a visible change (animation, new text, transition, or motion element).
2. Descending duration: Later scenes can be slightly shorter than earlier ones to create acceleration toward the CTA.
3. Hook compression: The hook scene should feel urgent. 2-3 seconds maximum. If the hook needs more time, the text is too long.
4. CTA brevity: The CTA scene is not for new information. Keep it under 4 seconds. The viewer has already decided to act or not.
5. Reading speed: Assume 150 words per minute for on-screen text. A 5-second scene supports approximately 12 words.

Animation Catalog

Ten animation types are available. Each maps to a Remotion animation implementation using useCurrentFrame() and interpolate().

Animation Selection Rules

1. Hook scenes: Use fade-in, scale-in, or wipe. Never use slide-left or slide-right for the first scene — they feel like continuation, not an opening.
2. Point scenes: Alternate slide-left and slide-right for pattern interrupt. Same direction on every scene is monotonous.
3. Number scenes: Always use counter-up for the number itself. Use fade-in for the context text below.
4. CTA scenes: Use bounce or scale-in for emphasis. The CTA must feel like an arrival, not a slide.
5. Comparison scenes: Use wipe for dramatic before/after reveals. slide-left/slide-right for less dramatic comparisons.
6. Step scenes: Use slide-up consistently for all steps. The upward motion creates a sense of building/progressing.
7. Never use more than 3 different animation types in a single video. Consistency is more important than variety.

Animation Timing

Transitions

Four transition types connect scenes. Transitions occur between the end of one scene and the start of the next.

Transition Rules

1. First scene always uses cut: The video must start immediately. No fade-in from black — the hook text must be visible from frame 1.
2. Default is crossfade: When no transition is specified, use crossfade. It is the safest and most professional option.
3. Use wipe sparingly: Maximum 2 wipe transitions per video. Overuse makes the video feel gimmicky.
4. slide for CarouselAnimated: The slide transition mimics the Instagram carousel swipe gesture, making animated carousels feel native.
5. Transition frames overlap: Transitions consume frames from both the outgoing and incoming scenes. They do not add to total duration.

Platform Rules

Instagram Reels

YouTube Shorts

TikTok

YouTube (Horizontal)

Brand Integration

Color Mapping from brand-voice.yaml

yamlCopy code
# brand-voice.yaml colors map to video elements:
primary:     # Scene accent colors, progress bar fill, icon highlights
secondary:   # Secondary highlights, subtext emphasis, background accents
background:  # Video background color, gradient base
text:        # All text (headlines, body, subtext)
accent:      # CTA button color, emphasis elements, counter-up numbers

Color Application by Scene Type

Watermark Positioning

The brand watermark (@handle) is rendered by the BrandWatermark component:

Watermark rules:

• Fade-in at the start of the first scene, stays visible for entire video
• Opacity: 0.7 (visible but not distracting)
• Font size: 18-22px
• Color: text color from brand at 70% opacity
• Never place over the main text area of any scene

Progress Bar

The animated progress bar shows video progress (0% to 100% over the full duration):

• Position: Top of frame (default) or bottom of frame
• Height: 4px
• Color: primary color from brand
• Background: white at 20% opacity
• Animation: Width interpolates from 0% to 100% linearly across totalFrames

Retention Triggers

Visual Change Cadence

The single most important retention factor in short-form video is visual change frequency. The human brain habituates to static visuals in 3-5 seconds and the viewer's finger moves to scroll.

Rule: A visible change must occur every 3-5 seconds.

Types of visible changes (in order of impact):

1. Scene transition — new background, new text, new layout (strongest)
2. Animation start — text slides in, number counts up, element scales (strong)
3. Color shift — background gradient animates, accent color pulses (moderate)
4. Progress bar movement — visible progress update (weak but cumulative)

Retention Trigger Catalog

Retention Anti-Pattern Checklist

Before finalizing any storyboard, verify these are NOT present:

Copy code
Retention Anti-Pattern Checklist:
[ ] No scene exceeds 8 seconds without a visual change
[ ] No two consecutive scenes use the same animation direction
[ ] Hook scene text is visible from frame 1 (no fade-from-black)
[ ] CTA scene is under 5 seconds (viewer has already decided)
[ ] No "intro" scene before the hook (no logos, no "welcome to...")
[ ] Total duration is within platform sweet spot
[ ] Progress bar is enabled (completion motivation)
[ ] At least 1 counter-up animation if content contains numbers
[ ] No scene has more than 20 words of text

Anti-Patterns

Content Anti-Patterns

Technical Anti-Patterns

Strategic Anti-Patterns

Carousel-to-Video Conversion

When to Use CarouselAnimated

Convert existing HTML carousel content to animated video when:

• The user explicitly requests an animated version of an existing carousel
• Cross-posting strategy targets video-first platforms (TikTok, YouTube Shorts)
• Carousel performance data suggests video would perform better
• The content is evergreen and worth repurposing

Conversion Rules

Slide-to-Scene Mapping

Copy code
Carousel slide_plan:                    Video storyboard:
  slide 1 (cover)           -->         scene 1 (hook, 4s, fade-in)
  slide 2 (content)         -->         scene 2 (point, 4s, slide-left)
  slide 3 (content)         -->         scene 3 (point, 4s, slide-right)
  ...                                   ...
  slide N (cta)             -->         scene N (cta, 4s, bounce)

Content Adaptation

Timing Calculation

Copy code
Carousel with N slides:
  Each slide becomes a 4-second scene
  Total duration = N * 4 seconds

  Example: 7-slide carousel = 28-second video

  If total > 60s: reduce per-scene duration to 3s
  If total < 15s: increase per-scene duration to 5s

Transition for Carousel-Animated

Always use slide transition for CarouselAnimated. This mimics the Instagram carousel swipe gesture and makes the animated version feel like a natural extension of the carousel format.

Design Spec Inheritance

When converting from an existing carousel, the CarouselAnimated template inherits:

• Color palette from the carousel's design_spec.palette
• Brand handle from the carousel's design_spec.brand.handle
• Typography style from the carousel's design_spec.typography

Do not re-derive these from brand-voice.yaml — use the carousel's existing design decisions for visual consistency between the static and animated versions.

Shared Components Reference

Six Remotion React components are available for all templates:

Output Contract

yamlCopy code
output_contract:
  skill: remotion-video
  format: composition_json
  required_fields:
    template: string       # Must match a registered template name
    fps: integer           # Always 30
    width: integer         # From template spec
    height: integer        # From template spec
    totalFrames: integer   # Calculated sum of all scene durationFrames
    brand: BrandProps      # From brand-voice.yaml
    scenes: SceneProps[]   # Mapped from storyboard
    showProgressBar: boolean
    showWatermark: boolean
  scene_required_fields:
    type: string           # hook | point | comparison | number | step | demo | cta
    startFrame: integer    # Calculated cumulative position
    durationFrames: integer # scene.duration * fps
    text: string           # Scene headline text
    animation: string      # From animation catalog
  scene_optional_fields:
    subtext: string
    icon: string
    transition: string     # Default: crossfade
  validation:
    total_frames_within_template_range: true
    all_animations_in_catalog: true
    all_transitions_in_catalog: true
    frame_calculations_correct: true
    brand_colors_present: true
    no_scene_exceeds_max_duration: true

Remotion Environment Discovery & Rendering

CRITICAL: Run this discovery routine BEFORE any render attempt.

The Remotion CLI may be installed differently on each user's machine. Never assume a fixed path or command. Follow this discovery sequence exactly.

Step 1: Locate the GrowthOS Remotion Project

The Remotion project lives inside the GrowthOS plugin directory. Discover its path dynamically:

bashCopy code
# Strategy 1: Relative to the growthOS plugin root
GROWTHOS_ROOT="$(find . -maxdepth 4 -name 'brand-voice.yaml' -exec dirname {} \; 2>/dev/null | head -1)"
REMOTION_PROJECT="${GROWTHOS_ROOT}/remotion"

# Strategy 2: If brand-voice.yaml not found, search for remotion/src/Root.tsx
REMOTION_PROJECT="$(find . -maxdepth 5 -path '*/growthOS/remotion' -type d 2>/dev/null | head -1)"

# Strategy 3: Check common Claude Code plugin locations
PLUGIN_LOCATIONS=(
  "${HOME}/.claude/plugins"
  "${HOME}/Downloads"
  "$(pwd)"
)
for loc in "${PLUGIN_LOCATIONS[@]}"; do
  if [ -f "${loc}/growthOS/remotion/src/Root.tsx" ] || [ -f "${loc}/growthOS/remotion/index.ts" ]; then
    REMOTION_PROJECT="${loc}/growthOS/remotion"
    break
  fi
done

Validation: After locating, confirm the project is valid:

bashCopy code
# Must have at least one of these entry points
[ -f "${REMOTION_PROJECT}/index.ts" ] || [ -f "${REMOTION_PROJECT}/src/Root.tsx" ]

Step 2: Determine the Entry Point

GrowthOS has two Remotion entry point structures. Detect which one is active:

bashCopy code
# Preferred: Full project with 6 compositions (src/ structure)
if [ -f "${REMOTION_PROJECT}/src/Root.tsx" ] && [ -f "${REMOTION_PROJECT}/src/compositions/index.ts" ]; then
  ENTRY_POINT="${REMOTION_PROJECT}/src/index.ts"
  ENTRY_TYPE="full"
  # Available compositions: ReelTips, ReelBeforeAfter, ReelNumbers, ExplainerSteps, ExplainerDemo, CarouselAnimated

# Fallback: Simplified structure (root-level)
elif [ -f "${REMOTION_PROJECT}/index.ts" ]; then
  ENTRY_POINT="${REMOTION_PROJECT}/index.ts"
  ENTRY_TYPE="simple"
  # Available compositions: ReelTips only (others must be added)
fi

Entry point decision table:

Step 3: Discover the Remotion CLI

Remotion CLI can be installed in multiple ways. Check in order of preference:

bashCopy code
# Method 1: Local npx (most reliable — uses project's node_modules)
cd "${REMOTION_PROJECT}" && npx remotion --version 2>/dev/null
REMOTION_CMD="npx remotion"

# Method 2: Project-level node_modules binary
if [ -x "${REMOTION_PROJECT}/node_modules/.bin/remotion" ]; then
  REMOTION_CMD="${REMOTION_PROJECT}/node_modules/.bin/remotion"
fi

# Method 3: GrowthOS parent node_modules (if deps installed at growthOS level)
GROWTHOS_BIN="${GROWTHOS_ROOT}/node_modules/.bin/remotion"
if [ -x "${GROWTHOS_BIN}" ]; then
  REMOTION_CMD="${GROWTHOS_BIN}"
fi

# Method 4: Global install
if command -v remotion &>/dev/null; then
  REMOTION_CMD="remotion"
fi

# Method 5: Not found — install needed
if [ -z "${REMOTION_CMD}" ]; then
  echo "Remotion not found. Installing..."
  cd "${REMOTION_PROJECT}" && npm install
  REMOTION_CMD="npx remotion"
fi

Discovery result table:

Step 4: Verify Dependencies

Before rendering, confirm all dependencies are installed:

bashCopy code
cd "${REMOTION_PROJECT}"

# Check if node_modules exists and has remotion
if [ ! -d "node_modules/remotion" ]; then
  echo "Installing Remotion dependencies..."
  npm install
fi

# Verify Chrome Headless Shell (Remotion downloads this automatically on first render)
# No manual action needed — Remotion handles this. But if it fails:
# npx remotion browser ensure

Step 5: Render Commands

Use the discovered REMOTION_CMD and ENTRY_POINT to execute renders:

bashCopy code
# Ensure output directory exists
mkdir -p "${GROWTHOS_ROOT}/.growthOS/output/videos/$(date +%Y-%m-%d-%H%M%S)"
OUTPUT_DIR="${GROWTHOS_ROOT}/.growthOS/output/videos/$(date +%Y-%m-%d-%H%M%S)"

# List available compositions (verify before render)
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} compositions "${ENTRY_POINT}"

# Render MP4 video
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} render "${ENTRY_POINT}" <CompositionId> "${OUTPUT_DIR}/video.mp4"

# Render a still frame (preview/thumbnail)
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} still "${ENTRY_POINT}" <CompositionId> "${OUTPUT_DIR}/preview.png" --frame=45

# Open Remotion Studio (interactive preview in browser)
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} studio "${ENTRY_POINT}"

Passing dynamic props (from composition.json):

bashCopy code
# Pass scene data from the storyboard via --props flag
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips "${OUTPUT_DIR}/video.mp4" \
  --props="${OUTPUT_DIR}/composition.json"

Step 6: Cross-Platform Considerations

macOS-specific:

bashCopy code
# Render and open
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4 && open out/video.mp4

Linux-specific:

bashCopy code
# Ensure headless Chrome dependencies
sudo apt-get install -y chromium-browser 2>/dev/null || true
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4 && xdg-open out/video.mp4

WSL-specific:

bashCopy code
# Render in WSL, open in Windows
cd "${REMOTION_PROJECT}" && ${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4
explorer.exe "$(wslpath -w out/video.mp4)"

Step 7: Performance Tuning

bashCopy code
# Default concurrency (auto-detected from CPU cores)
${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4

# Explicit concurrency (use 50-75% of available cores)
${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4 --concurrency=8

# Lower quality for fast preview
${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/preview.mp4 --jpeg-quality=60 --scale=0.5

# High quality for publication
${REMOTION_CMD} render "${ENTRY_POINT}" ReelTips out/video.mp4 --jpeg-quality=90 --crf=18

Troubleshooting

Complete Discovery Script (copy-paste ready)

bashCopy code
#!/bin/bash
# GrowthOS Remotion Discovery — run from project root
set -e

# 1. Find GrowthOS root
GROWTHOS_ROOT="$(find . -maxdepth 4 -name 'brand-voice.yaml' -exec dirname {} \; 2>/dev/null | head -1)"
if [ -z "$GROWTHOS_ROOT" ]; then
  echo "ERROR: brand-voice.yaml not found. Run /grow setup first."
  exit 1
fi

# 2. Find Remotion project
REMOTION_PROJECT="${GROWTHOS_ROOT}/remotion"
if [ ! -d "$REMOTION_PROJECT" ]; then
  echo "ERROR: Remotion project not found at ${REMOTION_PROJECT}"
  exit 1
fi

# 3. Determine entry point
if [ -f "${REMOTION_PROJECT}/src/compositions/index.ts" ]; then
  ENTRY_POINT="src/index.ts"
  echo "Entry: full (6 compositions)"
else
  ENTRY_POINT="index.ts"
  echo "Entry: simple (ReelTips only)"
fi

# 4. Ensure dependencies
if [ ! -d "${REMOTION_PROJECT}/node_modules/remotion" ]; then
  echo "Installing dependencies..."
  cd "$REMOTION_PROJECT" && npm install
fi

# 5. Verify
cd "$REMOTION_PROJECT" && npx remotion compositions "$ENTRY_POINT"

echo ""
echo "Remotion ready!"
echo "  Project: ${REMOTION_PROJECT}"
echo "  Entry:   ${ENTRY_POINT}"
echo "  Render:  cd ${REMOTION_PROJECT} && npx remotion render ${ENTRY_POINT} <CompositionId> out/video.mp4"
echo "  Studio:  cd ${REMOTION_PROJECT} && npx remotion studio ${ENTRY_POINT}"