Python-based command-line movie thumbnail creator – designed for efficiency and simplicity
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Python video thumbnail contact sheet creator.

pyVideoSheet is designed for efficiency and simplicity, allowing users to create video contact sheets rapidly. pyVideoSheet can be used as a standalong command-line application and as an importable package.



pyVideoSheet requires the following softwares and packages to work:

  • Python (Of course! pyVideoSheet is written in Python 2.7 though)
  • Python Image Library (PIL)
  • FFmpeg

Basic instruction on how to install dependencies


Because pyVideoSheet is written in Python, therefore there must be a valid Python installed to use pyVideoSheet.

Python package for any platform can be downloaded from

Python Image Library (PIL)

There are many ways to install PIL, but here we would recommend to use Pillow, a nice and easy folk of PIL. To install Pillow, run this command

easy_install Pillow

More details instruction on how to install Pillow can be found in Pillow's documentation.


FFmpeg is a cross-platform media solution that pyVideoSheet uses as the primary way to interact with a video. pyVideoSheet requires a working FFmpeg to work.

You can get the latest FFmpeg from its website . Because compiling FFmpeg properly is quite tricky, we'd recommend you to stick to the pre-built packages unless you really need otherwise.

Please note that FFmpeg must be included in the system search path for pyVideoSheet to work correctly. You can test this by running

ffmpeg -h

If you can see FFmpeg's help, it should work alright. Otherwise please check how to add FFmpeg to search path in its documentations

Installing pyVideoSheet

  1. Get the latest version of pyVideoSheet. This can be done by either using git:

    git clone

    or by downloading the zip archive and extract it.

  2. Go into the downloaded directory

    cd pyVideoSheet-<version>
  3. Install the package

    python install

Using pyVideoSheet as a standalone application

pyVideoSheet can be used as a command-line application. This provides a quick and easy way to create contact sheets. The best thing about being a command-line application, as opposed to a GUI one, is the ease of writing a batch script for it, especially when one has to work with lots of videos.

Let's see how to create a contact sheet for a video. In this readme we're going to make contact sheets for this lovely creative common film Big Buck Bunny by Peach project. To make a contact sheet, run this command

python -m pyVideoSheet.create Big_Buck_Bunny_1080p.avi

and you should get this result. example sheet This executes create utility of pyVideoSheet to create a contact sheet with the same name as our video using default options. Customisation options can be added using optional flags.

There are many customisation options, as follows:

Options Example Description
-h, --help --help Display pyVideoSheet's instruction on command-line
-o, --output -o out.png Specify contact sheet's filename
-n, --number -n 30 Specify total number of thumbnails. Each thumbnail is at equidistant apart. The default option is -n 20. This option cannot be use with --interval.
-i, --interval -i 300 Specify fixed interval between each thumbnails. Total number of thumbnail is vary. This option cannot be use with --number.
-c, --column -c 6 Specify number of column of the thumbnail grid. The default is -c 5.
--notime --notime Remove thumbnail's timestamp.
--header --header 120 Specify the height of description header in pixels. The default is 100.
-t, --thumbsize -t 300 250 Specify the maximum size of thumbnail. Thumbnails will retain its aspect ratio. The default is -t 220 220.
--textcolour --textcolour 255 255 0 0 Specify description's text colour in RGBA format.
--bgcolour --bgcolour 255 255 0 0 Specify description's text colour in RGBA format.
--font --font font-file.ttf 12 Specify description's font and font size. Support any TrueType font.
--preview --preview Preview the contact sheet on default image viewer.

Using pyVideoSheet as a package

pyVideoSheet can be imported into any Python project, allowing a quick and flexible way to create a video contact sheet programatically.


First example shows how to create a simple contact sheet for Big_Buck_Bunny_1080p.avi

import pyVideoSheet as pvs

vid = pvs.Video("Big_Buck_Bunny_1080p.avi")
vsheet = pvs.Sheet(vid)

This results in a default contact sheet. code example png

The next example shows the full customisation capability of pyVideoSheet.

import pyVideoSheet as pvs

vid = pvs.Video("Big_Buck_Bunny_1080p.avi") # create Video object
vidLength = vid.getVideoDuration() # get video duration in seconds

