Installing TVheadend from source on Raspberry Pi 2 & 3

This Tutorial addresses:
  • Home Theatre
  • DVR
  • raspberry pi
  • Audio/Video Players
By ,
Copyright 2017 LinuxTopix

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover

A copy of the license is included in the section entitled "GNU
Free Documentation License".

Copyright 2017 LinuxTopix

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

This is not only for the brave, but also for the patient. If you are neither, leave now.

This is a minimal list of packages for cross-compiling this on the Raspberry Pi 2 or 3.

I have not yet gotten to the phase of testing older Pi and other diverse versions of the Pi.

Here is the entire process, as candle-burning as it may ever be.

If you recompile the entire thing on the Pi the way I did on my Toshiba laptop running Debian 8, you will need a rather large microSD card, a heat sink, and fan.

Because of the amount of space it takes to install FFmpeg and the amount of space it will eventually occupy, you do not want to expand the file system to fill the entire card before compiling it. It may be advisable to do that last. If you are not on a headless installation of Raspbian Lite, 16 GB may not be enough for what you are doing if you have expanded the file system already. It depends on how much you have going on already, remember you must also have storage to open, run, and even close your applications. When you are compiling the card is used for storing data that is transferred, and this can be a significant amount of space.

You may have to run:

sudo apt-get clean

You may have to still reboot to clear fragmented memory before you finish.

You may also get an error there is no more space if you work in the same directory for too long. This happens in LVM partitioning also, and it is nothing new or fun. Try to avoid it and get a card big enough to build and compile on.

Remote into your Raspberry Pi device with SSH.

sudo ssh

Install these build dependencies first:

sudo apt-get install gcc g++ build-essential pkg-config gettext gzip libssl-dev git

To add a repository you must install software-properties-common:

sudo apt-get install software-properties-common

Install cmake3.x:

sudo add-apt-repository ppa:george-edison55/cmake-3.x
sudo apt-get update
sudo apt-get install cmake

You will also need the FFmpeg codec installed or it will fail in the end.

The instructions here are thorough and complete:

Downloading & Compiling LibaacPlus

sudo apt-get install libtool-bin automake
sudo tar -xzf libaacplus-2.0.2.tar.gz
cd libaacplus-2.0.2
sudo ./ --with-parameter-expansion-string-replace-capable-shell=/bin/bash --host=arm-unknown-linux-gnueabi --enable-static
sudo make
sudo make install

Downloading & Compiling Libx264

sudo git clone git://
cd x264
sudo ./configure --host=arm-unknown-linux-gnueabi --enable-static --disable-opencl
sudo make
sudo make install
cd ..

Downloading & Compiling LibVPX

sudo git clone
cd libvpx
sudo ./configure
sudo make
sudo make install
cd ..

If you are installing on a Raspberry Pi 2 (or going to try this on other kinds of Pi), make sure if your CPU is ARMv6 that it compiles x264 instead of x265. Do not let it install both. If that happens, I would advise you to take a break and start again. If you catch it trying to install x265 on ARMv6 you can go back and rerun configuration with:

sudo ./configure --target=armv6-linux-gcc

Downloading & Compiling LibRTMP

sudo git clone git://
cd rtmpdump
sudo make SYS=posix
sudo make install
cd ..

Now to make sure all the changes are implemented run the command:

sudo ldconfig

Downloading & Compiling Libfaac

sudo curl -#LO
sudo tar xzvf faac-1.28.tar.gz
cd faac-1.28
sudo nano -c common/mp4v2/mpeg4ip.h

When you’re in the nano editor, you will need to go to line 126.

Once you’re at that line, make the below code the code in the file…

#ifdef __cplusplus
extern "C" {
#ifndef _STRING_H
char *strcasestr(const char *haystack, const char *needle);
#ifdef __cplusplus

To write out the changes and exit use CTRL+O, ENTER, and CTRL+X.

sudo ./configure --host=arm-unknown-linux-gnueabi
sudo make
sudo make install
sudo ldconfig
sudo reboot

Downloading & Compiling LibFDK-aac

wget -O fdk-aac.tar.gz
sudo tar xzvf fdk-aac.tar.gz
cd mstorsjo-fdk-aac*
sudo autoreconf -fiv
sudo ./configure --enable-shared
sudo make -j2
sudo make install

sudo apt-get install lame libmp3lame-dev libavcodec-extra-* mercurial
sudo apt-get update
sudo apt-get dist-upgrade

Downloading & Compiling FFmpeg

sudo git clone --depth 1
cd FFmpeg
sudo ./configure
sudo make -j3
sudo make install

For it to work FFmpeg has to successfully compile for TVH to work.

I had to restart several times to install build dependencies not on my system and such, and there may be some that I had that you may need. Thus, meaning they are not known to me to be able to document them here. If you need to rollback your build, remember to use:

sudo make clean

...before you rerun:

sudo ./configure

If you want to do something even a little more tricky (only a little more ;)  ), try this instead:

