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.

####fast

• Location: Commandline, Global, Channel
• Commandline: --fast ,-f /--slow, -s
• Values: boolean
• Default: False

This option sets whether any detail-pages should be fetched. By default they are. If fast is True detail-pages are only retrieved from the cache (if present). Can be set globaly or per channel.

####offset

• Location: Commandline, Global
• Commandline: --offset ,-o <0-14>
• Values: (integer) 0-14
• Default: 0

The first day to return programme info for. By default this is today.

####days

• Location: Commandline, Global
• Commandline: --days ,-g <0-14>
• Values: (integer) 0-14
• Default: 14

The total days to return data for starting at offset. The sum off offset and days can not exceed 14 days. So offset 1 and days 1 means only data for tomorrow. If data is already present in the cache that will be used. Only data not present and data for today will be fetched from the source.

####slowdays

• Location: Commandline, Global, Channel
• Commandline: --slowdays , -G <0-14>
• Values: (integer) 0-14, None
• Default: None

For the here set days detail pages if not already present in the cache are fetched. Any further days will be fetched in fast modus. If set other then to None the value for fast will be ignored. If set to the same value as days fast = False or slow modus is assumed. If set to 0 fast modus is assumed.
Even in slow modus detail pages are not retrieved for all programmes. In the JSON data-file a list of genres is present for which programmes, detail pages should get retrieved.

####disable_source

• Location: Commandline, Global, Channel
• Commandline: --disable-source <ID>
• Values:
• Default:

Disable the given source either global or just for one channel. Run with --show-sources to get a list of the available sources. If a source experiences problems we can also (temporarily) through the JSON datafile disable a source.

####disable_detail_source

• Location: Commandline, Global, Channel
• Commandline: --disable-detail-source <ID>
• Values:
• Default:

Disable the given source for detail fetches either global or just for one channel. Run with --show-detail-sources to get a list of the available sources.

####disable_ttvdb

• Location: Commandline, Global, Channel
• Commandline: --disable-ttvdb
• Values: boolean
• Default: False

Disable ttvdb-lookup either global or just for one channel. If you disable ttvdb-lookup globally you can not enable it for one channel.
Through the JSON datafile channels can also be excluded from ttvdb-lookup. Notable radio and regional channels. Also lookup is only attempted if it is marked as a series and an episode-title is present.

####prime_source

• Location: Channel
• Values: integer
• Default: Set through the JSON data-file

The prime_source is the source delivering all start and stop times.
Normally you do not need to set this explicitly as the channel default set in the JSON data-file should be optimal. In there there firstly is a general source preference list with the most dependable source listed first. Next a prime_source can be set for a channel group and lastly for a channel.

####prefered_description

• Location: Channel
• Values: integer
• Default: The longest description given by any of the sources

By default the longest description given by any of the sources is added to the xmltv output. This however does not need to be the best one. On channel level you can set this value to prefer if present the description from a specific source. If this source does not supply a description the longest of the remaining descriptions is used. Any description will be prepended with the subgenre and if found the broadcaster (for channels with multiple broadcasters).

####mark_hd

• Location: Commandline, Global, Channel
• Commandline: --mark-HD , -H
• Values: boolean
• Default: False

Some sources mark programmes as being in HD. If you're recording in SD or even analog you might not be interested. By default this information therefor is not added. Set this to True either global or for selected channels to add this information to your xmltv output.

####add_hd_id

• Location: Channel
• Values: boolean
• Default: False

If you can receive a channel both in HD and in SD you might want the HD channel listing to have the above mentioned HD info while you do not want it for the other. By turning this option on for a channel two listings are returned in the xmltv output. One without and one with the HD information and wit -hd appended to the xmltvid.

####cattrans

• Location: Commandline, Global, Channel
• Commandline: --cattrans / --nocattrans, -t
• Values: boolean
• Default: True

Genre translation happens in two steps. The first from source specific to a generic genre/subgenre set and the second from genre/subgenre to a single genre with the subgenre prepended to the description. This switch can disable/enable the second step. The translation tables have a default in the JSON data-files. They also are updated on every run and written to the ~/.xmltv/tv_grab_xx_py.set file, where you can see and update them.

####overlap_strategy

• Location: Commandline, Global, Channel
• Commandline: --overlap_strategy , -a <average|stop|start|none>
• Values: average|stop|start|none
• Default: avarage

####max_overlap

• Location: Commandline, Global, Channel
• Commandline: --max_overlap, -m <minutes>
• Values: integer
• Default: 10

The by a source given end-times do not always match the start-time for the next programme. These two options determin how to treat these incidenses. Any difference (positive or negative) larger then max_overlap will always be left as-is. The treatment of a smaller value is decided by overlap_strategy:

• avarage: take the average of the two times and adjust both
• stop: keep the stop-time and adjust the start-time to it
• start: keep the start-time and adjust the stop-time to it
• none (or an invalid value): leave it as-is.

####desc_length

• Location: Commandline, Global, Channel
• Commandline: --desc-length , -l <characters>
• Values: integer
• Default: 475

This is the maximum length you want a description to be (including spaces and the at the beginning added subgenre and optional broadcaster). Any text past this length will be truncated and replaced with an ellips (...). I myself keep it at 1000. If you set it to 0 the program switches to fast modus!

####ratingstyle

• Location: Global
• Values: ong|short|single|none
• Default: short

If your frontend incorporates a rating (not to be confused with a star-rating), this setting determins how this is represented in the xmltv output:

• long: Include if present for each occurence both descriptive text and any logo
• short: Include if present for each occurence a few character code and any logo.
• single: Include a singletext item being the appended short codes. This options is especially for MythTV as it will only read a single item for each programme and limits it to a text value of 16 characters. Any logo is disregarded.
• none: Add nothing

####use_split_episodes

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

This is an option originally from tv_grab_nl_py that has not jet been implemented. Sometimes sources list following episodes of the same series as one programme item, while others name them separately. When we implement this it gives you the choise of wich to prefere. At present it depends on how the first source handles this.

##tv_grab_xx_py.set