finder-video-thumbnails

Generate macOS Finder thumbnails for video files that don't have one, using ffmpeg and fileicon.

By default, video files in Finder show a generic icon (or a low-res QuickLook preview that disappears when you scroll away). This tool grabs a frame from each video and sets it as a permanent custom Finder icon — so the thumbnails are always visible, in any view, with the natural aspect ratio preserved.

Requirements

• macOS (uses fileicon which sets com.apple.FinderInfo xattr — won't work on Linux/Windows)
• ffmpeg — brew install ffmpeg
• fileicon — brew install fileicon

Install

npm install -g @joaodotwork/finder-video-thumbnails

Or run without installing:

npx @joaodotwork/finder-video-thumbnails <folder>

Usage

finder-video-thumbnails [options] <folder> [seek_seconds]

Arguments

• <folder> — folder to process (recursive)
• seek_seconds — timestamp (in seconds) to grab the frame from. Defaults to 1

Options

• -h, --help — show help and exit
• -V, --version — print version and exit
• --force — re-generate icons even if a custom icon is already set

Examples

Add thumbnails to every video in ~/Movies (recursive):

finder-video-thumbnails ~/Movies

Grab the frame at the 5-second mark:

finder-video-thumbnails ~/Movies 5

Re-generate all thumbnails, overwriting existing ones:

finder-video-thumbnails --force ~/Movies

Supported formats

.mov, .mp4, .m4v, .avi, .mkv, .webm (case-insensitive)

How it works

For each video without a custom icon:

1. ffmpeg extracts a single frame at the seek timestamp.
2. The frame is scaled to fit a 512×512 box, preserving aspect ratio, then padded to a square with a transparent background. This ensures Finder displays the thumbnail with the video's natural aspect ratio rather than stretching it.
3. fileicon writes the resulting PNG as the file's custom Finder icon.

Re-runs are idempotent: files that already have a custom icon are skipped unless --force is passed.

License

MIT