Thursday, 23 August 2018

Idiots Guide - Installing TVHeadEnd on Ubuntu 18.04.1 with the UK XBox USB TV Tuner and linking it to a Plex DVR



Yes, I know.  It's a shocker.  I am a geek though so not every post on here will be about running.
I spent a good few hours faffing around with this trying to get it to work this weekend, following various guides from places such as Kieren Anderson's Guide here, pages from the TVHeadEnd Project Boards and a few more random places.

Why am I doing this?

A bit of background.  I read the Plex DVR specs and assumed that the "Hauppauge Freeview HD TV for Xbox One" was in fact the "Official Xbox One Digital Tuner" (note, never assume).  So I blindly ordered two of the Official Xbox One Digital Tuner's (only £6 each from Argos eBay outlet so no massive loss).  Assuming I'd bought the Hauppauge and that it would work with Windows I set about installing them only then realised that I'd ordered the wrong thing when the Hauppauge drivers failed to recognise it in either Windows 7, or Windows 10.

A bit of googling showed that the USB tuners I had bought do work under Linux with TVHeadEnd, and that you can use a program called tvhProxy to send this to Plex as if it was a HDHomeRun to watch live TV and have DVR functionality.

The reason for me doing this is that I want to put a TV in the kitchen, and I don't want to drill holes through the wall to put in an aerial, so if I can get live TV through Plex, I can put a chromecast, or fire stick or something on the TV in the kitchen and save me causing a complete mess in the kitchen with a drill..

With that in mind, I needed an idiots guide to follow as myself and Linux have a tempestuous relationship at the best of times.  The guide by Kieran above seemed ideal, as it basically did what I needed but he didn't use the Xbox tuners and was tuning in TV in Australia  It was a good start though but as you can guess by the fact I'm writing this, it wasn't completely idiot proof enough for me so I needed my own guide.

Pre-Requisites for this guide. 

Ubuntu Server 18.04 ISO from (I'm going to assume you know how to create a bootable USB stick, or burn a DVD or however you'd normally install an OS).  If you do need help creating a USB bootable stick to use, check out this link.

A physical machine, connected to your network, to put it on (VM's don't always play nicely with sharing USB resources, yours may work but I put this on a physical PC as I had a spare lying around).

Plex Server already setup and a Plex Pass subscription on a machine of your choice.

Xbox One USB Digital Tuner
A decent Aerial.
Internet access.
PuTTY SSH terminal.

Note on commands.  If you need to type, or copy and paste something in a terminal, I will change the font to courier to differentiate it.  It will generally be on a separate line and centred as well to help distinguish it.  Each distinct line will be separated by a line break, so if a command wraps on to the next immediate line, then that is one command.  So
sudo mv /etc/netplan/50-cloud-init.yaml /etc/netplan/50-cloud-init.yaml.bak
is one command and should be pasted as one line.  It seems that blogger doesn't have nice sections for code so its the best I can do.


Install Ubuntu Server 18.04.1 from USB.

Firstly, forgive my poor quality screen grabs, I had to use my mobile phone.

Stick your boot medium in and boot your PC.  Choose to boot from the medium and you will shortly be presented with the following screen.

Choose English (or the language of your choice).

Choose "Install Ubuntu"

If you have a worrking DHCP server on your network (and a lan cable attached), you'll see the following screen.  If not it will say it cannot configure it, either way, just choose "Done" and move on.

If you need a proxy to get out on to the internet, enter it here.  I don't so click "Done" when ready.

Choose "Done" on the alternate mirror details (the defaults are fine).

Click "Use An Entire Disk" if, like me, you are using an entire machine for this.  If you are not, then choose your preferred option and click "Done" when ready.

Select the Disk.  Only one in my machine so press Enter.

It'll come back with the preferred disk settings, just accept them and click "Done".

Final confirmation.  No turning back after this stage.  EVERYTHING ON YOUR DRIVE IS ABOUT TO BE LOST FOREVER.  Yes, even your windows stuff, everything.  So only proceed if you are sure you want to carry on.  Select "Continue" if you do and let it do its thing formatting.

Now it will ask for usernames and passwords.  Nice and simple, your name: tvheadend, servers name: tvheadend, username: tvhead, password of your choice.  If you want to import your ssh identity, here is the place to do it.  I do not.  Click "Done".

Ignore all this, click "Done".

Watch the installer install all the gubbins and wait.

Once completed, a reboot now will appear.  Click "Reboot Now" and let your machine reboot.

When it reboots (and you login), you'll see something similar to the screen below.  If you see the installer again, you've let the machine boot from the install medium again, so reboot and remove it.  Log in with the user and password we created earlier.

