gifgrep sheet

Sample N frames from a GIF and lay them out as a single PNG contact sheet. Local files or URLs, no provider key needed.

gifgrep sheet <gif> [--frames N] [--cols N] [--padding px] [-o <file>|-]

#Examples

gifgrep sheet cat.gif -o sheet.png
gifgrep sheet cat.gif --frames 16 --cols 4 --padding 4 -o sheet.png
gifgrep sheet https://example.com/cat.gif --frames 9 --cols 3 -o - > sheet.png
gifgrep sheet cat.gif --frames 12 -o sheet.png --reveal

#Flags

--frames <N>          frames to sample (default 12)
--cols <N>            columns; 0 = auto (default 0)
--padding <px>        pixels of padding between frames (default 2)
-o, --output <file>   output path (default: sheet.png), '-' for stdout
--reveal              open the result in Finder/Explorer after writing

#How sampling works

Frames are sampled at evenly-spaced timestamps across the GIF's full duration. If you ask for more frames than the GIF actually has, you get every frame (no duplication, no resampling).

Sampling preserves positive source delays, including pauses longer than one second. A zero delay uses the decoder's 80 ms default.

--cols 0 (the default) picks a column count that yields a roughly square grid; otherwise the layout is cols × ceil(frames / cols).

Output is limited to 40 million pixels. Dimensions or padding that overflow or exceed that budget return an error before allocating the sheet.

Encoded input is limited to 20 MiB. Local files and HTTP responses are checked while reading, including responses without a content length.

#Writing to stdout

gifgrep sheet cat.gif --frames 9 --cols 3 -o - > sheet.png
gifgrep sheet cat.gif -o - | pngquant - > sheet-small.png

In stdout mode, progress and warnings go to stderr.

#Pairs well with

• still when you want a single frame at a known timestamp.
• search + --download to grab the GIF first, then sheet it.

gifgrep cats --download --max 1 --format url
gifgrep sheet ~/Downloads/cat-typing.gif --frames 12 --cols 4 -o sheet.png