Introduction: Adding Icons and Different EPG to Tvheadend

Broadcast TV in my cord cutting system uses four USB TV receivers connected to a PC running ubuntu and tvheadend. Each TV is connected to a Raspberry Pi running Kodi on OSMC. Tvheadend provides many features including personal video recording (PVR, which is also known as digital video recording, or DVR).

Tvheadend comes with a built-in electronic programming guide (EPG). An EPG is like a TV guide providing show start and stop times and a description of the show. The built-in EPG pulls information about upcoming shows from the over-the-air broadcast signal.

I am not satisfied with the level of detail provided about the shows.

After some research, Schedules Direct and zap2it seem to be the best alternatives for broadcast TV channels in the US. Schedules Direct charges a fee (~$20/yr), and zap2it is free. So, I chose zap2it, but sometime in January zap2it changed its website and downloading EPG data broke. The download code was updated, but the new code failed to download the EPG data. Also, the zap2xml page contains a link to mc2xml, and the link contains a virus. So, I switched to Schedules Direct.

I googled installation zap2it and zap2xml instructions many times and was not satisfied with what I found. I am sure really good instructions are out there, I just couldn’t find them. (See my Duh Moment below)

By not satisfied, I mean the zap2it instructions gloss over critical steps or are outdated. As an example, this reddit post is really great and got me interested in improving the EPG, but it glosses over some very important steps. And it ends with:

"Hope this make some sense to you, and good luck - it IS doable but until you have done it the first time, the process will seem a bit convoluted!"

My Duh Moment: When I finished this instructable using zap2it, I was going back through each step to ensure they worked. And I realized rocky4546's Automatic Installation steps were exactly correct and very easy to follow. For whatever reason, I locked-in on various manual installation guides and skipped his Automated Installation, which works perfectly. I am not sure if this instructable will be helpful, but it was educational for me to go through the manual steps.

I've updated the instructable to use Schedule Direct. Schedule Direct directions are much simpler than zap2it.

Step 1: Gather Parts

This instructable is an add on to this instructable: My Cord Cutting System


  • PC running tvheadend on OSMC
  • Raspberry Pi running Kodi on OSMC
  • Since I was upgrading the icons and the TV Guide, I also changed the skin. I used the standard Kodi skin for several months. So, my wife and I could determine what we liked and what we didn't like. I changed the skin to "xperience1080"
  • Schedules Direct account $19.99 per year


  • Text enclosed in spades is meant to be replaced by your data, ♣username♣

Step 2: Setup Schedule Direct Account

Register for Schedule Direct account

  • Follow this link to Schedules Direct
  • Complete the registration page (image 2)
  • Click Signup! button
  • Schedules Direct should go to your account page. If not, login using your email and password

Step 3: ​Select Your Schedules Direct Channels

Broadcasters are actually transmitting many channels. For example, in my area, The CW (54.1) is broadcasting LAFF (54.2) and Grit (54.3).

I set my system up to only use the main channels in Central Texas: ABC (24.1), CBS (42.1), The CW (54.1), Fox (7.1), NBC (36.1), PBS (18.1), and PBS Kids (18.4). You can choose whatever channels are available. You can always add more channels later.

Select your channels

  • By default all channels are included
  • Click on the link "Add Lineup" (image 1)
    • Enter your zip code
    • Select "Broadcast (Antenna)"
  • Add your favorite channels (image 3)
    • These are mine: ABC (24.1), CBS (42.1), The CW (54.1), Fox (7.1), NBC (36.1), PBS (18.1), and PBS Kids (18.4)
  • Click "Save"

Step 4: Setup Schedules Direct on Your Server

Tvheadend needs to read an xml file from Schedules Direct.

It uses /usr/bin/tv_grab_na_tvmedia. If you do not have this installed, then run:

$ sudo apt-get install xmltv-util

Open a terminal window on your MacBook and log into the the tvheadend server using one of the following:

