claude-video-promo
Create promo videos using free stock footage (Pixabay/Pexels) as backgrounds with Remotion text overlays, transitions, effects, and audio. Contrast-aware text placement adapts to background brightness. Use when user says "promo video", "stock footage video", "marketing video", "video with stock", "/video promo", or describes creating a video from stock clips with text overlays.
How do I install this agent skill?
npx skills add https://github.com/agricidaniel/claude-video --skill claude-video-promoIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a workflow for generating promotional videos using stock footage and Remotion. It automates searching, downloading, and rendering media through local scripts. Analysis indicates the skill follows safe practices for handling API keys and external resources.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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_KEYenv var) - Pexels API key (optional): Free at https://www.pexels.com/api/ (set
PEXELS_API_KEYenv 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
- Never overwrite source files: all operations produce new files
- Check API key before searching: fail clearly if PIXABAY_API_KEY is missing
- Validate stock video duration >= scene duration before rendering
- Pre-trim music to match total video duration (Remotion Audio doesn't loop)
- Confirm before batch downloads: stock video files can be large
Text Position Reference
| Position | Where | Best For |
|---|---|---|
center | Vertically + horizontally centered | Hero statements, titles |
lower-third | Bottom 25%, full width | News-style, documentary |
upper-left | Top-left corner | Subtitles, labels |
upper-right | Top-right corner | Branding, logos |
Transition Reference
| Type | Effect | Use When |
|---|---|---|
fade | Opacity crossfade (0.5s) | Default, smooth |
wipe-left | Horizontal clip reveal from left | Sequential progression |
wipe-right | Horizontal clip reveal from right | Reverse/callback |
zoom | Scale + fade dissolve | Dramatic emphasis |
cut | Instant switch | Fast pacing, urgency |
Scripts
scripts/stock_search.py: Search Pixabay + Pexels video/music APIs (stdlib only)scripts/stock_download.py: Download + FFmpeg preprocess to 1080p 30fpsscripts/analyze_contrast.py: Frame luminance analysis → JSON contrast map
Remotion Components
src/components/PromoVideo.tsx: Main composition: sequences scenes + audiosrc/components/StockScene.tsx: Single scene: OffthreadVideo bg + adaptive text + Ken Burnssrc/components/AdaptiveText.tsx: Contrast-aware text with spring/fade/typewriter/slide-up animationssrc/components/Transitions.tsx: Fade, wipe, zoom transitions between scenessrc/components/AudioLayer.tsx: Background music with voiceover duckingsrc/hooks/useContrast.ts: Reads contrast map, returns per-frame adaptive text styles
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/agricidaniel/claude-video/claude-video-promo">View claude-video-promo on skillZs</a>