If FFmpeg still has trouble compiling, go into the ~ /FFmpeg directory
after it is installed and run the following commands:

cd FFmpeg
sudo PATH="$HOME/bin:$PATH" PKG_CONFIG_PATH="$HOME/ffmpeg_build/lib/pkgconfig"
./configure \
--prefix="$HOME/ffmpeg_build" \
--pkg-config-flags="--static" \
--extra-cflags="-I$HOME/ffmpeg_build/include" \
--extra-ldflags="-L$HOME/ffmpeg_build/lib" \
--bindir="$HOME/bin" \
--enable-gpl \
--enable-libass \
--enable-libfdk-aac \
--enable-libfreetype \
--enable-libmp3lame \
--enable-libopus \
--enable-libtheora \
--enable-libvorbis \
--enable-libvpx \
--enable-libx264 \
--disable-libx265 \
PATH="$HOME/bin:$PATH" make
make install
hash -r

Realize you must often sudo and the error message may not be able to more appropriately tell you. For some reason, perhaps because it is already handling x264, it does not want to handle x265. It is not an “issue,” it is actually a concept called code fragmentation. When there is many instead of one version of an application or package in use and the new version cannot fully replace the old one, fragmentation occurs. The Android OS is an easy example of software fragmentation. There are multiple versions of Android operating systems in use across devices everywhere. This creates an issue mostly for upstream developers.

There is OS (operating system) fragmentation, software fragmentation, and code fragmentation. It is nothing new. It is nothing new to me and you. And actually in this case, it looks like the developer more likely followed the process on the second link I used. That is, after all, the official support page on the site hosted by the developers of FFmpeg. Who knows best how to install there own software, except perhaps in the diverse world of personal devices and generic electronics.

And finally after all the system prep, let's actually install Tvheadend!

cd ~
cd /
sudo apt-get install dvb-apps
sudo git clone

cd tvheadend-rbp/
sudo ./configure
sudo make
sudo make install

To configure TVheadend settings go here:

cd $HOME/.hts/tvheadend

So, let's do a little house-cleaning and reboot.

sudo apt-get autoremove
sudo apt-get autoclean
sudo reboot

To start TVheadend run:

sudo ./build.linux/tvheadend

When the Pi boots up, type in ffmpeg and you should see output.

TVH should come up as a reachable server in any enabled frontend clients, but it will not yet render recording management services. You still need to install the rest of the addons that make TVH more than just a little red dot that records and a square that makes it stop. That advanced functionality is not provided by TVH alone.

Only a legitimate IPTV service operates on private (though public as commercial) protocols that are able to use recording timers. What that means is to actually have timers that start recording when a show starts and stop when a show stops you have to have a real IPTV service, not an illegal one. The rest of these notes tell how to set up the necessary addons to make TVH use recording timers. So, make sure your service is legit if you do everything right and still have issues. Although I am not sure about this exact graphics card, you could try adding a USB graphics card for better video quality too.

To make the recordings work on the Raspberry Pi, aside from the hardware requirements just described we must also install two other crucial addons. One gives TVH timers it can use for recordings, because recordings without timers are just recordings. Some timers can record just one show, others only run for a duration. The other addon is the TVH Client. The most fun to have is configuring the TV Guide. I would suggest trying one of many services made to help you build your own TV Guide.

You should also make sure at least this one addon is part of your main build:

By installing this addon into the addons directory in its default location in whatever flavor of embedded XBMC Linux distribution or standalone version of Kodi you are running. For me it is as easy to switch to that directory as running:

cd ~/.kodi/addons/

If you install the client addon before compiling, it will become an integrated part of the main media center application you build. It is installed alongside the rest of the build and should run as smoothly as one would expect a compiled application should. This particular addon will require you to upgrade cmake if the only version you have comes from your distribution's main repository.

From inside the proper addons folder to install this addon first clone it:

sudo git clone
cd pvr.hts && sudo mkdir build && cd build
sudo cmake -DADDONS_TO_BUILD=pvr.hts -DADDON_SRC_PREFIX=../.. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=../../xbmc/kodi-build/addons -DPACKAGE_ZIP=1 ../../xbmc/cmake/addons

The path in the code given by the addon author will probably need to be modified to be properly prefixed for your personal directory setup. I have never seen a folder called /kodi-build/ and I am sure this is before my participation, because I have never been able to keep the path prefixed this way. It has always varied and never has there been a folder by such a name while I have been building Kodi. It has not been that long. So, that does not say anything. Make sure the path is correct for your fork and version. Do not finish the install with make install. The compiler will finish compiling the addon along with the XBMC/Kodi application itself.

