sisko.org

What is XMLTV and why do I need it?

To quote its developer, XMLTV is…

…a set of utilities to manage your TV viewing. They work with TV listings stored in the XMLTV format, which is based on XML. The idea is to separate out the backend (getting the listings) from the frontend (displaying them for the user), and to implement useful operations like picking out your favourite programmes as filters that read and write XML documents.

XMLTV is pretty much the key to getting your homebrew PVR working well: it’s the magic that grabs TV listings from wherever they’re available on the web and translates them into a format that your PVR can understand. Without XMLTV, you’d be reduced to having to programme your PVR to record manually on a particular channel at a particular time — in other words, your PVR becomes nothing more than an expensive (and stupid!) VCR.

Using XMLTV in the UK

There are a couple of different routes you can take to use XMLTV in the UK. Andrew Flegg’s bleb.org service is rapidly expanding and now includes most digital channels, and may soon be the weapon of choice for the UK home PVR builder. But the service most PVR users seem to have fixed on is Alan Birtles’s Radio Times XMLTV grabber, which uses the data from the Radio Times web site. For now, this data is freely available and includes all the terrestrial and digital TV channels, but at the moment doesn’t (ironically enough, given the name of the site) include digital radio channels.

In simple terms, here’s how it all fits together:

• The XMLTV grabber downloads all the programme data from the Radio Times web site
• The XMLTV grabber writes the programme data into the XMLTV format
• The PVR software reads the XMLTV data and populates its on-screen EPG

And you can set the whole thing up to work automatically, so your PVR software will always have up-to-date program listings.

For the purposes of this article, I’m going to assume you’re running Windows XP, you’re using SageTV as your PVR software, and that you’ve got a single TV capture card in your PVR. If you’ve got multiple tuners, then lucky you! You can follow these instructions, but when you get to step 4, you’ll need to install a different version of the XMLTV plug-in. Head along to the Frey Technologies forums for more advice.

Step 1: Using the XMLTV grabber

• Download the latest version of Alan Birtles’s excellent tool from here.
• Double-click the file you downloaded, which will be called something like xmltvrt_2.131W.exe and follow the on-screen instructions to install it
• Make a note of where you choose to install the program: I’d suggest accepting the default of C:\Program Files\XMLTV Radio Times as this will make the automation step easier a bit later on

ou’ve installed the program, run it. You’ll see something like this:




• Click the Configure menu, which launches a dialog (never mind!)
• You’ll see the Channels page, which lists all the channels the Radio Times covers.
• The quickest way to add them is to click the top channel in the Available Channels list, scroll down the list, Shift-click the bottom channel in the list, then click the > > button to add all of those channels to the Selected Channels list, then remove individual channels from the right-hand list using the < < button, so you end up with something like this:




• Now choose the Settings tab.
• Click Save Listings To… and tell it to save the listings to the XMLTV Radio Times folder (normally C:\Program Files\XMLTV Radio Times\ by default), and call the file data.xml
• You can also set some of the other options in this dialog, which will change the appearance of the information you see in SageTV’s EPG. Here’s what I have set at the moment:

• Switch on Add ‘Movie:’ to the title of films
• Switch on Add episode numbers to program subtitle
• Switch on Mark all non-repeats as ‘Premieres’
• Switch on Add production date to description (where available)

Pay a quick visit to the Logging and Connection pages of the dialog. Logging is useful if you run into any problems with your scheduled grabs (you can even choose to have it emailed to you!), and you may need to set up some proxy server gubbins to allow the grabber to connect to the internet. But if you’re using a standard broadband connection, chances are the defaults are absolutely fine.

Finally, click OK.

To give the grabber a test run, click Grab Listings, and watch the progress bars whizz across. On my system, to download the guide data and write the XML file takes about four minutes.

Step 2: Download and install XMLTV

Although we’re going to use Alan Birtles’s tool to grab the listings themselves, we need to munge them a little to make SageTV’s life as easy as possible when parsing them. For that, we need to install XMLTV itself, like this:

• Go to XMLTV’s project page at Sourceforge
• Download the most recent Windows version of XMLTV. At the time of writing, it’s xmltv-0.5.37-win32.zip. It’s around 6Mb, so it’ll take a few moments to download.
• Unzip the .zip file you downloaded and put the resulting folder inside C:\Program Files. Rather than leave the folder called xmltv-0.5.37-win32 (or whatever), rename it simply to XMLTV. (In step 3 you’re going to need to know what you did with this folder, so take care.)

