XMLTV (zap2xml.pl for OSX)

Setting up XMLTV using zap2xml.pl with OSX seems more difficult than setting one up in Windows. Took me a few hours to get it working since this is my first time setting it up with OSX.


  • OSX Plex Media Server

Step 1: Command Line Tools

Launch Terminal (found in /Application/Utilities)

Type the following command to install Command Line Tools:

xcode-select --install

OS X 10.10 Yosemite-2015-03-25-20-40-28

Click Install and wait for it to be completed.


Step 2: Install Perl Modules

Using Terminal, install cpanm with security privileges using the following commands:

sudo cpan App::cpanminus

Once complete, install the JSON module:

sudo cpanm JSON


Step 3: Download zap2xml.pl

Obtain the latest copy of zap2xml.pl from http://zap2xml.awardspace.info/.

Copy to a folder of your choice. For this tutorial, my folder will be:



Step 4: zap2it.com

Go to http://www.zap2it.com/tvlistings/ and set the zip code and provider. For this example, my zip code  would be 01851 and provider Broadcast (Antenna).

The following information from your URL would be used to create your zap2xml command:

  • zip
  • lineupid



Step 5: Test Run

Using Terminal, navigate to the folder where zap2xml.pl resides and run the perl script with the desired options.

Navigate to the folder with the following command:

cd /Users/admin/HDHRViewer

Example perl script with options:

perl zap2xml.pl -Z zipcode -Y lineupid -d days
perl zap2xml.pl -Z 01851 -Y USA-OTA01851 -d 2

Note: By default, zap2xml will fetch 7 days of data without the -d option. Setting -d 2 will make zap2xml fetch 2 days for of data which keeps the xmltv.xml file small and at the same time, shows listing that is past midnight. The smaller the file, the faster HDHR Viewer runs with XMLTV enabled.

Note: If you have a zap2it account, utilize it to set favorite channels to fetch data for channels you only have, or would like to see. The command would be different, refer to zap2xml’s site. Example:

perl zap2xml.pl -u myemail@example.com -p MyPassword -d 2

OS X 10.10 Yosemite-2015-03-25-21-26-14

OS X 10.10 Yosemite-2015-03-25-21-28-22


Step 6: HDHR Viewer Test Run

Go to the HDHR Viewer Settings, check Enable XMLTV, and set the XMLTV Location to location path of your file (eg. /Users/admin/HDHRViewer/xmltv.xml)

OS X 10.10 Yosemite-2015-03-25-21-37-46

Test it out.zap2xml4


Step 7:  Shell script + launchd

Create a zap2xml.sh shell script file using TextEdit (remember to Format->make Plain Text) in the HDHRViewer directory. Example:

cd /Users/admin/HDHRViewer
perl zap2xml.pl -Z 01851 -Y USA-OTA01851 -d 2

Give the zap2xml.sh file an executable permission using the command:

chmod +x zap2xml.sh

Test your shell script to make sure it works by running:


Create a com.zap2xml.plist file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Copy the com.zap2xml.plist file to /Library/LaunchDaemons or /Library/LaunchAgents (run, when user logs in).

sudo cp com.zap2xml.plist /Library/LaunchDaemons

To run the file without rebooting:

launchctl load -w /Library/LaunchDaemons/com.zap2xml.plist


launchctl load -w /Library/LaunchAgents/com.zap2xml.plist