You also need to install dtv-scan-tables before you can actually install TVH.

sudo apt-get install debhelper dh-autoreconf autotools-dev autoconf-archive doxygen graphviz libasound2-dev libtool libjpeg-dev libqt4-dev libqt4-opengl-dev libudev-dev libx11-dev udev doxygen libudev-dev qt5-default qtdeclarative5-dev

sudo git clone

cd v4l-utils

sudo ./
sudo ./configure
sudo make

If ./configure exits with errors try:

sudo autoreconf -i --force
sudo ./configure

sudo make install

Once you have v4l-utils installed, you can install dtv-scan-tables:

sudo git clone

To install the files as DVBv5 simply run:

sudo make install

To install the files as DVBv3 simply run:

sudo make install install_v3

To add extra parameters you need to do so now on the command line:

PREFIX=<dir> (default: /usr/local)
DATADIR=<dir> (default: $(PREFIX/share)
DVBV3DIR=<subdir> (default: dvbv3)
DVBV5DIR=<subdir> (default: dvbv5)

There is no real need to change the defaults.

To scan run:

sudo make clean
sudo dvbv3

To individually convert files from DVBv5 to DVBv3:

dvb-format-convert -I dvbv5 -O channel dvb-c/ch-Rega-Sense legacy-format-ch-Rega-Sense

To convert files back to DVBv5 run:

dvb-format-convert -I channel -O dvbv5 legacy-format-ch-Rega-Sense dvb-c/ch-Rega-Sense

Make sure to also install the recording timers, and follow the instructions along with the addon from this GitHub repository as well:

sudo git clone

You may need to install the proper tool by running:

sudo apt-get install visudo

After that run visudo:

sudo visudo
sudo Cmnd_Alias PVR_CMDS = /home/kodi/.kodi/addons/service.tvh.manager/resources/lib/

This next code will allow TVheadend to react to the Power button be ticked in the app or pressed on the remote.

sudo nano ~/.kodi/userdata/keymaps/remote.xml

Or, for embedded media center Linux distributions like OpenELEC, LibreELEC, and OSMC, you would instead use:

sudo nano /storage/.kodi/userdata/keymaps/remote.xml

And you copy and paste this code into remote.xml:

<!-- This is the keyboard section -->
<!-- This is the remote section -->

Write out the changes with CTRL+O and exit with CTRL+X. You should run make on this addon, but you do not have to run make install if you are going to compile it along with the main XBMC or Kodi application itself.

For information on how to build the kernel and use menuconfig to enable kernel support for specific hardware, please read up on these following links:

In the kernel, you can enable game controller support, video graphics hardware support, and other kinds of hardware support under the hood of the kernel. You might have to do more to configure the software side of enabling CPU support, but that varies from device to device. It is quite a menu of hardware support options to see building the kernel using menuconfig, and though quite a lengthy task, quite an amazing tour.

Installing a desktop environment onto Raspbian Lite:

When you think it is no longer time for fun, you can check out Android boxes with built-in tuners. The reason I mention this is, it goes along with what I would suggest trying if you consider using buildroot. Of course, I will make my own embedded MC distro of Linux, but then there is also the possibility of doing that for Android devices. Raspberry Pi is just an educational tool. Itself it is not a qualified solution. Most Android TV boxes and quality streaming sticks can easily beat the pants off a Raspberry Pi when it comes to streaming.

So, though certainly it will be worth trying more of the features found in Pi. The permanent fix for a true PVR client device is to build your own embedded Android operating system and compile it onto an Android TV set box with a built-in tuner. The PVR itself would run more efficiently on a minimal Debian-based distribution mini-PC made for media streaming.

A headless setup without a GUI is most efficient if you want to maximize resources for performance. You can go into the app store and search for TVheadend and TVH Client apps that work on Android so you do not have to be on a PC to configure TVH. There are several mobile apps that can be used on tablets too.

You could either create a headless PVR device without any desktop environment and only the command line if you plug it into the TV, or you could install a minimal DE. If you use buildroot, your operating system will be XBMC. What you see will be only Kodi. For more information on buildroot, check out these great references:

If you wish to go with a headless setup, I would recommend starting with Raspbian Lite and compiling everything there. If you desire a GUI, you can read how to install a desktop environment.

This link might also be helpful:

This reference might also prove helpful for you if you are new to developing:
Can't find your answer ? Ask !
Tom’s guide in the world
  • Germany
  • France
  • Italy
  • Ireland
  • UK
Follow Tom’s guide
Subscribe to our newsletter
  • add to twitter
  • add to facebook
  • ajouter un flux RSS