TVHeadend, IPTV & EPG

I tried initially running TVHeadend (TVH) in a docker container initially, but whilt PVR functionality worked fine, watching streams live was very hit and miss. In the end, I installed it from a PPA on ubuntu and it has worked flawlessly.

I'm not intending to go through the installation instructions, these are readily available elsewhere such as this link from the TVH website:, when I followed the guide the host was down, and appears to have been down for a while. I used the PPA instructions at the bottom of that page, which worked fine.

Once installed, when you browse to http://YOUR.IP:9981/ you should see the basic configuration page to pick languages etc.

I'm sure there are other ways of setting this up, and I'm no expert, but this approach worked for me. First thing to do is to change the web view to Expert, as a lot of the settings are hidden when in basic view. You can find this setting under Configuration>General>Base as shown below.

Next we need to head to Configuration>DVB Inputs>Networks and click Add.

I juse used IPTV Networkk, but I've seen a lot of others use the automatic version. Your mileage may vary.

Next fill in the items with your details. Most of it can be ignored, but you will need to click enable, give it a Network Name, along with your URL for your m3u list. As you can see, I've just picked one that doesn't exist for the sake of this screenshot.

If you are only allowed a certain number of streams by your provider, this is where you limit it. I believe the default is 0 (zero) which no limit. Finally, I allow it to scan after creation to find the various

When you have entered your details, save & close this dialogue box. Under Configuration>DVB Inputs>Networks you will now see your name, and after a few moments you should see the number of Muxes increase. I would wait while TVH scans all the muxes one by one until the number of services identified is similar to the number number of Muxes.

Next click over the Configuration>DVB Inputs>Services where we can map all services. I'm no TVH expert, but I think this pulls them into TVH so we can associate EPG data with them.

Once mapped we can look into the EPG side of things. However, I can't stress this strongly enough, it is worth waiting for all services to be scanned, and sucessfully mapped before looking at EPG.

I will be using the EPG information my IPTV supplier provides rather than one of the other online oned. Under the Configuration>Channel/EPG>EPG Grabber Modules, disable any that are all ready enabled by default. The chances are, even if they are enabled they are not configured yet so are unlikely to work from a fresh install.

We need to enable, is probably at the top of the list called "External: XMLTV". When you click on it, we just need to click enable, make a note of the Path and then save.

On my install, the path is "/home/hts/.hts/tvheadend/epggrab/xmltv.sock" we will be using this path to simply squirt our EPG file from the provider directly into the TVH specified socket. In order to do this we need a utility called "socat" which is a multipurpose relay tool. I believe we can also use the netcat utility if you prefer. To install socat on any ubuntu based distro is as easy as:

sudo apt update && sudo apt install socat -y

Once installed, it is a simply a case of downloading your epg file from your provider, then using socat to provide it into TVH.



cd /home/hts/
wget $EPGURL -O epg.xml

cat epg.xml | socat - UNIX-CONNECT:.hts/tvheadend/epggrab/xmltv.sock 

exit 0

Once you have created this script, run it, and assuming your URL etc is all correct you should now have some EPG data within TVH. Click on the bottom right corner of the TVH interface, and the logging window will open.

With that open, when you run the simple bash script you will see the input information into TVH.

Once we have the feed, many of the channels will be automatically mapped by TVH. However, there may be some where this hasn't been possible. I would recommend going to Configuration>Channel/EPG>Channels and checking it. Select a channel and click edit. You should see something similar to the screenshot below:

Once you have been through and mapped any channels not already done so. Once the EPG data is next imported, the EPG on TVH should show the correct information.

As with everything on this site, this is primarily aimed at helping me next time I have to do this. If in the mean time, it helps someone else, then great. I am not a TVH expert, nor a good bash script author. YMMV.