Home

Python Video Thumbnailer is a command line tool for creating video preview thumbnails. It can be used to create preview images of individual video files, videos located in a directory and optionally its subdirectories. It is based on PyAv, MediaInfo and the PIL fork Pillow.

This is an example of a preview thumbnails image of Big Buck Bunny:

The image was created using the built-in defaults with the exception of the header and timestamp font, which was set to DejaVuSans.ttf.

Installation

Python 3 needs to be installed in order to run Python Video Thumbnailer. Python Video Thumbnailer can be installed from PyPI using the Python Package Installer:

python3 -m pip install pyvideothumbnailer

As of Ubuntu 22.04 LTS (Jammy Jellyfish), Ubuntu users can alternatively install the DEB package from this Ubuntu PPA. Dependencies: python3 (>= 3.7.0), python3-pymediainfo, python3-av, python3-pil

sudo add-apt-repository ppa:haraldhetzner/ppa
sudo apt update

The optional configuration file .pyvideothumbnailer.conf needs to be placed in the user's home directory.

Usage

Quick start

Python Video Thumbnailer has meaningful defaults. So you can just start creating your first preview thumbnails image of an individual video file by invoking:

pyvideothumbnailer [VIDEO FILE]

or to create thumbnails of all video files located in the current working directory:

pyvideothumbnailer

or to create thumbnails of all video files located in a directory:

pyvideothumbnailer [DIRECTORY CONTAINING VIDEOS]

or in case that you want to create previews of videos in subdirectories as well:

pyvideothumbnailer --recursive [DIRECTORY CONTAINING VIDEOS]

If not requested otherwise using the option --override-existing, Python Video Thumbnailer will never overwrite any existing image files with the same file name as the image files that it would create.

The parameters --comment-text and --comment-label can be used to add a user-defined comment at the bottom of the header with the video metadata.

Parameters

Order of precedence

Parameters are considered in the following order of precedence:

1. Command line arguments
2. Parameters specified in the configuration file .pyvideothumbnailer.conf in the user's home directory
3. Built-in defaults

The video file name or the directory, where multiple videos are located, always need to be specified as parameter on the command line.

Command line arguments

To print the list of command line arguments, run:

pyvideothumbnailer --help

Configuration file

The configuration file uses the INI syntax recognized by the Python ConfigParser. The parameters have the same names as the command line arguments, but use underscores _ in place of dashes - between the words and have no leading dashes --. The parameters are organized into sections in square brackets [SECTION] and may not be defined outside of the respective section as they will not be recognized otherwise.

The sample configuration file .pyvideothumbnailer.conf contains explanations on all parameters and the parameters commented out.

You need to take into account the following particularities of the ConfigParser syntax:

• String values may not be put into quotes.
• To define a Python value of None, meaning the parameter is explicitly not set, you need to declare it without assigning a value: parameter =.

List of parameters

The following table lists the parameters recognized as command line arguments and variables in the configuration file.

