create-product-demo-video

Create Product Demo Video

Overview

Create the actual video artifact, not only mock screens. Treat visual composition, timing, motion, audio, validation, and final encoding as one production workflow.

Prefer a versioned local production folder such as /tmp/product-video-v1 or a user-provided folder. Keep source files, generated stills, rendered frames, and final MP4s together so later revisions are cheap.

Workflow

1. Gather the brief:

   • Objective, audience, platform, duration, aspect ratio, output path.
   • Required assets: app screens, screen recordings, Figma exports, logos, product images, voiceover, soundtrack.
   • Style: calm, energetic, premium, playful, technical, clinical, educational, etc.
   • Constraints: brand colors, forbidden terms, required captions, no stock, no AI voice, no audio, etc.

2. Choose the video approach:

   • Use an HTML/GSAP or HyperFrames-style composition for animated product videos, app walkthroughs, zooms, taps, isometric layouts, captions, and end cards.
   • Use Remotion when the repo already uses React video composition or the user wants reusable component-driven video.
   • Use direct FFmpeg edits for simple tasks: adding audio, trimming, changing volume, concatenating clips, or replacing a soundtrack.
   • Use image/video generation only when the user needs new visual assets and policy allows it.

3. Build the storyboard before animating:

   • Intro: brand or topic signal, 2-4 seconds.
   • Setup: who is using the product and why.
   • Core flow: 3-6 beats showing the main workflow or benefit.
   • Outcome: progress, result, success state, comparison, or visual payoff.
   • Outro: logo, tagline, or clean final frame.

4. Compose the visuals:

   • Use real product screens or faithful exports when the product UI matters.
   • Avoid decorative filler when a concrete product state can be shown.
   • Make taps/buttons feel physical when the source app has that behavior.
   • Validate scaled UI: no stretched avatars, hidden text, double progress bars, clipped labels, ghost overlays, or transparent patches.
   • When changing text inside screenshots/SVGs, prefer editing the source SVG/export rather than covering it with large overlays.

5. Validate before rendering:

   • Capture stills at key timestamps: intro, each major screen, busiest animation, audio-relevant moments, outro.
   • Inspect stills visually. Fix obvious layout issues before full rendering.
   • Check media durations with scripts/probe_media.py or ffprobe.
   • Confirm the final canvas, resolution, FPS, duration, and file size.

6. Render:

   • Encode MP4 with H.264, yuv420p, +faststart.
   • Default vertical social/app output: 1080x1920, 30fps.
   • Default horizontal output: 1920x1080, 30fps.
   • Save with a versioned filename: name-v01.mp4, name-v02-audio.mp4, name-v03-final.mp4.

7. Mix audio:

   • Voice must be intelligible before music is judged.
   • Start narration after the intro unless the brief says otherwise.
   • Keep music low, typically 6-15% of original gain.
   • Use ducking when music and voice overlap.
   • Add short fade-in and longer fade-out.
   • Validate by listening or by checking rough levels. Voice peaks can be near -1 dB; music should not mask consonants.

Useful Scripts

Use scripts from this skill by resolving them relative to this SKILL.md.

Inspect media:

python scripts/probe_media.py input.mp4 voice.mp3 music.mp3

Mix existing narration from a video with a background track:

python scripts/mix_demo_audio.py \
  --video demo-with-voice.mp4 \
  --music soundtrack.mp3 \
  --output demo-final.mp4 \
  --use-video-audio \
  --music-volume 0.08

Add a separate narration file and soundtrack to a silent video:

python scripts/mix_demo_audio.py \
  --video silent-demo.mp4 \
  --narration voice.mp3 \
  --music soundtrack.mp3 \
  --output demo-final.mp4 \
  --narration-delay 3.5 \
  --voice-lufs -14 \
  --music-volume 0.08

References

• Read references/audio-mix.md when adding voiceover, background music, ducking, fades, or diagnosing low voice/high music.
• Read references/visual-qa.md before claiming the video is ready.
• Read references/project-structure.md when starting a new video project from scratch.

Completion Checklist

• Final video file exists at the promised path.
• ffprobe confirms codec, duration, dimensions, FPS, and audio stream.
• Key stills were inspected after the final visual change.
• Voice/music balance was checked if audio exists.
• The final response includes a local Markdown media link with the absolute path.