NAME
tv_grab_na - Grab Canadian and US TV listings.
SYNOPSIS
tv_grab_na [--help] [--debug] [--config-file FILE] [--output FILE] --configure CONFIG_OPTIONS
tv_grab_na [--help] [--debug] [--config-file FILE] [--output FILE] GRAB_OPTIONS
tv_grab_na [--output FILE] (--postalcode X | --zipcode X) --list-providers
tv_grab_na [--output FILE] (--postalcode X | --zipcode X) --provider P --list-channels
DESCRIPTION
Output TV listings for Canada and the USA in XMLTV format. The data currently comes from the zap2it.com site.
First you must run tv_grab_na --configure to set your local area, service provider and which channels you wish to download. Then running tv_grab_na with no arguments will get a week's listings for the channels you chose. If the upstream data changes (for example, new channels appear) you will be prompted to rerun --configure to update your choices.
Some options are available in both configure and grab mode:
--help Print help to standard output and exit successfully.
--debug Turn on debugging checks.
--quiet disable all status messages (that normally appear on stderr).
--release-check X Specify whether or not we should attempt to check for new releases. X should be either "true" or "false" at http://sourceforge.net/projects/xmltv (default=true) (output disabled if --quiet is used)
--config-file FILE The location of the config file, which is written in configure mode and read in grab mode. The default location is ~/.xmltv/tv_grab_na.conf.
--output FILE Write output to FILE rather than standard output.
Configuration is normally interactive, but it can be run noninteractively, usually to update an existing set of choices. The following options are used to invoke --configure in a non-interactive mode:
--retry-limit X Specify retry limit on www site failures.
--retry-delay X Specify number of seconds to delay before retrying www site failures.
--postalcode X, --zipcode X Specify your postal code or zip code.
--provider ID Specify the id of your service provider. This is a number assigned by the zap2it site. During interactive configuration you are presented with a list of provider names, but if you already know the id you can specify it here.
--auto-fail-on-provider-changes BOOLEAN If true, exit with failure if the provider id has changed on the zap2it site.
--auto-new-channels [ignore|add] Ignore or automatically add new channels in schedule listing.
--auto-missing-channels [ignore|remove] Ignore or remove channels no longer in schedule listing.
Interactive mode is entered if some necessary information is not given (for example no postal or zip code in the existing configuration file, and not given on the command line).
After successful configuration you can start grabbing. The options here are:
--debuglistings Add debugging information to the output as XML comments.
--stats force output of grab stats (stats output disabled in --quiet mode).
--output FILE Write output to FILE rather than standard output. If the file exists it is overwritten. FILE may contain date(1) and keyword substitions like --listings.
--listings FILE Write output to FILE rather than standard output. FILE may contain date(1) style substitutions, for example use --listings "listings-%d%m%Y.xml" to separate output by day. Keywords %postalcode and %zipcode are also substituted from settings current configuration. Channel-based keywords %ChannelNumber and %ChannelCallLetters may be used, which cause the filename to be re-evaluated between each channel for each day, instead of just when a new days listings is started. Be warned, adverse results can occur if you use the %ChannelNumber and/or %ChannelCallLetters in the output pathname for a multi-day grab without some %d (or similar) substitution. For instance, if you use --listings "listings-%ChannelNumber" for a multi-day grab, the listings file will only contain the first days listings (or last days listings if --listings-overwrite is used) since the file will be re-evaluated after ever channel grab.
--listings-overwrite X Should tv_grab_na overwrite existing --listings output files or skip the ones that exist? (default=false - do not overwrite already grabbed listings files)
--days N When grabbing, grab N days of listings. The default is 7.
--offset N Number of days in the future to offset the start of the listings. The default is 0, meaning today.
--retry-limit X Specify retry limit on www site failures.
--retry-delay X Specify number of seconds to delay before retrying www site failures.
--gzip-command X Specify the command line for .gz output files. The default is "gzip".
--zip-command X Specify the command line for .zip output files. The default is "zip".
--bzip2-command X Specify the command line for .bz2 output files. The default is "bzip2".
To help programs that want to do automated configuration there are the options:
--list-providers Produce a list of providers and their descriptions for the postal/zip code provided in --postalcode or --zipcode arguments.
--list-channels Produce a list of channels available. Requires you also specify provider/location information via --provider and one of --postalcode or --zipcode options.
SEE ALSO
xmltv(5), http://www.zap2it.com/
AUTHOR
Jerry Veldhuis, jerry@matilda.com
BUGS
Zap2it recently removed the (ends at HH:MM) hints in their text listings. This value was being use to confidently compute the programme's stop time, without this, we no long can. Instead we compute the stop time by assuming it stops when the next program starts. This doesn't work for the last program of the the day (since the listings only show one day at a time and we grab chronologically), for these programs, tv_grab_na doesn't emit a stop time in the programme in the xml output. A post-grab call to tv_sort can fill these in using the next programme start time, but this assumes the next program is always available. WARNING: Although zap2it seems to have fixed the programming holes problem, this format change removes our chances of confidently finding them.
Because we parse the text listings (at zap2it), not the grid, output doesn't include the colour coded program categories such as Sports,Movie,Series,News,Special and Children that appear in the grid listings.
There is no way to get listings for only part of each day; the old --startHour and --endHour options no longer exist. This makes grabbing slower than it needs to be if you only want listings for certain hours.
The zap2it site has a long list of program qualifiers such as Live, Animated, HDTV and so on. Most of these are understood by tv_grab_na and included in the XMLTV output. But some new ones pop up occasionally and generate a warning message (which should be reported to the author). Some qualifiers such as Live do not yet have a good translation into XMLTV format.