scroll-world-landing-pages

Fal Scroll-World Landing Pages

Build a landing page in which scroll scrubs a pre-rendered, continuous camera flight across a series of scenes. This skill uses the current Fal.ai equivalents of the original Scroll World video roster and uses Hermes image_generate for GPT Image 2 stills under the configured OpenAI subscription; it does not create real-time 3D. The scrub engine remains framework-agnostic vanilla JavaScript from the MIT upstream oso95/scroll-world project.

When to Use

• “Make a scroll-through world landing page.”
• “Turn this brand or value chain into a 3D diorama journey.”
• “Build an Apple-style scroll-scrubbed cinematic page.”
• “Create a continuous fly-through of our product, process, or place.”

Prerequisites

• A server-side Fal API key as FAL_KEY; never expose it in browser code.
• A virtual environment with the Fal Python client, installed through terminal: bash uv venv .venv && .venv/bin/pip install fal-client
• ffmpeg and ffprobe available through terminal.
• Clone the upstream engine/template through terminal when needed: bash git clone https://github.com/oso95/scroll-world.git
• For scene stills, use image_generate, not Fal’s openai/gpt-image-2 endpoint. Hermes is configured with gpt-image-2-medium, so these images are covered by the configured OpenAI subscription rather than consuming Fal credits.

How to Run

Use image_generate for cohesive scene stills. Invoke scripts/fal_i2v.py through the terminal tool for each Fal video clip; it uploads local frames to Fal CDN, calls the exact endpoint, waits for completion, and writes the resulting MP4. When featuring a real product, render its phone/UI state as a controlled DOM/canvas overlay or screen capture—not as generated video—and reserve a blank screen recess in the environment stills. Copy the upstream skills/scroll-world/references/scrub-engine.js into the target project using read_file and write_file. See references/transition-and-product-overlay-pattern.md.

Quick Reference

export FAL_KEY='…'
python3 /home/avalon/.hermes/skills/creative/scroll-world-landing-pages/scripts/fal_i2v.py \
  --model seedance --start assets/stills/farm.png --out assets/raw/farm.mp4 \
  --duration 8 --resolution 1080p --aspect-ratio 16:9 \
  --prompt "Single continuous cinematic camera move, no cuts. Begin high and far…"

ffmpeg -v error -sseof -0.15 -i assets/raw/farm.mp4 -frames:v 1 -q:v 2 assets/frames/farm-last.png
ffmpeg -v error -ss 0 -i assets/raw/shop.mp4 -frames:v 1 -q:v 2 assets/frames/shop-first.png
ffmpeg -v error -y -i src.mp4 -an -vf "unsharp=5:5:0.8:5:5:0.0" -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p -g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart out.mp4

Procedure

1. Collect the brief. Ask openly for subject, one-line pitch, brand name, 4–6 named palette hex values, tone, and an ordered 5–7 scene journey. Each scene needs id, label, subject, eyebrow, title, body, and up to three tags. Ask whether the user wants the mobile beta: it adds 720p/GOP-4 assets and must be described as a performance improvement, not a guarantee for low-end phones.

2. Generate and review stills directly. Reuse one art-direction preamble verbatim for every scene; the source default is a warm, isometric low-poly clay diorama on a plain solid background, centred with no text or logos. Use image_generate once per still with aspect_ratio="landscape". Preserve full-resolution PNGs as solid-background video inputs and posters. Review every still before video work; re-generate only off-style assets.

3. Choose the camera architecture. - A — continuous forward take: for a grounded walkthrough. Leg 0 begins from the first still; every later leg begins from the prior rendered leg’s actual last frame. Do not send an end frame. Each prompt must finish in a slow, steady forward drift. Render legs serially and set connectors: []. - B — dive plus aerial connector: only for miniature or map-like worlds. Every scene has a dive, and each pair is joined with a pull-up aerial connector. This deliberately reverses camera direction, so it is unsuitable for a first-person walkthrough.

4. Use a single Fal model for the chain. Default to seedance; use seedance-mini for a cheap seam-validating previz; use kling-v3-pro only as the documented same-roster alternative or for an individual moderation fallback. Pass --audio only if native audio is intentionally part of the deliverable; for scroll-scrub pages, leave it off and strip audio at encode. Use --bitrate-mode high only when quality justifies larger Fal output files.

5. Render architecture-A legs. Invoke the script via terminal. For the first clip, pass the first still as --start; for every later clip, extract the previous clip’s last frame and pass that as --start. Do not use --end. Inspect the last frame before generating the next leg; it must read as a calm forward continuation.

