case 01

Trickplay

The scrub-preview thumbnails every video platform ships — as one command.

// the problem

The thumbnails a player shows while you scrub. Every serious video platform ships them: a sprite sheet of frames sampled at a fixed interval, plus an index that maps each moment on the timeline to a rectangle in the sheet. Hover the bar, the player slices the rect, you see where you’re going.

Generating them isn’t hard — it’s fiddly. Duration probing, sheet-capacity math, per-thumb xywh bookkeeping, the manifest conventions your player expects, batch, naming. The kind of glue everyone writes once and then maintains forever. The convenience is having it as one CLI and one widely shared template.

what trickplay does — this mock was itself rendered by m0saic

// the template

One command, one output set per video in the folder: numbered sprite sheets, a WebVTT storyboard (the format Video.js, JW Player, Bitmovin and hls.js UIs read), and a JSON manifest carrying Jellyfin-compatible fields and DASH-IF thumbnail_tile grid info. Every thumbnail is an exact per-frame seek — no sampling drift — because each cell of the sheet is its own addressed rectangle with its own timestamp.

A real trickplay sprite sheet of Big Buck Bunny — 20 thumbnails at 24-second intervals in a 5×4 grid

real output — Big Buck Bunny, 20 thumbs @ 24s, one 5×4 sheet1600 × 720 png

WEBVTT

00:00:00.000 --> 00:00:24.000
trickplay-bbb__sheet_01.png#xywh=0,0,320,180

00:00:24.000 --> 00:00:48.000
trickplay-bbb__sheet_01.png#xywh=320,0,320,180
...

{
  "thumbnailCount": 20,
  "intervalMs": 24000,
  "tileWidth": 320, "tileHeight": 180,
  "jellyfin": { "Width": 320, "Height": 180, "TileWidth": 5,
                "TileHeight": 4, "ThumbnailCount": 20, "Interval": 24000 },
  "dashIf":   { "schemeIdUri": "http://dashif.org/guidelines/thumbnail_tile",
                "value": "5x4" }
}

Long movie? Sheets number themselves and the index spans them. Whole library? Point --input-dir at the folder — one sheet set per title, one bad file never kills the batch. Want an animated contact-sheet preview instead? Same template, one knob (outputFormat: mp4). And because the template is a typed, unit-tested program, the layout is validated before anything renders — mistakes fail loudly instead of quietly in your player.

// run it yourself

One command, straight from a terminal. The CLI carries the template, the engine, and the validator — if the layout can’t render correctly, it fails before a single frame is written.

npx m0saic make @m0saic/media/trickplay/v1 --input-dir ./library -o trickplay.png

// read the source

The template behind this study is @m0saic/media/trickplay/v1 — a typed, unit-tested program, not a script. The template library is headed for open release; the m0saic source lives on GitHub.