Promo Video

First, ask how they want to provide context (no analysis yet):

{
  "questions": [{
    "question": "How should we define what this video is about?",
    "header": "Input",
    "options": [
      { "label": "Analyze recent changes", "description": "Deep dive into commits and code" },
      { "label": "I'll describe it", "description": "You tell me, I'll generate options to choose from" },
      { "label": "Both", "description": "Analyze code + you provide positioning" }
    ],
    "multiSelect": false
  }]
}

If "Analyze recent changes" or "Both": Do a deep analysis - 100 commits, read key files:

git log --oneline -100
# Read models, controllers, services, README

Then present findings as selectable options for confirmation.

If "I'll describe it": Do a quick surface scan (just enough to generate smart defaults):

head -30 README.md 2>/dev/null
ls app/models/ 2>/dev/null | head -5

Then present dynamic options based on what you found:

{
  "questions": [
    { "question": "What's the product?", "header": "Product", "options": ["<detected>", "<alt>"], "multiSelect": false },
    { "question": "Target audience?", "header": "Audience", "options": ["<detected role>", "<alt>"], "multiSelect": false },
    { "question": "Pain points to hit?", "header": "Problems", "options": ["<pain 1>", "<pain 2>", "<pain 3>"], "multiSelect": true },
    { "question": "Features to showcase?", "header": "Features", "options": ["<feat 1>", "<feat 2>", "<feat 3>", "<feat 4>"], "multiSelect": true }
  ]
}

Pre-populate options from scan so user clicks, not types.

Then ask about the CTA:

{
  "questions": [{
    "question": "What should the call-to-action be?",
    "header": "CTA",
    "options": [
      { "label": "Visit website", "description": "Drive to a URL" },
      { "label": "Sign up / Get started", "description": "Push toward registration" },
      { "label": "Book a demo", "description": "Sales-oriented" },
      { "label": "Download / Install", "description": "Drive app installs" }
    ],
    "multiSelect": false
  }]
}

The user can also provide custom CTA text via "Other".

Phase 2: Duration & Theme

Ask the user a couple quick setup questions. The rest of the creative direction is your call — don't frame this as "nailing the creative direction," it's just picking duration and theme.

Visual Style Suggestions:

• Clean and minimal with bold typography
• Dark mode with subtle accents and depth
• Light mode with soft gradients and shadows
• 3D elements with perspective and parallax
• Glassmorphism with blur and transparency

Transition Ideas:

• Zoom through: scale up current scene (1→3) with fade, new scene scales down from large (3→1)
• Metallic swoosh wipe across the screen
• Smooth scale + fade between scenes
• Directional slide with motion blur
• Particle dissolve effects

Animation Techniques:

• Spring physics for natural, bouncy motion
• Staggered reveals for lists and grids
• Parallax depth on layered elements
• Floating/pulsing ambient animations
• Typewriter or word-by-word text reveals

Browser Mockup Styles:

• Floating with dramatic shadow
• Perspective tilt (3D rotation)
• Nested in a device frame
• Screen recording style with cursor
• Split-screen comparison

Ask the user:

{
  "questions": [
    {
      "question": "How long should the video be?",
      "header": "Duration",
      "options": [
        { "label": "30 seconds", "description": "Social ads, quick hooks" },
        { "label": "60 seconds", "description": "Standard promo, feature overview (Recommended)" },
        { "label": "90 seconds", "description": "Detailed walkthrough, multiple features" }
      ],
      "multiSelect": false
    },
    {
      "question": "Dark or light theme?",
      "header": "Theme",
      "options": [
        { "label": "Light mode", "description": "Clean, bright, professional" },
        { "label": "Dark mode", "description": "Modern, bold, dramatic" }
      ],
      "multiSelect": false
    },
    {
      "question": "What voice style for the voiceover?",
      "header": "Voice Style",
      "options": [
        { "label": "Professional", "description": "Polished broadcast/corporate voices" },
        { "label": "African American", "description": "Authentic African American voices" },
        { "label": "Caribbean", "description": "Jamaican, Trinidadian, island vibes" },
        { "label": "African", "description": "Nigerian, West African accents" },
        { "label": "Latino", "description": "Spanish, Dominican, Colombian, Argentine" }
      ],
      "multiSelect": false
    }
  ]
}

Then based on voice style selection, ask for specific voice:

If "Professional":

{
  "questions": [{
    "question": "Which professional voice?",
    "header": "Voice",
    "options": [
      { "label": "Matilda (F)", "description": "Warm, confident — polished and versatile" },
      { "label": "Rachel (F)", "description": "Calm, clear — smooth and authoritative" },
      { "label": "Daniel (M)", "description": "Authoritative — broadcast/advertising tone" },
      { "label": "Josh (M)", "description": "Friendly, conversational — approachable" }
    ],
    "multiSelect": false
  }]
}

If "African American":