That’s it. Now let’s get the Radio Times grabber and XMLTV to talk to each other.

Step 3: Scheduling the grabber

We want our grabber to run every day, so that our PVR software always has access to 15 days’ programme listings. So we need to write a little batch file that will get the data, munge it as appropriate using XMLTV, copy the file to the right place for SageTV to use it, and schedule it to run every day.

• Open Notepad, and write the following. You may have to adjust the paths if you’ve used non-default paths to either the XMLTV Radio Times grabber, SageTV, or XMLTV.



C:
"C:\Program Files\XMLTV Radio Times\xmltvrt.exe" /Grab
cd "C:\Program Files\XMLTV"
copy "C:\Program Files\XMLTV Radio Times\data.xml" data.xml
xmltv tv_sort --by-channel --output "C:\Program Files\XMLTV\epgdata.xml" data.xml
copy "C:\Program Files\XMLTV\epgdata.xml" "C:\Program Files\Frey Technologies\SageTV"
echo "Done!"

• Save this as xmltv.bat to somewhere simple, e.g. in the root of your C: drive
• Choose Start > Control Panel and double-click Scheduled Tasks
• Double-click Add New Task, and the little wizard will appear:




• On the next page, click Browse and choose your xmltv.bat file




• On the third page, type a meaningful name for your task, and switch on the Daily option




• On the fourth page, choose a suitable time to download the data (I choose 4am because it’s unlikely much else is going on at that time of night), and click Next




• Finally, choose which user should run the task, and type your password, as appropriate, before clicking Next




• On the last page of the wizard, check the box Open advanced properties for this task when I click Finish, and click Finish




• If your user account doesn’t have a password set (like mine… how naughty!), you’ll probably see the following error message:




• Click OK and you’ll be taken to the task properties dialog. Switch on Run only if logged on and click OK

Step 4: Install SageTV’s XMLTV plug-in

Now we’ve got a steady stream of EPG data coming in, it’s time to make use of it. SageTV doesn’t support XMLTV “out of the box,” but thanks to the XMLTV plug-in written by a mysterious chap known only as “corykim” (whoever you are, you masked man, thank you!), it’s quite simple to set up.

In fact, users in the UK need to make use of a specially modified version of the XMLTV plug-in, so don’t rush off and download the plug-in from the link above. We’ll get onto that in a minute!

• First, quit SageTV if it’s running — don’t put it into sleep mode, actually quit it. And you also need to stop the SageTV service, if it’s running. To stop the service:

• Choose Start > Control Panel, double-click Administrative Tools. In the list that appears, double-click Services, and the Services applet is launched
• In the list of services, scroll down to SageTV and click the Stop this service link.
• Once you’re told that the service has been stopped, you’re good to go: minimize the Services applet (you’ll need it again in a minute to restart the service).

Using Windows Explorer (or your Explorer replacement of choice), navigate to your SageTV folder (normally C:\Program Files\Frey Technologies\SageTV)

Note to the cautious: If you want to back up your SageTV installation just in case you think you’re going to screw it up (though if you follow these instructions carefully you’ll be fine), now’s the time to do it. Simply copy the entire SageTV program folder to somewhere safe, and call it something like SageTV Backup so you know where to find it if everything goes wrong. If you ever need to restore from your backup, simply delete the existing SageTV folder, copy in your backup folder, and rename it back to SageTV. Easy!

Using Notepad (or your text editor of choice), edit the Sage.Properties file. Look for the line that says:


epg/epg_import_plugin=


and change it to:


epg/epg_import_plugin=xmltv.XMLTVImportPlugin


which tells SageTV where to look for the XMLTV plug-in. Make sure you type it exactly as above: it’s case-sensitive, and there should be no trailing spaces at the end of the line.

Now download the XMLTV plug-in itself. (If the link doesn’t work, it’s because you’re not a registered user in the Frey Technologies forum; this attachment comes from this thread, so try visiting it directly to download.)

Unzip the archive you downloaded, and extract its contents into a folder called xmltv inside your SageTV program folder

You also need to download the Xerces XML parser, xerces.jar. (Some browsers rename .jar files to .zip when they download them, so if this happens, rename the downloaded file to xerces.jar before you proceed.)

