| Both sides previous revision Previous revision Next revision | Previous revision |
| vcs:conf_files [2010/03/08 00:02] – Fixes Toni Corvera | vcs:docs:conf_files [2016/04/17 23:28] (current) – ↷ Links adapted because of a move operation Toni Corvera |
|---|
| ====== Configuration files ====== | ====== Configuration files ====== |
| |
| There are three configuration files that will be loaded if found: | **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 | * ''/etc/vcs.conf'': System-wide configuration |
| * ''~/.vcs.conf'': User configuration ((''~'' means the user's home directory)) | * ''~/.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 | * ''./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. | 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 files follow a simplified shell-like syntax: |
| * Lines starting with ''#'' are comments (and are ignored) | * Configuration options are set as ''SETTING=VALUE''. Spaces in the value are allowed. Don't quote the value unless you want quotes displayed. |
| * Configuration options are set as ''OPTION=VALUE''. Spaces in the value are allowed, the current version will display any quotes included. | * Everything following a ‘''#''’ or ‘'';''’ are comments (and are ignored). |
| | * Use ‘''$#''’ to put ''#'' in a value |
| | * '';'' is always ignored |
| * Options not recognised will be ignored | * Options not recognised will be ignored |
| |
| Certain options 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. | 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**\\ | **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'' | * 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: ''output_format=jpg''. Added to a configuration file (the command-line option ''[[vcs:cli_options#jpeg|-j]]'' does the same for a single run). | * 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**\\ | **Example configuration file**\\ |
| |
| # Output to JPEG... | # Output to JPEG... |
| output_format=jpg | format=jpg |
| # ...with 90% quality | # ...with 90% quality |
| output_quality=90 | quality=90 |
| # Sign as "myname" | # Sign as "myname" |
| user=myname | user=myname |
| # Use "Snapshots grabbed by myname" instead of "Preview created by myname" | # Use "Snapshots grabbed by myname" instead of "Preview created by myname" |
| user_signature=Snapshots grabbed by | signature=Snapshots grabbed by |
| |
| ===== List of options ===== | ===== List of options ===== |
| |
| In a future version (probably 1.12) a [[vcs:devel:conf:new_syntax|cleanup of these options]] will be made, some will be renamed and maybe others removed. Those options will be marked as deprecated in the list below. The list of deprecated options and their replacements is not final. | **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. | ''Integer'' in //Additional details// means the value can only accept numeric values. |
| |
| ^ Option ^ Default ^ Description ^ Additional details ^ Deprecated? ^ | ^ Option ^ Default ^ Description ^ Additional details ^ |
| ^ Main behaviour options ^^^^^ | ^ Main behaviour options ^^^^ |
| | ''DEFAULT_INTERVAL'' | ''300'' | Default capture interval | Integer: Seconds FIXME Does it take symbolic values? | Already. Use ''interval'' instead | | | ''interval'' | ''300'' | Default capture interval | [[vcs:docs:time_syntax|Time]] | |
| | ''DEFAULT_NUMCAPS'' | ''16'' | Default number of captures | Integer | Already. Use ''numcaps'' instead | | | ''numcaps'' | ''16'' | Default number of captures | Integer | |
| | ''DEFAULT_COLS'' | ''2'' | Default number of columns | Integer | Already. Use ''cols'' instead | | | ''columns'' | ''2'' | Default number of columns | Integer | |
| | ''HPAD'' | ''2'' | Padding between captures | Integer. **Since 1.11** | | | | ''padding'' | ''2'' | Padding between captures | Integer| |
| | ''th_height'' | | Height | Can be a fixed value or a percentage. By default same as input. **Since 1.11** | | | | ''height'' | | Height | Can be a fixed value or a percentage. By default same as input | |
| | ''user_signature'' | "Preview created by" | Text before the user name in the signature | | | | | ''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:cli_options#user|-u]]'' (''[[vcs:cli_options#user|--user]]'') and ''[[vcs:cli_options#fullname|-U]]'' (''[[vcs:cli_options#fullname|--fullname]]'') | | | | ''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]]'') | |
| | ''output_format'' | png | Sets the output format | Should match the extension of a format known by ImageMagick | Maybe | | | ''format'' | png | Sets the output format | Should match the extension of a format known by ImageMagick | |
| | ''output_quality'' | 92 | Image quality for output in lossy formats | Integer, Only affects the final image | | | | ''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 | | | | ''decoder'' | ''$DEC_FFMPEG'' | Controls which capturer to use by default | Symbolic: ''$DEC_FFMPEG'' => FFmpeg, ''$DEC_MPLAYER'' => MPlayer | |
| | ''timecode_from'' | ''$TC_INTERVAL'' | Selects between [[vcs:usage#capture_count_modes|number of captures or interval mode]] | Symbolic: ''$TC_INTERVAL'' => interval mode, ''$TC_NUMCAPS'' => number of captures mode | Yes ((Replaced by capture_mode)) | | | ''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:extended_mode]] | | | | ''extended_factor'' | ''0'' | Set the extended factor. | ''0'' disables extended mode.\\ See [[vcs:docs:extended_mode]] | |
| | ''DVD_MODE'' | ''0'' | Controls DVD mode | Set to 1 to enable. See also ''%%--%%dvd'' | | | | ''disable_shadows'' | ''0'' | Disables drop shadows when ''1''. | Equivalent command-line argument ''-ds''. | |
| | ''DVD_TITLE'' | ''1'' | Default DVD title (track) to capture in DVD mode | | | | | ''disable_timestamps'' | ''0'' | Disables timestamps on captures when ''1''. | Equivalent command-line argument ''-dt''. | |
| | ''DVD_FILE'' | | Default DVD device or ISO | | | | ^ Colours ((See ''$ convert -list color'')) ^^^^ |
| ^ 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_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_sign'' | ''SlateGray'' | Background for signature | | | | | ''bg_title'' | ''White'' | Background for the title (see ''-T'') | | |
| | ''bg_title'' | ''White'' | Background for the title (see ''-T'') | | | | | ''bg_contact'' | ''White'' | Background for the captures | | |
| | ''bg_contact'' | ''White'' | Background for the captures | | | | | ''bg_tstamps'' | ''#000000aa'' | Background for the timestamps box | | |
| | ''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_heading'' | ''Black'' | Font colour for meta info box | | |
| | ''fg_sign'' | ''Black'' | Font colour for signature | | | | | ''fg_sign'' | ''Black'' | Font colour for signature | | |
| | ''fg_tstamps'' | ''White'' | Font colour for timestamps | | | | | ''fg_tstamps'' | ''White'' | Font colour for timestamps | | |
| | ''fg_title'' | ''Black'' | Font colour for the title | | | | | ''fg_title'' | ''Black'' | Font colour for the title | | |
| ^ Fonts ((See ''$ convert -list font'')) ^^^^^ | | ''fg_all'' | | Sets the value of all ''fg_'' variables at once | Since 1.12.2 | |
| | ''font_tstamps'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was picked by ImageMagick)) | Used for timestamps over the thumbnails | | | | ^ Fonts ((See ''$ convert -list font'')) ^^^^ |
| | ''font_heading'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the meta info heading | | | | | ''font_tstamps'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was picked by ImageMagick)) | Used for timestamps over the thumbnails | | |
| | ''font_sign'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the signature box | | | | | ''font_heading'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the meta info heading | | |
| | ''font_filename'' | ''$FF_DEFAULT'' | Picks filename font, set to ''$FF_MINCHO'' to use the alternate font | This variable only accepts the ''$FF_*'' constants | | | | ''font_sign'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the signature box | | |
| | ''FONT_MINCHO'' | | Font used for non-latin filenames. | See ''$font_filename'' and ''-I''. Tries to pick automatically, can be set manually with -I | Partly ((Will be renamed)) | | | ''font_title'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the title (see ''-T'') | | |
| | ''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 | |
| ^ Font sizes ((Specified in points)) ^^^^^ | | ''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'' | |
| | ''pts_tstamps'' | ''14'' ((Up to 1.11 was ''18'')) | Used for the timestamps | Integer. This value is reduced for smaller captures | | | | ''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'' | |
| | ''pts_meta'' | ''14'' ((Up to 1.11 was ''16'')) | Used for the meta info heading | Integer | | | ^ Font sizes ((Specified in points)) ^^^^ |
| | ''pts_sign'' | ''10'' ((Up to 1.11 was ''11'')) | Used for the signature | Integer | | | | ''pts_tstamps'' | ''14'' ((Up to 1.11 was ''18'')) | Used for the timestamps | Integer. This value is reduced for smaller captures | |
| | ''pts_title'' | ''33'' ((Up to 1.11 was ''36'')) | Used for the title (see ''-T'') | Integer | | | | ''pts_meta'' | ''14'' ((Up to 1.11 was ''16'')) | Used for the meta info heading | Integer | |
| ^ Low level options ^^^^^ | | ''pts_sign'' | ''10'' ((Up to 1.11 was ''11'')) | Used for the signature | Integer | |
| | ''GETOPT'' | ''getopt'' | 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). | | | | ''pts_title'' | ''33'' ((Up to 1.11 was ''36'')) | Used for the title (see ''-T'') | Integer | |
| | ''DEBUG'' | ''0'' | Control debug mode default status | Integer: 0=Off, 1=On | | | ^ Low level options ^^^^ |
| | ''shoehorned'' | | Inserts additional parameters into ''ffmpeg'' or ''mplayer'' capture commands | | Yes ((No longer believed to be required)) | | | ''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). | |
| | ''DEFAULT_END_OFFSET'' | ''60'' | Default value for end offset. See ''-E'' | | Yes ((Will be simplified in future versions)) | | | ''debug'' | ''0'' | Control debug mode default status | Integer: 0=Off, 1=On | |
| | ''MIN_LENGTH_FOR_END_OFFSET'' | ''19m30s'' | End offset is only used if the video is at least this long | | Yes ((Will be simplified in future versions)) | | | ''shoehorned'' | | Inserts additional parameters into ''ffmpeg'' or ''mplayer'' capture commands | Scheduled for removal in 1.13 | |
| | ''safe_rename_pattern'' | ''%b-%N.%e'' | Pattern used for output files to avoid overwriting existing files. | ''%b'': Basename \\ ''%N'': Incremental number \\ ''%e'': extension | | | | ''end_offset'' | ''5%'' | Default value for end offset. See ''-E'' | | |
| | ''verbosity'' | ''$V_ALL'' | Verbosity level | Available: ''$V_ALL'', ''$V_NONE'', ''$V_ERROR'', ''$V_WARN'', ''$V_INFO'' \\ See also ''[[vcs:cli_options#quiet|--quiet]]'' | | | | ''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 | |
| | ''plain_messages'' | ''0'' | Controls colour output ((**From 1.11**: Also the alternative prefixes when no colour is available)) to console. | Set to ''1'' to disable colour | | | | ''verbosity'' | ''$V_ALL'' | Verbosity level | Available: ''$V_ALL'', ''$V_NONE'', ''$V_ERROR'', ''$V_WARN'', ''$V_INFO'' \\ See also ''[[vcs:docs:cli_options#quiet|--quiet]]'' | |
| | ''stdout'' | ''/dev/null'' | Standard output of decoder is sent here | | Maybe ((Might be moved to the ''%%--%%undocumented'' subset)) | | | ''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 | |
| | ''stderr'' | ''/dev/null'' | Standard error of decoder is sent here | | Maybe ((Might be moved to the ''%%--%%undocumented'' subset)) | | | ''stdout'' | ''/dev/null'' | Standard output of decoder is sent here | | |
| | | ''stderr'' | ''/dev/null'' | Standard error of decoder is sent here | | |
| |