configuration

##The Options There are options to use on the command line, others you use in your configuration file, global or for just one channel. Or you can use them in all of those circumstances. Location will tell you. The header is the name to use in your configuration, any commandline options are given separatly after Commandline and often have hivens in stead of underscores.

####help

• Location: Commandline
• Commandline: --help, -h

####version

• Location: Commandline
• Commandline: --version, -V

Display frontend and API version

####description

• Location: Commandline
• Commandline: --description

Display a short description of the frontend

####long_descr

• Location: Commandline
• Commandline: --long-descr, -d

Display a more extensive description of the API

####capabilities

• Location: Commandline
• Commandline: --capabilities

Does return:

baseline
cache
manualconfig
preferredmethode

####preferredmethod

• Location: Commandline
• Commandline: --preferredmethod

Does return:

allatonce

####language

• Location: Commandline , Global
• Commandline: --language, -l
• Values: (two char string) at present: en|nl
• Default: en

Sets the language for log and most messages. If a text is missing for that language, fall-back to the English text is tried, else an error is given. See in the .\tvgrabpyAPI\texts directory for the available language files. See languagefile on creating extra language files.

####show-sources

• Location: Commandline
• Commandline: --show-sources

List all sources used by this frontend

####show-detail-sources

• Location: Commandline
• Commandline: --show-detail-sources

List all sources used by this frontend with detail pages

####show-logo-sources

• Location: Commandline
• Commandline: --show-logo-sources

List all logo sources for this frontend

####log_level

• Location: Global
• Values: (integer) 0-511
• Default: 175

This is the sum of one or more of the following values:

• 0 Nothing (use quiet mode to turns off screen output, but keep a log)
• 1 include Errors and Warnings
• 2 include page fetches
• 4 include (merge) summaries
• 8 include detail fetches and ttvdb lookups to the screen
• 16 include detail fetches and ttvdb lookups to the log
• 32 include matchlogging (see match_log_level)
• 64 Title renames and other title manipulations according to the tables in tv_grab_xx_py.set
• 128 ttvdb failures
• 256 DataTreeGrab warnings

####match_log_level

• Location: Global
• Values: (integer) 0-15
• Default: 11

What to log about the merging process and it is the sum of one or more of the following values. Only relevant if log_level 32 is set:

• 0 = Log Nothing (just the above summary if selected)
• 1 = log not matched programs that are added
• 2 = log left over programs that are not added
• 4 = Log matches
• 8 = Log group slots

####mail_log

• Location: Global
• Values: boolean
• Default: False

Mail your log using the below settings. It does not support ssl/starttls or authentication as it is meant to be used with your own local linux mail system. When you the first time set this option, you best first test it in a console as any errors do not show in the log which then already is closed.

####mailserver

• Location: Global
• Values: string
• Default: localhost

The dns-name for your mailserver.

####mailport

• Location: Global
• Values: Integer
• Default: 25

The port your mailserver is listening.

####mail_log_address

• Location: Global
• Values: string
• Default: postmaster

The mail-address to send the log to.

####quiet

• Location: Commandline, Global
• Commandline: --quiet, -q /--verbose , -v
• Values: boolean
• Default: False

Whether to send any logging to the screen

####configure

• Location: Commandline
• Commandline: --configure, -c

Fetch the channel information for all the sources and create a configuration file. If it allready exists use the there found settings and rename the old one to *.old. The default name is ~/.xmltv/tv_grab_xx_py.conf but you can specify a different file and location with the --config_file option.
Use this option also to update your lineup when in your log changes are announced. Existing settings are always kept!
If you run --configure as root without giving a filename, the new configuration is placed in /etc/tvgrabpyAPI and will be used as a default if a configuration in the users ~/.xmltv directory does not exist. The log however will be placed in ~/.xmltv. Running in normal fetching mode as root will fail! Also be aware that --configure also stores configuration data in the sqlite database. It is therefore advisable to at least ones run --configure as the user, and thus with the database, used on normal runs.

####group_active_channels

• Location: Commandline, Global
• Commandline: --group_active_channels
• Values: boolean
• Default: False

As a commandline option only relevant together with --configure and on updating an existing configuration file. You can also set it to True in your configuration, the commandline option then has no longer any effect. The commandline option will not change the value in your configuration.
Place all active channels at the top of the [Channels] section in a separate group.

####config_file

• Location: Commandline
• Commandline: --config-file, -C <bestand>
• Values: Path and filename
• Default: ~/.xmltv/tv_grab_xx_py.conf

The configuration file to use. This name (and location) is also used for the log-file but with .log appended in stead of the default: ~/.xmltv/tv_grab_xx_py.log. (replace xx with the language/country short in the name of your grabber).
If there are insufficient rights or the file does not exist a fatal error will follow, but not after first checkking if a default configuration in /etc/tvgrabpyAPI can be found and opened.

####save_options

• Location: Commandline
• Commandline: --save-options, -O

Save the current set commandline options to the configuration file.

####always_use_json

• Location: Global
• Values: boolean
• Default: True

Many settings are set in the grabber and source JSON files downloaded from internet and kept up-to-date there. Some of these settings you can change in your configuration file, but would get reset on running --configure. Setting this value in your configuration to False prevents this. The effected settings are prime_source, the channelgroup, the channelname and the channellogo. The disadvantage of turning this off is that you do not benefit from any update on those settings.

