Files
skills/public/remotion-video.md
zeekayandHanzo Dev 65c3b27843 160 marketing, growth and PM skills, on our own connectors
Four MIT collections ported — growthOS, openclaw-marketing-skills,
Marketing-Skills and pm-skills — as 160 skills, 12 agents and 45
commands, each naming its origin in its own frontmatter so the tree can
be checked against THIRD_PARTY_NOTICES rather than trusted. Sixteen names
appeared in more than one collection and none of the copies were
identical; the longest wins, which lands on the more developed text where
they genuinely diverge.

A fifth collection is deliberately absent. awesome-growth-hacking-skills
carries NO licence, which leaves its author every right by default — and
it is a list of links rather than a collection of skills, so there is
nothing in it to port and no permission to port it with. It is cited as a
directory to read.

THE CONNECTOR SKILLS ARE REWRITTEN, not ported. They arrived installing
vendor SDKs, running OAuth flows of their own, and ending with long-lived
credentials in JSON files under .agents/ and ~/.growthos/ at mode 600.
That is a secret on a disk with no rotation path, protected from other
users and not from the agent — and one auth implementation per skill.
Hanzo holds these connectors in Go, per user, sealed in KMS, so `connect`
is the one home for the flow and the platform skills defer to it by
provider id: google_ads, meta_ads, x. It is reachable as HTTP or as MCP
tools at api.hanzo.ai/v1/mcp — the same routes, typed once in Go, so a
tool and a curl cannot disagree.

Two had nothing real behind them and now say so. There is no
search_console provider, so that skill names what does answer the same
questions (google_analytics, google_bigquery) and states that the remedy
is a provider in hanzoai/cloud rather than a vendor SDK here. And
getxapi-connect was a wrapper around a paid reseller of X's public data
with the vendor's key in an env var; it is `listen` now, on our own x
connector — a skill named after a vendor makes the vendor the capability
and dies with it.

The skills referenced paths that only existed inside the source repo, so
the shared material they read is ported to reference/ and the paths
rewritten. Three skills need the growthOS APPLICATION rather than its
data; per the estate's own split an application belongs in hanzoai/ads,
social, email or sms as a cloud plugin, so those three say what they need
instead of carrying an import that resolves to nothing.

Third-party product names are out of our prose and kept in the notices,
which is where the licence requires them and the only place they belong.
A skill's persona names a role, not somebody else's product.


Co-authored-by: Hanzo Dev <[email protected]>
2026-09-15 01:27:26 -07:00

38 KiB

name, description, source
name description source
remotion-video Remotion video composition knowledge — 6 template specs, storyboard-to-composition mapping, frame calculations, animation catalog, transition types, platform rules, retention triggers, and anti-patterns for video production melgarafael/growthOS

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

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) < 1.5s
YouTube Shorts 30-60s Medium (4-6s per scene) < 2s
TikTok 15-60s Fast (3-5s per scene) < 1s
YouTube (long) 60-180s Measured (8-15s per scene) < 3s

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 Description Best For Remotion Implementation
fade-in Opacity from 0 to 1 over 15 frames Hook scenes, gentle reveals interpolate(frame, [0, 15], [0, 1]) on opacity
fade-out Opacity from 1 to 0 over 15 frames Scene exits, before transitions interpolate(frame, [end-15, end], [1, 0]) on opacity
slide-left Element enters from right edge, slides to center Content points (odd positions) interpolate(frame, [0, 20], [width, 0]) on translateX
slide-right Element enters from left edge, slides to center Content points (even positions) interpolate(frame, [0, 20], [-width, 0]) on translateX
slide-up Element enters from bottom, slides to center Steps, reveals, lists interpolate(frame, [0, 20], [height, 0]) on translateY
scale-in Element scales from 0.5 to 1.0 with slight bounce Hooks, reveals, emphasis interpolate(frame, [0, 20], [0.5, 1]) on scale with spring config
bounce Element enters with elastic bounce effect CTAs, emphasis, fun reveals spring({ frame, fps, config: { damping: 8, stiffness: 100 } })
typewriter Text appears character by character Quotes, statements, dramatic reveals Render substring text.slice(0, charIndex) per frame
counter-up Number counts from 0 to target value Statistics, metrics, data interpolate(frame, [0, durationFrames], [0, targetNumber]) rounded
wipe Horizontal wipe reveals new content Before/after reveals, dramatic transitions ClipPath animation from inset(0 100% 0 0) to inset(0 0 0 0)

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

