Latest revision as of 17:47, 29 January 2014

XMLTV Grabber Command-Line Parameters

This document describes the command-line interface to the xmltv grabbers. It contains the parameters that are common between many grabbers. Each grabber may support additional parameters apart from the ones listed below.

All grabbers shall support a --description parameter. It shall print a description that identifies the grabber:

Example:

$ tv_grab_se_swedb --description
Sweden (tv.swedb.se)
$

The command-line parameters are divided into a number of groups called capabilities. Each capability has a name and defines a set of parameters that all grabbers that claim to implement that particular capability must support.

To list the capabilities that a grabber supports, call the grabber with a single parameter: --capabilities. The grabber shall then respond by printing a list of all the capabilities that it supports to stdout, one capability per line, and then exiting with an exit code of 0. It must be possible to run the grabber with the --capabilities parameter without any prior configuration.

Example:

$ tv_grab_se_swedb --capabilities
baseline
manualconfig
apiconfig
$

Each section below describes which command-line parameters that capability includes.

baseline

If the grabber claims to implement the baseline capability, it must support the following command-line options when grabbing data:

--quiet

Suppress all progress information. When --quiet is used, the grabber shall only print error-messages to stderr.

--output FILENAME

Redirect the xmltv output to the specified file. Otherwise output goes to stdout. This option is mostly there for Windows where there can be strange difficulties redirecting stdout.

--days X

Supply data for X days. Each grabber may have an upper limit to the number of days that it can return data for. If X is larger than that limit, the grabber shall return no data for the days that it lacks data for, print a warning to stderr, and exit with an error-code. See XmltvErrorCodes.

In other words, if too many days are requested, the grabber will return data for as many days as it can.

The default number of days is 'as many as possible'.

--offset X

Start with data for day today plus X days. The default is 0, today; 1 means start from tomorrow, etc.

--config-file FILENAME

The grabber shall read all configuration data from the specified file.

A grabber that claims to support the baseline capability must also be able to download data without any command-line options apart from the ones listed above. All other information must be supplied in the configuration stage.

Ideally, default values should be provided within the grabber so it can be run without any command-line options at all.

The grabber must output data that adheres to the XmltvFormat with the following additional requirements:

• All start- and stoptimes must include a timeoffset (e.g. +0100). Timezones (e.g. EST) are not permitted.
• The data must contain exactly one <channel> entry for each channel mentioned in the file.
• The data must not contain <channel> entries for channels that are not included in the data.
• All xmltvids must match the regexp /^[-a-zA-Z0-9]+(\.[-a-zA-Z0-9]+)+$/.
• If the grabber is first run with --offset 1 --days 1 and then with --offset 2 --days 1, then the two datasets returned must not overlap in time. By concatenating the two datasets, the result shall be identical to the output provided by --offset 1 --days 2.
  In practice this means the first programme output should be that which starts within the requested date range (i.e. not one which started yesterday).
• Days should run from midnight to midnight - some data sources run from 06:00 - 06:00 so will need some adjustment.

manualconfig

The manualconfig capability means that the grabber implements a configuration procedure where it asks the user a set of questions using the XMLTV::Ask library. This library currently has two implementations: one to prompt on the terminal and one to ask graphically with a Perl/Tk interface.

--configure

Allow the user to answer questions regarding the operation of the grabber. This can include usernames, passwords and lineup and it should also include a way for the user to specify which channels he wants to download data for.

If this parameter is combined with --config-file, the configuration is written to the specified file.

   ?EdAvis: Personally, as I've mentioned on the list, I'm not that happy with including passwords 
as part of configuration. But I don't want to fight a holy war about this right now. I suppose we 
can have passwords in the config file for grabbers that need them - though no grabber should require it.

apiconfig

The grabber shall support the following parameters to allow for automated configuration:

--configure-api

Return an xml-document compliant with the XmltvConfigurationDtd. The document describes any questions that the user must answer to configure the grabber.

--stage STAGENAME

Specify which stage of the configuration shall be run.

--list-channels

See XmltvConfigurationApi for a more detailed explanation and examples.

share

The grabber supports the following command-line option:

--share sharedir

sharedir specifies the location of the metadata for the grabber. For a properly installed grabber, this parameter should not be necessary to use.

cache

The grabber can cache the response to HTTP-requests in a file and reuse them without contacting the server again. This is useful if the grabber is run multiple times or when doing tests. Note that some grabbers may return the wrong result if a cachefile from a previous day is specified.

--cache cachefile

Store the cache in cachefile.

preferredmethod

The grabber can tell the application how it prefers to be called in order to download data as efficiently as possible.

If the grabber does not support the preferredmethod capability, the calling application shall assume that the consumed bandwidth is proportional to the number of days of data that is requested. It is therefore more efficient to download data for only the days that the application wants data.

--preferredmethod

Prints a single word to stdout (?) that tells the calling application that the grabber prefers to be used in a specific way. By calling the grabber in this way, the calling application can make sure that the grabber uses as little bandwidth as possible.

Available responses:

allatonce

The grabber downloads data in a single chunk and filters out the requested days. This means that it is more efficient to call this grabber once with a long period instead of several times with short periods. For example: If the application needs data for day 1 and 5, it should call the grabber with

tv_grab_xx --offset 1 --days 5

instead of

tv_grab_xx --offset 1 --days 1

tv_grab_xx --offset 5 --days 1

Additional responses may be defined in the future. If the application does not understand the response, it shall act as if the grabber did not support the preferredmethod capability.

Proposed Capabilities

This section describes a number of capabilities that have been discussed on the xmltv mailing list, but that no grabber has implemented yet and the details may change.

newchannels

The newchannels capability means that the grabber can notify a PVR application if it can supply data for channels that weren't available when the grabber was last configured. The behaviour of this mechanism can be controlled with the following command-line parameter:

--channel-updates add|ignore|notify

"add" means that the grabber shall automatically supply data for all new channels without informing the PVR application.

"ignore" means that the grabber shall ignore any new channels until the grabber is reconfigured.

"notify" means that the grabber shall tell the PVR application that there are new channels available by exiting with a special error-code after outputting the data for all the configured channels. See XmltvErrorCodes.

The default value for --channel-updates is "ignore". This is also the behaviour implemented by all grabbers that don't implement the newchannels capability.

   I wonder if it makes sense to include this information in the output XML. For example when a new channel appears just start writing channel elements for it in the output XML though not necessarily programmes. Need to think about this some more.

channelnumberremapping

The grabber can change the channel number associated with each channel. This is described in XmltvConfigurationFile.

lineups

See LineupProposal, LineupProposal2, NoLineupProposal.