The important info here is the IP address for eno1, which in this case is  We will use this to SSH on to the machine using PuTTY and continue the configuration using that.

From another machine, using PuTTY, connect to your IP listed above (in my case,

You will get a warning about an SSH key, this is only because its your first time logging in to the machine via SSH.  Its perfectly fine and just click Yes to accept it.

You'll then be faced with this screen. Login using the details we created above, "tvhead" and the password you chose.

Once logged in, we need to set a static IP address.  This is essential to allow the server to connect to Plex and to administer it via your web interface going forward.

We do this using netplan on Ubuntu 18.04 (this is new).  Firstly we need to edit a new config file for our network adapter.  We need to find out some details for this config file and we can get them by using the "ifconfig" command, so type that and press enter and something similar to the following will appear.


The highlighted section on the second line "inet" shows we have been allocated by our DHCP server and I would rather give it something more memorable.

Create a new file by using the following command in your PuTTY session.
sudo nano /etc/netplan/01-netcfg.yaml 
And once in the file, paste the following information in to the file via your PuTTY session.  The spacing is very important.  For every line you can see indenting, you must indent by 2 spaces.  Note: For this code example, I have not centred it as the formatting is important.

# This file describes the network interfaces available on your system
# For more information, see netplan(5).

  version: 2
      dhcp4: false
      dhcp6: false

It should look like the following screengrab when you are done:

To exit nano, press CTRL-X, y (enter), (enter)

Some comments here, the IP address must match the information from ifconfig the the first three octets (the 192.168.x), so if say your ifconfig showed an ip of, then the IP you are choosing will need to be in that range (using my example of 123 it will be, the gateway will (more than likely) be etc). 

The name of the interface above is eno1, that the name of the interface shown when we used ifconfig.  Make sure it matches.

There is also a default config for the cloud service which we do not need, and it actually can conflict with the settings we've just made so its best to move it out of the way.  To do this, type the following:

sudo mv /etc/netplan/50-cloud-init.yaml /etc/netplan/50-cloud-init.yaml.bak

To commit the change, and to check you have the syntax correct, type the following.
sudo netplan apply

We now need to update the OS so its bang up to date.  Most guides don't advise to do this but i'm a rebel so lets go for it.

Type the following:

sudo apt-get update

This will grab a list of updates from the ubuntu servers.  We then need to actually install them.  We do this using the following command:

sudo apt-get upgrade

select Y and let it do its thing, whilst its installing, you'll see info like the following.

Let it finish, the we will do the first (of many) reboots.  To reboot we use the command:

sudo reboot now

Let it reboot, reconnect your putty session *to your new IP address you set earlier* (in my case,

Install TVHeadEnd

The following steps here are basically taken from and it may be worth just checking there to see if the process has changed any before cracking on.  As of 21st of August 2018, the following settings worked for me using the Doozer method, the BinTray settings did not work.

Install the GPG keys for the Doozer installation method.

wget -qO- | sudo apt-key add -

We then need to add in the doozer repo to apt-get.  Use the following command to do this:

echo "deb bionic main" | sudo tee -a /etc/apt/sources.list.d/tvheadend.list

then run:

sudo apt-get update

The instructions then tell you to do this:

sudo apt-get install tvheadend

However, if you do this, it will give an error (as seen above) about some missing dependencies.

For some reason, there is a universal repo missing from Ubuntu which contains some parts of the tvheadend requirements.  Not sure why but we need to add it in before we try and install tvheadend.  To do this, cut and paste the following command.

sudo add-apt-repository "deb $(lsb_release -sc) universe"

once its done, we can now do the command:

sudo apt-get install tvheadend

It will tell you that it will take up 124 meg of HDD space, and do you want to continue.  Heck yes we do, so hit Y and enter and let it start downloading and installing.

The installer then kicks in.

It asks for a username, I just chose admin

Enter a password, you'll need both the username and password to finish the setup and administer tvheadend later so try and remember it.

Here it tells you that you can access it later using the localhost address and the port 9981.

Click OK and it will continue with the install.

Once its finished, you'll see the screen above.  We now need to configure the XBox One tuner by grabbing the latest drivers for tvheadend and also the firmware for the tuner.

Drivers first.  We need to compile and build these, and for some reason again the files needed for this are missing in Ubuntu server.  So perform the following:

git clone git://
cd media_build/

and it will fail with the following message

Cut and paste the highlighted line in your terminal session and install the missing files.  Note: I've not included it here as you may already have some of the dependencies I needed, or you may need more etc so just copy whatever it tells you that you need and install those.

Let it finish, and once installed, go back to the media_build folder (you should still be in it to be fair) and again, type:

This time it will show you a warning, its fine just let it do its thing.  It takes about 3 minutes on my machine but just go make a brew and come back and it should be done.

Its done.

It will now tell you to run "make install", well, almost.  Because we actually want to run

sudo make install

This will actually install the drivers we have just built.  Again, let it do its thing and once its done we will need to copy over the firmware.

The firmware for the tuner need to be placed in "/lib/firmware"

the easiest way to do this it type the following in your PuTTY session:

cd /lib/firmware

Once copied, its time for another reboot.

sudo reboot now

Allow the machine to reboot, and in your web browser, type the following to connect to tvheadend:

It will ask you for the username and password we setup earlier (admin, password of your choice).

Log in, and you will be presented with the following wizard, just click Cancel.

We are interested in the Configuration tab, followed by DVB Inputs and hopefully, you should see the XBox Tuner listed (as a Panasonic MN88472).  It will have two devices listed, DVB-T and DVB-C, DVB-T is terrestrial (i.e. freeview) and DVB-C is for Cable.  We are only interested in the DVB-T adapter.

Click on the "Networks" tab, and then click "Add", in the new box, select the dropdown and choose "DVB-T Network"

Give it a friendly name, i've called mine WinterHill as thats the name of my local transmitter.  Under Pre-defined muxes, select your local transmitter (again, mine is WinterHill, so I have selected uk-WinterHill).  Yours should be listed there, if you are unsure you can find out on various websites as to what your local one is such as Digital UK Coverage Checker.

Here is the network once you have clicked Add.

Heading back to the TV Adapters tab, we can now enable the card.  Click on the DVB-T part, and click on Enable.  Select the "WinterHill" network (the one we named earlier) and click Save.

Now, i've set this up twice, and the first time, this next step worked without a reboot,. but the second time it did not.  So give it a go, but if the scan finds nothing, reboot and try again.

Click Networks, Click on WinterHill and click "Force Scan".

Assuming its worked, you can head to the "services" tab and watch it populating the channels.  

Once its done, we need to then map the channels to services for TVHeadEnd to use.
To do this, click on "Services", "Map Services", "Map all services".

Make sure the following options are ticked and then click "Map Services".

Once its complete, we need to check we can actually play the channels, so go to a channel, and press the little "play" icon.

This will download an M3u playlist file.  Open it in VLC or something similar and you should see the TV playing.

Congratulations, tvheadend is installed and configured.


Install tvhProxy

We now need to install tvhProxy.  Thankfully this was a doddle following Kieran's guide so i'll mainly just cut n paste his instructions, because i'm lazy.

The only gotcha I found was that we needed to install the virtualenv system, so i'll just put that in at the appropriate step.  No screen grabs here as its really cut n paste friendly from here on.

Back in the PuTTY terminal run the following commands:

Firstly, we need to install PIP.

sudo apt install python-pip

We then need to add the virtualenv

sudo apt-get install virtualenv

Then we need to create another user for tvhProxy

sudo useradd -m tvh -s /bin/bash

Become the user ‘tvh’

sudo su - tvh

Get the files required and setup the environment

cd tvhProxy
virtualenv venv
. venv/bin/activate
pip install setuptools --upgrade
pip install wheel
pip install -r requirements.txt

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

cd /home/tvh/tvhProxy

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

sudo nano

Find and 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',

needs to be changed to


needs to be changed to

Press CTRL-X, y (enter), (enter) to exit nano.

Note: as before, these are my settings.  If you have setup a different IP address then use that in the settings above.

Create a service that automatically starts tvhProxy when the 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

Job done.  I'd give it a reboot here to make sure all is well.

sudo reboot now


Set up Plex Server

Adding to plex is very easy, so i'm going to lift Kieran's info again, it will look slightly different as he's doing the Australian channels but the principle is the same.

Nearly done! We are in the home stretch now.

Log into your Plex Server and go to Settings and Live TV & DVR.

Click on Set up Plex DVR.

The following window will appear. Click the little downward pointing arrow and enter the IP address of your TVHeadend Server ( with port 5004 on the end. Click on connect, and continue.

The next section will show you how many channels have been scanned. Click continue.

This section is device mapping. If everything looks right, click continue.

Setup complete, click on View Program Guide.

Done, you now have TV in Plex. Congrats!

It will take a wee while for the EPG to populate in Plex so let it finish but once its done you should have a fully functional DVR solution in Plex.

If you want to, you can add additional tuners to the setup, just do the same steps in TVHeadEnd to add them in and Plex should be able to pick them up.

And that ends the guide, I hope someone finds it useful.  If it helps one person get this installed and working properly then i'll be a happy bunny.

Did you get it working, leave me a comment below and let me know.

No comments:

Post a Comment