Video Contact Sheet *NIX

Last revision: 2017-05-23

Table of Contents

VCS — create contact sheets from videos
vcs.conf — vcs configuration file

Name

vcs — create contact sheets from videos

Synopsis

vcs [OPTION...] FILE [FILE...]

vcs [--output=OUTPUT1] [--output=OUTPUT2] [...] INPUT1 [INPUT2...]

vcs [[-n 20] | [-i 1m]] [-c 4] [-H 120] [...] FILE...

vcs [ { -h | --help } | --fullhelp | -DD ]

vcs [OPTION...] --generate { config | profile }

DESCRIPTION

vcs creates a preview image from videos in a contact sheet-like format (i.e. captures from different frames in the video are placed in a mosaic).

By default the output file will be named like the input file plus the png extension. Example: "file.avi" will produce a contact sheet in the file "file.avi.png".

The default mode of operation is to obtain captures every five minutes in the video, so the amount of captures will vary with each file. The command-line argument --numcaps (-n) can be used to change this behaviour or alternatively a configuration file might be used to change the mode of operation (see vcs.conf(5)).

This manual page documents vcs, further documentation can be found in the online documentation site.

OPTIONS

The program follows the usual GNU command line syntax, with long options starting with two dashes (`-'). A summary of options is included below.

-n number, --numcaps=number

Fixes the number of captures to obtain.

Sets the mode of operation to capture a fixed number of frames.

-i INTERVAL, --interval=INTERVAL

Sets the interval between captures.

Sets the mode of operation to capture at fixed intervals.

The number of captures will depend on the video length.

See the accepted syntax at the section called “INTERVALS”.

-c NUMBER, --columns=NUMBER

Number of columns in the contact sheet.

The number of rows will depend on this value and the number of captures (there's no way to set the number of rows).

-H HEIGHT, --height=HEIGHT

Height of captures.

Can be a number (of pixels) or a percentage (of the video height).

By default the same size as the video is used.

Note

The width is derived from height and aspect ratio.

Tip

HEIGHT x WIDTH can be manually forced by setting both -H and -a, e.g. 640x480:

$ vcs -a 640/480 -H 480 [...]

-o FILENAME, --output=FILENAME

Name of output file.

By default the video file name plus the output format is used (e.g. "video.avi.png" for "video.avi").

If an extension is provided, it will define the output format, otherwise PNG will be used. I.e. sheet.jpg will produce a JPEG file while sheet or sheet.png will produce a PNG file.

-h, --help

Show summary of most common options.

--fullhelp

Show summary of all options.

-a ASPECT, --aspect ASPECT

Aspect ratio.

Accepts a floating point number or a fraction.

-f TIMESTAMP, --from TIMESTAMP

Set starting time. No captures will be made before this TIMESTAMP.

See the accepted syntax at the section called “INTERVALS”.

-t TIMESTAMP, --to TIMESTAMP

Set ending time. No captures will be made after this TIMESTAMP.

See the accepted syntax at the section called “INTERVALS”.

-T TITLE, --title TITLE

Add a title above the captures.

-j, --jpeg

Output file in JPEG format.

The default output format is PNG.

-j2, --jpeg2, --jpeg=2

Output file in JPEG 2000 format.

The default output format is PNG.

-V, --dvd

DVD mode.

In this mode the input files must be the DVD device(s) or ISO(s).

When in DVD mode all input files must be DVDs.

Note

Implies -A (auto aspect ratio).

--dvd-title TITLENUM

DVD title to use.

Using 0 (the default) will use the longest title.

-M, --mplayer

Use Mplayer to capture.

-F, --ffmpeg

Use FFmpeg to capture.

This is the default, except in DVD mode.

-E OFFSET, --end-offset OFFSET

This amount of time is ignored from the end of the video.

This value is not used when a explicit ending time is set (--to).

Accepted formats:

The default is 5.5%.

-q, --quiet

Don't print progress messages just errors.

Repeat to mute completely, even on error.

-d FEATURE, --disable FEATURE

Disable some default functionality.

Features that can be disabled are:

  • timestamps: use -dt or --disable timestamps

  • shadows: use -ds or --disable shadows

  • padding: use -dp or --disable padding

Note

Shadows introduce some extra padding

-A, --autoaspect

Try to guess aspect ratio from resolution.

A rude hard-coded method is used based only on known common dimensions.

-e, -e[FACTOR], --extended=[FACTOR]

Enables extended mode and optionally sets the extended factor.

When FACTOR is omitted, 4 is used, i.e. -e is the same as -e4.

-l TIMESTAMP, --highlight TIMESTAMP

Add the frame found at TIMESTAMP as a highlight.

See the accepted syntax at the section called “INTERVALS”.

-m, --manual

Manual mode.

In this mode only timestamps indicated by the user are used (use in conjunction with -S).

When using this option, -i and -n are ignored.

-S TIMESTAMP, --stamp TIMESTAMP

Add the frame at TIMESTAMP to the set of captures.

See the accepted syntax at the section called “INTERVALS”.

-u NAME, --user NAME

Set the user name (included by default in the contact sheet's footer) to NAME.

-U, --fullname

Use user's full/real name (e.g. John Smith) as set in the system's list of users (i.e. in /etc/passwd or through getent).

-p PROFILE, --profile PROFILE

Load profile named PROFILE.

Profile names starting with ':' are reserved and have special meanings, currently:

  • :list — Will list all profiles found in the system

If PROFILE doesn't exist, exit with error.

-C CONFIG, --config CONFIG

Load configuration file CONFIG

Configuration file names starting with ':' are reserved and have special meanings, currently:

  • :pwd — Will try to load ./vcs.conf.

    This file has been loaded by default up to vcs v1.13

If CONFIG doesn't exist, exit with error.

--generate config|profile

Generate configuration or profile from the current settings and print it.

All settings changed from the default, by either configuration, profiles or command-line options, will be included in the generated text.

-k MODE, --funky MODE

Funky modes

These are toy output modes in which the contact sheet gets a more informal look.

Caution

Order IS IMPORTANT, it affects output.

A bad order will produce a bad result.

Many of these modes are random in nature so using the same mode twice will usually lead to very different results.

Currently available funky modes:

overlap: Use -ko or --funky overlap

Randomly overlap captures.

rotate: Use -kr or --funky rotate

Randomly rotate each image.

photoframe: Use -kf or --funky photoframe

Adds a photo-like white frame to each image.

polaroidframe: Use -kL or --funky polaroidframe

Adds a polaroid picture-like white frame to each image.

photos: Use -kc or --funky photos

Combination of rotate, photoframe and overlap.

Same as -kp -kr -ko.

polaroid: Use -kp or --funky polaroid

Combination of rotate, polaroidframe and overlap.

Same as -kL -kr -ko.

film: Use -ki or --funky film

Imitates filmstrip look.

random: Use -kx or --funky random

Randomises colours and fonts.

--anonymous

Disable the «Preview created by USERNAME» line in the footer.

-Ij[=FONTNAME], -Ik[=FONTNAME], --nonlatin

Use an alternate font in the heading for the video file name.

Required to display correctly file names in some languages with non-Latin alphabets (Chinese, Japanese, Hangul, Cyrillic, ...).

When no font name is given, a reasonable choice will be made if possible.

When FONTNAME is given, it can be either a font name:

$ vcs -Ij=Sazanami-Mincho-Regular file.avi

Or a font file name:

$ vcs -Ij=/usr/share/fonts/ttf/ttf-japanese-mincho.ttf file.avi

A list of available fonts and their names can be obtained with the command identify -list font

-O SETTING=VALUE, --override SETTING=VALUE

Changes the value of SETTING to VALUE, as if it was set from a configuration file.

Some settings can only be changed through configuration files or overrides, while others have associated command-line options.

VALUE can be quoted to include spaces:

$ vcs -O SOME_SETTING="my value" ...

VALUE can also refer to some other setting:

$ vcs -O SOME_SETTING='$SOME_OTHER_SETTING' ...

See vcs.conf(5) and the online documentation for a list of possible SETTINGs.

-W WORKAROUND

Enables one of the known workarounds for problematic files, or some tweak:

-Ws

Increase length of safe measuring (try harder).

Repeat to increase further.

-WS

Scan all video, if required, to get a valid length measuring.

-Wp

Increase safe measuring precision (i.e. halve the probe stepping).

Repeat to increase further.

-WP

Inverse of -Wp.

-Wo

Change FFmpeg's arguments order, might work with some files that fail otherwise.

-Wc

Disable colour in console messages.

Note

Some colour will be printed by default until this option is handled. If you need to completely disable colour, e.g. to run in cron jobs, you can do so by setting an appropriate TERM environment variable e.g.

$ TERM=vt100 vcs

will make the script switch to monochrome output altogether.

DEBUGGING OPTIONS

-R FILE, --randomsource FILE

Use FILE as a source for "random" values.

They won't be random anymore, so two runs with the same source and same arguments will produce the same output in modes which use randomisation (e.g. the modes triggered by -k photos and -k polaroid).

-D

Debug mode.

Used to test features/integrity. It:

  • Prints the input command line

  • Sets the title to reflect the command line

  • Does a basic test of consistency

  • Prints a trace of all internal functions as they are called

Repeat to just test consistency and exit

-Z FEATURE, --undocumented FEATURE

Testbed for experimental and debugging features. Some FEATUREs might be promoted in the future to actual command-line options.

FEATUREs here are rough implementations and have no error-handling.

FEATURE names can be added or removed in every version, silently, so don't rely on them.

Useful for end-users:

idonly

Prints the file probing/identification information and exit.

display

Display the generated contact sheet.

discard

Remove the created file on exit.

FILES

/etc/vcs.conf

The system-wide configuration file to control the behaviour of vcs. See vcs.conf(5) for further details.

${HOME}/.vcs.conf, ${HOME}/.vcs/vcs.conf

The per-user configuration file to control the behaviour of vcs. See vcs.conf(5) for further details.

INTERVALS

Intervals and timestamps can be specified in seconds or in a human-readable format that follows the syntax

HOURShMINUTESmSECONDSs.MILLISECONDS

where each element is optional.

See http://p.outlyer.net/dox/vcs:time_syntax for more details.

Table 1. Interval syntax examples

ExampleEquivalenceStandard time format
1h30m301h30m30s.001:30:30.00
300h0m30s.000:00:30.00
36001h0m0s.001:00:00.00

ENVIRONMENT

TEMPDIR

Fallback temporary directory when /dev/shm is not available. Due to the big size of temporary files, it is recommended to use a temporary directory on a fast filesystem.

TERM

Affects the usage of colour output to console being on or off by default. See the documentation for -Wc.

DIAGNOSTICS

The default verbosity level will print vcs' progress and any errors or warnings on stderr.

--quiet can be used to reduce verbosity.

The verbosity level and where to direct stderr can be controlled through configuration files, see vcs.conf(5).

vcs provides some return codes, they follow the semi-standardised values defined in sysexits.h:

CodeDiagnostic
 0 (EX_OK)Program exited successfully.
64 (EX_USAGE)Error in the arguments.
66 (EX_NOINPUT)Can't access some input file or it has an incorrect format.
69 (EX_UNAVAILABLE)Unsatisfied dependency.
70 (EX_SOFTWARE)Internal inconsistency (bug).
73 (EX_CANTCREAT)Error creating temporary or output files.

BUGS

The upstream bug tracker system can be found at http://b.outlyer.net, bugs can be reported through the BTS or through e-mail addressed at .

Note

Recent versions of ImageMagick, mplayer and ffmpeg should be used for maximum compatibility.

Most testing is done on Debian Sid, plus FreeBSD for BSD compatibility tests.

Using OSes other than Debian Sid or FreeBSD might uncover bugs and produce incompatibilities unknown to the author.

SEE ALSO

vcs.conf(5), convert(1), ffmpeg(1), mplayer(1)


Name

vcs.conf — vcs configuration file

DESCRIPTION

This manual page describes the format and available settings in configuration and profile files for vcs(1)

There's two types of files that follow this syntax: configuration files (see the section called “CONFIGURATION FILES”) and profiles (see the section called “PROFILE FILES”). They'll be called collectively settings files in this manual page.

Configuration files are meant to be loaded by default, intended to set user's preferred options, while profiles are meant to be loaded on-demand, intended to allow different parallel sets of settings.

SYNTAX

Settings files contain a series of SETTING=VALUE assignments.

Comments can be included by preceding `#' to them.

META-INFORMATION

Meta-information fields can be contained in comments. They are written as 'vcs:FIELDNAME:'.

Currently supported meta-information fields:

vcs:conf:

Marks a file as following this format.

Files without this field will be rejected. [1]

vcs:desc: DESCRIPTION

Describes this particular file's purpose, it is shown e.g. when listing available profiles.

It is currently ignored for configuration files.

SYNTAX EXAMPLE

# vcs:conf:
# vcs:desc:  White-on-black
bg_all=black # Black background
fg_all=white # White foreground

CONFIGURATION FILES

There's three configuration files loaded by default if present, in order:

  • /etc/vcs.conf

  • ${HOME}/.vcs.conf

  • ${HOME}/vcs/vcs.conf

Every file in this list overrides the previous when it re-defines a setting.

Configuration files can be loaded manually off of any path by using the --config FILENAME option.

PROFILE FILES

No profile is loaded by default.

Profiles are searched in three possible locations, in order:

  • ${HOME}/.vcs/profiles/

  • /usr/local/share/vcs/profiles/

  • /usr/share/vcs/profiles/

Only the first profile for each name will be considered. Profiles with the same name will be hidden.

$ vcs --profile :list

can be used to get a list of available profiles.

Profiles can only be loaded from the listed paths.

SETTINGS

This list details the available settings. Settings are listed in alphabetical order.

A list of available settings, grouped by categories, is also kept online at http://p.outlyer.net/dox/vcs:conf_files

All settings

anonymous, bg_all, bg_heading, bg_contact, bg_sign, bg_title, bg_tstamps, capturer, columns, debug, decoder, disable_shadows, disable_shadows, disable_timestamps, end_offset, extended_factor, fg_all, fg_heading, fg_sign, fg_title, fg_tstamps, font_all, font_heading, font_sign, font_title, font_tstamps, format, getopt, height, interval, nonlatin_filenames, nonlatin_font, numcaps, padding, plain_messages, profiles, pts_meta, pts_sign, pts_title, pts_tstamps, quality, signature, stderr, stdout, timecode_from, user, verbosity

anonymous

Enables or disables the anonymous mode.

Set to 1 to enable this mode, in which the contact sheet footer won't include the «Preview created by $user» line.

Default: 0 (≡ disabled).

Equivalent command-line option: --anonymous.

bg_all

Sets the value of all bg_ variables at once (bg_contact, bg_heading, bg_sign, bg_tstamps and bg_title).

bg_heading, bg_contact, bg_sign, bg_title, bg_tstamps

These variables control the background colours of each section in the contact sheet.

Note

Valid colour values are those understood by ImageMagick, e.g. colour names or HTML/CSS-style colour specifications (#RRGGBB[AA], #RGB[A]).

See http://www.imagemagick.org/script/color.php for more details and additional formats.

Tip

The command $ convert -list color prints a list of all known colour names.

bg_heading — File meta information (size, codec, etc.). Default: #afcd7a [≡ RGB(175,205,122)]

bg_title — Title (with option -T). Default: White [≡ RGB(255,255,255)]

bg_contact — Captures. Default: White [≡ RGB(255,255,255)]

bg_tstamps — Timestamps boxes. Default: #000000aa [≡ RGBA(0,0,0,0.67)]

bg_sign — Footer. Default: SlateGray [≡ RGB(112,128,144)]

capturer

Controls which capturer to use.

Symbolic values: ffmpeg ⇒ FFmpeg, mplayer ⇒ MPlayer

Default: ffmpeg

Related command-line options: -F, --ffmpeg and -M, --mplayer

Warning

DVD mode sets the capturer to MPlayer disregarding the value of this setting.

Since version 1.13

columns

Number of columns

Default: 2

debug

Enable or disable debug mode. Set to 1 to enable.

Default: 0 (disabled).

Equivalent command-line option: -D.

decoder

Warning

This setting is deprecated, use capturer instead. Notice capturer has a different syntax.

Controls which capturer to use.

Symbolic values: $DEC_FFMPEG ⇒ FFmpeg, $DEC_MPLAYER ⇒ MPlayer

Default: $DEC_FFMPEG (FFmpeg)

Related command-line options: -F, --ffmpeg and -M, --mplayer

Warning

DVD mode sets the capturer to MPlayer disregarding the value of this setting.

disable_shadows

Disables drop shadows when set to 1.

Default: 0

Equivalent command-line option: -ds, --disable shadows.

disable_timestamps

Disables timestamps on captures when set to 1.

Default: 0

Equivalent command-line option: -dt, --disable timestamps.

end_offset

End offset value (amount of time ignored from the end of videos).

Can be a percentage (of the detected length of each video) or an amount of time, specified in the time syntax specified in vcs(1).

Default: 5%

Equivalent command-line option: -E, --end-offset.

extended_factor

Extended factor value.

When set to a value different than 0 enables extended mode.

Default: 0

See the extended mode documentation.

Equivalent command-line option: -e, --extended.

fg_all

Sets the value of all fg_ variables at once (fg_heading, fg_sign, fg_title and fg_tstamps).

Since version 1.12.2

fg_heading, fg_sign, fg_title, fg_tstamps

These variables control the font colours of each section in the contact sheet.

Note

Valid colour values are those understood by ImageMagick, e.g. color names or HTML/CSS-style color specifications (#RRGGBB[AA], #RGB[A]).

See http://www.imagemagick.org/script/color.php for more details and additional formats.

Tip

The command $ convert -list color prints a list of all known colour names.

fg_heading — File meta information. Default: Black [≡ RGB(0,0,0)]

fg_title — Title (with option -T). Default: Black [≡ RGB(0,0,0)]

fg_tstamps — Timestamps. Default: White [≡ RGB(255,255,255)]

fg_sign — Footer. Default: Black [≡ RGB(0,0,0)]

font_all

Sets the value of all font_ variables at once (font_heading, font_sign, font_title and font_tstamps)

Additional details: Since 1.12.2

font_heading, font_sign, font_title, font_tstamps

These variables control the fonts used in each section of the contact sheet.

font_heading — File meta information. Default: DejaVu-Sans-Book

font_title — Title (with option -T). Default: DejaVu-Sans-Book

font_tstamps — Used for timestamps over the thumbnails. Default: DejaVu-Sans-Book

font_sign — Footer / signature. Default: DejaVu-Sans-Book

format

Output file format

Default: png

Note

Should match the extension of a format known by ImageMagick.

Related command-line options: -j, --jpeg and --jpeg2

getopt

GNU getopt command

Default: getopt

Warning

The getopt command name must be set correctly or vcs won't work.

Must be a version compatible with GNU syntax.

Can only be set in configuration files (i.e. not from the command-line).

height

Height of individual captures.

Can be a fixed number of pixels or a percentage.

The default is the same as input i.e. 100%.

Equivalent command-line option: -H, --height.

interval

Interval between captures, when the mode of operation is to capture at fixed intervals.

Accepts the same format as any option accepting times, see vcs(1) for details on the acceptable syntax.

Default: 300 (≡ 5 minutes).

Note

Unlike its command-line counterpart (-i or --interval), changing the value of interval doesn't automatically switch modes to capture at intervals.

The mode of operation is controlled by timecode_from.

Equivalent command-line option: -i, --interval.

nonlatin_filenames

Enables or disables the usage of an alternate font to print filenames in the contact sheet meta-information section.

Set to 1 to use nonlatin_font to print filenames.

Default: 0  ⇒  use the standard font, font_heading.

Since 1.12.2

Equivalent command-line option: --nonlatin, -Ik, -Ij.

nonlatin_font

Font used for non-Latin filenames when nonlatin_filenames is enabled.

Default: (picked automatically)

Note

This font is, when possible, picked automatically.

Can be set manually with the -Ik or -Ij option.

Equivalent command-line option: -Ik, -Ij.

numcaps

Number of captures, when the mode of operation is to do a fixed number of captures.

Default: 16.

Note

Unlike its command-line counterpart (-n or --numcaps), changing the value of numcaps doesn't automatically switch modes to do a fixed number of captures.

The mode of operation is controlled by timecode_from.

Equivalent command-line option: -n, --numcaps.

padding

Number of pixels between captures when placed in the contact sheet.

Default: 2

Related command-line option: -dp, --disable padding.

plain_messages

Allows disabling colourised feedback to the console.

Set to 1 to print plain, monochrome, feedback.

Default: 0 (≡ don't disable colours).

Note

Some colour will be printed by default until this option is handled. If you need to completely disable colour, e.g. to run in cron jobs, you can do so by setting an appropriate TERM environment variable e.g.

$ TERM=vt100 vcs

will make the script switch to monochrome output altogether.

Related command-line option: -Wc.

profiles

Loads profile(s).

Its value must be a profile name or a comma-separated list of profile names.

Example: profiles=white,mosaic will load the white and mosaic profiles.

Default: (empty).

Equivalent command-line option: -p, --profile.

pts_meta, pts_sign, pts_title, pts_tstamps

These variables control font size of each section in the contact sheet.

These sizes are expressed in points.

pts_meta — File meta-information. Default: 14

pts_title — Title (with option -T). Default: 33.

pts_tstamps — Timestamps. Default: 14.

Note

The value of pts_tstamps is reduced for smaller captures.

pts_sign — Footer/signature. Default: 10

quality

Image quality (level of compression) when outputting to lossy formats.

0 to 100, with 100 being the best quality (the least compression).

Default: 92.

Note

This value only affects the final image.

signature

Text before the user name in the footer.

Default: "Preview created by".

stderr

Standard error of programs when probing and capturing is sent here.

Default: /dev/null.

Note

Setting it to /dev/stderr to will return capturer programs to their normal behaviour.

stdout

Standard output of programs when probing and capturing is sent here.

Default: /dev/null.

Note

Setting it to /dev/stdout to will return capturer programs to their normal behaviour.

timecode_from

Controls the main mode of operation: capture at intervals or capture a fixed number of snapshots.

Possible values are $TC_INTERVAL to capture at intervals (will use interval), and $TC_NUMCAPS to capture a fixed number of images (will use numcaps).

Default: $TC_INTERVAL.

Note

This setting is affected by command-line options -i and -n.

Related command-line options: -i, --interval and -n, --numcaps

user

User name for the footer's signature.

Default: $(id -un) (≡ system user name).

Related command-line options: -u, --user and -U, --fullname

verbosity

Verbosity level.

Possible values:

ValueMeaning
$V_ALLPrint everything. Equivalent to $V_NOTICE.
$V_NONEPrint no feedback at all. Equivalent to command-line option -qq.
$V_ERRORPrint only errors.
$V_WARNPrint warnings and errors.
$V_INFOPrint informational messages, warnings and errors. This encompasses all messages, so it is equivalent to $V_ALL.

Default: $V_ALL.

Related command-line option: -q, --quiet.

SEE ALSO

vcs(1), id(1)



[1] ./vcs.conf won't be rejected if this field is missing, though it's preferable to include it to be ease moving the file to a different location or turning it into a profile.