Video Contact Sheet *NIX

vcs for short.

Besides the packages provided above, vcs can be found packaged by other users at the following standard repositories.
I don't take part in creating these packages and can't confirm they work as expected.

Archlinux's AUR

$ git clone
$ cd video-contact-sheet
$ makepkg -si

Homebrew (aka Brew)

NixOS / Nix

$ nix-env -i vcs

Note as of this writing vcs is incorrectly flagged as unfree in Nix 23.11, but already corrected in unstable. You can enforce the install with

$ env NIXPKGS_ALLOW_UNFREE=1 nix-env -i vcs


This is a bash script meant to create video contact sheets (previews) of videos. Any video supported by mplayer and ffmpeg can be used. A note of warning: Unlike most similar tools it, by default, makes screenshots the same size as the video, see below for details on how to change this.

Take a look at the documentation and/or use the –help and –fullhelp options to learn how to use it.

  • Using -i or -n with values that lead to the same number of vidcaps doesn't necessarily yield exactly the same vidcaps, you'll have to play with them for best results.
    • Example: With a video that lasts for 22min 14secs, -n 6 will create the six vidcaps:
      3:22, 6:44, 10:04, 13:28, 16:50 and 20:12, while -i 3m will create 3:00, 6:00, 9:00, 12:00, 15:00 and 18:00.
      As you can see, -n distributes the vidcaps all over the video while -i N starts at N and goes in increments of it up to the end.
  • You can set the aspect ratio of the video with -a. It is only required for anamorphic material and discouraged for the rest.
    It can take either a floating point number (like 1.33 or 1.778) or a fraction (like 4/3 or 16/9). The latter is slightly preferable.

By using configuration files and/or command line options the default behaviour can be tweaked to your needs, these are the defaults, followed by a link with the explanation on how to change it:

  • Captures are made every 5 minutes. See Usage.
  • Captures are the same size as the input video. See Size and aspect ratio.
  • Captures are arranged in 2 columns (if there's more than one capture). See Number of columns.

Samples with varied options:
5x4 grid Black contact sheet 5x4 grid, no padding Complete contact sheet Command: vcs -E0 -S 2 -S 4m38 -i 1m 169_heavyrain_om_ps3_051906_hd.avi Command: $ vcs -n6 -H 540  mariposaHD.S01E05.1080p.en.wmv Filmstrip-mode sample White contact sheet

More samples can be found in the documentation pages, e.g. in: Samples, Example configuration, Setting Contact Sheet Colours.

  • Getting stuck on first frame
    • This happening is a sign that the decoder (FFmpeg or MPlayer) has problems dealing with the input file. Interrupt with CTRL+C and re-run with -O stderr=/dev/stderr to display decoder errors. It might be due to unsupported codecs or broken files, there's little more you can do, except trying with the other decoder (-M to use MPlayer, -F to use FFmpeg, which is the default).
  • Getting gray frames
    • This is a decoder error (either due to a broken file or some codec bug). Again little to be done other than switching decoders.

Remember this is a (neverending) work in progress, please report any bugs you encounter, either through e-mail or the bug tracker.

See roadmap.

VCS Ruby rewrite by Thomas: Reuses part of VCS' code to produce the same style of contact sheets.

vcs-creator by tudo75: Small gui for VCS

Other similar tools available for POSIX/UNIX-like systems:

These are the changes of some interest to end users, since the last full version.
Additionally a selection of changes for all versions and the full changelog (gzipped version) are available. (Contributors are listed there too.)

  • Fix number of columns being ignored in Bash 5.0
  • Fix wrong file sizes being displayed when using mawk
  • Fix alternative blank frame evasion offsets being ignored

Announcement post

  • Correct header rendering in newer versions of ImageMagick
  • Other fixes (see changelog)

Announcement post

  • Fix for sheets with MPlayer as capturer containing one extra capture

Announcement post

  • Minor bugfixes

Announcement post

  • Blank frame avoidance
  • Automatic profile loading from configuration
  • New 'compact' profile
  • Bugfix: FreeBSD support restored
  • Other fixes

Announcement post

© 2007, 2008, 2009, 2010, 2011, 2013, 2014, 2017, 2018, 2019 Toni Corvera <outlyer at>

All dates/times in this page are UTC.
  • vcs.txt
  • Last modified: 2024/05/06 11:34
  • by Toni Corvera