# create a 5x6 grid contact sheet with blue text without timestamp
vsheet1 = pvs.Sheet(vid) # create Sheet object
vsheet1.setProperty('gridColumn',6) # set 6 columns
vsheet1.setProperty('textColour',(0,0,255,0)) # set text to blue
vsheet1.setProperty('timestamp',False) # disable timestamp

sheet_1 = vsheet1.makeSheetByNumber(30) # create contact sheet of 5 times 6 columns'grid_example.png') # save with PIL save() # preview with PIL show(). The created sheet is kept as Sheet.sheet variable.

# create a single row preview with black text on white background
vsheet2 = pvs.Sheet(vid) # create Sheet object
vsheet2.setProperty('gridColumn',1) # set 1 columns
vsheet2.setProperty('textColour',(0,0,0,0)) # set text to black
vsheet2.setProperty('backgroundColour',(255,255,255,0)) # set background to white
vsheet2.setProperty('maxThumbSize',(500,500)) # allow larger thumbnails

sheet_2 = vsheet2.makeSheetByInterval(600) # create one thumbnail every 10 minutes'column_example.png') # save with PIL save()

This is our sheet_1 "grid_example.png" grid example png

And this is our sheet_2 "column_example.png"

column example png

Video class

Video class represents a video object. It contains information regarding each specific video as well as providing low level interaction between Python and video.

####Video class functions


Constructor of Video class.

  • Parameter: file—a file name string of video (including its path).
  • Return: A Video object.


Get file size of the video in MB.

  • Return: File size in MB.


Get duration of the video in seconds.

  • Return: Duration in seconds.


Capture a frame at seektime seconds from the beginning.

  • Parameter: seektime—time in seconds.
  • Return: A PIL Image object.


Create a list of frames captured at every fixed interval.

  • Parameter: interval—time in seconds.
  • Return: A List of PIL Image objects.


Reduce the resolution of Video.thumbnails.

  • Parameter: maxSize—a tuple of (maxWidth, maxHeight).
  • Return: Video.thumbnails.

Sheet class

Sheet class handles the creation of contact sheet. Contact sheet's customisation can be done by setting Sheet class's properties.

####Sheet class functions


Constructor of Sheet class.

  • Parameter: Video—a Video object.
  • Return: A Sheet object.


Set customisation options of Sheet.

  • Parameter: prop—a property string. value—a property value
Property string Default Property Value Description
'font' ('Cabin-Regular-TTF.ttf', 15) Set description's font and font size. Takes value as a tuple of font file name (string) and font size (integer).
'backgroundColour' (0,0,0,0) Set header's background colour. Takes value as a tuple containing 4 value for RGBA colour.
'textColour' (255,255,255,0) Set description's text colour. Takes value as a tuple containing 4 value for RGBA colour.
'headerSize' 100 Set header's height in pixels.
'gridColumn' 5 Set number of thumbnail columns in the grid.
'maxThumbSize' (220,220) Set maximum width and height of each thumbnail. The thumbnail will always retain its aspect ratio. Takes value as a tuple of max width and max height.
'timestamp' True Enable thumbnail timestamp. Takes boolean as its value.


Create a contact sheet. Each thumbnail is created at fixed interval. The total number of thumbnails is vary by the video duration divided by interval.

  • Parameter: interval—a time in seconds.
  • Return: A PIL Image object.


Create a contact sheet. The total number of thumbnails is fixed. Each thumbnail is created at the interval defined by the video duration divided by number.

  • Parameter: number—a number of thumbnails.
  • Return: A PIL Image object.

Supported formats

pyVideoSheet works based upon PIL and FFmpeg, thus the supporting formats are set by these dependencies. Most commonly used video formats (such as mp4, avi, mov etc.) should work with FFmpeg, thus should work with pyVideoSheet. Most encoding should be supported as well (including MPEG-2, Xvid, h264). For more information on FFmpeg supported formats, please check FFmpeg documentation Most image formats (including JPEG and PNG) should also work as an output format.

License and development information


pyVideoSheet source, including this document, is distributed under Mozilla Public License 2.0. Please refer to LICENSE file for information.


pyVideoSheet is created and maintained by Wattanit Hotrakool. You can reach the developer directly through twitter.

Development log

30 October 2015

  • Converted into a python package with setup script.

28 October 2015

  • Converted into a executable module (legacy)

27 October 2015

  • First working version