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

| Property | Value | |----------|-------| | Aspect Ratio | 9:16 (1080x1920) | | FPS | 30 | | Duration Range | 15-60 seconds (450-1800 frames) | | Scene Flow | hook(3s) > points(5s each) > CTA(4s) | | Background | Dark gradient with accent color from brand | | Default Animations | fade-in + scale-in for hook, alternating slide-left/right for points, bounce for CTA | | Best For | Quick tips, lists, how-tos, hacks |

Props Schema:

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

2. ReelBeforeAfter

| Property | Value | |----------|-------| | Aspect Ratio | 9:16 (1080x1920) | | FPS | 30 | | Duration Range | 15-30 seconds (450-900 frames) | | Scene Flow | hook(3s) > comparisons(6s each) > reveal(4s) > CTA(3s) | | Background | Split dark/light for before/after contrast | | Default Animations | wipe transitions for comparisons, slide for reveal | | Best For | Transformations, comparisons, results, upgrades |

Props Schema:

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

3. ReelNumbers

| Property | Value | |----------|-------| | Aspect Ratio | 9:16 (1080x1920) | | FPS | 30 | | Duration Range | 15-30 seconds (450-900 frames) | | Scene Flow | hook(3s) > number+context(5s each) > insight(5s) > CTA(3s) | | Background | Solid dark with accent-colored number highlights | | Default Animations | counter-up for numbers, fade for context text | | Best For | Statistics, data points, metrics, growth numbers |

Props Schema:

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

4. ExplainerSteps

| Property | Value | |----------|-------| | Aspect Ratio | 16:9 (1920x1080) | | FPS | 30 | | Duration Range | 60-180 seconds (1800-5400 frames) | | Scene Flow | intro(5s) > steps(15s each) > summary grid(10s) > CTA(5s) | | Background | Clean light or branded gradient | | Default Animations | slide-up for steps, scale-in for summary | | Best For | Tutorials, how-to guides, processes, setup guides |

Props Schema:

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

5. ExplainerDemo

| Property | Value | |----------|-------| | Aspect Ratio | 16:9 (1920x1080) | | FPS | 30 | | Duration Range | 30-120 seconds (900-3600 frames) | | Scene Flow | problem(5s) > solution intro(5s) > features(15s each) > social proof(10s) > CTA(5s) | | Background | Branded gradient or solid | | Default Animations | fade transitions, scale for features | | Best For | Product demos, feature showcases, SaaS walkthroughs |

Props Schema:

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

6. CarouselAnimated

| Property | Value | |----------|-------| | Aspect Ratio | 4:5 (1080x1350) | | FPS | 30 | | Duration Range | 15-60 seconds (450-1800 frames) | | Scene Flow | cover(4s) > content slides(4s each) > CTA(4s) | | Background | Inherits from carousel design spec or brand palette | | Default Animations | slide-left transitions between slides | | Best For | Animated versions of existing carousel content |

Props Schema:

{
  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

| Storyboard Scene Type | Remotion SceneProps.type | Typical Animation | Notes | |----------------------|-------------------------|-------------------|-------| | hook | "hook" | fade-in, scale-in | Always first scene. Must fire immediately. | | point | "point" | slide-left, slide-right | Content scenes. Alternate directions for pattern interrupt. | | comparison | "comparison" | wipe, slide-left | Before/after pairs. Use wipe for dramatic reveal. | | number | "number" | counter-up | Numbers animate from 0 to target value. | | step | "step" | slide-up, fade-in | Tutorial steps. Numbered prominently. | | demo | "demo" | scale-in, fade-in | Product feature highlights. | | cta | "cta" | bounce, scale-in | Always last scene. Brand handle visible. |

Frame Calculation

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):

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:

# 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

{
  "template": "",
  "fps": 30,
  "width": "",
  "height": "",
  "totalFrames": "",
  "brand": "",
  "scenes": [
    {
      "type": "",
      "startFrame": "",
      "durationFrames": "",
      "text": "",
      "subtext": "",
      "icon": "",
      "animation": "",
      "transition": ""
    }
  ],
  "showProgressBar": true,
  "showWatermark": true
}

---

Timing and Pacing

Duration Rules by Scene Type

