Update (25/09/2020) : This guide is now out-of-date and is only provided for archive purposes. This guide has now been adopted to the Raspberry Pi and updated based on this. The Raspberry Pi has more than enough power to perform TV duties in this mannor.

Update (23/10/2019) : As many of you now know, Plex replaced FreeEPG with IceTV which now no longer lets us use open source solutions like TVHeadend Server. Unfortunately due to this change, the below guide now no longer works within Australia and a couple of other countries which use the IceTV EPG service . I have been trying some alternatives, but to date none have functioned at all through Plex.

This guide will cover how to install TVHeadend, tvhProxy and integrate this all into Plex through the Live TV & DVR options.

This guide will use the following applications to achieve this:

TVHeadend: an application that reads video streams and allows the sources to be recorded or streamed via network.

tvhProxy: an application to proxy between TVHeadend and Plex. This will mimic a HDHomerun Tuner.

Plex: Media Center Server. This should already be setup prior to going through this guide. Setup of Plex will not be covered in this guide.


Installing Ubuntu Server 16.04.2

In the screenshots below I installed Ubuntu Server on a old desktop and I have had to capture the screenshot with my phone.

I have found it is easier to setup on a physical device rather than virtually. It is possible to do this virtually on either VMware ESXi or UnRaid. You do need to have PCI passthrough working correctly before attempting however. To simplify the setup I opted to run it on an old desktop.

  1. From a pre-provisioned USB with Ubuntu Server 16.04 installed boot to the USB.
  2. Ubuntu Server will load up, select English to begin the installation.
  3. Select Install Ubuntu Server.
  4. Select your Language. English
  5. Select your Region. Australia
  6. Configure your keyboard. No
  7. Configure keyboard country of origin. English (US)
  8. Configure the keyboard layout. English (US)
  9. Select your network adapter. In my case I also had a wireless card installed. Hence the options for 2 adapters, in your case it will default to the NIC adapter and may not prompt either.
  10. Enter your Hostname. Can be anything you like, I went with “TVHeadend”.
  11. Enter Full first and last name of the user. In my case I just entered “tvheadenduser”.
  12. Enter the user account. tvheaduser
  13. Enter a password and verify the password.
  14. Encrypt your home directory? No
  15. Timezone check. Australia/ Queensland - Yes
  16. Partitioning of the disk. This step you will need to pick the disk you want to install Ubuntu Server on. In my case it was the 128GB drive.
  17. Partitioning method. Guided - use entire disk.
  18. The ‘Are you sure’ part of the installation. Write changes to disk. Yes
  19. Proxy information. Leave blank if you don’t have a HTTP proxy.
  20. Automatic updates? I usually set this to No automatic updates, and manually install them. This server has a purpose of only running TVHeadend and if I automatically do an update will it break it or be compatible? These are the checks I will do prior to updating the box.
  21. Install features we want on the server. Because this box will be headless we want a way to remote into the server. The easiest way is to SSH in. Select OpenSSH Server and hit continue.
  22. Install the GRUB boot loader master boot record to boot into Ubuntu Server. Yes
  23. Location of the boot record. Because we are installing from a USB, the USB storage is also an option to set the boot loader on. Select your local drive. In my case its the 128GB drive again.
  24. We now have installed Ubuntu Server, remove the USB drive and select continue.
  25. The computer will now reboot and load into Ubuntu Server. You should now be able to login using the credentials you set.
  26. Once logged in run the following command to determine the IP address.



  27. As you can see is the current IP of the server. Depending on the router/ DHCP configuration you may need to check to ensure that this remains static. The IP of the TVHeadend Server must be a static address for it to work.
  28. Open up a new Putty session and login to your server. The host is the IP address. Select Yes to accept the new key.
  29. You should now see a terminal into your server. Again login.

Installing TVHeadend

The following steps have been sourced from

