Movie Thumbnailer (mtn) Setup: Installation, Options, and TroubleshootingMovie Thumbnailer (mtn) is a lightweight command-line tool for generating thumbnails and contact sheets from video files. It supports many video formats, offers flexible selection and layout options, and can be easily integrated into scripts and media workflows. This article walks through installation, common options, usage examples, and troubleshooting tips to help you get the most from mtn.
Overview and use cases
Movie Thumbnailer extracts frames from videos to produce:
- Single thumbnails at a specific time or percentage.
- Multiple evenly spaced thumbnails.
- Contact sheets (grids of thumbnails).
- Animated GIF previews (via additional tools).
Common use cases:
- Generating preview images for media libraries or web galleries.
- Creating storyboards for video editing.
- Automated batch generation of thumbnails for streaming/media servers.
Installation
Linux (Debian/Ubuntu)
On Debian-based systems, mtn is often available in the package repositories:
sudo apt update sudo apt install mtn If you need a newer version or it’s not available, compile from source (see “Build from source”).
Fedora / CentOS / RHEL
On Fedora:
sudo dnf install mtn On CentOS/RHEL, use EPEL if available:
sudo yum install epel-release sudo yum install mtn macOS
Using Homebrew:
brew install mtn Windows
mtn is primarily a Unix-style tool. On Windows you can:
- Use WSL (Windows Subsystem for Linux) and install via the Linux instructions.
- Or build with MSYS2 / MinGW environments if experienced with those toolchains.
Build from source
- Install dependencies: a C/C++ compiler, pkg-config, libav/ffmpeg development headers (or libavformat/libavcodec), and optional libraries (libpng, libjpeg, libexif).
- Clone and build:
git clone https://github.com/bruhautomation/mtn.git cd mtn ./autogen.sh ./configure make sudo make installAdjust configure flags if libraries live in nonstandard paths.
Basic usage
The simplest command extracts a single thumbnail:
mtn -i input.mp4 -o thumbnail.jpg Key flags:
- -i, –input
: input video file (use ‘-’ for stdin). - -o, –output
- -s, –size
: max width or height (preserves aspect ratio). Example: -s 320×240 or -s 320. - -t, –time
- -n, –number
: number of thumbnails to create. - -w, –width and -h, –height: explicit dimensions (use with caution).
- -f, –format
: output image format (jpeg, png).
Example — generate 9 thumbnails evenly spaced:
mtn -i movie.mkv -n 9 -o thumbs_dir Example — single thumbnail at 25% into the video:
mtn -i movie.mp4 -t 25% -o thumb.jpg Contact sheets and layout options
mtn can create tiled contact sheets with rows and columns:
- -c, –columns
: number of columns in a contact sheet. - -r, –rows
: number of rows. - -g, –gap
: gap between thumbnails. - –title: add file title text.
- –font and –fontsize: control text appearance (requires freetype support).
Example — 4×3 contact sheet with gaps:
mtn -i movie.mp4 -n 12 -c 4 -r 3 -g 10 -o contact.jpg If you specify only -c or -r, mtn will calculate the other dimension based on -n.
Time selection strategies
Choosing where to capture frames matters for representativeness and avoiding black frames.
- Even spacing (-n): good default for overview.
- Percentages (-t 5%..95%): avoid exact start/end points that may be black or logo screens.
- Range and increment: use -t with ranges if supported by your version or script time points externally and supply multiple -t values.
- Skip black frames: mtn itself may not reliably detect black; combine with ffprobe/ffmpeg filters to find non-black timestamps, then call mtn with specific times.
Example using ffmpeg to find a frame at a non-black time (workflow example):
- Use ffmpeg to detect scene changes or non-black frames.
- Pass timestamps to mtn for thumbnail generation.
Image quality and encoding
- Use -f jpeg for JPEG output and control quality via –quality or equivalent if supported; older mtn versions use default libjpeg settings.
- PNG output ensures lossless images: -f png.
- If you need finer control (subsampling, progressive), use ffmpeg to extract frames and then process with imagemagick or jpegoptim.
Batch processing and scripting
Generate thumbnails for many files:
for f in *.mp4; do mkdir -p thumbs/"${f%.*}" mtn -i "$f" -n 9 -o thumbs/"${f%.*}" done Or parallelize using GNU parallel:
ls *.mkv | parallel mtn -i {} -n 9 -o thumbs/{.} For media server integration (Plex, Emby), produce thumbnails using naming conventions those systems expect.
Common problems and troubleshooting
Problem: mtn fails with “cannot open input” or no frames extracted
- Verify input path and permissions.
- Check that mtn was built with proper ffmpeg/libav support. Run
mtn -vor check configure output. - Try extracting a frame with ffmpeg to confirm the file is readable:
ffmpeg -i input.mp4 -ss 00:00:10 -vframes 1 out.jpg
Problem: black thumbnails or thumbnails of the first frame (logo/black screen)
- Skip start/end points: use -t with percentages that avoid 0%/100%.
- Detect and skip black frames using ffmpeg’s blackdetect filter, then feed good timestamps to mtn.
Problem: missing fonts or title text doesn’t render
- Ensure freetype development support was available at build time.
- Install font packages or specify –font with a full path.
Problem: output quality or wrong dimensions
- Use explicit -s, -w/-h flags.
- Remember aspect ratio preservation: providing only width (-s 320) scales height automatically.
- If using post-processing tools, check their options for resampling/filtering.
Problem: performance slow or high CPU usage
- mtn decodes video frames — performance depends on codec, resolution, and CPU.
- Reduce decode cost: scale down with -s or pre-transcode lower-resolution copies.
- Run jobs in parallel carefully; avoid saturating disk I/O.
Advanced workflows
- Integrate with ffmpeg filters to select frames (scene detection) and then create thumbnails from those timestamps.
- Create animated GIF previews by extracting frames with mtn or ffmpeg and assembling with ffmpeg/imagemagick.
- Use thumbnails as part of static web galleries, embedding contact sheets or generated sprite sheets for fast preview scrubbing.
Example commands — quick reference
Single thumbnail at 30 seconds:
mtn -i input.mp4 -t 30 -o thumb.jpg Nine thumbnails evenly spaced, max width 320:
mtn -i input.mp4 -n 9 -s 320 -o thumbs_dir 4×3 contact sheet with title and gap:
mtn -i movie.mp4 -n 12 -c 4 -r 3 -g 8 --title "My Movie" -o contact.jpg Batch for directory of movies:
for f in *.mp4; do mtn -i "$f" -n 9 -s 320 -o thumbs/"${f%.*}"; done Useful alternatives and complementary tools
- ffmpeg: more control over frame extraction, filters, and encoding.
- mpv/mpv-tools or ffprobe: to inspect files and detect keyframes or scene changes.
- imagemagick: post-process thumbnails (resize, annotate).
- scene-detection scripts: for more intelligent thumbnail placement.
| Tool | Strength |
|---|---|
| mtn | Quick, purpose-built thumbnail/contact-sheet generation |
| ffmpeg | Full control over extraction and filtering |
| imagemagick | Advanced image processing |
| ffprobe/mpv | Metadata and frame inspection |
Summary
Movie Thumbnailer (mtn) is an efficient tool for generating thumbnails and contact sheets for videos. Install from your distribution or build from source if needed, use -n/-t/-s/-c/-r to control output, and combine with ffmpeg/imagemagick for advanced selection and processing. When troubleshooting, verify dependencies, check input readability, and avoid start/end black frames by choosing appropriate timestamps.
If you want, tell me your OS and example file and I’ll give exact install/build commands and a tailored command for your needs.