Configuration files

This syntax is updated to v1.12. Previous versions won't accept it.

There are four configuration files that will be loaded if found:

  • /etc/vcs.conf: System-wide configuration
  • ~/.vcs.conf: User configuration 1)
  • ~/.vcs/vcs.conf: Newer alternative to ~/.vcs.conf)
  • ./vcs.conf: (i.e. vcs.conf in the current directory) Per-dir configuration

See also Profiles for an alternative to auto-loading configuration files.

They're loaded in this order, and when a configuration option is present in more than one file the last file takes precedence.

Since 1.12: Additionally configuration files can be loaded manually with the --config (-C) command-line option, e.g. $ vcs -C myconfig.cfg. Files will need to have a comment like # vcs:conf: near the beginning or end to be accepted by --config.

Configuration files follow a simplified shell-like syntax:

  • Configuration options are set as SETTING=VALUE. Spaces in the value are allowed. Don't quote the value unless you want quotes displayed.
  • Everything following a ‘#’ or ‘;’ are comments (and are ignored).
    • Use ‘$#’ to put # in a value
    • ; is always ignored
  • Options not recognised will be ignored

Certain setings have no equivalent command-line option. They can be set from the command-line by using the special option -O (--override) followed by OPTION=VALUE. In general, customisation of the script shouldn't require any editing of the script itself.

Examples

  • Setting background colour for the heading to blue: bg_heading=blue. Added to a configuration file or from the command-line: $ vcs -O 'bg_heading=blue' file.avi
  • Output to JPEG by default: format=jpg. Added to a configuration file (the command-line option -j does the same for a single run).

Example configuration file

# Output to JPEG...
format=jpg
# ...with 90% quality
quality=90
# Sign as "myname"
user=myname
# Use "Snapshots grabbed by myname" instead of "Preview created by myname"
signature=Snapshots grabbed by

List of options

These are the accepted options in 1.12, previous versions had different names

  • Option names are case insensitive
  • font_filename was removed in 1.12 as part of the reworked handling of non-latin filename, next version will provide an alternative

Integer in Additional details means the value can only accept numeric values.

Option Default Description Additional details
Main behaviour options
interval 300 Default capture interval Time
numcaps 16 Default number of captures Integer
columns 2 Default number of columns Integer
padding 2 Padding between captures Integer
height Height Can be a fixed value or a percentage. By default same as input
signature “Preview created by” Text before the user name in the signature
user $(id -un) 2) User name for signature. See -u (--user) and -U (--fullname)
format png Sets the output format Should match the extension of a format known by ImageMagick
quality 92 Image quality for output in lossy formats Integer, Only affects the final image
decoder $DEC_FFMPEG Controls which capturer to use by default Symbolic: $DEC_FFMPEG ⇒ FFmpeg, $DEC_MPLAYER ⇒ MPlayer
timecode_from $TC_INTERVAL Selects between number of captures or interval mode Symbolic: $TC_INTERVAL ⇒ interval mode, $TC_NUMCAPS ⇒ number of captures mode
extended_factor 0 Set the extended factor. 0 disables extended mode.
See Extended mode
disable_shadows 0 Disables drop shadows when 1. Equivalent command-line argument -ds.
disable_timestamps 0 Disables timestamps on captures when 1. Equivalent command-line argument -dt.
Colours 3)
bg_heading #afcd7a 4)5) Background for meta info (size, codec…)
bg_sign SlateGray Background for signature
bg_title White Background for the title (see -T)
bg_contact White Background for the captures
bg_tstamps #000000aa Background for the timestamps box
bg_all Sets the value of all bg_ variables at once Since 1.12.2
fg_heading Black Font colour for meta info box
fg_sign Black Font colour for signature
fg_tstamps White Font colour for timestamps
fg_title Black Font colour for the title
fg_all Sets the value of all fg_ variables at once Since 1.12.2
Fonts 6)
font_tstamps DejaVu-Sans-Book 7) Used for timestamps over the thumbnails
font_heading DejaVu-Sans-Book 8) Used for the meta info heading
font_sign DejaVu-Sans-Book 9) Used for the signature box
font_title DejaVu-Sans-Book 10) Used for the title (see -T)
font_all Sets the value of all font_ variables at once (font_heading, font_sign, font_title and font_tstamps) Since 1.12.2
nonlatin_font (detected) Font used for non-latin filenames. See $font_filename and -I. Tries to pick automatically, can be set manually with -I. Used to be FONT_MINCHO
nonlatin_filenames 0 Control the font used to print the filename in the sheet header Since 1.12.2.
0: Use standard font (default)
1: Use nonlatin_font
Font sizes 11)
pts_tstamps 14 12) Used for the timestamps Integer. This value is reduced for smaller captures
pts_meta 14 13) Used for the meta info heading Integer
pts_sign 10 14) Used for the signature Integer
pts_title 33 15) Used for the title (see -T) Integer
Low level options
getopt getopt GNU getopt command The getopt command must be set correctly or the script won't work. Must be a version accepting GNU syntax. Can only be set in configuration files (i.e. not from the command-line).
debug 0 Control debug mode default status Integer: 0=Off, 1=On
shoehorned Inserts additional parameters into ffmpeg or mplayer capture commands Scheduled for removal in 1.13
end_offset 5% Default value for end offset. See -E
safe_rename_pattern %b-%N.%e Pattern used for output files to avoid overwriting existing files. %b: Basename
%N: Incremental number
%e: extension
Scheduled for removal in 1.13
verbosity $V_ALL Verbosity level Available: $V_ALL, $V_NONE, $V_ERROR, $V_WARN, $V_INFO
See also --quiet
simple_feedback 0 Controls colour output 16) to console. Set to 1 to disable colour
stdout /dev/null Standard output of decoder is sent here
stderr /dev/null Standard error of decoder is sent here
1)
~ means the user's home directory
2)
i.e. your username
3)
See $ convert -list color
4)
#afcd7a=RGB(175,205,122)
5)
Up to 1.11 was YellowGreen
6)
See $ convert -list font
7)
Up to 1.11 was picked by ImageMagick
8) , 9) , 10)
Up to 1.11 was helvetica
11)
Specified in points
12)
Up to 1.11 was 18
13)
Up to 1.11 was 16
14)
Up to 1.11 was 11
15)
Up to 1.11 was 36
16)
From 1.11: Also the alternative prefixes when no colour is available
All dates/times in this page are UTC.
  • vcs/docs/conf_files.txt
  • Last modified: 2016/04/17 23:28
  • by Toni Corvera