Hacking the XML in Your TiVo
When I was a kid, our television set picked up just a few broadcast channels over the wire aerial mounted on our roof. This offered us a limited choice of what to watch, so we saw a lot of I Love Lucy reruns. Now that we have hundreds of channels over the satellite dish, libraries of DVDs and videotapes, Netflix, a great local video store, increasing access to video over the Web, and especially a TiVo, what do we save up on the TiVo to watch together as a family besides The Simpsons and Monty Python's Flying Circus? Old I Love Lucy episodes.
We don't watch every recorded episode. The TiVo offers various options for finding out the episode titles and plot summaries of what it recorded, so that we can find Simpsons episodes we've never seen and alert our kids to particularly classic Monty Python and I Love Lucy episodes. The simplest way to see what you have is to use your TiVo remote to bring up the Now Playing menu. Things get more interesting when your TiVo—which is ultimately a Linux box with a big hard disk and a timer-triggered channel changer—has a wireless network adapter that connects to your home network. An HTTP server built into the TiVo lets you browse web page versions of TiVo metadata from a browser on the same network, and a RESTful API lets you pull XML versions of the same information. With some short stylesheets and a little help from the free wget utility, I wrote a simple application that puts onto my weblog a "TiVoRoll" of what shows our TiVo's been recording, and another app that gives me an Atom feed showing which episodes have been recorded lately.
Before I describe how to do this, I'm making two assumptions:
-
Your TiVo is on your home network. As the TiVo documentation explains, you just plug a network adapter into the USB port on the TiVo's back panel and run a setup routine. Make sure that you get your network adapter from someplace where you can return it if necessary, because the TiVo can be very picky about these, sometimes accepting and rejecting different adapters of the same make and model due to slight differences in the version number. I found the website tivocards.com to be very helpful.
-
You're using one of the Series 2 TiVos that have been available for over four years now. For information on great hacks that you can do with both Series 2 and Series 1 TiVos, see the O'Reilly book TiVo Hacks.
To retrieve data from the HTTP server in your TiVo, you first need to find out its IP address. From the TiVo main menu, pick Messages & Settings, Settings, and then Phone & Network to display the Network Settings screen, which will have your IP address. This number was dynamically assigned and may change if you reboot some part of your home network, so don't hardwire this IP address into your code when creating an application around it. The same TiVo screen also shows your MAC ID (formerly the MAK, for Media Access Key), which will be your password to gain access to the TiVo's metadata, so note that as well.
Browsing the TiVo HTTP Server
Let's say that your TiVo's IP address is 192.168.2.103. To see its web server's home page, point a browser on one of your home network's machines to https://192.168.2.103. (Remember to make it https and not http, which will give you a screen that tells you nothing about what you have on your TiVo.) You may get a dialog box saying "Web Site Certified by an Unknown Authority" and one saying "Domain Name Mismatch," and then you'll be prompted for a username and password. Your username is "tivo", and your password is the MAC ID that you copied from your TV screen when you got the TiVo's IP address. The default web page redirects your browser to https://192.168.2.103/nowplaying/index.html, which summarizes the shows you have recorded:
Clicking "folder" on the right lists individual episodes of a show that you have recorded, and clicking "classic" at the bottom lists all the individual episodes on the TiVo hard disk.
The third method for finding out about recorded episodes, besides the web page interface and using the remote to display the Now Playing list on your television, is the most interesting: with a URL full of parameters that tell the TiVo's HTTP server to give you an XML version of the information. Pointing your browser to the URL
https://192.168.2.103/TiVoConnect?Command=QueryContainer&Container=%2FNowPlaying&Recurse=Yes
(with your own TiVo's IP address substituted if necessary) displays something like this:
The parameters in this URL are documented in the TiVo Home Media Option Music and Photos Server Protocol Specification, an Acrobat file. The free Home Media Option lets your TiVo display pictures and play music stored on another computer on your home network. Its API documentation mostly describes how to retrieve XML about your picture and music files (as well as the files themselves, as we'll see), but by specifying the appropriate Container parameter, as shown in the URL above, you get Now Playing metadata. The protocol specification describes other commands besides QueryContainer, but none looked particularly interesting to me. For example, QueryServer tells you the version of the TiVo server and nothing else.
