Claude Video Promo

claude-video-promo: Stock Footage + Remotion Promo Videos

Create polished promo/marketing videos by combining free stock footage with Remotion text overlays, transitions, and audio: with contrast-aware text placement.

V2 Intelligence Layer

The pipeline includes a scene planner that automatically makes aesthetic decisions:

Scene Intent Classification

The planner reads headlines/subtexts and classifies each scene:

• hook: First scene, dramatic, dark (Ken Burns: zoom out reveal)
• problem: Tension, urgency (Ken Burns: slow pan)
• feature: Clean, professional (Ken Burns: zoom in focus)
• proof: Warm, collaborative (static or medium)
• cta: Last scene, urgent (Ken Burns: subtle zoom, 15% larger text)

Transition Decision Tree

Transitions are auto-selected based on scene context:

• Dark to bright: fade (0.7s, smooth brightness ramp)
• Hook to problem: cut (punchy, immediate)
• Feature to feature: wipe-left (progression feel)
• Any to CTA: zoom (builds urgency)

Audio Intelligence

Per-scene ducking levels and ramp speeds:

• Hook: duck to 0.10, 10-frame ramp
• Feature: duck to 0.10, 10-frame ramp
• CTA: duck to 0.08, 5-frame ramp (fastest, voice most prominent)
• Proof: duck to 0.15, 15-frame ramp (music more present)

Contrast Analysis V2

Uses worst-case zone brightness (not average) plus variance detection:

• High variance (busy background): always strong backing
• Bright zone in text area (>0.5): force backing regardless of average
• Clean dark background: no backing, just shadow

Prerequisites

• Pixabay API key: Free at https://pixabay.com/api/docs/ (set PIXABAY_API_KEY env var)
• Pexels API key (optional): Free at https://www.pexels.com/api/ (set PEXELS_API_KEY env var)
• FFmpeg: Required for video preprocessing and contrast analysis
• Node.js + npm: For Remotion rendering
• Remotion project: The promo-pipeline/ directory bundled with this plugin

Pipeline: 3 Stages

1. ACQUIRE          2. ANALYZE           3. RENDER
Stock search     →  Frame contrast   →   Remotion composition
Stock download       analysis             AdaptiveText overlay
FFmpeg preprocess    Luminance grid        Transitions + Audio
TTS voiceover        contrast-map.json    Final MP4 output

Workflow

Step 1: Understand the Request

Determine from the user (conversationally or via YAML config):

• What scenes are needed (topic, text, duration)
• What stock footage to search for (keywords, mood)
• Text positioning (center, lower-third, upper-left, upper-right)
• Transitions between scenes (fade, wipe-left, wipe-right, zoom, cut)
• Audio: background music query + voiceover text
• Output: resolution, codec, destination path

Step 2: Search Stock Footage

python3 promo-pipeline/scripts/stock_search.py \
  --query "aerial city night" \
  --source pixabay \
  --orientation landscape \
  --min-duration 8 \
  --count 5

For music:

python3 promo-pipeline/scripts/stock_search.py \
  --query "upbeat corporate" \
  --source pixabay \
  --media-type music \
  --count 3

Present results to user with preview URLs. Let them pick.

Step 3: Download + Preprocess

python3 promo-pipeline/scripts/stock_download.py \
  --url "DOWNLOAD_URL" \
  --output promo-pipeline/public/stock/scene-id.mp4 \
  --trim-duration 10 \
  --gpu

This scales to 1080p 30fps, pads if needed, and encodes H.264.

Step 4: Analyze Contrast

python3 promo-pipeline/scripts/analyze_contrast.py \
  --input promo-pipeline/public/stock/scene-id.mp4 \
  --output promo-pipeline/public/stock/scene-id-contrast.json

Produces a per-second 4x3 luminance grid. The Remotion AdaptiveText component reads this to adjust text backing plates:

• Dark background → white text, no backing, subtle shadow
• Mid background → white text, semi-transparent dark plate
• Bright background → white text, strong dark plate

Step 5: Generate TTS (if voiceover needed)

Use the existing Gemini TTS script:

python3 promo-pipeline/scripts/tts_generate.py \
  --text "Your voiceover text here" \
  --output promo-pipeline/public/voiceover/scene-id.wav

Step 6: Build Scene Config JSON

Create scene-config.json with all paths and contrast data resolved:

{
  "scenes": [
    {
      "id": "hook",
      "durationFrames": 150,
      "stockPath": "stock/hook.mp4",
      "contrastMap": { ... },
      "headline": "The Future is Here",
      "subtext": "Launching Spring 2026",
      "textPosition": "center",
      "transition": "fade",
      "voiceoverPath": "voiceover/hook.wav"
    }
  ],
  "musicPath": "music/background.mp3",
  "musicVolume": 0.3,
  "musicFadeInFrames": 30,
  "musicFadeOutFrames": 60,
  "voiceoverDucking": 0.15
}

Step 7: Render

cd promo-pipeline
npx remotion render PromoVideo --props scene-config.json --codec h264 --crf 18

YAML Config Format (Alternative to Conversational)

Users can write a YAML config and the pipeline resolves everything:

scenes:
  - id: hook
    duration: 5s
    stock:
      query: "aerial city night lights"
      source: pixabay
    text:
      headline: "The Future is Here"
      subtext: "Launching Spring 2026"
      position: center
    transition: fade
    voiceover: "The future of marketing is about to change."

  - id: features
    duration: 8s
    stock:
      query: "technology dashboard data"
      source: pexels
    text:
      headline: "AI-Powered Analytics"
      position: lower-third
    transition: wipe-left

audio:
  music:
    query: "upbeat corporate"
    volume: 0.3
    ducking: 0.15

Safety Rules

1. Never overwrite source files: all operations produce new files
2. Check API key before searching: fail clearly if PIXABAY_API_KEY is missing
3. Validate stock video duration >= scene duration before rendering
4. Pre-trim music to match total video duration (Remotion Audio doesn't loop)
5. Confirm before batch downloads: stock video files can be large

Text Position Reference

Transition Reference

Scripts

• scripts/stock_search.py: Search Pixabay + Pexels video/music APIs (stdlib only)
• scripts/stock_download.py: Download + FFmpeg preprocess to 1080p 30fps
• scripts/analyze_contrast.py: Frame luminance analysis → JSON contrast map

Remotion Components

• src/components/PromoVideo.tsx: Main composition: sequences scenes + audio
• src/components/StockScene.tsx: Single scene: OffthreadVideo bg + adaptive text + Ken Burns
• src/components/AdaptiveText.tsx: Contrast-aware text with spring/fade/typewriter/slide-up animations
• src/components/Transitions.tsx: Fade, wipe, zoom transitions between scenes
• src/components/AudioLayer.tsx: Background music with voiceover ducking
• src/hooks/useContrast.ts: Reads contrast map, returns per-frame adaptive text styles