Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
vcs:docs:conf_files [2010/04/06 17:55]
Toni Corvera Remove DVD config, not yet supported
vcs:docs:conf_files [2016/04/17 23:28] (current)
Toni Corvera ↷ Links adapted because of a move operation
Line 1: Line 1:
 ====== 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 allowedthe 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 madesome 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 ​          ​| ​IntegerSeconds 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]] | 
-^ Colours ((See ''​$ convert -list color''​)) ​^^^^^ +| ''​disable_shadows'' ​ | ''​0'' ​ | Disables drop shadows when ''​1''​. | Equivalent command-line argument ''​-ds''​. | 
-| ''​bg_heading'' ​      | ''#​afcd7a''​ ((#​afcd7a=RGB(175,​205,​122) ))((Up to 1.11 was ''​YellowGreen''​)) | Background for meta info (size, codec...) ​| | +| ''​disable_timestamps'' ​ | ''​0'' ​ | Disables timestamps on captures when ''​1''​. | Equivalent command-line argument ''​-dt''​. ​
-| ''​bg_sign'' ​         | ''​SlateGray''​ | Background for signature ​             ​| | +^ Colours ((See ''​$ convert -list color''​)) ^^^^ 
-| ''​bg_title'' ​        | ''​White'' ​    | Background for the title (see ''​-T''​) ​| | +| ''​bg_heading'' ​      | ''#​afcd7a''​ ((#​afcd7a=RGB(175,​205,​122) ))((Up to 1.11 was ''​YellowGreen''​)) | Background for meta info (size, codec...) | | 
-| ''​bg_contact'' ​      | ''​White'' ​    | Background for the captures ​          | | +| ''​bg_sign'' ​         | ''​SlateGray''​ | Background for signature ​             | | 
-| ''​bg_tstamps'' ​      | ''#​000000aa''​ | Background for the timestamps box     | | | +| ''​bg_title'' ​        | ''​White'' ​    | Background for the title (see ''​-T''​) | | 
-| ''​fg_heading'' ​      | ''​Black'' ​    | Font colour for meta info box         | | +| ''​bg_contact'' ​      | ''​White'' ​    | Background for the captures ​          | | 
-| ''​fg_sign'' ​         | ''​Black'' ​    | Font colour for signature ​            | | +| ''​bg_tstamps'' ​      | ''#​000000aa''​ | Background for the timestamps box     | | 
-| ''​fg_tstamps'' ​      | ''​White'' ​    | Font colour for timestamps ​           ​| | +| ''​bg_all'' ​          | | Sets the value of all ''​bg_''​ variables at once | Since 1.12.2 ​
-| ''​fg_title'' ​        | ''​Black'' ​    | Font colour for the title             | | | +| ''​fg_heading'' ​      | ''​Black'' ​    | Font colour for meta info box         | | 
-^ Fonts ((See ''​$ convert -list font''​)) ​^^^^^ +| ''​fg_sign'' ​         | ''​Black'' ​    | Font colour for signature ​            | | 
-| ''​font_tstamps'' ​    | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was picked by ImageMagick)) ​ | Used for timestamps over the thumbnails ​| | +| ''​fg_tstamps'' ​      | ''​White'' ​    | Font colour for timestamps ​           | | 
-| ''​font_heading'' ​    | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was ''​helvetica''​)) | Used for the meta info heading ​         ​| | +| ''​fg_title'' ​        | ''​Black'' ​    | Font colour for the title             | | 
-| ''​font_sign'' ​       | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was ''​helvetica''​)) | Used for the signature box              ​| | +| ''​fg_all'' ​          | | Sets the value of all ''​fg_''​ variables at once | Since 1.12.2 ​
-| ''​font_filename'' ​   | ''​$FF_DEFAULT'' ​| Picks filename font, set to ''​$FF_MINCHO'' ​to use the alternate font This variable only accepts ​the ''​$FF_*'' ​constants ​| | +^ Fonts ((See ''​$ convert -list font''​)) ^^^^ 
-| ''​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_tstamps'' ​    | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was picked by ImageMagick)) ​ | Used for timestamps over the thumbnails | | 
-''​font_title'' ​      ​| ''​DejaVu-Sans-Book'' ​((Up to 1.11 was ''​helvetica''​)) | Used for the title (see ''​-T''​)         | | +| ''​font_heading'' ​    | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was ''​helvetica''​)) | Used for the meta info heading ​         | | 
-^ Font sizes ((Specified in points)) ​^^^^^ +| ''​font_sign'' ​       | ''​DejaVu-Sans-Book''​ ((Up to 1.11 was ''​helvetica''​)) | Used for the signature box              | | 
-| ''​pts_tstamps'' ​     | ''​14''​ ((Up to 1.11 was ''​18''​)) | Used for the timestamps ​        | Integer. This value is reduced for smaller captures ​+| ''​font_title'' ​      ​| ''​DejaVu-Sans-Book'' ​((Up to 1.11 was ''​helvetica''​)) | Used for the title (see ''​-T''​) ​        
-| ''​pts_meta'' ​        | ''​14''​ ((Up to 1.11 was ''​16''​)) | Used for the meta info heading ​ | Integer ​+| ''​font_all'' ​        | | Sets the value of all ''​font_'' ​variables at once (''​font_heading'',​ ''​font_sign'',​ ''​font_title''​ and ''​font_tstamps''​) ​Since 1.12.2 ​
-| ''​pts_sign'' ​        | ''​10''​ ((Up to 1.11 was ''​11''​)) | Used for the signature ​         | Integer ​+| ''​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_title'' ​       | ''​33''​ ((Up to 1.11 was ''​36''​)) | Used for the title (see ''​-T''​) | Integer ​+| ''​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''​ | 
-^ Low level options ​   ​^^^^^ +^ Font sizes ((Specified in points)) ^^^^ 
-| ''​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_tstamps'' ​     | ''​14''​ ((Up to 1.11 was ''​18''​)) | Used for the timestamps ​        | Integer. This value is reduced for smaller captures | 
-| ''​DEBUG'' ​           | ''​0'' ​  | Control debug mode default status ​ | Integer: 0=Off, 1=On +| ''​pts_meta'' ​        | ''​14''​ ((Up to 1.11 was ''​16''​)) | Used for the meta info heading ​ | Integer | 
-| ''​shoehorned'' ​      ​| ​        | Inserts additional parameters into ''​ffmpeg''​ or ''​mplayer''​ capture commands | | Yes ((No longer believed to be required)) ​+| ''​pts_sign'' ​        | ''​10''​ ((Up to 1.11 was ''​11''​)) | Used for the signature ​         | Integer | 
-| ''​DEFAULT_END_OFFSET''​ | ''​60''​ | Default value for end offset. See ''​-E''​ | | Yes ((Will be simplified in future versions)) | +| ''​pts_title'' ​       | ''​33''​ ((Up to 1.11 was ''​36''​)) | Used for the title (see ''​-T''​) | Integer | 
-| ''​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)) ​+^ Low level options ​   ^^^^ 
-| ''​safe_rename_pattern''​ | ''​%b-%N.%e''​ | Pattern used for output files to avoid overwriting existing files. | ''​%b'':​ Basename \\ ''​%N'':​ Incremental number \\ ''​%e'':​ extension ​+| ''​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). | 
-| ''​verbosity'' ​       | ''​$V_ALL''​ | Verbosity level | Available: ''​$V_ALL'',​ ''​$V_NONE'',​ ''​$V_ERROR'',​ ''​$V_WARN'',​ ''​$V_INFO''​ \\ See also ''​[[vcs:​cli_options#​quiet|--quiet]]'' ​+| ''​debug'' ​           | ''​0'' ​  | Control debug mode default status ​ | Integer: 0=Off, 1=On | 
-| ''​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 ​+| ''​shoehorned'' ​      ​| ​        | Inserts additional parameters into ''​ffmpeg''​ or ''​mplayer''​ capture commands | Scheduled for removal in 1.13 
-| ''​stdout'' ​ | ''/​dev/​null''​ | Standard output of decoder is sent here | | Maybe ((Might be moved to the ''​%%--%%undocumented''​ subset)) ​+| ''​end_offset''​ | ''​5%''​ | Default value for end offset. See ''​-E''​ | | 
-| ''​stderr'' ​ | ''/​dev/​null''​ | Standard error of decoder is sent here | | Maybe ((Might be moved to the ''​%%--%%undocumented''​ subset)) ​|+| ''​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 | |
  
All dates/times in this page are UTC.