| Next revision | Previous revision |
| vcs:conf_files [2010/03/01 13:42] – created 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'' | * 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**\\ |
| | |
| | # 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 ===== | ===== List of options ===== |
| |
| In a future version (probably 1.2) a [[vcs:new_conf|cleanup of these options]] will be made, some will be renamed and maybe others removed. Those options 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** |
| |
| FIXME List of options to be added | * 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 |
| |
| ^ Option ^ Default ^ Description ^ Additional details ^ Deprecated? ^ | ''Integer'' in //Additional details// means the value can only accept numeric values. |
| ^ Low level options ^^^^^ | |
| | ''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). | | | |
| | ''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)) | | |
| | ''DEBUG'' | 0 | Control debug mode default status | Integer: 0=Off, 1=On | | | |
| | ''decoder'' | ''$DEC_FFMPEG'' | Controls which capturer to use by default | Symbolic: ''$DEC_FFMPEG'' => FFmpeg, ''$DEC_MPLAYER'' => MPlayer | | | |
| ^ Main behaviour options ^^^^^ | |
| | ''DEFAULT_INTERVAL'' | 300 | Default capture interval | Integer: Seconds FIXME Does it take symbolic values? | | | |
| | ''DEFAULT_NUMCAPS'' | 16 | Default number of captures | Integer only | | | |
| | ''DEFAULT_COLS'' | 2 | Default number of columns | Integer only | | | |
| | ''user_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]]'') | | | |
| | ''output_format'' | png | Sets the output format | Should match the extension of a format known by ImageMagick | Maybe | | |
| | ''output_quality'' | 92 | Image quality for output in lossy formats | Integer, Only affects the final image | | | |
| |
| Cut'n paste: | ^ Option ^ Default ^ Description ^ Additional details ^ |
| <code> | ^ Main behaviour options ^^^^ |
| # Options used in imagemagick, these options set the final aspect | | ''interval'' | ''300'' | Default capture interval | [[vcs:docs:time_syntax|Time]] | |
| # of the contact sheet | | ''numcaps'' | ''16'' | Default number of captures | Integer | |
| declare output_format=png # ImageMagick decides the type from the extension | | ''columns'' | ''2'' | Default number of columns | Integer | |
| declare -i output_quality=92 # Output image quality (only affects the final | | ''padding'' | ''2'' | Padding between captures | Integer| |
| # image and obviously only in lossy formats) | | ''height'' | | Height | Can be a fixed value or a percentage. By default same as input | |
| # Colours, see convert -list color to get the list | | ''signature'' | "Preview created by" | Text before the user name in the signature | | |
| declare bg_heading=YellowGreen # Background for meta info (size, codec...) | | ''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]]'') | |
| declare bg_sign=SlateGray # Background for signature | | ''format'' | png | Sets the output format | Should match the extension of a format known by ImageMagick | |
| declare bg_title=White # Background for the title (see -T) | | ''quality'' | 92 | Image quality for output in lossy formats | Integer, Only affects the final image | |
| declare bg_contact=White # Background of the thumbnails | | ''decoder'' | ''$DEC_FFMPEG'' | Controls which capturer to use by default | Symbolic: ''$DEC_FFMPEG'' => FFmpeg, ''$DEC_MPLAYER'' => MPlayer | |
| declare bg_tstamps='#000000aa' # Background for the timestamps box | | ''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 | |
| declare fg_heading=black # Font colour for meta info box | | ''extended_factor'' | ''0'' | Set the extended factor. | ''0'' disables extended mode.\\ See [[vcs:docs:extended_mode]] | |
| declare fg_sign=black # Font colour for signature | | ''disable_shadows'' | ''0'' | Disables drop shadows when ''1''. | Equivalent command-line argument ''-ds''. | |
| declare fg_tstamps=white # Font colour for timestamps | | ''disable_timestamps'' | ''0'' | Disables timestamps on captures when ''1''. | Equivalent command-line argument ''-dt''. | |
| declare fg_title=Black # Font colour for the title | ^ Colours ((See ''$ convert -list color'')) ^^^^ |
| # Fonts, see convert -list type to get the list | | ''bg_heading'' | ''#afcd7a'' ((#afcd7a=RGB(175,205,122) ))((Up to 1.11 was ''YellowGreen'')) | Background for meta info (size, codec...) | | |
| declare font_tstamps=courier # Used for timestamps over the thumbnails | | ''bg_sign'' | ''SlateGray'' | Background for signature | | |
| declare font_heading=helvetica # Used for the heading (meta info box) | | ''bg_title'' | ''White'' | Background for the title (see ''-T'') | | |
| declare font_sign=$font_heading # Used for the signature box | | ''bg_contact'' | ''White'' | Background for the captures | | |
| # Unlike other font_ variables this doesn't take a font name directly | | ''bg_tstamps'' | ''#000000aa'' | Background for the timestamps box | | |
| # but is restricted to the $FF_ values. This is to allow overrides | | ''bg_all'' | | Sets the value of all ''bg_'' variables at once | Since 1.12.2 | |
| # from the command line to be placed anywhere, i.e. in | | ''fg_heading'' | ''Black'' | Font colour for meta info box | | |
| # $ vcs -I file.avi -O 'FONT_MINCHO=whatever' | | ''fg_sign'' | ''Black'' | Font colour for signature | | |
| # as the font is overridden is after requesting its use, it wouldn't be | | ''fg_tstamps'' | ''White'' | Font colour for timestamps | | |
| # affected | | ''fg_title'' | ''Black'' | Font colour for the title | | |
| # The other font_ variables are only affected by overrides and not command | | ''fg_all'' | | Sets the value of all ''fg_'' variables at once | Since 1.12.2 | |
| # line options that's why this one is special. | ^ Fonts ((See ''$ convert -list font'')) ^^^^ |
| declare font_filename=$FF_DEFAULT # Used to print only the filename in the heading | | ''font_tstamps'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was picked by ImageMagick)) | Used for timestamps over the thumbnails | | |
| declare font_title=$font_heading # 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, in points | | ''font_sign'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the signature box | | |
| declare -i pts_tstamps=18 # Used for the timestamps | | ''font_title'' | ''DejaVu-Sans-Book'' ((Up to 1.11 was ''helvetica'')) | Used for the title (see ''-T'') | | |
| declare -i pts_meta=16 # Used for the meta info box | | ''font_all'' | | Sets the value of all ''font_'' variables at once (''font_heading'', ''font_sign'', ''font_title'' and ''font_tstamps'') | Since 1.12.2 | |
| declare -i pts_sign=11 # Used for the signature | | ''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'' | |
| declare -i pts_title=36 # Used for the title (see -T) | | ''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'' | |
| # See --shoehorn | ^ Font sizes ((Specified in points)) ^^^^ |
| declare shoehorned= | | ''pts_tstamps'' | ''14'' ((Up to 1.11 was ''18'')) | Used for the timestamps | Integer. This value is reduced for smaller captures | |
| # See -E / $end_offset | | ''pts_meta'' | ''14'' ((Up to 1.11 was ''16'')) | Used for the meta info heading | Integer | |
| declare -i DEFAULT_END_OFFSET=60 | | ''pts_sign'' | ''10'' ((Up to 1.11 was ''11'')) | Used for the signature | Integer | |
| # If the video is less than this length, end offset won't be used at all | | ''pts_title'' | ''33'' ((Up to 1.11 was ''36'')) | Used for the title (see ''-T'') | Integer | |
| declare MIN_LENGTH_FOR_END_OFFSET=19m30s | ^ Low level options ^^^^ |
| # This can only be changed in the configuration file | | ''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). | |
| # Change it to change the safe renanimg: | | ''debug'' | ''0'' | Control debug mode default status | Integer: 0=Off, 1=On | |
| # When writing the output file, the input name + output extension is | | ''shoehorned'' | | Inserts additional parameters into ''ffmpeg'' or ''mplayer'' capture commands | Scheduled for removal in 1.13 | |
| # used (e.g.: "some video.avi.png"), if it already exists, though, | | ''end_offset'' | ''5%'' | Default value for end offset. See ''-E'' | | |
| # a number if appended to the name. This variable dictates where the number is | | ''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 | |
| # placed. | | ''verbosity'' | ''$V_ALL'' | Verbosity level | Available: ''$V_ALL'', ''$V_NONE'', ''$V_ERROR'', ''$V_WARN'', ''$V_INFO'' \\ See also ''[[vcs:docs:cli_options#quiet|--quiet]]'' | |
| # By default "%b-%N.%e" where: | | ''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 | |
| # %b is the basename (file name without extension) | | ''stdout'' | ''/dev/null'' | Standard output of decoder is sent here | | |
| # %N is the appended number | | ''stderr'' | ''/dev/null'' | Standard error of decoder is sent here | | |
| # %e is the extension | |
| # The default creates outputs like "output.avi-1.png" | |
| # | |
| # If overridden with an incorrect value it will be silently set to the default | |
| declare safe_rename_pattern="$DEFAULT_SAFE_REN_PATT" | |
| # Controls how many extra captures will be created in the extended mode | |
| # (see -e), 0 is the same as disabling the extended mode | |
| # This number is multiplied by the total number of captures to get | |
| # the number of extra captures. So, e.g. -n2 -e2 leads to 4 extra captures. | |
| declare extended_factor=0 | |
| # Options added always to the ones in the command line | |
| # (command line options override them). | |
| # Note using this is a bit tricky :P mostly because I've no clue of how this | |
| # should be done. | |
| # As an example: you want to set always the title to "My Title" and output | |
| # to jpeg: default_options="-T'My Title' -j" | |
| #declare default_options= | |
| # Verbosity level so far from the command line can only be muted (see -q) | |
| # it can be overridden, though | |
| declare -i verbosity=$V_ALL | |
| # When set to 0 the status messages printed by vcs while running | |
| # are coloured if the terminal supports it. Set to 1 if this annoys you. | |
| declare -i plain_messages=0 | |
| # Experimental in 1.0.7b: | |
| # Experiment to get international font support | |
| # I'll need to get some help here, so if you use anything beyond a latin | |
| # alphabet, please help me choosing the correct fonts | |
| # To my understanding Ming/MinchÅ fonts should cover most of Japanse, | |
| # Chinese and Korean | |
| # Apparently Kochi Mincho should include Hangul *and* Cyrillic... which would be | |
| # great :) Although it couldn't write my hangul test, and also the default font | |
| # (helvetica) in my system seems to include cyrillic too, or at least a subset of | |
| # it. | |
| declare FONT_MINCHO=/usr/share/fonts/truetype/kochi/kochi-mincho.ttf | |
| # Output of capturing programs is redirected here | |
| declare stdout=/dev/null stderr=/dev/null | |
| declare -i DVD_MODE=0 DVD_TITLE=1 | |
| declare DVD_FILE= | |
| declare -i multiple_input_files=0 | |
| |
| # }}} # End of override-able variables | |
| </code> | |