ericrisco/rsc-harness / skills/scroll-film
scroll-film
VerifiedUse when a page's hero is a pre-rendered camera flight the visitor scrubs by scrolling, Apple-style: AI clips chained frame to frame so seams never pop, encoded for seeking, mounted with an engine that holds up on phones. NOT scroll reveals or pinning (that is `design`), NOT a finished MP4 (that is `ai-media`).
scroll-film — the camera moves, the scroll is the playhead
The page plays nothing. It holds a chain of pre-rendered clips and maps the scroll position to their playhead, so the visitor flies through scenes — outside a building, inside it, on to the next — without a cut. Three parts must be right, and each fails in its own way: the chain (seams), the encode (seeking) and the page (phones). This skill owns all three.
Not this skill — delegate:
- Scroll-linked reveals, parallax, pinned sections, a horizontal pan, with no video →
../design/SKILL.md. - A finished MP4 with voice and music →
../ai-media/SKILL.md. - The call to the model endpoint (queue, webhooks, cost per call) →
../fal/SKILL.mdor../replicate/SKILL.md. - The scene stills themselves →
../replicate-images/SKILL.md. - The words over the film →
../landing-copy/SKILL.md. A video rendered from code →../remotion-video/SKILL.md.
1. The gate: nothing renders before the user agrees to a number
A chain is many clips, each one slow and billed. Interview, price it, then wait for a yes.
- Subject. Ask it as an open question: what the world is about, in a sentence. A menu of industries decides their business for them.
- Scenes. 4 to 7, in the order the camera visits them, proposed from their own value chain and edited by them. The last one carries the call to action.
- Look. One art direction, written once as a style preamble and pasted unchanged into every still prompt. Identical text is what makes separate renders read as one world.
- Camera feel. Always ask. It picks the chain shape (section 3).
- Phones. Always ask. A real phone version is a second chain (section 6) and doubles the video bill.
- Brand. 4 to 6 hex colours, a name, a tone. The page background is the scene background.
Then the bill:
| Forward take (A) | Dive and hop (B) | |
|---|---|---|
| Video clips, desktop only | N | 2N − 1 |
| Video clips, with the phone chain | 2N | 4N − 2 |
Estimate = clips × seconds per clip × today's price per second, plus about 20% for re-rolls, plus N
stills. Read the price from the provider at build time; it moves (reading cost per call →
../fal/SKILL.md). State the total against the balance and wait for the yes. When money is tight,
offer a previz pass: the whole chain on the same model at its lowest resolution, approve the
journey, then render the finals.
2. The model must continue a shot, not just start one
A seam holds only if the model starts a clip on an exact frame you hand it. That capability, not quality or price, qualifies a model.
- Every clip needs a start-frame input. Hops (shape B) also need an end-frame input. Field
names vary by endpoint (
image_url,start_image,first_frame;end_image_url,tail_image_url,last_frame): read the input schema before batching. Model landscape →../ai-media/SKILL.md. - A reference-image input does not qualify. It steers the style; frame 0 is still a new render, and the seam pops.
- Probe once before the batch, with one cheap clip from a real still prepared at the clip's
aspect (16:9, or 9:16 for phones). Frame 0 must match the still and the bill must match the
advertised price. For hop duty, add an end frame from another still: the last frame must land on
that composition. A near miss is normal; the engine's dissolve covers it. Commands →
references/chain.md. - One model for the whole chain. Each model has its own grain, colour and motion; a swap
mid-chain keeps positions continuous and still pops. The one exception is a single clip a content
filter keeps blocking (
references/chain.md).
3. Pick the chain shape from the camera feel
| The user says | Shape | Clip k starts on | Clip k ends on | Fits |
|---|---|---|---|---|
| "one continuous walkthrough", "one fixed angle gliding over it" | A — forward take | leg k−1's real last frame (leg 0: the first still) | nothing — no end frame | photoreal, interiors, product, real estate |
| "fly from one island to the next" | B — dive and hop | dive: its still. hop: dive k's real last frame | hop: dive k+1's real first frame | miniature, diorama, map-like worlds |
- A renders one leg at a time, because each needs the previous one's last frame. B renders every dive in parallel, then every hop.
- Never give an A leg a wide establishing shot as its end frame. The camera pulls back to meet it, and the take reverses.
- The velocity rule. Inside one clip the camera is free: orbit, rise, push in and ease back. Across a seam it never reverses. Position matches, the motion flips, and it reads as a rewind, in both scroll directions. So every leg ends by settling into a slow forward drift, and the next one begins inside it. B reverses at every seam on purpose (pull out, hop, dive): charming over a miniature map, a stutter in a realistic walkthrough. If the user picks B for a photoreal look, say so before rendering.
Prompt templates (still, leg, dive, hop), the camera-move table by concept, the fixed-angle clause
and the batch loops → references/chain.md.
4. The seam law: hand off pixels, not descriptions
Every render redraws its scene a little differently. A hop that ends on the original still of scene 3 meets a dive that starts on its own render of scene 3: two pictures of one place, and the seam pops. So both ends of every clip come from the neighbours' actual renders.
# The true last frame: -update 1 overwrites per decoded frame, so the final one is what stays.
ffmpeg -v error -y -sseof -1 -i leg_02.mp4 -update 1 -q:v 2 leg_02_last.png
ffmpeg -v error -y -i dive_03.mp4 -frames:v 1 -q:v 2 dive_03_first.png
A plain -sseof -0.15 -frames:v 1 stops a few frames short of the end: 15 dB PSNR from the real
last frame on a 24 fps test clip. The engine parks the outgoing clip on its real last frame, so a
handoff from the earlier one starts the seam already off.
- Look at each last frame before chaining the next clip. In A, one bad handoff poisons every leg after it: re-roll that leg.
- The engine dissolves over a tenth of a viewport at each seam. That hides an end frame that landed close. It cannot hide a different picture.
5. Encode for seeking, not for playback
Scrubbing seeks on every frame, and each seek decodes every frame since the last keyframe. The keyframe interval sets how smooth the scrub feels.
# Desktop: native resolution (never upscale), a keyframe every 8 frames, no audio, index first.
ffmpeg -i leg_01.mp4 -an -c:v libx264 -preset slow -crf 20 -pix_fmt yuv420p \
-g 8 -keyint_min 8 -sc_threshold 0 -movflags +faststart assets/vid/shot-01.mp4
# Phone: 720 wide, a keyframe every 4 frames; a phone decoder pays more per frame.
ffmpeg -i leg_01_portrait.mp4 -an -vf scale=720:-2 -c:v libx264 -preset slow -crf 23 -pix_fmt yuv420p \
-g 4 -keyint_min 4 -sc_threshold 0 -movflags +faststart assets/vid/shot-01-m.mp4
# Poster: the clip's first frame. It is the LCP image and the reduced-motion fallback.
ffmpeg -v error -i assets/vid/shot-01.mp4 -frames:v 1 -c:v libwebp -quality 82 assets/shot-01.webp
One recipe for every clip in the chain. All-intra (-g 1) is the last resort for a low-end phone
that still stutters, at about three times the size.
6. Phones get their own chain, not a crop
A 16:9 film on a portrait phone shows its middle quarter. When the user asked for phones, render
the chain again at 9:16, frame-locked to its own renders. A landscape frame inside the portrait
chain pops on both sides. Start images: each still composited onto a 1080×1920 canvas in the page
background colour. The encodes are the -m.mp4 files above, and each portrait clip's first frame is
its posterMobile.
No budget for it: the engine crops the landscape film with object-fit: cover, steered by
--film-focus. Tell the user this is a stopgap. Never ship it as "the mobile version".
7. Mount the page
Copy assets/scrub-engine.js and assets/page-template.html into the project. The template is a
working page: its copy is real HTML that reads without JavaScript, and the script moves it onto the
film once the engine mounts.
const film = ScrollFilm.mount(document.getElementById('film'), {
shots: [
{ section: 0, src: 'assets/vid/shot-01.mp4', srcMobile: 'assets/vid/shot-01-m.mp4',
poster: 'assets/shot-01.webp', posterMobile: 'assets/shot-01-m.webp', length: 1.4, hold: 0.4 },
{ section: 0, src: 'assets/vid/hop-01.mp4', poster: 'assets/hop-01.webp', length: 0.9 },
// one entry per clip, in chain order
],
onChange: ({ section, sectionProgress }) => { /* fade the copy block for `section` */ },
});
What the engine does, and the failure each part prevents:
- Loads each clip as a Blob. On a host that ignores byte-range requests, a streamed
<video>reportsseekableas [0, 0] and every seek lands on frame 0. A Blob is always seekable. - Keeps one seek in flight per clip. Queued seeks are what freeze a phone on a fast flick.
- Keeps the poster up until a frame has painted, and primes each clip with a muted play and pause, again on the first touch. iOS paints nothing for a seeked video that never played.
- Picks phone sources at mount, ignores height-only resizes on touch (the URL bar sliding), and re-lays out on rotation.
- Reduced motion or Save-Data: no video is fetched; posters dissolve with the scroll and the copy still works.
- Fetches a clip once, when the scroll comes within 1.5 viewports of it.
destroy()removes everything it added. Call it from the effect cleanup in React or Vue.
design bans raw scroll listeners for animation. This one is passive and only requests a frame. If
the page already owns a scroll source (ScrollTrigger, useScroll), pass listen: false and call
film.update() from it. All options, the state object, theming, pacing and the Next.js and Vue
wiring → references/engine.md.
The film layer is aria-hidden; the meaning lives in the copy. Its words → ../landing-copy/SKILL.md.
Its type, colour and spacing → ../design/SKILL.md.
8. Verify before calling it done
-
The chain, by script. Pass the clips in chain order:
bash <skill-dir>/scripts/verify.sh --frames qa/seams \ assets/vid/shot-01.mp4 assets/vid/hop-01.mp4 assets/vid/shot-02.mp4 bash <skill-dir>/scripts/verify.sh --gop 4 --portrait \ assets/vid/shot-01-m.mp4 assets/vid/hop-01-m.mp4 assets/vid/shot-02-m.mp4It checks each clip's encode (H.264, yuv420p, no audio, index first, keyframe interval), that the chain shares one size and frame rate, and scores every seam against the clips' own frame-to-frame step. A fixed SSIM threshold cannot tell: on a soft landscape photo, a cut to a different picture still scored 0.76 and a fresh render of the same scene 0.92. Measured against the step (0.98 there), the frame-locked seam passed at 0.987 and both others were flagged. Open every flagged pair in
qa/seams/and judge by what you see: a wrong seam shows different objects. -
In a browser. Scroll slowly across each seam on desktop. Then emulate a phone at 4 to 6× CPU throttle and flick fast. Turn reduced motion on: posters only. In the Network panel, the phone gets the
-m.mp4files and the desktop gets the masters. -
On a real iPhone, if phones shipped: the first scene shows at once and no scene goes blank.
Anti-patterns
| Failure mode | Usually | Fix |
|---|---|---|
| A visible pop at one seam | The hop's end frame was the original still, or came from -sseof a few frames early | Extract the true frames from the neighbouring renders (section 4) |
| The camera seems to rewind at every seam | Velocity reverses across the seam: B in a realistic walkthrough, or an A leg given a wide end frame | Shape A with the settle-into-drift clauses and no end frame |
| Stuck on the first frame in production, fine locally | The host ignores byte ranges | Load as Blob; keep it when porting the engine to a framework |
| A phone freezes on a fast flick | A 1080p, 8-frame-GOP master on a phone decoder, plus queued seeks | -m.mp4 encodes at GOP 4; keep one seek in flight |
| Black scenes on iPhone until the first touch | The poster was hidden on loadedmetadata, or muted/playsinline lost in a port | Keep the poster until a frame paints; keep both attributes |
| The film scrolls away instead of sticking | An ancestor has overflow: hidden, often body { overflow-x: hidden } | overflow-x: clip |
| A cheaper model "just for the hops" | Each model renders its own grain and motion | One model for the chain; previz on the same model at low resolution |
| A content filter blocks a harmless interior | Words like bed, pool, spa or wine in the prompt | Re-roll, neutral wording, then the remedies in references/chain.md |
Orientación (siempre)
Habla con la voz de orient: frases cortas, una idea por frase, y cada respuesta se entiende sola. Registro técnico o con analogías según technical_level en 02-DOCS/wiki/harness/user-profile.md. Cierra cada turno con el bloque-brújula (📍 dónde estás · ➡️ siguiente, terminando en pregunta; ✅ y 🧭 cuando hay algo hecho o decidido). Nunca termines en seco. Protocolo completo: skill orient → skills/orient/references/orientation-contract.md. (Defiere a suggest el "¿instalo la skill que falta?".)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |