====== 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 ((''~'' means the user's home directory))
  * ''~/.vcs/vcs.conf'': Newer alternative to ''~/.vcs.conf'')
  * ''./vcs.conf'': (i.e. ''vcs.conf'' in the current directory) Per-dir configuration

See also //[[vcs:docs: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 ''[[vcs:docs:cli_options#jpeg|-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           | [[vcs:docs:time_syntax|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)'' ((i.e. your username)) | User name for signature. | See ''[[vcs:docs:cli_options#user|-u]]''  (''[[vcs:docs:cli_options#user|--user]]'') and ''[[vcs:docs:cli_options#fullname|-U]]'' (''[[vcs:docs:cli_options#fullname|--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 [[vcs:docs:usage#capture_count_modes|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 [[vcs:docs: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 ((See ''$ convert -list color'')) ^^^^
| ''bg_heading''       | ''#afcd7a'' ((#afcd7a=RGB(175,205,122) ))((Up to 1.11 was ''YellowGreen'')) | 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 ((See ''$ convert -list font'')) ^^^^
| ''font_tstamps''     | ''DejaVu-Sans-Book'' ((Up to 1.11 was picked by ImageMagick))  | Used for timestamps over the thumbnails | |
| ''font_heading''     | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the meta info heading          | |
| ''font_sign''        | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the signature box              | |
| ''font_title''       | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | 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 ((Specified in points)) ^^^^
| ''pts_tstamps''      | ''14'' ((Up to 1.11 was ''18'')) | Used for the timestamps         | Integer. This value is reduced for smaller captures |
| ''pts_meta''         | ''14'' ((Up to 1.11 was ''16'')) | Used for the meta info heading  | Integer |
| ''pts_sign''         | ''10'' ((Up to 1.11 was ''11'')) | Used for the signature          | Integer |
| ''pts_title''        | ''33'' ((Up to 1.11 was ''36'')) | 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 ''[[vcs:docs:cli_options#quiet|--quiet]]'' |
| ''simple_feedback'' | ''0'' | Controls colour output ((**From 1.11**: Also the alternative prefixes when no colour is available)) 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 | |