Copy xerces.jar into the \jars folder inside your SageTV folder (for SageTV 4.0 or laer only; for earlier versions, you need to copy this into the \lib\ext folder inside your Java installation; normally something like C:\Program Files\Java\jre_1.42_06\lib\ext.

That’s it for the installation of the plug-in.

Step 5: Configure SageTV to use XMLTV

Make sure you have already run your XMLTV grabber before you run SageTV after installing the plug-in, and that the file epgdata.xml is in the SageTV folder. If you had to stop the SageTV service in step 4 above, you can now restart it using the Services applet. Finally, restart the SageTV application itself.

• From the main menu, choose Setup, then choose Setup Wizard from the setup menu
• If you’ve already partially set up your capture card, we’ll need to start again. So click Add New Source. If you haven’t started setting up your capture card, click the name of the capture card you want to use as your recording source from the list (which may a very short list of only one item!).
• Choose the input of the capture device you’re going to use.
• When asked to select a tuning option, choose Use external Cable or Satellite receiver to tune channel if you’ve got your external infra-red transceiver set up already (the details of setting that up is to be the subject of a later article in this series); otherwise click Don’t Configure Tuning
• When asked about whether you want to use Programming Guide data, choose Use Programming Guide Data with this Source
• On the next screen, choose Cable or Satellite
• You will be asked to enter a zip code: enter 00000
• Now you’re asked to choose your cable or satellite provider. At this point, you should see only one option, XMLTV Lineup. If, instead, you see a whole bunch of US satellite providers (with names like Dish Network etc.), then I’m afraid you’ve not managed to install the XMLTV plug-in properly. The most likely explanation for this is that you didn’t stop the SageTV service as well as quit the SageTV application. Back you go to step 4!
• Click XMLTV Lineup and then wait patiently while it parses the epgdata.xml file. Sometimes, this screen just stays there, even after it’s finished parsing the file; if you’re still waiting after five minutes, go back to the main menu by clicking the SageTV logo in the top left, then go back to the Setup Wizard and click the name of your source.
• On the next screen, choose between Basic Service and Extended Basic Service. I always choose Extended Basic Service, but in fact there’s no difference between the two.
• You will now see a big old list of all the channels you imported from XMLTV. Congratulations — if you’ve made it this far, the worst is definitely over!
• At this point you may want to enable or disable channels, or possibly Remap them, but let’s just check that we now have real live guide data. Click Done with Channel Setup.
• You’re taken to the Source Details page. Now click the SageTV logo in the top left-hand corner to return to the main menu, and click Live TV Guide to admire your handiwork.

Troubleshooting

If you followed the instructions above, you shouldn’t have any problems, but there are a few things that can go wrong. If you don’t see the correct list of channels, chances are you didn’t properly quit SageTV and stop its service before you edited sage.properties. You can also try choosing a different source in SageTV’s Setup Wizard, and that the epgdata.xml is in the right place.

If the epgdata.xml file is in the right place, check that it validates correctly, using corykim’s plugintester, which you can download from this thread. Once you’ve downloaded the plug-in:

• Unzip the contents of the .zip file into the SageTV program folder
• Choose Start > Run and type cmd, then hit Return
• Type cd "C:\Program Files\Frey Technologies\SageTV" and hit Return. This will change to the SageTV program folder.
• Type: java -cp .;sage.jar PluginTester and hit Return. This will scroll through the epgdata.xml file. If all is well, the last line of the output should say Test complete, result was ‘true’.
• If you get a different result, you need to get yourself over to the dedicated forum for SageTV users in the UK.

What’s next?

You’ve now got 15 days’ EPG data in SageTV, and it’ll be updated every morning at 4am.

Next steps are to finish configuring the channel line-up in SageTV, make sure SageTV updates its EPG data soon after our data has finished downloading, and to set up the connection to the external video source, so that the PVR can actually start recording things!

Donate!

None of the above would be possible without the hard work of people who devote their free time to grokking all this stuff. If you use Alan Birtles’s XMLTV grabber and find it useful, please consider clicking the little Donate button on his web site and send him some money to thank him for all his efforts.

Acknowledgements

I wish I were clever enough to have worked out every detail of this by myself, but I’m not. So thanks must go to all those people whose knowledge has helped me determine every step listed above. In particular, thanks to robogeek, whose steps for installing the SageTV XMLTV plug-in were invaluable, and to SageTV forum member MrManson, who modified the original XMLTV import plug-in to work correctly in the UK.

Update (9 January 2005, 2pm)

Thanks to the denizens of the Frey Technologies Forums for casting their eyes over this document and pointing out a few things that could have been clearer. Thanks especially to newschapmj1, who offered his own configuration document for me to supplement the information in this one.