{
  "questions": [{
    "question": "Which African American voice?",
    "header": "Voice",
    "options": [
      { "label": "Hakeem (M)", "description": "African American narrator — confident, storytelling" },
      { "label": "Alex (M)", "description": "Mid-30s professional — warm, assured delivery" },
      { "label": "Christina (F)", "description": "30-40 years — calm, pleasant, relaxed tone" },
      { "label": "Alicia (F)", "description": "Mid-West — distinct, smooth, meditation-style" },
      { "label": "Clarity (F)", "description": "Soothing — adult female voice over" }
    ],
    "multiSelect": false
  }]
}

If "Caribbean":

{
  "questions": [{
    "question": "Which Caribbean voice?",
    "header": "Voice",
    "options": [
      { "label": "Justin (M)", "description": "Trinidadian accent — calm, news/narration style" }
    ],
    "multiSelect": false
  }]
}

If "African":

{
  "questions": [{
    "question": "Which African voice?",
    "header": "Voice",
    "options": [
      { "label": "Ayinde (M)", "description": "British Nigerian — urban, deep, melodic accent" },
      { "label": "Attank (M)", "description": "African accent — calm and excited range" },
      { "label": "Abdoulaye (M)", "description": "West African — training/educational delivery" },
      { "label": "Olufunmilola (F)", "description": "Nigerian Yoruba — authentic accent" },
      { "label": "Bukola (F)", "description": "Young Nigerian — friendly, storytelling" }
    ],
    "multiSelect": false
  }]
}

If "Latino":

{
  "questions": [{
    "question": "Which Latino voice?",
    "header": "Voice",
    "options": [
      { "label": "Abel (M)", "description": "Spanish-Dominican — warm, conversational" },
      { "label": "Alejandro (M)", "description": "Latin Spanish — natural, casual speaker" },
      { "label": "Agustin (M)", "description": "Argentino — powerful Buenos Aires accent" },
      { "label": "Daniela (F)", "description": "Latin America — high-energy, persuasive" },
      { "label": "Andrea (F)", "description": "Colombian Paisa — specialized sales style" },
      { "label": "Daisy Fuentes (F)", "description": "Latin female — audiobooks, e-learning" }
    ],
    "multiSelect": false
  }]
}

ElevenLabs Voice IDs (use these exact IDs, do not guess):

Professional Voices

African American Voices

Caribbean Voices

African Voices

Latino Voices

Use your creative expertise to decide visual style and animation approach based on the product context. Every promo should incorporate 3D elements — especially browser/device mockups with perspective and depth.

Then ask about transitions:

{
  "questions": [
    {
      "question": "What transition between main sections (e.g. Hook → Pain Points → Solution)?",
      "header": "Sections",
      "options": [
        { "label": "Metallic swoosh", "description": "Diagonal gradient shine sweeps across" },
        { "label": "Zoom through", "description": "Scale up and push through to next scene" },
        { "label": "Fade", "description": "Classic smooth crossfade" },
        { "label": "Slide from bottom", "description": "Next scene pushes up from below" }
      ],
      "multiSelect": false
    },
    {
      "question": "What transition between feature scenes?",
      "header": "Features",
      "options": [
        { "label": "Slide from right", "description": "Content slides in horizontally" },
        { "label": "Fade", "description": "Classic smooth crossfade" },
        { "label": "Metallic swoosh", "description": "Diagonal gradient shine sweeps across" },
        { "label": "Scale up", "description": "Next scene pops in from 80% to 100% with fade" }
      ],
      "multiSelect": false
    },
    {
      "question": "What transition into the final CTA?",
      "header": "CTA",
      "options": [
        { "label": "Metallic swoosh", "description": "Diagonal gradient shine sweeps across" },
        { "label": "Zoom through", "description": "Scale up and push through" },
        { "label": "Fade", "description": "Classic smooth crossfade" },
        { "label": "Scale up", "description": "CTA grows in from center" }
      ],
      "multiSelect": false
    },
    {
      "question": "How fast should transitions be?",
      "header": "Speed",
      "options": [
        { "label": "Quick (0.4s)", "description": "Snappy, energetic" },
        { "label": "Medium (0.7s)", "description": "Balanced, professional" },
        { "label": "Slow (1.2s)", "description": "Dramatic, cinematic" }
      ],
      "multiSelect": false
    }
  ]
}

If user selects "Metallic swoosh": Read metallic-swoosh.md before implementing. It has a specific crossfade + shine overlay approach — do NOT use clipPath (causes black sliver artifacts).

Phase 3: Build with Remotion

Create the project (non-interactive):

yes "" | npx create-video@latest --blank --no-git promo-video/<project-name>
cd promo-video/<project-name>
npm install
npm install lucide-react  # For icons

Set composition to 1920x1080 (full HD):

<Composition width={1920} height={1080} fps={30} ... />

