DEV Community

Shawon Saha
Shawon Saha

Posted on

How to Generate Ultra-High-Resolution Video Contact Sheets with vcsi

#cli #python #tools

Video contact sheets—also known as thumbnail preview grids—are the fastest way to inspect footage, catalog archival video libraries, or share visual overviews without streaming or transferring multi-gigabyte media files. While media players like VLC or MPC-HC can generate basic thumbnail sheets, they often output heavily compressed, low-resolution files where small details, motion blur, and sharp subtitles turn into muddy artifacts.

vcsi (Video Contact Sheet Instruction) is a lightweight CLI utility powered by Python and FFmpeg that solves this issue. It allows you to produce crystal-clear, custom-dimensioned, publication-ready contact sheets directly from the command line.

1. Installation and Prerequisites

vcsi acts as a wrapper around FFmpeg and the Pillow imaging library. To run it on macOS or Linux, ensure you have FFmpeg and Python installed.

On macOS using Homebrew:

# Install FFmpeg
brew install ffmpeg

# Install vcsi via pip
pip3 install vcsi
Enter fullscreen mode Exit fullscreen mode

On Ubuntu or Debian:

sudo apt update
sudo apt install ffmpeg python3-pip
pip3 install vcsi
Enter fullscreen mode Exit fullscreen mode

Once installed, verify the setup by running:

vcsi --version
Enter fullscreen mode Exit fullscreen mode

2. Generating Ultra-High-Resolution Sheets

By default, vcsi restricts image output to a fixed width of 1500 pixels. Across a 4×4 grid of a 4K file, each individual frame shrinks to roughly 375 pixels wide, losing fine textures. You can override this using either custom canvas scaling or true 1:1 pixel rendering.

Method A: Fixed 4K or 8K Canvas Output

If you need uniform file dimensions for web uploads, image hosting, or documentation, explicitly specify the canvas width using -w:

# 4K preview sheet (3840px wide)
vcsi "source_video.mp4" -g 4x4 -w 3840 -a --quality 100 -o "preview_4k.jpg"

# 8K preview sheet (7680px wide)
vcsi "source_video.mp4" -g 4x4 -w 7680 -a --quality 100 -o "preview_8k.jpg"
Enter fullscreen mode Exit fullscreen mode
  • -g 4x4: Generates a grid with 4 columns and 4 rows (16 captures total).
  • -w 3840: Forces the horizontal canvas width to 3840 pixels while maintaining aspect ratio.
  • -a / --accurate: Forces FFmpeg to decode exact target timestamps rather than snapping to the nearest I-frame, eliminating gray blocks and decoding artifacts on modern HEVC/AV1 footage.
  • --quality 100: Disables aggressive JPEG compression.

Method B: Native 1:1 Source Resolution

For master archives, studio delivery, or high-fidelity technical reviews, use the -S flag to bypass all scaling:

vcsi "source_video.mp4" -g 3x4 -S -a -f png -o "preview_native.png"
Enter fullscreen mode Exit fullscreen mode
  • -S / --actual-size: Each thumbnail inside the sheet renders at the native pixel resolution of the source video. A 3×4 grid of a 1080p source outputs an uncompressed composite over 5,700 pixels wide.
  • -f png: Employs lossless PNG output rather than lossy JPEG compression.

3. Formatting Typography for Hi-DPI Displays

When scaling canvas dimensions up to 4K or 8K, default headers and timestamp overlays will appear microscopic. vcsi allows you to scale metadata typography independently to match higher resolutions:

vcsi "source_video.mp4" \
  -g 4x4 \
  -w 3840 \
  -a \
  --metadata-font-size 28 \
  --timestamp-font-size 22 \
  --timestamp-border-size 2 \
  --grid-spacing 12 \
  -o "preview_styled.jpg"
Enter fullscreen mode Exit fullscreen mode
  • --metadata-font-size: Scales the top header block containing the filename, duration, audio/video codecs, and container details.
  • --timestamp-font-size: Enlarges the timecode stamped into the lower corner of each frame.
  • --grid-spacing: Adds padding (in pixels) between grid tiles to prevent adjacent frames from visually running together.

4. Automating Batch Processing Across a Directory

Generating contact sheets for an entire folder of video files takes just a standard shell loop:

#!/usr/bin/env bash

# Loop through all MP4 and MKV files in the current folder
for file in *.{mp4,mkv}; do
  # Skip loop if no matching files exist
  [ -e "$file" ] || continue

  echo "Processing: $file"
  vcsi "$file" \
    -g 4x4 \
    -w 3840 \
    -a \
    --metadata-font-size 26 \
    --timestamp-font-size 20 \
    -o "${file%.*}_contact_sheet.jpg"
done
Enter fullscreen mode Exit fullscreen mode

Pairing vcsi with FFmpeg delivers total control over video preview workflows, from single-frame precision to pixel-perfect high-DPI sheets that look razor-sharp on any monitor.

Top comments (0)