/marketing-demo — Product Demo Recorder

Record product demos for marketing. Two production paths: quick (ply + ffmpeg) for rough demos, polished (Remotion) for branded marketing videos.

Reads

• brand/creative-kit.md — Colors, fonts, logo paths for branded overlays
• brand/voice-profile.md — Tone guidance for text overlays
• brand/stack.md — Available tools (ply, ffmpeg, remotion)

On Activation

1. Read brand/creative-kit.md for colors, fonts, logo paths. If missing, ask for brand colors and logo.
2. Read brand/voice-profile.md for tone guidance on text overlays. If missing, use clear/neutral tone.
3. Read brand/stack.md to confirm available tools. If missing, detect tools directly.
4. Check tool availability:

   command -v ply && echo "ply: ready" || echo "ply: missing"
   command -v ffmpeg && echo "ffmpeg: ready" || echo "ffmpeg: missing"
   command -v npx && echo "remotion: available" || echo "remotion: unavailable"
   

5. If ply or ffmpeg missing, warn and suggest install.

Shot Duration Rules

Demo Storytelling Principles

Demos fail when they show the product mechanically instead of telling a story. The viewer needs a reason to keep watching. These principles come from what actually gets engagement on landing pages and social:

1. Open with the outcome, not the setup. The first 2 seconds decide if someone watches the rest. Show the "after" state — the dashboard with data, the completed design, the result. Setup (login, loading, navigation) earns zero attention.
2. One feature = one demo. Trying to cram 5 features into 30 seconds makes all of them forgettable. A focused demo of one feature is worth more than a rushed tour.
3. Show the magic moment. Every product has one interaction where users go "oh wow." Find that moment and build the demo around it — it's why people click "try it."
4. Add context with text overlays. Social videos autoplay muted. Without text callouts, viewers see UI changing with no idea what's happening or why it matters. Every shot needs a 3-6 word overlay explaining the value.
5. Pacing: 2-3 seconds per concept. This feels fast, but viewer attention is brutal. If a shot doesn't earn its screen time with new information, cut it.

Step 1: Determine Demo Type

Ask the user which type, or infer from context.

Step 2: Plan Shot List

Before recording, plan each shot:

## Shot List

1. [Action: Navigate to landing page]
   - URL: https://example.com
   - Wait: 1s for load
   - Highlight: Hero section

2. [Action: Click "Get Started" button]
   - Wait: transition animation
   - Highlight: Signup form

3. [Action: Fill demo data]
   - Type: demo@example.com
   - Highlight: Success state

Each shot = one ply screenshot or interaction sequence.

Step 3: Choose Production Mode

Mode A: Quick Demo (ply + ffmpeg)

Fast, rough demos from screenshots stitched into video.

Capture screenshots:

# Navigate and screenshot each shot
ply navigate "https://example.com"
ply screenshot --output marketing/demos/shot-01.png
ply click "Get Started"
ply screenshot --output marketing/demos/shot-02.png

Stitch with ffmpeg:

# MP4 from screenshots (2 seconds per frame)
ffmpeg -framerate 0.5 -i marketing/demos/shot-%02d.png \
  -c:v libx264 -pix_fmt yuv420p \
  -vf "scale=1280:800:force_original_aspect_ratio=decrease,pad=1280:800:(ow-iw)/2:(oh-ih)/2" \
  marketing/demos/demo.mp4

# Preview GIF (lower quality, smaller file)
ffmpeg -i marketing/demos/demo.mp4 \
  -vf "fps=10,scale=640:-1:flags=lanczos" \
  -c:v gif marketing/demos/demo-preview.gif

# Email GIF (600px wide, optimized)
ffmpeg -i marketing/demos/demo.mp4 \
  -vf "fps=8,scale=600:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" \
  marketing/demos/demo-email.gif

# Square crop for social (1080x1080)
ffmpeg -i marketing/demos/demo.mp4 \
  -vf "crop=min(iw\,ih):min(iw\,ih),scale=1080:1080" \
  marketing/demos/demo-square.mp4

Mode B: Polished Demo (Remotion)

For marketing-grade output with transitions, text overlays, branded intros.

Generate Remotion composition:

# Initialize if needed
npx remotion init marketing/demos/remotion-demo

# Render final video
npx remotion render marketing/demos/remotion-demo/src/index.tsx \
  --output marketing/demos/demo-polished.mp4

Composition structure:

src/
├── index.tsx          # Root composition
├── Intro.tsx          # Branded intro (logo, tagline)
├── DemoScene.tsx      # Screenshot with text overlay
├── Transition.tsx     # Fade/slide between scenes
└── Outro.tsx          # CTA + URL

Key Remotion patterns (see references/remotion-examples.md for complete component code):

• Use <Img> for screenshots, <AbsoluteFill> for layout
• useCurrentFrame() + interpolate() for animations
• Pull brand colors from brand/creative-kit.md
• 30fps for smooth playback, 1280x720 or 1920x1080
• Add text overlays calling out features with <Sequence>

Intro scene (2-3s): Logo centered, tagline fades in. Brand colors as background gradient. Keep it short — the product is the star.

Demo scene (per shot): Screenshot fills 80% of frame. Text overlay at top or bottom with 1-line feature callout. Use interpolate() for a subtle zoom-in (1.0 → 1.05 over the scene duration) to add life.

Transition between scenes: Fade + slight slide (200ms). Never use fancy wipes — they distract from the product.

Outro scene (3-4s): CTA text ("Try it free at [url]"), logo, and optional social proof line. This is the only slide that sells — keep all other slides focused on showing.

Error Recovery

ply failures (page doesn't load, element not found, timeout): Skip to shot N+1 and document the failure in the shot list. After all shots complete, review skipped shots and retry once. If still failing, use manual screenshots as fallback.

ffmpeg failures (codec not found, format error): Check ffmpeg -codecs for available codecs. If libx264 is missing, try -c:v h264 or install via brew install ffmpeg. For GIF palette issues, simplify the filter chain — drop split/palettegen/paletteuse and use basic -vf "fps=10,scale=640:-1".

Remotion failures (render crashes, composition errors): Check node version (node -v, needs 18+). If npx remotion render fails, try npx remotion render --gl=angle or --gl=swangle for GPU issues. For composition errors, verify all <Img> src paths are correct and images exist.

Step 4: Convert & Output

All outputs go to marketing/demos/. Name by type:

Step 5: Completion Summary

## Demo Assets Created

| Asset | Size | Format | Suggested Use |
|-------|------|--------|--------------|
| demo-hero.mp4 | 1.2MB | MP4 1280x800 | Landing page hero |
| demo-preview.gif | 3.4MB