$ ssh ♣username♣@♣tvheadend-server-name♣.local
$ ssh ♣username♣@♣tvheadend-server-ip-address♣

    On the tvheadend server in a MacBook terminal window, make a directory /home/♣username♣/xmltv with the commands:

    $ sudo mkdir /home/♣username♣/xmltv
    • And make a symbolic link from hts
    $ sudo su - hts
    hts$ ln -s /home/♣username♣/xmltv .xmltv
    hts$ logout

      The above may be a little bit confusing because you login as hts, and your home directory is /home/hts. To see this, enter $ ls ~/.

      When you enter $ logout, you log out of user hts user. The symbolic link won't be visible to your ♣username♣, but it is to the hts user and ~xmltv link is required for proper operation of tvheadend, which uses hts and doesn't know about your ♣username♣.

      Configure Schedules Direct

      Your API Key can be found on your account page (see Image)

      Configure Schedules Direct by running the command:

      $ /usr/bin/tv_grab_na_tvmedia --configure</span><br>
      API Key found on your account dashboard page (
      API Key: ♣your-api-key♣
      Choose one of your lineups. You can add or modify lineups from your account page (
      0: Broadcast-Cedar Park, TX
      Select one: [0 (default=0)] 0

      Step 5: Tvheadend Grabber Module

      Enable /usr/bin/tv_grab_na_tvmedia

      • In TVHeadend website, go to Configuration -> Channel / EPG -> EPG Grabber Modules

        • For each green check, (only do one at a time)
          • Uncheck the Enabled box, and
          • Save
          • You may have to refresh the page to ensure the green check are all gone
        • Now, look for "Internal: XMLTV: North America ( by TVMedia"
          • In the lower right corner, click on the double up arrow icon, which opens the log window
          • Select the line with tv_grab_file
          • Check the Enabled box
          • Save
          • the log window will show whether it is working or not

      Step 6: EPG Grabber

      EPG Grabber

      • In TVHeadend website, go to Configuration -> Channel / EPG -> EPG Grabber
      • Check "Update Channel Number"
      • In Cron multiline:
        • # grabber runs at 6am. Grabber runs at 6am, 2pm and 6pm everyday
0 5 * * *
0 14 * * *
0 18 * * *
      • Click Save

      EPG Channels

      • Channels should look like those in the image

      Step 7: TV Icons

      Find TV Icons

      • I googled: abc tv icon using the image setting, and was able to find icons for each of the networks.
      • I selected both png and jpg files and didn't worry about the size of the file
      • I saved the image to my MacBook

      Create directory

      • On the MacBook in a terminal window, login ($ ssh)
      • Create a directory
      $ sudo mkdir /home/♣username♣/xmltv/icons
      $ logout

      Copy icons to Raspberry Pi

      • In a terminal window, copy the icons to the Raspberry Pi
      $ scp *.png ♣username♣@♣tvheadend-server-name♣.local:/home/♣username♣/xmltv/icons/.

      Enable icons in tvheadend

      • In browser, go to tvheadend and Configuration -> Channel / EPG -> Channels
      • Select a line for one of your channels
      • Click Edit
      • In the User Icon field, enter the path, something like (Fox is channel 7.1, and the icon is 7.1.,png)
        • file:///home/hts/~xmltv/icons/7.1.png

      Step 8: Appendix: References

      Step 9: Appendix: Updates


      • was upgraded and several things changed. So, I made changes to accommodate the changes.


      • Earlier in the month, zap2it changed its website and somehow broke pulling the EPG data. I upgraded to the new version of code, but that didn't help and it would error out before completing.
      • Switched from zap2it to Schedules Direct, which is a pay service (~$20/yr), but it is much easier to use.
      • Updated instructable to reflect Schedules Direct

      Step 10: Appendix: Troubleshooting

      Step 11: Appendix: Automated Install

      While I didn't use this, it seems like it should work: