scroll-reveal-video

Scroll-Scrub Video

This skill turns any video into a scroll-driven animation: the video's playback position is mapped directly to scroll progress, so each frame reveals as the user scrolls. Includes optional animated text overlays that fade in and out at defined scroll positions.

Requires ffmpeg on PATH.

---

Step 0 — Gather Inputs

Before starting, confirm these with the user if not already provided:

• VIDEO_PATH — absolute path to the source video file
• OUTPUT_DIR — directory where the encoded video and HTML will be saved (default: same directory as the source video)
• SECTION_HEIGHT — how much vertical scroll travel the section takes up (default: 200vh; use 300vh for more time per text card)
• DISPLAY_WIDTH — max display width in px (default: 1920 for full-bleed object-cover; use 1280 for a contained layout)
• TEXT_OVERLAYS — optional list of 2–4 text cards. For each, ask: label (overline), headline, scroll start fraction (0–1), scroll end fraction (0–1). Skip if the user wants video only.

---

Step 1 — Probe the Source Video

ffprobe -v quiet -print_format json -show_streams "VIDEO_PATH" 2>&1

From the output, note:

• width × height — source resolution
• r_frame_rate — frame rate (e.g. "24/1")
• nb_frames — total frame count
• duration — total seconds
• codec_name — source codec

If the source width is already ≤ DISPLAY_WIDTH, set ENCODE_WIDTH to the source width (never upscale). Otherwise set ENCODE_WIDTH to DISPLAY_WIDTH.

---

Step 2 — Re-encode for Smooth Scrubbing

All-I-frame encoding means every frame is a full keyframe. This eliminates the blocking artifacts that appear when video.currentTime seeks to a B/P inter-frame — the root cause of graininess and stuttering in scroll-scrub effects.

ffmpeg -y -i "VIDEO_PATH" \
  -an \
  -vf scale=ENCODE_WIDTH:-2:flags=lanczos \
  -g 1 -keyint_min 1 \
  -crf 18 \
  -preset slow \
  -profile:v high \
  -movflags +faststart \
  "OUTPUT_DIR/scrub-video.mp4"