TVShows and

First and foremost, this post is about a technology. It is not about how to pirate TV shows or promoting such actions. It’s about using and modifying software.

A few years ago, a program for OS X called TVShows was released. It has two components. The first is a set of Ruby scripts which run every 30 minutes to probe for TV show torrents, and then downloads the new episodes. The second is a GUI front end which shows a list of available shows and allows the user to subscribe. And it worked. It worked really well. Unlike some alternatives which need to be running constantly (wasting resources and screen real estate on something which should happen in the background) or would download torrents pointing to private trackers, TVShows downloaded new episodes, every time. Its background process was invoked by launchd every 30 minutes, meaning it took no resources when it wasn’t running and only ran for about 30 seconds (a ridiculously generous estimate) every hour. The program wasn’t feature complete, but it worked well for what it did. It has been stuck at 0.3.4 since May 2007, and version 1.0 has been promised for years, but the project had seen no movement since then. But that was fine, because it worked.

Until it didn’t.

A few months ago, went offline. A message was shown saying that the site would return, but it never did. Since TVShows needed the TVRSS feeds to get new episodes, the program stopped working. Some weeks later,, a site which distributes TV show torrents, went down as well. After some new servers and a code update, the site rose from the ashes, and launched a new site as well: EZRSS was designed as a drop-in replacement for the now-defunct Its webpages respond to the same queries and give the same results.

Knowing what I know about languages like Ruby, I dove into the TVShows code and tried to understand its architecture. What I found was slightly confusing at first but very well laid out and ultimately easy to understand. I tried modifying my copy of the TVShows.rb script to use the new EZRSS pages. A simple Find & Replace worked really well, and I was able to get my copy to read the EZRSS feeds and try to download the torrents. Unfortunately, Ruby’s open-uri library seemed to have difficulty downloading the torrent files themselves. This was quite literally the first time I’d ever seriously looked at a Ruby script, and I wasn’t really able to figure out why open-uri was having trouble with these URIs.

Luckilly, someone much smarter than me could. On the TVShows Forums at Sourceforge, Adam Randall posted that he had fixed all the problems and had TVShows working again. He packaged it up and put it on his personal website, available at I’ve tested the program and it works perfectly. I ran a diff between it and TVShows 0.3.4 and everything looks clean (sorry Adam, I just had to be sure). As Adam mentions, Ruby had issues with the unescaped [ and ] in the torrent URLs, so they were replaced with %5B and %5D respectively.

With Adam’s changes downloaded and installed, TVShows, or as he now calls it, EZTVShows, is working perfectly. I have some tips on how to use it better.

First, run the script for the old TVShows before you install the new one. TVShows caches its script in the Application Support folder, so the changes Adam made won’t take effect if you don’t do this. To run it, open Terminal (it’s in Applications/Utilities), drag the script onto the Terminal window, and hit Return. Drag the TVShows program to the Trash. If you no longer have the file, a copy can be found in the eztvshows.tar.bz2 file from Adam’s site.

Second, there is a way to save your previous show subscriptions. Before you run the uninstall script, navigate to ~/Library/Application Support/TVShows in the Finder and copy the TVShows.plist file somewhere, like the Desktop. Next, run the uninstall script. Install Adam’s version into your Applications folder (by dragging the program there) and run it. You’ll see that none of your shows are selected. Close TVShows, and then go back to the ~/Library/Application Support/TVShows. Replace the TVShows.plist file that’s there with the one you copied earlier. Now, re-launch the TVShows program and you should see all your subscriptions return. However, the show list will be outdated, so click the Update List button to get the new version.

Adam did a great job with the changes and TVShows is working perfectly for me. Unfortunately, the original developer seems to have abandoned the project, and the latest version in the SVN repository on Sourceforge doesn’t build properly. If that can be fixed, there may be future versions of TVShows. But until then, 0.3.4 with the EZRSS changes, available from, is the latest, greatest version.