Skip to content

Use TvHeadend, Raspberry Pi and Kodi to stream TV in your home

TvHeadend is a TV streaming server and recorder that can use TV as an input source, such as cable, terrestrial and satellite, as well as SAT-IP and HDHomerun. It can be installed on a Rasprberry Pi, and TV content can be streamed over your local network using a multimedia player such as Kodi.

TVHeadend typically runs as a background service, and is then used to stream TV through your Local Area Network over http (using VLC), htsp (using Kodi) and even SAT-IP streaming.

Kodi is used as a frontend multimedia client service to view TV content (and other media) on devices such as smart TVs, desktop PCs, laptops, tablets and mobile devices. Kodi is very versatile as it can be installed on all the main operating systems, from Windows, macOS, Linux, Android and iOS.

TVHeadend works beautifully on an energy miser such as a Raspberry Pi, as typically we want the TV service to run around the clock, especially if we wish to record TV content at night or during the day.

What is needed

  • A working TV connection
  • A TV tuner
  • A Raspberry PI 4 with Libre Elec OS
  • A device with Kodi installed to view the content

The TV tuner provides the TV stations and muxes, and acts as an input source for TvHeadend.

For this project I went with an Xbox One usb TV tuner that I picked up in a local shop for nine euros. They can also be found online and are a cheap alternative that work well for DVB-T, which is terrestrial TV. They also work with DVB-C, which is cable television.

You will need a Raspberry Pi 4 or higher for best performance. The optimal setup is LibreElec, which translates to just enough OS for Kodi to run, a lean image that gives good performance. Another advantage of LibreElec is that TvHeadend is included as part of the package, it does not need to be installed.

LibreElec can be flashed onto an SD card for use with the Pi, using the Raspberry Pi Imager, which can be downloaded on all the main operating systems.

Xbox One tuner setup

The latest version of Raspberry Pi OS is based on Debian Bookworm and has the lastest Linux Kernel 6+. What this means is that the tuner usb firmware will be recognised and will work on the Raspberry Pi. The firmware for the actual Xbox tuner itself may need to be installed.

The following firmware file is required for the Xbox tuner: dvb-demod-mn88472-02.fw

Go to > /lib/firmware and verify if the file is installed on the system. If not, it needs to be downloaded from the internet and added to this directory on the Raspberry Pi.

Libre Elec is a barebones system, and as such, there is no terminal or shell installed. This means that you need to access the system over SSH, and transfer the needed firmware file to the /lib/firmware folder with scp or sftp.

If you are not familiar with SSH, an easier option is to install TvHeadend directly on to a Raspberry Pi OS, with the following: 

sudo apt install tvheadend
A quick internet search for "firmware for Xbox One tuner" will lead you in the right direction. Once you have this installed in the /lib/firmware diretory, the Xbox One tuner should be ready, connected and initialized.

To check this, run the following command: 

sudo dmesg | grep dvb
This searches for dvb devices on the system, and if you get a message saying that the tuner is connected and intialized, you're good to go.

This step is essential to ensure that the tuner is working correctly before moving on to the next step which is the setup and configuration of TVHeadend.

TvHeadend setup and configuration

TVHeadend by default will run on port 9981.

Check for the IP address of the Raspberry Pi: 

ip -a
Then type this in a browser, followed by the port number, such as

192.168.0.115:9981 This will bring you directly to the TvHeadend interface, where the service runs, and where it can be configured.

An admin user can be set up in the Users tab, > Configuration > Users, where the password can be set. This is important for basic security on a server such as this one which is running on your local network.

TVHeadend has a setup wizard that can be used for the intial setup. The respective network is DVB-T and this must be attached to the tuner so that it works correctly. TVHeadend does have a database of stored frequencies for TV transmitters in the various countries. In practice this database is often outdated and may lead to TvHeadend being unable to tune in to the TV services.

My advice is to check the local TV transmitters for your area, and on what frequencies they broadcast on. Once you know this information, you're in a much better position for a successful outcome.

For my TV service, it is DVB-T and run on two muxes, both of which run on their respective frequencies from my local transmitter. Go to Configuration > DVB Inputs.

The first tab is TV Adapters, here your tuner should be listed. The next tab is Networks, here your network should be listed. The next tab is muxes, this is the important one where all available information should be set to enable TVHeadend to tune in to the local stations.

Most of the settings here can be left at default, except frequency ( the most important setting), bandwidth and transmission. Fill in your respective values here and save the settings. My bandwidth setting was 8Mhz, from my research this appears to be common for DVB-T in Europe. My transmission mode was 8k.

TvHeadend should then proceed to scan in the channels. If nothing happens, you can go to the Networks tab and do a force scan. All the tuned channels may not show up directly on the EPG. If this is the case, you need to go to Services > enable all services.

Once you have all the channels displaying in the browser, you know that TVHeadend is now configured and working.

I had the curious error, where if I tried to play/stream the channels directly in the TVHeadend browser, the whole server would crash. If this happens to you do not worry, in my experience it will not affect the ability of Kodi to stream and display the content later.

Kodi setup

As mentioned previously, Kodi can run anywhere. As an intial test I installed Kodi on my Android device, through the Play Store. Inside Kodi, you need to go to Settings > Add-Ons > Install from a repository > PVR Clients. Scroll down the list until you find TVHeadend. Install it on Kodi. Then open it up and hit the configure tab.

You will see something like "edit locahost", click on this and configure the settings. 

Name                    <any name you wish>
Enabled                 <tick on>
IP address of server    <x.x.x.x>
Username                <name>
Password                <password>
The ip address is the address that TVHeadend is running on. If you set it up on the Pi, then you will input the Pi IP address here.

Once these settings are saved, go back to the main Kodi home page. Everything should now be working correctly and you should be able to click on the TV tab, where you TV channels should appear, ready for viewing.

Kodi can now be installed on any smart TV, PC or smart device in the house. Using the above settings, any device can be configured to view the TV stream running on your LAN courtesy of TVHeadend. Happy viewing! 😄