A Python application that processes video files, extracts screenshots at evenly spaced intervals, and assembles them into grid images with optional metadata labels.
ScreenMachine functions similarly to AMT Auto Movie Thumbnailer, but is 30x as fast for generating screenshots. This is the result of advanced seeking optimizations allowed by FFmpeg.
ScreenMachine functions optimally over the network, with spinning hard drives, and with NVME/SSD, seeking frames dynamically to reduce read strain and CPU consumption as much as possible.
Adjust the number of worker threads for your use case.
- Recursively processes all videos in a selected directory and subdirectories
- Extracts screenshots at calculated intervals based on video length
- Assembles screenshots into a customizable grid layout (rows × columns)
- Resizes screenshots to fit within specified maximum dimensions
- Adds optional metadata labels (title, resolution, file size, duration, codec)
- Configurable JPG quality/compression
- Option to overwrite existing images or skip them
- Modern GUI built with customtkinter
- MP4
- AVI
- WMV
- MKV
- MOV
- M4V
- WEBM
- Python 3.8 or higher
- FFmpeg (installed on system or will be auto-downloaded on Windows)
- See
requirements.txtfor Python dependencies
-
Clone or download this repository
-
Install dependencies:
Windows:
pip install -r requirements.txt
FFmpeg will be auto-downloaded on first run if not found in PATH.
Linux:
# Install system packages sudo apt-get install python3-tk python3-dev ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev # Install Python dependencies pip3 install -r requirements.txt
python main.py# Install dependencies first (if not already installed)
sudo apt-get install python3-tk python3-dev ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
# Install Python dependencies
pip3 install -r requirements.txt
# Run the application
python3 main.pyNote: On Linux, you may need additional system packages for video processing:
python3-tk- For GUI supportpython3-dev- For building Python extensionsffmpeg- For video processinglibavcodec-dev,libavformat-dev,libavutil-dev,libswscale-dev- For PyAV library support
To create a standalone executable (no Python installation required):
# Recommended: Use the provided build script (handles everything automatically)
python build_executable.pyNote: FFmpeg is not bundled with the executable. The app will automatically download FFmpeg on first run if not found in system PATH (Windows only).
# Recommended: Use the provided build script (handles everything automatically)
python3 build_executable.pyNote: FFmpeg must be installed on the target system. On Linux, you may need to install additional dependencies:
sudo apt-get install python3-tk python3-devThe executable will be created in the dist folder and can be distributed without requiring Python.
After building, run the executable:
# Make the executable executable (if needed)
chmod +x dist/ScreenMachine
# Run the executable
./dist/ScreenMachineNote: On Linux, you may need to make the file executable with chmod +x if it doesn't have execute permissions. The executable is a standalone file and doesn't require Python or any dependencies to be installed.
- Select an input directory containing video files
- Configure grid layout (rows and columns)
- Set screenshot size (max width/height)
- Adjust JPG quality
- Choose which metadata labels to include
- Select whether to overwrite existing images
- Click "Start Processing"
The application will:
- Scan for all video files in the selected directory (recursively)
- For each video, extract screenshots at evenly spaced intervals
- Resize screenshots to fit within specified dimensions
- Assemble screenshots into a grid layout
- Add metadata labels at the top (if enabled)
- Save the result as a JPG file with the same name as the video
Output files are saved as: [video_name].jpg
- Grid Layout: Number of rows and columns for the screenshot grid
- Screenshot Size: Maximum width and height for each screenshot
- JPG Quality: Compression quality (1-100)
- Metadata Labels: Toggle individual labels on/off
- Overwrite Existing: Whether to overwrite existing output files
The application uses a configurable logging system with four log levels:
- DEBUG: Detailed diagnostic information (frame-by-frame extraction details)
- INFO: General informational messages (fallback messages, processing status)
- WARNING: Warnings that don't stop processing (partial frame extraction, corrupt videos)
- ERROR: Serious errors that prevent processing (failed file opens, no video streams)
# Set log level
python main.py --log DEBUG
python main.py --log INFO
python main.py --log WARNING
python main.py --log ERROR
python main.py --log NONE
# Shortcuts
python main.py --verbose # Equivalent to --log INFO
python main.py --debug # Equivalent to --log DEBUG
# Specify log file
python main.py --log-file path/to/logfile.log
# Combine flags
python main.py --verbose --log-file screenmachine.logDefault: No logging (logging is disabled unless explicitly enabled via flags)
DEBUG: Show all messages including detailed frame extraction infoINFO: Show informational messages and above (including fallback messages)WARNING: Show warnings and errors only (recommended for normal use)ERROR: Show only serious errorsNONE: Disable all logging
Note: Logging is only enabled when you use --log, --verbose, --debug, or --log-file flags. No log file is created automatically.
- The number of screenshots extracted is determined by the grid size (rows × columns)
- Screenshots are evenly distributed throughout the video duration
- Screenshots maintain aspect ratio when resized
- The application processes videos sequentially (one at a time)
- Partial frame extraction warnings are normal for corrupt or incomplete video files