Guide To Using as EPG Source For EyeTV

Below is a user-contributed guide that was originally prepared for the EyeTV forum. We are sharing here with permission from WisconsinEric.


With the built in TV Guide electronic program guide (EPG) for North America not available for EyeTV as of February 5, 2019, the following guide shows you how to restore the same functionality using one of the two on-line EPG sources for North America: (based in Ottawa, Ontario). A second EPG source,, also provides an EPG you can use in EyeTV with some information xmltvlistings lacks (notably series and episode number), but is less user friendly.

Update 9/2/19: EyeTV has restored its EPG, but it is not necessary to update to Build 7528 (released in August 2019) to use EyeTV. EyeTV's previous release build, 7524, will continue to work properly using either of these alternate EPG's. Of these three EPG's, XMLTVLISTINGS.COM is the cheapest, at $19.99/year.

What this guide shows you how to do in three basic steps:

  1. a) Download a 14-day EPG from
  1. b) Load this downloaded EPG into EyeTV, where it will display in the EyeTV Program Guide, looking just like TV Guide did. Steps 1a and 1b run as a single program.
  1. Automate this so it runs invisibly, updating your EyeTV Program Guide daily at a time you choose.
  1. (optional) Restore the ability to manually update the EPG from within EyeTV; this was lost when the TV Guide source ceased to function.

Throughout this guide information you have to type in that is specific to you and your computer is highlighted.

Important Notes Before We Start

Step 0: Preparatory Steps

0.1. Sign up for an account (14 day free trial in which everything works). Set up your custom channel lineup, and in your dashboard there take note of two pieces of information: the API key, and your 4-digit channel lineup number. The lineup number appears after you've set up the lineup; the API key is issued when you sign up for the account. Both numbers are in your dashboard whenever you log in. When entered in the program below, these numbers eliminate the need for you to log in to download the EPG.

Hint: use the "Modify" button to customize your channel lineup, so just the channels you watch/record appear. This could greatly reduce file size and make loading into EyeTV go much faster. Your final channel lineup needs to exactly match the one you will set up in EyeTV in the next step.

0.2 Prepare EyeTV to receive an xmltv EPG file.

0.2.1 Do a manual download (just this once) from xmltvlistings of the EPG for your channel lineup (click on the blue Download button on your account dashboard, next to your 4-digit Lineup ID). It will give you a 7-day EPG listing. You will use this to set up EyeTV to automatically receive future EPG files in xmltv format.

0.2.2. Open EyeTV and in Preferences set the EPG source to 'none'.

0.2.3 Drag the downloaded EPG file (step 0.2.1) onto the EyeTV icon to load the EPG. You won't see it in program listings until you go to the EyeTV Channels window and do these 3 things:

First, mark as active (checkbox) exactly the same channels you specified for your xmltvlistings channel lineup.

Second, in the EPG column, for each channel, open the drop down menu and select the bottom option, xmltv. This must be done manually for each active channel, but just this once. Ignore the inactive channels. For each channel when you do this, you will be asked to assign the corresponding channel from your xmltvlistings lineup (which is why you had to load it into EyeTV first). As soon as you do that, the EPG schedule for that channel will fill in the EyeTV Program Guide.