Animation Default Duration (frames) At 30fps
fade-in 15 0.5s
fade-out 15 0.5s
slide-left 20 0.67s
slide-right 20 0.67s
slide-up 20 0.67s
scale-in 20 0.67s
bounce 30 1.0s
typewriter varies (2 frames/char) varies
counter-up matches scene duration varies
wipe 25 0.83s

Transitions

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

Transition Frame Duration At 30fps Description Best For
crossfade 15 frames 0.5s Outgoing scene fades out while incoming fades in. Smooth and professional. Default for most scene changes. Points, steps, generic transitions.
wipe 20 frames 0.67s Horizontal wipe reveals the new scene from left to right. Dramatic. Before/after reveals, comparison pairs, dramatic moments.
cut 0 frames 0s Instant switch. No transition effect. Sharp and immediate. Hook scene start (always use cut for the first scene), rhythm breaks.
slide 15 frames 0.5s Outgoing scene slides out while incoming slides in from opposite edge. Carousel-animated (mimics swipe gesture), sequential content.

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

Parameter Value Notes
Aspect Ratio 9:16 (1080x1920) Mandatory for full-screen Reels
Max Duration 90 seconds Algorithm favors 15-30s for reach
Min Duration 3 seconds Below 3s feels like an error
Sweet Spot 15-30 seconds Highest completion rate and reach
Hook Window < 1.5 seconds Text must be readable immediately
Safe Zones 250px top, 400px bottom Avoid UI overlay areas (username, music, buttons)
Audio Optional (motion-only supported) Add caption overlay for sound-off viewers

YouTube Shorts

Parameter Value Notes
Aspect Ratio 9:16 (1080x1920) Same as Reels
Max Duration 60 seconds Hard limit enforced by YouTube
Min Duration 15 seconds Below 15s may not get Shorts shelf
Sweet Spot 30-60 seconds YouTube Shorts audience tolerates longer content
Hook Window < 2 seconds Slightly more forgiving than IG
Safe Zones 200px top, 350px bottom Similar to Reels but slightly different UI
Audio Recommended YouTube Shorts discovery relies more on audio

TikTok

Parameter Value Notes
Aspect Ratio 9:16 (1080x1920) Standard vertical
Max Duration 3 minutes (180s) Extended from original 60s
Min Duration 5 seconds Below 5s may not surface in For You
Sweet Spot 15-60 seconds Depends on content type
Hook Window < 1 second TikTok has the shortest attention span
Safe Zones 150px top, 500px bottom Large bottom safe zone for comments/buttons
Audio Strongly recommended TikTok is audio-first platform

YouTube (Horizontal)

Parameter Value Notes
Aspect Ratio 16:9 (1920x1080) Standard horizontal
Max Duration No limit Platform supports any length
Min Duration 30 seconds Below 30s feels rushed for horizontal
Sweet Spot 60-180 seconds For explainers and demos
Hook Window < 3 seconds More patient audience
Safe Zones Minimal Full-screen video, no UI overlays during playback
Audio Expected Horizontal YouTube content almost always has narration

Brand Integration

Color Mapping from brand-voice.yaml

# 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

Scene Type Background Text Accent Usage
hook background color or dark gradient text color, large accent on key word or underline
point background color text color primary on icon, secondary on subtext
comparison split: muted background / vibrant background text color accent on "after" state
number background color text color for context accent on the animated number
step background color text color primary on step number
demo background color or branded gradient text color accent on feature highlights
cta accent color as background or accent border text color (inverted if needed) accent dominant

Watermark Positioning

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

Position Pixel Offset Best For
bottom-right 40px from bottom, 40px from right Default. Most natural position.
bottom-left 40px from bottom, 40px from left When bottom-right conflicts with platform UI
top-right 40px from top, 40px from right When bottom area is crowded

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