| Scene Type | Minimum | Recommended | Maximum | Notes | |-----------|---------|-------------|---------|-------| | hook | 1.5s | 2-3s | 3s | Must fire immediately. Hook text readable in under 2s. | | point | 3s | 4-6s | 8s | One concept per scene. Text + subtext readable in duration. | | comparison | 4s | 6-8s | 10s | Before/after pair needs time to register contrast. | | number | 3s | 4-5s | 6s | Counter-up animation needs 2-3s, context text needs 2s. | | step | 8s | 12-15s | 20s | Tutorial steps need reading time + comprehension. | | demo | 8s | 12-15s | 20s | Product features need visual demonstration time. | | cta | 2s | 3-4s | 5s | Short, clear, actionable. Don't linger. |

Pacing by Platform

| Platform | Total Duration Sweet Spot | Scene Pacing | Hook Window | |----------|--------------------------|-------------|-------------| | Instagram Reels | 15-30s | Fast (3-5s per scene) | 8s without visual change | Viewer habituates, scrolls away | Split scene or add mid-scene animation | | Static text (no animation) | Looks like a screenshot, not a video | Add entrance animation to every text element | | No CTA at the end | Viewer watches but takes no action | Always end with a clear, single CTA | | Hook > 3 seconds | Loses viewers before the content starts | Compress hook to 2-3s max. If text is too long, simplify. | | Intro/logo before hook | Wastes the critical first 1.5s | Hook first, always. Brand watermark handles attribution. | | Slow pacing (>6s per point scene) | Feels like a slideshow, not a video | Speed up to 4-5s per point. Cut unnecessary subtext. | | Too many words per scene | Text unreadable in scene duration | Max 20 words per scene. 12 words is ideal for 5s scenes. | | Same animation on every scene | Monotonous, no pattern interrupts | Alternate directions, mix animation types (max 3 types). |

Technical Anti-Patterns

| Anti-Pattern | Why It Fails | Fix | |-------------|-------------|-----| | Duration outside template range | Remotion render may fail or produce bad output | Check template duration constraints before composing | | Wrong aspect ratio for platform | Video appears letterboxed or cropped | Match template aspect ratio to target platform | | Transition frames exceeding scene duration | Scene content gets cut by transition overlap | Ensure scene durationFrames > transition frame count | | Missing brand colors | Video looks generic, no brand recognition | Always load and inject BrandProps from brand-voice.yaml | | Counter-up without sufficient duration | Number animation too fast to read | Minimum 3s for counter-up scenes | | Watermark over main text | Blocks content, looks amateur | Position watermark in corner away from text area |

Strategic Anti-Patterns

| Anti-Pattern | Why It Fails | Fix | |-------------|-------------|-----| | Using explainer template for reel content | Wrong pacing, wrong audience expectations | Match template to content type and platform | | 60s reel for a 3-point topic | Padded content feels thin, hurts retention | Shorter content = shorter video. 3 points = 25-30s reel. | | Animated carousel without original carousel | No source content to adapt | Use reel or explainer template instead. CarouselAnimated is for converting existing content. | | Ignoring platform safe zones | Text hidden behind platform UI elements | Respect safe zone margins per platform | | No progress bar on reels | Viewer has no sense of video length | Always enable progress bar for short-form content |

---

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

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

| Carousel Element | Video Adaptation | |-----------------|-----------------| | Slide headline | Scene text (keep as-is, already optimized) | | Slide body text | Scene subtext (may need trimming for reading speed) | | Slide bullets | Convert to sequential text reveals within scene | | Slide icon/emoji | Scene icon (keep as-is) | | Progress dots | Replace with animated progress bar | | Brand watermark | Map to BrandWatermark component |

Timing Calculation

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 /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:

# 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:

# 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:

| Structure | Entry Point | Compositions | When to Use | |-----------|-------------|-------------|-------------| | src/ (full) | remotion/src/index.ts | All 6 templates | Default — use this when available | | Root-level (simple) | remotion/index.ts | ReelTips only | Fallback if src/ not present |

Step 3: Discover the Remotion CLI

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

# 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:

| Method | Command | Reliability | Notes | |--------|---------|-------------|-------| | npx remotion | High | Uses local node_modules, auto-resolves version | Preferred | | ./node_modules/.bin/remotion | High | Direct binar

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: melgarafael
• Source: melgarafael/growthOS
• License: MIT

Install and usage instructions live in the source repository linked above.