Third, save this as a new channel lineup (see bottom of Channels page) and delete the previously active one; the new one will become your active channel lineup for the EPG. I recommend this step as necessary because some of us on the EyeTV Forum found that otherwise the EPG selections revert back to TVGuide or ATSC whenever you quit EyeTV or restart the computer (strangely, for some this third step was not necessary, but it won't hurt).

0.3 On your Mac, in your User/[username]/ directory, create a new folder named Scripts. That's where the program you will create in Step 1 is going to be put. And you're now ready to create it.

Step 1: Program to Download EPG and Load It Into Eyetv

What this step will do: download the 14-day EPG file from to your computer, and then immediately load it into EyeTV, where it will fill in the Program Guide schedule.

1.1 Create the program file. Open text editing software on your Mac. If you are using TextEdit, open Preferences and set it to do plain text files, not rich text. The rich text format (RTF) may contain formatting markers that will cause the program below to fail. Open a window for a new file, and type in the program on the next page.

CRITICALLY IMPORTANT: Manually type in, do NOT copy and paste the code on the next page. Copy/paste is likely to cause errors from unseen formatting markers and spaces; many users have reported that problem.

Comments on step 1.1: I dispensed with a conditional command in the example posted on the EyeTV Forum to check for an active Internet connection; if you wish, get that code from the Forum and insert it here. Or instead add a much shorter but equivalent connection check in the launchd script in Step 2 below. I added a 30 second pause to make sure the download has time to complete (that can be shortened if you wish). John Smith suggests an alternative, which is now (9/2/19) included as an option in Step 1.2 below.

In line 3 below, the curl command has 3 variables you must insert, marked in red following the "get/"):

  1. your API key shown in your account;
  2. your 4-digit lineup number from that you want to download;
  3. the number of days in the future you want the schedule to display. The maximum is '14', which I am using here. You can also delay it, for example 14 days listings starting tomorrow; see the xmltvlistings site under Help, then API for how to do that. Brackets with red text show information you need to insert (without the brackets!).
cd /Users/[yourusername]/Scripts/
curl[your API key]/[your lineup ID]/14 > xmltv.xml
#pause 30 seconds as cushion for download to complete
sleep 30s
#load EPG into EyeTV
open -a EyeTV xmltv.xml

1.2 Option - suggestion by John Smith (8/20/19): "I increased the efficiency of the program by eliminating the 30-second sleep command. Instead concatenate the commands together using "&&". Using that concatenator, the next command runs after the preceding command exits without errors. This will perfectly compensate for a really big EPG on a really slow Internet connection on a really slow computer. So no matter if it takes 3 seconds or 3 minutes, it will wait only as long as necessary. I posted the code change in the EyeTV forum."

1.3 Save this program as a plain text file, with no file type (I used the name getepg). In the rest of this Guide I'm calling this yourprogramname. Drag the file into the Scripts folder you created (in Step 0.3 above). That's also where the downloaded EPG file will automatically go.

[Notes from John Smith 8/17/19: "If chmod fails with "No such file or directory" (it did for me), then you may have your file extensions hidden. Do a File / Get Info in the Finder on [yourprogramname], and uncheck "Hide Extension". Then rename the file in the Get Info Name & Extension box to remove the ".txt" extension. (Note: If it isn't ".txt" extension, then you may not have set TextEdit to plain text as requested in step 1.1). Also, for users of Little Snitch software: If you have a host-based application firewall like Little Snitch, then you should create an "Any Process" rule that allows all outgoing connections to the domain, forever."]

1.4 Identify this as an executable program. Open Apple's Terminal software and type the following 2-lines of instructions (you only have to do this once):

cd /Users/[yourusername]/Scripts/
chmod 755 [yourprogramname]

1.5 This program will be automated in Step 2 below. To run it manually at any time, open Terminal and type these 2 commands; the first is not necessary if you are already in Terminal in the Scripts directory:

cd /Users/[yourusername]/Scripts/

What Step 1 will accomplish: log into your xmltvlistings account, download a 14-day EPG into your Scripts folder (where it will overwrite any previous EPG download), and load it into EyeTV, where it will almost instantly populate the Program Guide.

Automate the Program to Download an EPG from and Load It Into EyeTV

What this step will do: automate Step 1 to run every day at a specific time you choose, so the EPG in EyeTV will update daily without your having to do anything further.

2.1 Wake up your computer to run the program: Pick the time you want this to run (I am using 5:02 am). Go the Mac's Preferences, then under Energy Saver click on Schedule (lower right corner). Set your computer to wake up 2 minutes before the program on the next page runs (so 5 am daily). Optionally, you can sleep the computer 15 minutes later (give ample time for the program to finish).

2.2 Open TextEdit, in Preferences, New Document: Under Format, set it to Plain text. Rich text has additional characters for formatting that can crash a program.

