Preview Sheets

// the problem

A directory full of long videos is opaque. Shared drives, archives, asset managers, QC queues — anywhere someone needs to know what’s in this file before committing to opening it, the answer that actually works is an image: a preview sheet. Frames sampled across the runtime, tiled into a grid, with the file’s vitals — duration, resolution, codec, size — in a pane up top. Serving one image beats streaming one video, every time.

Like trickplay, none of this is deep magic — it’s glue: probing, grid math, header compositing, per-file naming. The convenience is one CLI and one widely shared template that carries all of it.

// the template

@m0saic/media/screencap_grid/v2 renders the whole sheet as one validated layout: an ffprobe info pane (filename, duration, bitrate, streams), a rows × cols grid where every tile is an exact seek wearing its own timestamp chip, and pixel-exact gaps at any canvas size. Knobs for the details — timestamp corner and colors, cover vs contain, gap width, pane alignment — and one outputFormat knob that flips the deliverable: png is a static contact sheet, mp4 is an animated grid where every tile plays from its own timestamp.

// aspect safe — both orientations, one render

A desktop catalog page wants a wide sheet; a phone gallery wants a tall one. @m0saic/media/screencap_grid_aspect_safe/v1 emits both from one invocation — a landscape and a portrait deliverable per source. You declare the cell shape you want (landscape, square, portrait, or an exact ratio) and the template searches grid factorizations for the pair whose cells match it on both canvases — gridChoice pages through the ranked alternatives if you want a different density.

// batch

The source knob takes a file, many files, or a folder. More than one input and the template fans out into a multi-output pipeline — one render invocation, one sheet per title, named after each file, and one unreadable file never kills the batch. The aspect-safe variant does the same with two outputs per source. That is the whole library-preview workflow: point --input-dir at the collection and collect the sheets.

// custom grids

The generated rows × cols grid is the default, not the limit. The customGrid escape hatch takes an m0 layout string and binds one tile — with its timestamp — to each cell, in document order. Size a cell bigger and that moment gets emphasis; the gaps stay exact and the string is validated before anything renders:

# a hero cell up top, a filmstrip row beneath
"advanced": { "customGrid": "2(3(F,F,F),3(F,>,F))" }

Because the layout is just an m0 string, a custom sheet design is shareable the same way the template is — paste it, render it, get the identical sheet.

// 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.

// read the source

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