Trigger Implementation Why It Works
Motion on every scene All scenes have entrance animations Static text = scroll away. Motion = visual interest.
Counter-up for numbers Numbers animate from 0 to target Brain tracks counting, creates micro-anticipation.
Alternating slide directions Odd scenes slide-left, even slide-right Pattern interrupt prevents visual habituation.
Progress bar Animated bar from 0% to 100% Creates completion motivation (endowed progress effect).
Hook in first 1.5s Text visible from frame 1, no fade-from-black First impression determines stay/go. No wasted time.
Text in motion Typewriter, slide, fade — never just "appear" Motion triggers peripheral vision attention.
Color contrast on key words Accent color on numbers, names, key terms Draws eye to the most important information.
Scene type variety Mix hooks, points, numbers, comparisons Different layouts prevent monotony.

Retention Anti-Pattern Checklist

Before finalizing any storyboard, verify these are NOT present:

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

Anti-Pattern Why It Fails Fix
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

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 < 15s: increase per-scene duration to 5s

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:

Component Purpose Props
AnimatedText Renders text with specified animation type and delay text, animation, delay, style
ProgressBar Animated bar showing video progress (0-100%) position ("top" or "bottom"), color, height
BrandWatermark Brand handle overlay in corner, fades in on first scene handle, position, color, opacity
TransitionWipe Renders transition effect between scenes type ("crossfade", "wipe", "cut", "slide"), durationFrames
BackgroundGradient Animated gradient background with subtle color shift colors (array), direction, animationSpeed
CounterUp Counts from 0 to target number with easing target, durationFrames, style, easing

Output Contract

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 Remotion Project

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

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

# Strategy 2: If brand-voice.yaml not found, search for remotion/src/Root.tsx
REMOTION_PROJECT="$(find . -maxdepth 5 -path '*/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}/remotion/src/Root.tsx" ] || [ -f "${loc}/remotion/index.ts" ]; then
    REMOTION_PROJECT="${loc}/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

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:  parent node_modules (if deps installed at  level)
REMOTION_BIN="${PROJECT_ROOT}/node_modules/.bin/remotion"
if [ -x "${REMOTION_BIN}" ]; then
  REMOTION_CMD="${REMOTION_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 binary, no npx overhead Fast alternative
Global remotion Medium May version-mismatch with project deps Check version compatibility
Not found — — Run npm install in remotion project dir

Step 4: Verify Dependencies

Before rendering, confirm all dependencies are installed:

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:

# Ensure output directory exists
mkdir -p "${PROJECT_ROOT}/.output/videos/$(date +%Y-%m-%d-%H%M%S)"
OUTPUT_DIR="${PROJECT_ROOT}/.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):

# 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

Platform Working Dir Separator Shell NPX Available Notes
macOS / zsh/bash Yes (with Node) Default dev platform. open file.mp4 to play.
Linux / bash Yes (with Node) xdg-open file.mp4 to play. May need apt install chromium for headless.
Windows (native) \ PowerShell/cmd Yes (with Node) Use start file.mp4 to play. Paths need backslash or quotes.
Windows (WSL) / bash Yes (with Node) Render inside WSL, output accessible at /mnt/c/.... explorer.exe file.mp4 to play.

macOS-specific:

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

Linux-specific:

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

# 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

# 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

Error Cause Fix
remotion: command not found CLI not installed cd ${REMOTION_PROJECT} && npm install then use npx remotion
Cannot find module 'remotion' Dependencies not installed cd ${REMOTION_PROJECT} && npm install
Could not find composition Wrong entry point or composition ID Run ${REMOTION_CMD} compositions ${ENTRY_POINT} to list available
Chrome Headless Shell not found First render, downloading Wait for auto-download, or run npx remotion browser ensure
ENOMEM / out of memory Video too long or high concurrency Reduce --concurrency or add --scale=0.5
ENOSPC / disk space Not enough disk for render frames Free 500MB+ before rendering
Timed out Render exceeds 5min Reduce duration, lower quality, or increase --timeout
JSX element type 'X' does not have any construct TypeScript/React version mismatch Check tsconfig.json has "jsx": "react-jsx"
Module not found: @remotion/cli/config Old remotion.config.ts API Update to import { Config } from "@remotion/cli/config"

Complete Discovery Script (copy-paste ready)

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

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

# 2. Find Remotion project
REMOTION_PROJECT="${PROJECT_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}"