See remotion-best-practices skill for animation patterns.

Framing & sizing guidelines:

• Fill the frame. Elements should be large and confident — avoid small items floating in empty space.
• Headlines: 60–90px minimum. Subtext: 32–44px. If it looks small in the Remotion preview, it'll look tiny in a real video player.
• Browser mockups / device frames should take up 60–80% of the frame width. Not a tiny thumbnail in the center.
• Padding from edges: 60–100px. Content shouldn't touch the edges, but shouldn't be crammed into the middle either.
• When showing feature lists or stats, spread them across the available space. Use the full width.
• If a scene feels empty, the elements are too small. Scale up before adding filler.

Your creative toolkit:

• spring() for natural motion (play with damping, mass, stiffness)
• interpolate() for precise timing control
• CSS 3D transforms (perspective, rotateX, rotateY, translateZ) for depth and device mockups
• Box shadows and gradients for depth
• Blur filters for glassmorphism
• SVG paths for custom shape animations
• Lucide icons

Scene structure is flexible. Classic structure as a starting point:

• Hook/Opening → Pain Points → Solution Reveal → Features → Results → CTA

But you might do:

• Cold open on a feature → zoom out to problem → solution
• Customer quote → problem → solution → features
• Single continuous zoom through all content

Trust your instincts.

After building the composition, launch Remotion Studio for preview:

npx remotion studio

Then ask the user:

{
  "questions": [{
    "question": "How does the video look? Ready to add voiceover and music?",
    "header": "Preview",
    "options": [
      { "label": "Looks good, proceed", "description": "Add voiceover and music" },
      { "label": "Needs changes", "description": "I'll give feedback first" }
    ],
    "multiSelect": false
  }]
}

If "Needs changes", iterate on their feedback before moving on.

Phase 4: Voiceover (Critical)

The voiceover must match the visuals. This is non-negotiable.

1. Extract scene timings from your composition
2. Write script that references what's on screen
3. Generate with ElevenLabs (needs ELEVEN_LABS_API_KEY)
4. Verify with Whisper - check actual timestamps
5. Fix ALL overlaps immediately - don't ask, just fix:
   • Shorten text (make it punchier)
   • Increase gaps between sections
   • Regenerate and verify again
   • Repeat until zero overlaps

See voiceover.md for generation script and details.

Phase 5: Music & Final Render

Ask about music:

{
  "questions": [{
    "question": "Background music?",
    "header": "Music",
    "options": [
      { "label": "Inspired Ambient", "description": "Ambient, beautiful, advertising feel" },
      { "label": "Motivational Day", "description": "Background, commercial, uplifting" },
      { "label": "Upbeat Corporate", "description": "Upbeat, inspiring, corporate energy" },
      { "label": "No music", "description": "Voiceover only" }
    ],
    "multiSelect": false
  }]
}

Music files (royalty-free from Pixabay, bundled in skill):

# Copy selected track to project
cp "${SKILL_DIR}/music/inspired-ambient-141686.mp3" background-music.mp3
# OR
cp "${SKILL_DIR}/music/motivational-day-112790.mp3" background-music.mp3
# OR
cp "${SKILL_DIR}/music/the-upbeat-inspiring-corporate-142313.mp3" background-music.mp3

# Verify
ls -lah background-music.mp3 && file background-music.mp3

Mix audio:

ffmpeg -y -i voiceover-normalized.mp3 -i background-music.mp3 \
  -filter_complex "[1:a]volume=0.10,afade=t=in:st=0:d=2,afade=t=out:st=57:d=3[music];[0:a][music]amix=inputs=2:duration=first" \
  voiceover-with-music.mp3

Render video:

npx remotion render MainPromo out/promo-hq.mp4 --image-format png --crf 1

Combine video + audio:

ffmpeg -y -i out/promo-hq.mp4 -i voiceover-with-music.mp3 \
  -c:v copy -map 0:v:0 -map 1:a:0 \
  out/promo-final.mp4

Iteration Checklist

When user gives feedback, common fixes:

DON'Ts

• No jitter effects - No shaking, vibrating, or jittery motion. Everything should feel smooth and controlled.
• No full scene spinning - Don't rotate the entire scene or composition. 3D rotation should be subtle and purposeful (e.g. a browser mockup with slight perspective tilt, not a 360° spin).
• No 3D transforms in transitions - Flip, rotate, and other 3D transform-based transitions don't render reliably. Stick to 2D: opacity, position, scale, and gradient masks. (3D transforms are fine for in-scene elements like browser mockups.)

Resources

• voiceover.md - Script writing, ElevenLabs, Whisper timing verification
• promo-patterns.md - Example scene components (use as inspiration, not templates)
• metallic-swoosh.md - Metallic swoosh transition implementation (DO NOT use clipPath, use crossfade + shine overlay)
• scripts/generate_voiceover.py - Voiceover generation with timing checks