Skip to content
Create video contact sheets, thumbnails
Branch: master
Clone or download
Latest commit d6765c0 Apr 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests improve compatibility between --grid and --interval (as well as with (#… Mar 17, 2019
vcsi bump version for new pypi release Apr 15, 2019
.gitignore add script for releasing to pypi. close #44 Jul 16, 2018
.travis.yml drop support for python 2.7 and 3.3 Feb 20, 2019
LICENSE update date in license Mar 10, 2019 make pypi release: cleanup build before making new release Jul 19, 2018
requirements.txt add --interval Feb 24, 2018 add missing dependencies Jan 16, 2019


Build Status Coverage Status License PyPI version

Create video contact sheets. A video contact sheet is an image composed of video capture thumbnails arranged on a grid.


$ vcsi bbb_sunflower_2160p_60fps_normal.mp4 \
-t \
-w 850 \
-g 4x4 \
--background-color 000000 \
--metadata-font-color ffffff \
--end-delay-percent 20


$ vcsi bbb_sunflower_2160p_60fps_normal.mp4 \
-t \
-w 850 \
-g 3x5 \
--end-delay-percent 20 \
-o output.png


The above contact sheets were generated from a movie called "Big Buck Bunny".



$ pip install vcsi

Distribution packages

vcsi is currently packaged for the following systems:

Linux packages
Arch (AUR)
Arch (AUR, git master)

Your system is not listed?

$ apt-get install ffmpeg
$ python install

Running Windows? See the note below.

Note for Windows users

Download a binary build of ffmpeg from Zeranoe here (e.g. 64bit static):

Extract the archive and add the bin directory to your PATH so that ffmpeg and ffprobe can be invoked from the command line.

If you have issues installing numpy with pip, download an already built version of numpy here:


Python modules:

  • numpy
  • pillow
  • jinja2
  • texttable
  • parsedatetime

Must be in your PATH:

  • ffmpeg
  • ffprobe


$ vcsi -h
usage: vcsi [-h] [-o OUTPUT_PATH] [--start-delay-percent START_DELAY_PERCENT]
            [--end-delay-percent END_DELAY_PERCENT]
            [--delay-percent DELAY_PERCENT] [--grid-spacing GRID_SPACING]
            [--grid-horizontal-spacing GRID_HORIZONTAL_SPACING]
            [--grid-vertical-spacing GRID_VERTICAL_SPACING] [-w VCS_WIDTH]
            [-g GRID] [-s NUM_SAMPLES] [-t]
            [--metadata-font-size METADATA_FONT_SIZE]
            [--metadata-font METADATA_FONT]
            [--timestamp-font-size TIMESTAMP_FONT_SIZE]
            [--timestamp-font TIMESTAMP_FONT]
            [--metadata-position METADATA_POSITION]
            [--background-color BACKGROUND_COLOR]
            [--metadata-font-color METADATA_FONT_COLOR]
            [--timestamp-font-color TIMESTAMP_FONT_COLOR]
            [--timestamp-background-color TIMESTAMP_BACKGROUND_COLOR]
            [--timestamp-border-color TIMESTAMP_BORDER_COLOR]
            [--template METADATA_TEMPLATE_PATH] [-m MANUAL_TIMESTAMPS] [-v]
            [-a] [-A ACCURATE_DELAY_SECONDS]
            [--metadata-margin METADATA_MARGIN]
            [--metadata-horizontal-margin METADATA_HORIZONTAL_MARGIN]
            [--metadata-vertical-margin METADATA_VERTICAL_MARGIN]
            [--timestamp-horizontal-padding TIMESTAMP_HORIZONTAL_PADDING]
            [--timestamp-vertical-padding TIMESTAMP_VERTICAL_PADDING]
            [--timestamp-horizontal-margin TIMESTAMP_HORIZONTAL_MARGIN]
            [--timestamp-vertical-margin TIMESTAMP_VERTICAL_MARGIN]
            [--quality IMAGE_QUALITY] [-f IMAGE_FORMAT]
            [-T TIMESTAMP_POSITION] [-r] [--timestamp-border-mode]
            [--timestamp-border-size TIMESTAMP_BORDER_SIZE]
            [--capture-alpha CAPTURE_ALPHA] [--version]
            [--list-template-attributes] [--frame-type FRAME_TYPE]
            [--interval INTERVAL] [--ignore-errors]
            filenames [filenames ...]

Create a video contact sheet

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
                        save to output file (default: None)
  --start-delay-percent START_DELAY_PERCENT
                        do not capture frames in the first n percent of total
                        time (default: 7)
  --end-delay-percent END_DELAY_PERCENT
                        do not capture frames in the last n percent of total
                        time (default: 7)
  --delay-percent DELAY_PERCENT
                        do not capture frames in the first and last n percent
                        of total time (default: None)
  --grid-spacing GRID_SPACING
                        number of pixels spacing captures both vertically and
                        horizontally (default: None)
  --grid-horizontal-spacing GRID_HORIZONTAL_SPACING
                        number of pixels spacing captures horizontally
                        (default: 5)
  --grid-vertical-spacing GRID_VERTICAL_SPACING
                        number of pixels spacing captures vertically (default:
  -w VCS_WIDTH, --width VCS_WIDTH
                        width of the generated contact sheet (default: 1500)
  -g GRID, --grid GRID  display frames on a mxn grid (for example 4x5)
                        (default: 4x4)
  -s NUM_SAMPLES, --num-samples NUM_SAMPLES
                        number of samples (default: None)
  -t, --show-timestamp  display timestamp for each frame (default: False)
  --metadata-font-size METADATA_FONT_SIZE
                        size of the font used for metadata (default: 16)
  --metadata-font METADATA_FONT
                        TTF font used for metadata (default:
  --timestamp-font-size TIMESTAMP_FONT_SIZE
                        size of the font used for timestamps (default: 12)
  --timestamp-font TIMESTAMP_FONT
                        TTF font used for timestamps (default:
  --metadata-position METADATA_POSITION
                        Position of the metadata header. Must be one of
                        ['top', 'bottom', 'hidden'] (default: top)
  --background-color BACKGROUND_COLOR
                        Color of the background in hexadecimal, for example
                        AABBCC (default: 000000FF)
  --metadata-font-color METADATA_FONT_COLOR
                        Color of the metadata font in hexadecimal, for example
                        AABBCC (default: FFFFFFFF)
  --timestamp-font-color TIMESTAMP_FONT_COLOR
                        Color of the timestamp font in hexadecimal, for
                        example AABBCC (default: FFFFFFFF)
  --timestamp-background-color TIMESTAMP_BACKGROUND_COLOR
                        Color of the timestamp background rectangle in
                        hexadecimal, for example AABBCC (default: 000000AA)
  --timestamp-border-color TIMESTAMP_BORDER_COLOR
                        Color of the timestamp border in hexadecimal, for
                        example AABBCC (default: 000000FF)
                        Path to metadata template file (default: None)
                        Comma-separated list of frame timestamps to use, for
                        example 1:11:11.111,2:22:22.222 (default: None)
  -v, --verbose         display verbose messages (default: False)
  -a, --accurate        Make accurate captures. This capture mode is way
                        slower than the default one but it helps when
                        capturing frames from HEVC videos. (default: False)
                        Fast skip to N seconds before capture time, then do
                        accurate capture (decodes N seconds of video before
                        each capture). This is used with accurate capture mode
                        only. (default: 1)
  --metadata-margin METADATA_MARGIN
                        Margin (in pixels) in the metadata header. (default:
  --metadata-horizontal-margin METADATA_HORIZONTAL_MARGIN
                        Horizontal margin (in pixels) in the metadata header.
                        (default: 10)
  --metadata-vertical-margin METADATA_VERTICAL_MARGIN
                        Vertical margin (in pixels) in the metadata header.
                        (default: 10)
  --timestamp-horizontal-padding TIMESTAMP_HORIZONTAL_PADDING
                        Horizontal padding (in pixels) for timestamps.
                        (default: 3)
  --timestamp-vertical-padding TIMESTAMP_VERTICAL_PADDING
                        Vertical padding (in pixels) for timestamps. (default:
  --timestamp-horizontal-margin TIMESTAMP_HORIZONTAL_MARGIN
                        Horizontal margin (in pixels) for timestamps.
                        (default: 5)
  --timestamp-vertical-margin TIMESTAMP_VERTICAL_MARGIN
                        Vertical margin (in pixels) for timestamps. (default:
  --quality IMAGE_QUALITY
                        Output image quality. Must be an integer in the range
                        0-100. 100 = best quality. (default: 100)
                        Output image format. Can be any format supported by
                        pillow. For example 'png' or 'jpg'. (default: jpg)
                        Timestamp position. Must be one of ['north', 'south',
                        'east', 'west', 'ne', 'nw', 'se', 'sw', 'center'].
  -r, --recursive       Process every file in the specified directory
                        recursively. (default: False)
                        Draw timestamp text with a border instead of the
                        default rectangle. (default: False)
  --timestamp-border-size TIMESTAMP_BORDER_SIZE
                        Size of the timestamp border in pixels (used only with
                        --timestamp-border-mode). (default: 1)
  --capture-alpha CAPTURE_ALPHA
                        Alpha channel value for the captures (transparency in
                        range [0, 255]). Defaults to 255 (opaque) (default:
  --version             show program's version number and exit
  --frame-type FRAME_TYPE
                        Frame type passed to ffmpeg
                        'select=eq(pict_type,FRAME_TYPE)' filter. Should be
                        one of ('I', 'B', 'P') or the special type 'key' which
                        will use the 'select=key' filter instead. (default:
  --interval INTERVAL   Capture frames at specified interval. Interval format
                        is any string supported by `parsedatetime`. For
                        example '5m', '3 minutes 5 seconds', '1 hour 15 min
                        and 20 sec' etc. (default: None)
  --ignore-errors       Ignore any error encountered while processing files
                        recursively and continue to the next file. (default:

Metadata templates

vcsi now supports metadata templates thanks to jinja2. In order to use custom templates one should use the --template argument to specifiy the path to a template file.

Here is a sample template file:

File size: {{size}}
{% if audio_sample_rate %}
Audio sample rate: {{audio_sample_rate/1000}} KHz
{% endif %}

{% if audio_bit_rate %}
Audio bitrate: {{audio_bit_rate/1000}} Kbps
{% endif %}

{{frame_rate}} fps

Resolution: {{sample_width}}x{{sample_height}}

Exposed metadata template attributes

Attribute name Description Example
size File size (pretty format) 128.3 MiB
size_bytes File size (bytes) 4662788373
filename File name video.mkv
duration Duration (pretty format) 03:07
sample_width Width of samples (pixels) 1920
sample_height Height of samples (pixels) 1080
display_width Display width (pixels) 1920
display_height Display height (pixels) 1080
video_codec Video codec h264
video_codec_long Video codec (long name) H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10
display_aspect_ratio Display aspect ratio 16:9
sample_aspect_ratio Sample aspect ratio 1:1
audio_codec Audio codec aac
audio_codec_long Audio codec (long name) AAC (Advanced Audio Coding)
audio_sample_rate Audio sample rate (Hz) 44100
audio_bit_rate Audio bit rate 192000
frame_rate Frame rate (fps) 23.974
You can’t perform that action at this time.