Managing TV with XMLTV

The open source software XMLTV recently made my life much easier, even though I don't use MythTV. I have a DVD recorder with a hard drive for recording television shows (a Philips HDRW 720/17, if you are really curious). It has a built-in TV guide listing service, but I quickly became disappointed with the amount of detail in the listings. I tried using my newspaper's TV listings but those, too, did not have the level of detail that I wanted.

Let me elaborate. Some family members and I were discussing some classic TV shows, particularly The Cosby Show. We recalled one episode where Cliff (Bill Cosby) and some friends were playing cards and some players were cheating by discussing everyday things that related to the suits they had in their hands. For example, "I was working in my garden today with my spade."

I decided that I needed to see that episode of The Cosby Show again, but the TV guide data I could get would only indicate that The Cosby Show was on at a particular time, not giving any information like the title or a plot summary about the episode. I was not so dedicated to this hunt that I would record every episode and watch them in the hope that it would be the episode "The Card Show." Subsequently, I embarked on a quest to find a tool to supplement the device's TV guide.

Signing Up

I quickly settled upon XMLTV as the back-end and front-end for getting detailed TV listings. XMLTV downloads data from Zap2It using their Data Direct service and provides multiple ways to filter, sort, and augment the data. The first step in using XMLTV is setting up an account with Zap2It. There you will need to accept their license agreement and provide some personal information to get an account. I have never received a marketing email from them, but do need to renew my registration every three months by filling out another short survey of ten questions or so. When setting up your account, the most important thing to do is choose your local channel line-up. After selecting this, it is possible to filter stations by using the Details button under Actions. It is better to do this at the Zap2It site rather than with XMLTV, as you'll have to download much less data. When you download data with the tv_grab_na_dd script, it will include a notification of your subscription's expiration date.

Installation

After setting up a Zap2It account, the next step is to download and install the XMLTV software. It is in most apt repositories so you should be able to use the commands apt-cache search xmltv and then apt-get install to install the appropriate package. The XMLTV home page also hosts source code, if you need to install it from source. To install it from source, unpack the source code via tar jvfz xmltv*. xmltv is a Perl program, so install it with Perl.

Several Perl modules are required, including some you may not have installed. The required modules are Term::ReadKey, XML::Writer, XML::Parser, XML::Twig, Date::Manip, CGI, SOAP::Lite, Term::ProgressBar, and Unicode::String. The default make options will work, as you only need to maketv_grab_na_dd and tv_pick_cgi. To install XMLTV, run perl Makefile.PL, then make, make test, and make install. The README file provides more detailed instructions.

Configuration

Now that you have XMLTV installed, configure it to grab the data from Zap2It. Run tv_grab_na_dd --configure. The first question is what time zone offset to use. I recommend using the tv_pick_cgi front end for choosing what to watch, so specify the time zone here. However, remember to change it again when Daylight Savings Time starts or ends (or monitor XMLTV, as the developers are working on this).

Next, enter your Zap2It username and password and choose your channel line-up. The tv_grab_na_dd script will now download channel data and create a configuration file at ~/.xmltv/tv_grab_na_dd.conf. The file contains only your username, password (if you stored it), time zone, and channel line-up. This is where you should change the time zone when DST starts or ends.

With the tv_grab_na_dd configuration file set up, you can now starting downloading TV schedule information. The tv_grab_na_dd command downloads listings and outputs them to STDOUT, so be sure to redirect them to a file of your choice. For example, I use tv_grab_na_dd > tvlistings.xml. After downloading the listings, I like to sort them in chronological order with tv_sort:

cat tvlistings.xml | tv_sort > sorted_tvlistings.xml

The sorted listings still are not in the best format for actually picking what you want to watch yet. In my case, I don't care about any shows that have already aired, so I used the tv_grep filter to find only shows on after now: