tv_grab_na_dd - Grab TV listings for North America using Zap2IT's Data Direct service.

    tv_grab_na_dd --help

    tv_grab_na_dd --version

    tv_grab_na_dd --configure [--config-file FILE] [--dd-data FILE]
                              [--reprocess] [--auto-config add|ignore]
                              [--gui OPTION]

    tv_grab_na_dd --list-lineups [--config-file FILE] [--dd-data FILE]
                              [--reprocess]

    tv_grab_na_dd [--config-file FILE] [--dd-data FILE]
                  [--reprocess] [--auto-config add|ignore]
                  [--days N]  [--offset N] [--quiet]
                  [--old-chan-id] [--low-mem] [--output FILE]
                  [--list-channel] [--share SHAREDIR] [--list-times]
                  [--download-only] [--list-times]

This scripts downloads listings from Zap2IT's DataDirect service, converts it to XMLTV format, and outputs the results.

You must first register with Data Direct at: <http://labs.zap2it.com>

You'll need to provide the XMLTV certificate code CWZYZM-TE5O-SBUT (Letter O)

The data is provided free of charge, except for a short periodic web survey.

Once you've registered and added a lineup to your account, run CWtv_grab_na_dd --configure to provide set up the grabber.

Once configured, running tv_grab_na_dd with no arguments will output listings in XML format to standard output.

--configure

Activates configure mode, If a config file already exists the values are used as defaults.

--gui OPTION

Use this option to enable a graphical interface to be used. OPTION may be 'Tk', or left blank for the best available choice. Additional allowed values of OPTION are 'Term' for normal terminal output (default) and 'TermNoProgressBar' to disable the use of Term::ProgressBar.

--list-lineups

Lists available lineups. Only requires username in the config file. Used by programs that automate the --configure process.

--config-file file

Set the name of the configuration file, the default is ~/.xmltv/tv_grab_na_dd.conf. This is the file created during --configure mode.

--dd-data file

Store DataDirect data to this file. (default is a temporary file)

--reprocess

Don't don't get data from DataDirect, but reprocess a file saved with --dd-data.

--auto-config add|ignore

When used in --configure mode, updates the config file, removing old channels, and adding or ignoring new channels. Prompts are skipped if defaults are available in the current config file. When used in grab mode, appends new channels to the config file.

--days n

grab n days. The default is 7.

--offset n

start N days after the default.

--quiet

suppress some messages normally written to standard error.

--old-chan-id

use a channel id similar to the one used by the old tv_grab_na grabber.

--low-mem

Omit all but the most basic program information. Reduces memory usage.

--output file

write xml to file rather than standard output.

--list-channel

same as --days 0

--download-only

Don't generate any output, just fetch the data. Personally I don't see the point, but it was requested and easy to add.

--list-times

report to STDERR the DataDirect blockedTime (not currently enforced) and suggestedTime values to assist automated processes with scheduling.

--help

Print a help message and exit.

-share SHAREDIR

tv_grab_na_icons stores icons in SHAREDIR/icons. The share directory is set at install time, but there may be times when it needs to be specified. (for example: no write access to the default share directory)

As mentioned above, Zap2IT's Data Direct service is not freeware, but surveyware. Periodically (currently every 3 months) you will be asked to fill out a short survey in exchange for the data. It's a win-win for everyone.

A message from Zap2IT is passed on by the grabber informing you of your account expiration date. Seven days before expiration, Zap2IT will send you a email asking you to fill out another survey.

Sometimes applications want to call tv_grab_na_dd as a standalone application, but automate the configure process. The best way is to hook in to the XMLTV::Ask module, but if that's not available, here is a solution. Step1. Application creates config file with username (and optionally password). Step2. CWtv_grab_na_dd --dd-data lineups.xml --list-lineups Step3. Application adds desired lineup to config file. Step4. CWtv_grab_na_dd --dd-data lineups.xml --reprocess --auto-config add --list-channels Step5. Application edits config file as needed, and deletes lineups.xml.

Most of us typically schedule the grabs at night to reduce load on the servers. Well, too much of a good thing can be bad! Zap2IT/Data Direct has requested we try and randomize automated runs.

I propose the following: Run the grabber at the hour of date of your birth ( subtract 24 if over 24) and the minute you read this message. That should spread the load and help the servers as well as everyone's speed fetches.

Note: This request is for automated fetches only, poll manually at any time. Also, if your needs require a special time, go for it.

tv_grab_na_dd only outputs a single lineup. If your DataDirect account has multiple lineups, they are all downloaded even though only one is output.

To process multiple lineups, specify a different --config-file. To prevent re-downloading the data on subsequent passes, the --reprocess option is recommended.

Here's an example: (the = sign is optional, but helps readability)

 tv_grab_na_dd --config-file=lineup1.dat --output=lineup1.xml --dd-data=dd.xml
 tv_grab_na_dd --config-file=lineup2.dat --output=lineup2.xml --dd-data=dd.xml --reprocess
 tv_grab_na_dd --config-file=lineup3.dat --output=lineup3.xml --dd-data=dd.xml --reprocess

Each config file specifies the desired lineup and channel list. The login information is is only used in the first command, but it doesn't hurt in the other entries.

If you want to merge the lineups into a single file, you can use tv_cat

 tv_cat lineup1.xml lineup2.xml lineup3.xml >guide.xml

tv_grab_na_dd checks for channel icons in a directory BIshare/icons. The share directory is usually set during the install. For windows exe users, it defaults to the location where xmltv.exe is. tv_grab_na_icons is available to download the icons.

Channel lists can be configured both at the DataDirect website and through the grabber. This is done to allow multiple config files with different channel lists as DataDirect only supports a single channel map per lineup.

Similarly, tv_grab_na_dd only supports a single channel mapping for a station. If multiple mappings are detected, only the first one is used and you are advised to adjust your DataDirect lineup.

Three episode-num formats are supplied (when available)

xmltv_ns

always CW..a/b for part CWa of CWb. First two xmltv_ns fields always blank.

dd_progid

TMS generated CWa.b.c/d where CWa is a unique program id, CWb is a unique episode id, CWc/d is part CWc of CWd similar to xmltv_ns.

onscreen

Distributor-designated number corresponding to an episode of a specific show. Varies by distributor.

If a password is stored in the config file, the config file should be properly protected. Instead of storing the password in the config file, it can be omitted, and will be prompted for.

DataDirect currently adds a channel to your lineup automatically when it is available. When tv_grab_na_dd sees the new channel in the DataDirect lineup, it prints a message (and potentially adds or ignores it based on --auto-config).

If you are sensitive to bandwidth issues, I would set --auto-config ignore and periodically check your --config-file for ignored channels and remove from your DataDirect Lineup <http://labs.zap2it.com>.

Zap2it is considering making this configurable, but at the moment it is not.

none!

xmltv(5).

Author/Maintainer: Robert Eden, rmeden@yahoo.com

Ed Avis, ed@membled.com Don Huettl, drh@huettl.net Matti Airas, mairas@iki.fi (I used tv_grab_fi as a template) The folks at Tribune Media <http://labs.zap2it.com/> and of course everyone else I forgot to mention. :)