####output_file

• Location: Commandline, Global
• Commandline: --output ,-W <bestand>
• Values: Path and filename or None
• Default: None

By default the resulting XMLTV file is sent to stdout (the value None). Here you can give a filename with a complete path to sent it to. If insufficient rights exist a fatal error follows.

####output-windows-codeset

• Location: Commandline
• Commandline: --output-windows-codeset
• Values: boolean
• Default: False

By default the XMLTV output is coded in UTF-8. Especially under msWindows you can choose to use the default Windows cp1252 codeset instead. All screen-output is under msWindows already coded with this codeset.

####cache

• Location: Commandline
• Commandline: --cache, -A <bestand>
• Values: Path and filename or None
• Default: ~/.xmltv/program_cache3

Sets the file and pathname to use for the sqlite cache. Setting it to None disables the cache. The here given name is appended with .db.

####use-only-cache

• Location: Commandline
• Commandline: --use-only-cache, -U

Tels the API to not extract data from internet. It will only use already gathered data from the cache. This will make a run very fast.

####clean_cache

• Location: Commandline
• Commandline: --clean_cache

Remove outdated (older then yesterday) data from the cache.
This happens automatically on every run.

####clear_cache

• Location: Commandline
• Commandline: --clear_cache

Clear all programme data from the database.
This has preference over removing the database file as also configuration and ttvdb data is stored there.

####clear_ttvdb

• Location: Commandline
• Commandline: --clear_ttvdb

Clear all ttvdb data from the database.
Before possible retrieving data from theTVdb.com first the database is checked. Only if a series is not found there or the last check on theTVdb.com is more then a month old the theTVdb.com is queried. If a series is not found there an empty record is inserted into the database to prevent repeatedly fruitless queries for the next month.

####add-ttvdb-title

• Location: Commandline
• Commandline: --add-ttvdb-title <serie titel> [<taalcode>]
• Values: string optionally followed by a language code

It is possible that a series present on theTVdb.com is not found. For instance the series 'Castle' is stored as 'Castle (2009)` as already an earlier series by the name 'Castle' exists. Through this option you can tell the API to look for 'Castle (2009)'. When you call this option a list of possible matching series is shown, giving you the oportunity to select the right one. At the same time then the data for this series is stored into the database. By default data for English and the for your frontend defined languages is retrieved. You can add optionally an extra two letter language code after the series title. If spaces are precent in the title you need to enclose it with quotes.

####xmltvid_alias

• Location: Channel
• Values: string
• Default: None

By default the chanids set through the JSON data-files and present in your configuration-file as the third item in the channel string is used as the xmltvid. You can however choose to set a different xmltvid for any of your channels. If for whatever reason a chanid changes, we also can set such an alias in the JSON data-files. If then on running --configure the old chanid is found active, this old chanid is set as xmltvid_alias for that channel.

####legacy_xmltvids

• Location: Commandline, Global, Channel
• Commandline: --legacy_xmltvids ,-X
• Values: boolean
• Default: False

Only valid for the Dutch frontend. If set to True xmltvids as used pre version 2.2 are used for the sources up to 3. You are not encouraged to use it as in time we might remove this option. Use xmltvid_alias to set a not default xmltvid instead.

####compat

• Location: Commandline, Global, Channel
• Commandline: --compat, -x
• Values: boolean
• Default: False

According to the xmltv.dtd an xmltvid should take the form . in a URL like form. By default we do not append such a sourcename (as there are potentially multiple sources). By setting this value to True, either global or per channel, the in the JSON data-file set sourcename is appended to the chanid to create the xmltvid. Also to a set xmltvid_alias this sourcename is appended.

####logos

• Location: Commandline, Global, Channel
• Commandline: --logos / --nologos, -n
• Values: boolean
• Default: True

Add if present in your configuration a URL to a channel-logo to the xmltv output.

####output_tz

• Location: Global
• Values: A string like "Europe/Amsterdam" or "UTC"
• Default: "UTC" (depending on what your frontend has set)

With this option you determine what timezone is used in the xmltv output for start and stop times. See in Linux under /usr/share/zoneinfo for possible values. That path might differ slightly on your Linux flavor. Your frontend should set it to a reasonable default.
On the commandline you can always switch to "UTC" with the --utc option. If you give an invalid timezone, UTC is used.

####utc

• Location: Commandline, (Global)
• Commandline: --utc ,-u

Use UTC times in the xmltv output file. Originally in the configuration a similar boolean use_utc option is supported. It will be recognized, but use output_tz = UTC instead.

####max_simultaneous_fetches

• Location: Global
• Values: integer
• Default: 5

If your frontend knows many sources, your internet-connection can get saturated when every source tries to grab a page at the same time causing failures. Therfore by default the number of simultaneous fetches is maxed to 5. If you have a very wide and fast or small and slow connection, you can raise or lower this value. Do not expect to realy lower the total fetch time by raising this value as there is a mandatory waiting time between every fetch on one source. Failures on the other hand will raise this time as they are tried a second time later.

####global_timeout

• Location: Global
• Values: integer
• Default: 10

This is the time (in seconds) to wait on any request completion before calling it a failure. If you see many incomplete reads or time-out errors and you have an old and slow internet connection raising this might help. If it does not help lowering it can speed-up the total time slightly.