Scroll Video Hero

Turn any static hero image into a scroll-controlled cinematic video background. The hero stays pinned while the user scrolls; the video scrubs forward with scroll progress, then releases into normal page flow.

Pipeline

1. Generate video from hero image via KIE API (Veo 3 image-to-video)
2. Compress with ffmpeg (target <3MB)
3. Embed as sticky scroll-controlled background in Next.js

Step 1: Generate Video

Use KIE API Veo 3 Fast for image-to-video. See references/kie-video-api.md for full endpoint details.

curl -s -X POST "https://api.kie.ai/api/v1/veo/generate" \
  -H "Authorization: Bearer $KIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "<describe subtle motion: particles, light shifts, gentle camera push>",
    "model": "veo3_fast",
    "aspect_ratio": "9:16",
    "generationType": "FIRST_AND_LAST_FRAMES_2_VIDEO",
    "image": "<publicly-accessible-image-url>"
  }'

Prompt guidelines

• Keep motion subtle: particles, light pulses, gentle camera push-in, atmospheric drift
• Avoid drastic scene changes (it must look like the same hero image, animated)
• Include "slow motion feel" and "seamless loop friendly" for smoother scrubbing
• Match the brand's visual language in the prompt

Aspect ratio selection

• 9:16 (portrait): Best for full-viewport sticky heroes on desktop. Fills tall viewports.
• 16:9 (landscape): Use only if the hero section is short/cinematic-bar style.
• 1:1: Good compromise for mixed desktop/mobile.

Polling for completion

curl -s "https://api.kie.ai/api/v1/veo/record-info?taskId=$TASK_ID" \
  -H "Authorization: Bearer $KIE_API_KEY"

• successFlag: 0 = still generating (poll every 30s, typically 2-5 min)
• successFlag: 1 = done, URL in response.resultUrls[0]
• successFlag: 2 or 3 = failed, retry

Step 2: Compress Video

Strip audio, compress for web, enable fast-start streaming:

ffmpeg -i input.mp4 -vcodec libx264 -crf 28 -preset fast -an -movflags +faststart output.mp4

Target: <3MB for hero backgrounds. Adjust -crf (lower = better quality, bigger file).

Step 3: React Component

Dependencies

• framer-motion (useScroll, useTransform, useMotionValueEvent)
• next/image (fallback poster)

Pattern: Sticky Scroll-Scrubbed Video

'use client';

import { useRef } from 'react';
import { useScroll, useMotionValueEvent } from 'framer-motion';
import Image from 'next/image';

interface ScrollVideoHeroProps {
  videoSrc: string;        // path to compressed mp4
  posterSrc: string;       // fallback image (same as source image)
  posterAlt: string;
  runwayVh?: number;       // scroll runway height in vh (default 250)
  children: React.ReactNode; // hero text content
}

export function ScrollVideoHero({
  videoSrc,
  posterSrc,
  posterAlt,
  runwayVh = 250,
  children,
}: ScrollVideoHeroProps) {
  const wrapperRef = useRef<HTMLDivElement>(null);
  const videoRef = useRef<HTMLVideoElement>(null);

  const { scrollYProgress } = useScroll({
    target: wrapperRef,
    offset: ['start start', 'end end'],
  });

  useMotionValueEvent(scrollYProgress, 'change', (v) => {
    const video = videoRef.current;
    if (video && video.duration && video.readyState >= 2) {
      video.currentTime = v * video.duration;
    }
  });

  return (
    <div ref={wrapperRef} className="relative" style={{ height: `${runwayVh}vh` }}>
      <div className="sticky top-0 h-screen w-full overflow-hidden">
        {/* Fallback image (base layer) */}
        <Image src={posterSrc} alt={posterAlt} fill className="object-cover" priority />

        {/* Video (on top of image) */}
        <video
          ref={videoRef}
          src={videoSrc}
          muted
          playsInline
          preload="auto"
          className="absolute inset-0 w-full h-full object-cover z-[1]"
        />

        {/* Overlay gradients (on top of video) */}
        <div className="absolute inset-0 z-[2] bg-gradient-to-r from-black/80 via-black/50 to-transparent" />
        <div className="absolute inset-0 z-[2] bg-gradient-to-t from-white via-transparent to-transparent" />

        {/* Content (highest layer) */}
        <div className="absolute inset-0 z-[3] flex items-center">
          {children}
        </div>
      </div>
    </div>
  );
}

Key architecture decisions

• Outer div height controls scroll runway. 250vh = ~2.5 screens of scrolling before release. Adjust based on video duration (longer video = more runway).
• sticky top-0 h-screen pins the visual hero to the viewport.
• Z-index layers: Image (base) → Video (z-1) → Gradients (z-2) → Text (z-3).
• readyState >= 2 check prevents errors before video data loads.
• preload="auto" ensures the video buffers ahead of scroll.
• Image as poster: The <Image> shows immediately while the video loads. Once the video has data, it paints over the image. No flash of empty content.
• Gradient overlays ensure text readability. Customize colors to match the page background for seamless blending at the bottom edge.

Customization

Mobile considerations

• playsInline is required for iOS (prevents fullscreen hijack)
• muted is required for autoplay policies
• 9:16 aspect fills mobile viewports naturally
• Consider reducing runwayVh on mobile (150-200vh) to avoid excessive scrolling