6. Frame-lock architecture-B seams. A connector’s endpoints must be pixels extracted from its neighboring rendered clips—not original diorama stills: bash ffmpeg -v error -sseof -0.15 -i dive_i.mp4 -frames:v 1 -q:v 2 dive_i_last.png ffmpeg -v error -ss 0 -i dive_next.mp4 -frames:v 1 -q:v 2 dive_next_first.png python3 /home/avalon/.hermes/skills/creative/scroll-world-landing-pages/scripts/fal_i2v.py \ --model seedance --start dive_i_last.png --end dive_next_first.png --out connector_i.mp4 \ --duration 5 --resolution 1080p --aspect-ratio 16:9 --prompt "Single continuous camera move, no cuts. Pull up and back out…" The required invariant is dive_i.end == connector.start and connector.end == dive_next.start. Use a short engine crossfade only as insurance.

7. Prove one transition before the paid full chain. Generate two dive clips plus one connector, then use terminal to concatenate them and extract a bounded contact sheet for vision_analyze. Exact rendered boundary frames are necessary but not sufficient: inspect the connector middle for invented objects, lighting shifts, or reversed velocity. If it fails direction twice, stop rerolling by default; omit that connector and use the engine's direct dive-to-dive crossfade through a shared aperture, doorway, screen recess, or rail. See references/transition-and-product-overlay-pattern.md.

8. Encode for scrubbing. Invoke the Quick Reference ffmpeg master command through terminal for every clip at its native source resolution. Do not default to all-intra video: the upstream engine fetches clips as Blob URLs, avoiding host byte-range limitations. For opted-in mobile variants, create 720p, GOP-4 siblings: bash ffmpeg -v error -y -i src.mp4 -an -vf "scale=-2:720,unsharp=5:5:0.6:5:5:0.0" -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p -g 4 -keyint_min 4 -sc_threshold 0 -movflags +faststart out-m.mp4

9. Integrate and configure the engine. Copy upstream scrub-engine.js and optionally its index-template.html with read_file / write_file, then mount it after the container exists: js mountScrollWorld(document.getElementById('world'), { brand: { name: 'BRAND', href: '#top' }, diveScroll: 1.3, connScroll: 0.9, sections: [{ id: 'farm', label: 'The Farms', still: 'assets/farm.webp', clip: 'assets/vid/farm.mp4', accent: '#8FB98A', eyebrow: '...', title: '...', body: '...', tags: [] }], connectors: [] }); For architecture B, connectors must be ordered and contain exactly sections.length - 1 entries. Add clipMobile and connectorsMobile only when mobile beta was selected.

10. QA the real page. Use browser_navigate, browser_scroll, browser_vision, and browser_console. Check frames immediately before and after every seam, console errors, video.seekable.end(0) > 0, reduced-motion behavior, and a phone viewport. For mobile beta, verify the -m.mp4 source loads and a fast scroll does not freeze.

Creative Reference

For a grounded pattern that combines generated environment video with real astrology-product screens, see references/astral-hermes-north-star-scroll-world.md. Use it whenever a scroll world must showcase Time Wave, a chart renderer, rulership-chain storytelling, or a North Star 3-style celestial instrument direction without hallucinated UI.

Pitfalls

• Using the wrong Fal field names: Seedance requires image_url; Kling V3 Pro requires start_image_url. Both use end_image_url for the last frame.
• A visible connector pop: its start/end frames came from stills or newly generated frames, not neighboring rendered clips.
• Rewind-like stutter: architecture B reverses velocity by design; use architecture A for grounded scenes.
• Seedance mini limits: it tops out at 720p and does not expose bitrate_mode.
• Kling V3 Pro differs from Seedance: it has no resolution or aspect_ratio inputs on this endpoint; do not send them.
• Video fixed at frame zero: retain the upstream Blob loader rather than relying on host range requests.
• Blank iOS frame: preserve the engine’s muted, playsinline, still poster, and first-gesture priming.
• Fal key exposure: use FAL_KEY only server-side or through terminal; never put it in the shipped client JavaScript.

Verification

Run python3 -m py_compile /home/avalon/.hermes/skills/creative/scroll-world-landing-pages/scripts/fal_i2v.py, then use browser_scroll on the deployed page and confirm in browser_console that no errors occur and every loaded video reports video.seekable.end(0) > 0.