Pre-encoding with the CLI

Prepare videos before you deploy, so every visitor gets smooth scrubbing on the first visit.

vidscroll encode turns any video into one that scrubs smoothly: keyframes close together, a sensible size for the web, no audio. Run it once before you deploy, and visitors skip the in-browser re-encode entirely. Not sure whether a file needs it? The video checker tells you.

Set it up

The command uses ffmpeg, the standard command-line video tool. vidscroll doesn’t bundle it because it’s a large native program, so you provide it. The ffmpeg-static package is the easiest way; it’s only used on your machine or in CI, never shipped to visitors.

Get ffmpeg. Skip this if ffmpeg already works in your terminal.
```
npm install -D ffmpeg-static
```
```
pnpm add -D ffmpeg-static
```
```
yarn add -D ffmpeg-static
```
```
bun add -d ffmpeg-static
```

Encode the video.

Terminal

npx vidscroll encode public/videos/hero.mp4

It prints a summary when it’s done:

Terminal

public/videos/hero.scroll.mp4  11.9MB (input 4.7MB), keyframe every 10 frames

Point src at the new file.

Hero.tsx

<ScrollVideo src="/videos/hero.scroll.mp4" length="400vh" />

vidscroll finds ffmpeg in this order: the FFMPEG_PATH environment variable, then the ffmpeg-static package, then ffmpeg on your PATH.

Options

Terminal

npx vidscroll encode <input> [output] [options]

Option	Default	What it does
`[output]`	input name + `.scroll.mp4`	Where to write the result. `hero.mov` becomes `hero.scroll.mp4`. An existing file is overwritten.
`–resolution <px>`	`720`	Short side of the output. Smaller videos are never enlarged.
`–gop <frames>`	`10`	Frames between keyframes. Lower is smoother to scrub and bigger.
`–crf <n>`	`22`	Quality: lower is better and bigger. 18 to 28 is the useful range.
`–fps <n>`	source rate	Frame rate cap. Faster sources are reduced; slower ones keep their rate.
`-h`, `–help`		Show the help.

Write options with a space before the value (--resolution 1080), not with =.

Choosing settings

The defaults suit most pages. Two things are worth adjusting:

Resolution. 720 keeps files small and looks fine on phones and in smaller layouts. Use --resolution 1080 when the video fills large screens and detail matters; expect roughly twice the file size.
Keyframe spacing. The gap between keyframes is gop divided by the frame rate: 10 frames at 30 fps is a third of a second. vidscroll accepts gaps up to 0.5 s without re-encoding in the browser.

Size

Close keyframes make files larger than a normal export. For a 60-second clip:

File	Size
Original export, 1080p	4.7 MB
`vidscroll encode`	11.9 MB
`vidscroll encode –resolution 1080`	22.4 MB

To bring the size down: shorten the clip, lower --resolution, or raise --crf a little. Keep the keyframe spacing.

In a build step

Encoding is fast enough to run in CI. Add a script and run it before building the site:

package.json

{
  "scripts": {
    "videos": "vidscroll encode videos/hero.mp4 public/videos/hero.scroll.mp4"
  }
}

With ffmpeg-static in devDependencies, the same command works on any machine without installing ffmpeg separately.