2.3 Open a new document in TextEdit, and type in the following code (top of next page). Again, do NOT copy and paste; in doing so you will often pick up extra characters which make the program fail. This code runs the program created in Step 1. Notes [in brackets] beside the program below are for your information, not part of the code. Here we are using Apple's "launchd" software that controls the ability to run software on a periodic basis.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">
<string>com.[yourusername].[yourprogramname]</string> [note: do not include .plist in this name]
<string>/Users/[yourusername]/Scripts/[yourprogramname]</string> [note: you put the named program from Step 1 in the Scripts folder you created]

Comments on Step 2.3. In the above code, time is the 24 hour clock (so you'd enter '13' under the key variable Hour to run it every day at 1 pm). There are additional optional capabilities in launchd (e.g., to check for an Internet connection before proceeding); you can find several beginners manuals that are pretty easy to follow by searching "Mac launchd user guide" in Google.

2.4 Install the above file in the right place.

2.4.1 Save the file with the file name you chose in Step 1 , except the name will now end in .plist, using this format:
com.[yourusername].[yourfilename].plist. For example: com.smithj.getepg.plist.

2.4.2 Save it into this folder location: /Users/[yourusername]/Library/LaunchAgents . Or you can save on the desktop and drag it into that folder. Note: there is also a LaunchAgents folder in the System Library, you don't want that one. If you can't see the Library folder, press 'Command-Shift-period' to display hidden files and folders. This works both in the Finder and File/Open dialog boxes.

2.5 Final step: load the program so it will run automatically. Launchd has a procedure for loading a program manually using Terminal, but since all programs in the LaunchAgents folder load on computer startup, just reboot your computer and it's ready to run.

What Step 2 will accomplish: runs your previously-created program from Step 1 "yourprogramname" to download the EPG and load it into EyeTV every day at a time you pick (5:02 am in the code above).

You're done. Hopefully, you will have to do all this just once. From now on, you will see an automatically updated 14-day schedule in EyeTV every day.

Step 3: Return Update EPG Now capability to EyeTV

This capability was lost when you switched from TV Guide to xmltv as the EPG source. An "Update EPG Now" option used to appear in the Program Guide drop down menu (which starts with "Go to Now").

What Step 3 will do: add an AppleScript menu to your EyeTV Menu Bar; it will appear as an icon between Window and Help. It will have just one program in it: to update the EPG Guide immediately (I called mine UpdateEPGNow). Click it, and the program you prepared for Step 1 will run instantly. It seems to take 30 seconds to a minute to complete. EyeTV appears to freeze while this runs (but will return to normal when it is done), so I suggest not doing this when you record or watch.

3.l Open Apple's "Script Editor" software; you will find it in Applications/Utilities. Enter just the following one line command:

do shell script "/Users/[yourusername]/Scripts/[yourprogramname]"

[note: this instructs the computer to run the program from Step 1]

3.2 Save it with a descriptive file name (I used UpdateEPGNow); this file name will appear in the AppleScript menu in EyeTV. Save it into this obscure location:
/Library/Application Support/EyeTV/Scripts/

Notes on step 3.2: if there is no Scripts folder, create one. There is also an EyeTV folder within a different Application Support folder in your user account; you do not want that one.

3.3 Quit EyeTV. The new AppleScript menu will appear the next time you restart it (or reboot your computer).

Comment on Step 3: Step 2 probably makes Step 3 superfluous, but in rare occasions (e.g., a late change in TV programs due to a major event) you might want to run it.


Most of what's above is not my original work, I have simply collected in one place work posted by others on the EyeTV Forum, EyeTV users who know more than I do about writing code. I have adapted it in minor ways for using as the EPG source; most of what has been posted on the Forum is for using, which is more complicated. In particular, SPECIAL THANKS TO DC Rackerby (res-ponsible for most of the code I've posted here), Earl Noe, and Millstadt Weber, and to UnixGuy for the Apple-Script code to update EPG now from within EyeTV! And (added 9/2/19) thanks for John Smith (John10044) for additional suggestions and some code testing.