TVHeadend.org and may be subject to change in the future. It is best to double check their source first and verify if it matches what is below here. As of the 13/03/2018 the following steps are up-to-date.

  1. Add the bintray’s GPG key

    sudo apt-key adv –keyserver hkp://keyserver.ubuntu.com:80 –recv-keys 379CE192D401AB61

  2. Select which build type you want and add the repository accordingly. In my case the below is what I used.

    echo “deb https://dl.bintray.com/tvheadend/deb xenial stable-4.2” sudo tee /etc/apt/sources.list.d/tvheadend.list

    ### Supported Distributions and Architectures




    Debian Jessie “jessie” (8.x)

    - i386 - amd64

    Debian Stretch “stretch” (9.x)

    - i386 - amd64

    Ubuntu Xenial “xenial” (16.04)

    - i386 - amd64 - armhf - arm64

    armhf/arm64 do not have transcoding support (yet)

    Trusty “trusty” (14.04)

    - i386 - amd64

    ### Build Types and Versions

    Build Type



    Repo Component


    The latest version marked for release




    The latest stable code with changes/fixes between releases




    This is the current development “bleeding-edge”



  3. Refresh the available packages and install. Keep an eye out for anything that mentions TVHeadend.

    sudo apt update sudo apt-get install tvheadend

  4. Set a username of the TVHeadend administrator. I used Admin.
  5. Set a password.
  6. Once the installation is complete, you can access via http://localhost:9981.
  7. TVHeadend installation completed.
  8. Access TVHeadend URL with your favorite browser and login.
  9. The following Welcome setup wizard will prompt, click on Cancel.
  10. Go to Configuration, DVB Inputs and TV Adapters. Verify that your TV Tuner cards are being detected. I have had a lot of luck with the tuner cards I have thrown at TVHeadend. If you stick with the Avermedia/ Leadtek brands you should be okay.
  11. Now that we have verified that the tuner is working we need to setup the scanning range to tell the tuner what frequency to scan in. The next couple of steps are very similar to setting up a new tv. Click on Networks beside TV Adapters.
  12. Select Add, Click on the drop down arrow and select DVB-T Network.
  13. In the Add DVB-T Network, enter the following and select Create.
  14. Go back to the TV Adapters tab and select the tv adapter. On the right hand side select the drop down on Networks and select Australia and Enable the adapter. Click on save.
  15. Now that we have added a way for the TV tuner to scan channels, lets scan some channels. Go back into the Networks tab and select the Australia network, and select Force Scan.
  16. Coffee break.. This is a good time to grab yourself your favorite beverage. Depending on hardware this could take about 30 minutes to complete.
  17. Click on the Services tab now and you should start to see after a while TV channels being picked up. At this stage I would also go to an actual TV and check the EPG guide and see how many channels it picks up. Once the scan on TVHeadend completes you want to see the same amount of channels. In my area locally I can pick up about 30 - 40 free to air channels.As you can see there have been channels added but none of the channel ID information has been detected yet.
  18. Once everything is finished up you should see something similar like the following, you now have TV channels with IDs.
  19. We now need to add them finally to TVHeadend. Click on Map Services and Map all services.
  20. Click on Map services. This will now start to map each channel and get it imported into the TVHeadend database.
  21. We now need to test a couple of channels to ensure that everything is working as it should. Click on the Play button on one of the channels and you should download a .m3u file.
  22. Open it up with VLC and you should see live TV start to play. Ensure that the quality and sound is okay. At a later stage I will add a channel troubleshooting guide to outline some things you could do if you run into channel problems.


Setting up tvhProxy

Now that we have TVHeadend installed and working correctly we need to setup the proxy between Plex and TVHeadend. Originally when I first found the tvhProxy I had some trouble getting it to run and didn’t understand what was going on. It turned out that there were also other users in the same boat. Steps 1 to 4 were not actually in the readme!

Back in the Ubuntu Server putty terminal run the following commands:

  1. Install PIP

    sudo apt install python-pip

  2. Create another user for tvhProxy

    sudo useradd -m tvh -s /bin/bash

  3. Become the user ‘tvh’

    sudo su - tvh

  4. Get the files and setup the environment

    git clone https://github.com/jkaberg/tvhProxy.git cd tvhProxy virtualenv venv . venv/bin/activate pip install setuptools –upgrade pip install wheel pip install -r requirements.txt

  5. Exit out of the tvh user account and go into the home directory of tvh.

    exit cd /home cd tvh cd tvhProxy

  6. We now need to setup the tvhProxy.py script with details from the TVHeadend server.

    sudo nano tvhProxy.py

  7. Edit the following lines:

    ‘tvhURL’: os.environ.get(‘TVH_URL’) or ‘http://test:test@localhost:9981’, ‘tvhProxyURL’: os.environ.get(‘TVH_PROXY_URL’) or ‘http://localhost’,

    http://test:test@localhost:9981 > http://[user account to log into tvheadend with]:[Password of this account]@[IP address of the TVHeadend server]:9981

    http://localhost > http://[IP of TVHeadend Server]

  8. Create a service that automatically starts when Ubuntu Server boots.

    sudo cp tvhProxy.service /etc/systemd/system/tvhProxy.service sudo systemctl daemon-reload sudo systemctl enable tvhProxy.service sudo systemctl start tvhProxy.service


Setting up Plex

Nearly done! We are in the home stretch now.

  1. Log into your Plex and go to Settings and Live TV & DVR.
  2. Click on Set up Plex DVR.
  3. The following window will appear. Enter the IP address of your TVHeadend Server with port 5004 on the end. Click on connect, and continue.
  4. The next section will show you how many channels have been scanned. Click continue.
  5. This section is device mapping. If everything looks right, click continue.
  6. Setup complete, click on View Program Guide.
  7. Done, you now have TV in Plex. Congrats!


[caption id=”attachment_1257” align=”alignnone” width=”1024”] Discover[/caption]

If you have done everything right, you should now see your Program Guide displaying content and a new section called Live with Recording Schedule and Program Guide.

[caption id=”attachment_1259” align=”alignnone” width=”1024”] Watch Now - Live TV. Representation of each live channel.[/caption]


[caption id=”attachment_1261” align=”alignnone” width=”1024”] TV Shows[/caption]

As you can see the TV Shows is missing some covers. From time to time I have noticed that this occurs. Most of the time its because the internal scanners can’t pick up the correct cover art to display.

[caption id=”attachment_1260” align=”alignnone” width=”1024”] Movies[/caption]


[caption id=”attachment_1258” align=”alignnone” width=”1024”] Recording Schedule[/caption]

I have now been trialing this for some time now and can say that it works very well and has been a great alternative to some of the other options out there. I am a huge fan of this as now ALL my media is together in the one place.



  • (15/05/2018) Added install PIP step in tvhProxy.