Command line	Configuration file	Section	Type	Default	Explanation
-h, --help					Show the help message and exit.
--width X	width	Layout	int	800	The intended width of the preview thumbnails image in px. Actual width may be slightly less due rounding upon scaling.
--columns X	columns	Layout	int	4	The number of preview thumbnail columns.
--rows X	rows	Layout	int	3	The number of preview thumbnail rows.
---vertical-video-columns X	vertical_video_columns	Layout	int		The number of preview thumbnail columns in place of --column in case of vertical videos.
---vertical-video-rows X	vertical_video_rows	Layout	int		The number of preview thumbnail rows in place of --rows in case of vertical videos.
--spacing X	spacing	Layout	int	2	The spacing between and around the preview thumbnails in px.
--background-color X	background_color	Layout	str	white	Name or other definition of the PIL color to use for the image background, for information on accepted values see Pillow ImageColor.
--no_header	no_header	Program	bool	False	Do not include a header with metadata and optional comment. Enabling this option will make all header settings irrelevant.
--header-font X	header_font	Layout	str		The name of a true type font found in the system font path to use for the header text providing information on the video file and its metadata. If omitted, a built-in default font is used.
--header-font-size X	header_font_size	Layout	int	14	The font size of the header font, if a true type font is specified. With the built-in font, this value is ignored.
--header-font-color X	header_font_color	Layout	str	black	Name or other definition of the PIL color to use for the header font, for information on accepted values see Pillow ImageColor.
--timestamp-font X	timestamp_font	Layout	str		The name of a true type font in the system font path to use for the preview thumbnail timestamps. If omitted, a built-in default font is used.
--timestamp-font-size X	timestamp_font_size	Layout	int	12	The font size of the timestamp font, if a true type font is specified. With the built-in font, this value is ignored.
--timestamp-font-color X	timestamp_font_color	Layout	str	white	Name or other definition of the PIL color to use for the timestamp font, for information on accepted values see Pillow ImageColor.
--timestamp-shadow-color X	timestamp_shadow_color	Layout	str	black	Name or other definition of the PIL color to use for the shadow of the timestamps, for information on accepted values see Pillow ImageColor. To suppress the shadow, define timestamp_shadow_color = in the configuration file.
--comment-label X	comment_label	Header	str	Comment:	Label used for an optional user-defined comment, which is added at the bottom of the video metadata information. If not defined, the default label 'Comment:' is used.
--comment-text X	comment_text	Header	str		Text of an optional user-defined comment, which is added at the bottom of the video metadata information.If not defined, no comment is added and the respective text line is omitted in the header.
--skip-seconds X	skip_seconds	Video	float	10.0	The number of seconds to skip at the beginning of the video before capturing the first preview thumbnail.
--suffix X	suffix	File	str		An optional suffix to append to the file name of the generated preview thumbnails images.
--jpeg-quality X	jpeg_quality	File	int	95	The quality of the JPEG image files that are created.
--override_existing	override_existing	File	bool	False	Override any existing image files, which have the same name as the generated images. By default, a preview thumbnails image is not created, if the file to be created already exists.
--recursive	recursive	File	bool	False	If creating preview thumbnails of video files in a directory, process subdirectories recursively.
--output-directory X	output_directory	File	str		A directory, where all created preview thumbnails images should be saved. If omitted, preview thumbnails images are saved in the same directory, where the respective video file is located.
--raise-errors	raise_errors	Program	bool	False	Stop if an error occurs by raising it. By default, errors are ignored and the affected preview thumbnails image is skipped. This is useful, when processing multiple video files in a directory.
--verbose	verbose	Program	bool	False	Print verbose information and messages.

Automatic preview thumbnails image generation (Linux)

On Linux, incrond can be used to automatically generate preview thumbnails of new video files created in, copied or moved to a directory (e.g. web upload) with pyvideothumbnailer.

The first step is editing /etc/incron.allow and add the name of the user who will own the video and preview files and run pyvideothumbnailer. This enables the user to make use of incrond.

The second step is editing the incrontab of this user. As the user run:

incrontab -e

Let's assume that we expect video files to be uploaded to /srv/videos/upload and we would like to have the preview thumbnails images being available in /srv/videos/preview. In this case we add the following line to the user's incrontab.

/srv/videos/upload     IN_CREATE,IN_MOVED_TO     pyvideothumbnailer --output-directory /srv/videos/preview $@/$#

• IN_CREATE will trigger a the command if a file or directory is created in the watched directory /srv/videos/upload
• IN_MOVED_TO will trigger the command if a file or directory is moved to the watched directory /srv/videos/upload
• $@ is a special variable representing the watched filesystem path (in this case /srv/videos/upload)
• $# is a special variable representing the event-related file name (in this case a file created in or moved/copied to /srv/videos/upload)

From now on, incrond will call pyvideothumbnailer to create a preview thumbnails image in /srv/videos/preview each time that a video file is created in or moved/copied to the watched directory /srv/videos/upload.

Examples

Here are a few examples of preview thumbnails of Big Buck Bunny demonstrating the layout options of pyvideothumbnailer.

Using Defaults:

pyvideothumbnailer bbb_sunflower_1080p_60fps_normal.mp4

Using DejaVuSans TrueType font for header and timestamps instead of the built-in font:

pyvideothumbnailer --header-font DejaVuSans.ttf --timestamp-font DejaVuSans.ttf bbb_sunflower_1080p_60fps_normal.mp4

Adding a comment at the bottom of the header:

pyvideothumbnailer --comment-text "Created with pyvideothumbnailer" bbb_sunflower_1080p_60fps_normal.mp4

White header font on black background:

pyvideothumbnailer --background-color black --header-font-color white bbb_sunflower_1080p_60fps_normal.mp4

Preview image width of 1024 pixels and 5 x 4 preview thumbnails:

pyvideothumbnailer --width 1024 --columns 5 --rows 4 bbb_sunflower_1080p_60fps_normal.mp4