Published on (
 See this if you're having trouble printing code examples

Managing TV with XMLTV

by Brian Murray

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.


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 make tv_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.


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:

$ cat sorted_tvlistings.xml | tv_grep --on-after now > reallistings.xml

This whole process is easy to automate via a script like:

tv_grab_na_dd | tv_sort | tv_grep --on-after now > /var/www/cgi-bin/tv.xml
# apache is the default web user in Fedora
chown apache.apache /var/www/cgi-bin/tv.xml
Linux Multimedia Hacks

Related Reading

Linux Multimedia Hacks
Tips & Tools for Taming Images, Audio, and Video
By Kyle Rankin

The CGI Front End

I have chosen to use tv_pick_cgi as the front end for my XMLTV installation, as I can use a web browser anywhere to review the upcoming TV schedule and quickly choose which shows to watch. If you do the same, you must manually install the tv_pick_cgi script in xmltv-0.5.40/choose/tv_pick/ by copying it to the cgi-bin of your web server and ensuring that it is executable and has the appropriate file extension. In the event that you don't have a web server, the lynx web browser has a CGI simulation that will also work. The tv_pick_cgi script expecting the TV listings data in a file named tv.xml in the same directory as the script. That's why the example script copied the data to /var/www/cgi-bin/.

With this installed, use a web browser to visit and choose the show you want to watch. A web page will display with the name of the TV show, the date it originally aired, the episode name, a short description of the episode, and a list of actors. This is much more data than I was getting from the TV guide of my DVD recorder, which is exactly what I was looking for and allowed me to find "The Card Game" episode of The Cosby Show.

With each TV show listed, there are four radio buttons for you to indicate your preference for that particular show. They are: never, meaning you never want to watch that show and it will never displayed again; no, meaning that you do not want to watch it this time but do want it to display the next time it is on; yes, meaning you do want to watch it this time and to see the display when it is on again; and always, meaning that you always want to watch it, so it will not show up again in listings. For The Cosby Show, I chose no, indicating that I didn't want to watch that particular episode, but wanted to keep seeing episode information for that show.

The initial run through of picking TV shows to watch can be quite slow. By default, the program displays 100 shows per page--and you have no preferences set yet. However, it should go more quickly every time as you mark more never or always. For example, with The Cosby Show, I kept choosing no until I found the episode I wanted, and after I had recorded it, I marked it as never.

As an aside, I did run into an issue once where tv_pick_cgi would not return any data, and my web server was logging a "premature end of script headers" in my httpd error_log. The root of the problem was the amount of time it takes the tv_pick cgi script to parse the XML data. I resolved the issue by modifying my httpd.conf and changing the Timeout value (the number of seconds before receives and sends) from 300 to 1200, which used to be the default in an earlier version of Apache httpd.

Using Your Schedule

The final web page generated by tv_pick_cgi shows that you have finished choosing shows and that it has created the file towatch.xml. In addition, there is now a file called tvprefs in /var/www/cgi-bin/, which contains the titles of TV shows and your preference for them. This file is directly editable, which comes in handy if you have accidentally marked a show as never or always.

The XML file output by tv_pick_cgi isn't ideal for using to set up my DVD recorder, though, and that is where tv_to_text comes in. It can convert the XML file to a text file (tv_to_text --output FILENAME towatch.xml) which you can then print. However, I always edit the file with my favorite text editor to resolve any conflicting shows and remove any shows I may have accidentally added.

Beyond the issues mentioned already, my only complaint has ironically been some inadequacies in the TV listings. The listing data isn't always complete for The Daily Show, for example, in that sometimes the only information will be the show title. I think this is because of a lack of data provided by Comedy Central, as my friends with TiVos have the same issue.


Now I have a more detailed listing of television shows that I want to record and can subsequently set up my DVD recorder with this information. I have been using XMLTV for a few months now to streamline the process of deciding what to watch, and to replace the TV guide features of my DVD recorder. I am very happy with it, and was able to record the episode of The Cosby Show I was looking for and watch with my family.

Brian Murray is a system administrator at the Open Source Development Labs where his responsibilities include teaching and assisting new Linux users.

Return to

Copyright © 2009 O'Reilly Media, Inc.