Tvheadend can run isolated from other host processes in a Docker container. The official Tvheadend container can be pulled from the GitHub container repo:

$ docker pull ghcr.io/tvheadend/tvheadend:master-debian

There is also an established community container from the linuxserver.io team:

https://fleet.linuxserver.io/image?name=linuxserver/tvheadend

Community created and supported Tvheadend packages for Synology and QNAP users are available from community package repositories. See below for more information:

Synology

https://synocommunity.com/package/tvheadend

QNAP

https://www.myqnap.org/product/tvheadend

Please note that General support issues with Tvheadend are welcome in our forum but installation issues with these packages are best directed to NAS vendor forums.

Tvheadend has physical and software considerations:

• Intel compatible (i386/x86_64) or ARM (arm/aarch64) CPU

• Minimum 1GB RAM

• Minimum 1GB storage for app/configuration data

• Large capacity storage for recordings

• Tuner device(s) with suitable power and connectivity

• Operating System that supports the tuners

Server Hardware

Tvheadend is tested on Intel compatible i386/x86_64 CPUs and ARM SoC arm/aarch64 processors. It will need a minimum of 1GB disk space for application binaries and configuration data, although the total required will depend on the number and type of tuners you have, the number of channels received, the choice of programme guide data, etc.

Tvheadend is intended to be lightweight and will run in less than 1GB RAM on low-powered NAS and Single Board Computer devices. Many users run Tvheadend on older Raspberry Pi boards with 512MB physical RAM and perhaps only 256MB free memory: although more is sensible and will result in a better user experience. Note that transcoding is CPU intensive and this feature runs best on powerful multi-core systems.

Recordings consume large amounts of disk storage. SD quality MPEG2 video will typically use 1GB of disk per-hour, while higher-bitrate HD quality H264 will often consume 5GB+ per-hour. Most users who use Tvheadend to record will plan and provision their Tvheadend server with large capacity local HDD or remote-mounted NAS storage.

You will need one or more tuner devices to receive Cable, Satellite, or Terrestrial broadcast sources, or IP sources. Tuner options are discussed in more detail here.

Server Software

Tvheadend is designed for use on Linux and we provide general purpose binary pacakges and Docker containers that can be used with a large range of Linux distributions and distro versions:

• Debian derivatives (Debian, Raspberry Pi, Ubuntu, Mint, etc.)

• RedHat derivatives (Fedora, RHEL)

Tvheadend is available as an installable add-on for the Kodi focussed distro LibreELEC

Users needing a more specific combination of Tvheadend capabilities can also compile their own binaries or build containers from our public source code.

Connectivity

Internet access is essential for installation and maintenance of Tvheadend, but is not essential during use. Tvheadend needs an accurate clock for EPG timers to work, but this can be synchronised from the broadcast signal if ntp services are not available. Most broadcast services also provide some form of EPG data "over the air" alongside the broadcast signal.

Server hardware and perhaps tuner hardware will require power and physical access to a broadcast feed from aerial, dish, or cable; or via the LAN if you are using SAT>IP, network tuners, or IP sources.

Architecture

Tvheadend can be run in a single-host configuration where the Tvheadend server runs on the same host as client software, e.g. Kodi, and with media recordings stored locally on the same disk. This is common with compact or lower-budget Tvheadend setups with a smaller number of tuners.

In a multi-host configuration Tvheadend runs on a dedicated server, with client software on a separate device. This allows a compact client device to sit alongside the TV while the Tvheadend server (usually a larger device with multiple tuners) is located somewhere else with convenient access to the physical aerial, dish or coax cables that provide input to your tuners

Tvheadend can be installed either as a VM (linux guest OS) or as an LXC container.

The TV tuner must be passed through to the VM/container

Proxmox VM - Debian

• Host OS: Proxmox 8.3.1

• Guest OS: Debian 12.8 (bookworm) amd64

Note: the TV tuner is passed through from the Host to Guest (PCI or USB pass through) - installation of the tuner is done on the VM/Guest OS

1. Install Debian as a VM with at least the minimum requirements - command-line only installs (without desktop environment) recommended to minimise resource usage

2. Update Debian to latest package versions with

# apt update
# apt upgrade

1. Install Curl package to allow set up of Apt repository

# apt install curl

1. Set up Apt repository - for DEB packages using Curl

# curl -1sLf 'https://dl.cloudsmith.io/public/tvheadend/tvheadend/setup.deb.sh' | sudo -E bash

1. Update Apt package list

# apt update

1. Install Tvheadend

# apt install tvheadend

1. Passthrough TV tuner hardware to VM guest OS (this can be done through the proxmox web GUI)

2. Install the TV tuner on the VM guest OS

3. Access the Tvheadend web configuration interface at: https://<yourtvhserverip>:9981

4. Continue setup/configuration (in next section)

Proxmox LXC - Debian

• Host OS: Proxmox 8.3.1

• Container Template (Guest OS): Debian 12 standard (12.2-1-amd64)

Note: the TV tuner is first installed on the Host OS (Proxmox) and then passed through to the LXC container (see below) - the pass through must be the whole enumerated device in /dev/dvb/adapter0/<files> and not /dev/usb or /dev/pci as the LXC does not have the kernel modules to install the device.

1. Set up an LXC container with at least the minimum requirements The Debian 12 standard LXC template can be downloaded from the Proxmox web GUI

2. Update Debian packages to latest version Note: a lot of packages will be updated as the Proxmox LXC template is quite old

# apt update
# apt upgrade

1. Install Curl package to allow set up of Apt repository

# apt install curl

1. Set up Apt repository - for DEB packages using Curl

# curl -1sLf 'https://dl.cloudsmith.io/public/tvheadend/tvheadend/setup.deb.sh' | sudo -E bash

1. Update Apt package list

# apt update

1. Install Tvheadend

 # apt install tvheadend

1. Passthrough TV tuner hardware to VM guest OS Passthrough all the devices files under /dev/dvb/adapter0/ Set UID=0 (root) and GID=44 (video) for all devices - GUI method: From web GUI, nagivate to container, resources, add, pass through - add the devices: /dev/dvb/adapter0/demux0 /dev/dvb/adapter0/dvr0 /dev/dvb/adapter0/frontend0 /dev/dvb/adapter0/net0 OR - Command-line method: Manually edit the LXC config file at: /etc/pve/lxc/<containerid>.conf Add in the following lines /dev/dvb/adapter0/demux0,gid=44,uid=0 /dev/dvb/adapter0/dvr0,gid=44,uid=0 /dev/dvb/adapter0/frontend0,gid=44,uid=0 /dev/dvb/adapter0/net0,gid=44,uid=0

2. Restart LXC container to allow passthrough

3. Access the Tvheadend web configuration interface at: https://<yourtvhserverip>:9981

4. Continue setup/configuration (in next section)

w_scan is an external utility, not supplied with TVHeadEnd (TVH), that can scan for all available muxes and services. If the default scan files provided with TVH are unable to locate the muxes or services that a user expects to see in their location, the output from w_scan can also be used as a scan file for TVH.

Example

The following command can be used to create a scan file called au-wscan: w_scan -f t -c AU -x > au-wscan The explanation of every w_scan parameter is beyond the scope of this document, however, the -x parameter is required to produce the output format required by TVH. Use w_scan -h and w_scan -H for a full list of parameters.

#------------------------------------------------------------------------------
# file automatically generated by w_scan
# (http://wirbel.htpc-forum.de/w_scan/index2.html)
#! <w_scan> 20170107 1 0 TERRESTRIAL AU </w_scan>
#------------------------------------------------------------------------------
# location and provider: <add description here>
# date (yyyy-mm-dd)    : 2024-06-26
# provided by (opt)    : <your name or email here>
#
# T[2] <freq> <bw> <fec_hi> <fec_lo> <mod> <tm> <guard> <hi> [plp_id] [# comment]
#------------------------------------------------------------------------------
T 177500000 7MHz  3/4 NONE    QAM64   8k 1/16 NONE	# Seven Network
T 184500000 7MHz  3/4 NONE    QAM64   8k 1/16 NONE	# SBS Sydney
T 191625000 7MHz  3/4 NONE    QAM64   8k 1/16 NONE	# Nine Network Australia
T 219500000 7MHz  3/4 NONE    QAM64   8k 1/16 NONE	# Network TEN
T 226500000 7MHz  3/4 NONE    QAM64   8k 1/16 NONE	# ABC Sydney

This file can be copied to the scan file location and once TVH has been restarted, used to scan for services.

Depending upon the exact installation of TVH, scan file can be found in various locations: /usr/local/share/tvheadend/data/dvb-scan/ /usr/share/tvheadend/data/dvb-scan/

Please Note: depending upon the parameters used, w_scan can take a very long time to perform a scan.

Tvheadend is operated primarily through a tabbed web interface. There are some basic navigation concepts that will help you use it effectively:

Page Structure

• The web interface uses tabs with similar functions grouped together. Tabs for major configuration functions are located on the top row, with tabs for configuration items related to the currently selected major function located on the row below. In some cases a third row of config options will be shown.

• Most tabs have display a menu bar with Add, Save, Edit, Undo functions and a spreadsheet-like grid below. Grid items are frequently editable.

• Most configuration items are in this grid. However, some item-specific configuraiton is accessed through the Add and Edit dialog boxes. For example: the main network configuration tab grid covers parameters common to DVB-S, DVB-T, DVB-C and IPTV networks, but configuration like FEC rolloff or mux URL is only present in dialogs for networks that need these values.

Displaying & Manipulating Columns

• Some columns are hidden. If you hover the mouse over a column heading a down-arrow will show, and when clicked a drop-down menu appears allowing you to select which columns are visible and which columns are hidden.

• The drop-down menu also allows you to sort results. You can also sort columns by clicking on the column header: first click will sort ascending and a second click will reverse the sort (descending).

• The same drop-down menu also allows you to filter results using basic string pattern matching.

• Columns can be rearranged by dragging the column header to a new position.

• Columns can be resized by dragging the edges of the column header to the width position required.

Editing Fields

• To edit a cell in the grid, double click on it and make changes. After a cell has been changed, a red flag or triangle appears in the top-left corner to indicate it has been changed. Changes can be kept (click Save) or discarded (click Undo).

• To change a checkbox or radio button, click once.

• To add a new entry press the Add button. The new (empty) entry will be shown in the interface but will not be stored in the server configuration until values are added, the configuration is marked as enabled, and then saved. Changes are applied when saved, not when edited.

• Most grid views support ctrl+click to select multiple fields at the same time, and shift+click to select field ranges.

Tvheadend binary packages can be downloaded from https://apt.tvheadend.org or you can configure a local package repo to install and update from by running the following shell commands:

DEB Packages (Debian, Ubuntu, RaspiOS)

Run the following shell command to setup a local apt repo:

curl -1sLf 'https://dl.cloudsmith.io/public/tvheadend/tvheadend/setup.deb.sh' | sudo -E bash

RPM Packages (Fedora, RedHat)

Run the following shell command to setup a local dnf or yum repo:

curl -1sLf 'https://dl.cloudsmith.io/public/tvheadend/tvheadend/setup.rpm.sh' | sudo -E bash

Tvheadend aims to provide installable packages for as long as possible to extend the usable life of server and tuner hardware. In practice this means if we can still automate regular build testing for popular distributions and versions we will have binaries available.

Source Code

Please refer to development documentation on compiling Tvheadend from source

Tvheadend documentation is authored and maintained by Tvheadend users. If you see something is incorrect or missing please click the GitBook link below to join our documentation team. The GitBook online app makes changing documentation simple, with changes sent directly to our documentation repo on GitHub as a pull-request that project staff can review and merge.

https://app.gitbook.com/invite/GUiJM9P5N3CkY42Hcs8P/7hmZSVRZkZqEIJarLFX5

* IMPORTANT *

Please do not be concerned about your English language skills when contributing changes to our documentation. It is easier for a native speaker to merge your content and then make corrections than to write everything themselves. And if there is no obvious place to put content (the current structure is sparse and incomplete) please create pages under the WIP section. It can be merged and moved later as the documentation structure evolves.

Q: How do I get a playlist for all my channels?

Tvheadend can generate a playlist of all your mapped services (channels). You can download it from the webui at http://<ip>:<port>/playlist, e.g. http://192.168.0.2:9981/playlist.

Q: Why am I getting a playlist when trying to view/stream a channel?

By default Tvheadend’s Play links are playlists, although not all players accept them (e.g. Media Player Classic Home Cinema). You can bypass this by removing the /play/ path from the url.

Q: Tvheadend has scanned for services but some rows in the Service Name column are blank, is that normal?

Yes, not all services are given a name by providers. These services are usually hidden for a reason and may be used for things like encrypted guide data for set-top boxes, interactive services, and so on. If you do not see any service names at all this may indicate an issue with your hardware or configuration.

Q: I get a blank page when trying to view the web interface!

This usually happens when Tvheadend is installed incorrectly. On Debian and Ubuntu systems check the web interface path /usr/share/tvheadend/src/webui/static/ exists and isn’t empty. On other distros the path may be different.

Q: Why can’t I see my tuners in Tvheadend’s interface?

This is normally because they are not installed properly. Check syslog/dmesg (e.g. dmesg | grep dvb) and see that you have startup messages that indicate whether or not the tuners have initialized properly. Similarly, check /dev/dvb to see if the block device files used to communicate with the tuner have been created correctly?. The other major cause of this issue is when you run Tvheadend as a user that does not have permissions to access the tuners, e.g. not a member of the video group.

Tvheadend setup normally involves the following stages:

1. Ensure tuners are available for use

2. Install Tvheadend software

3. Create a network

4. Associate the network with tuners

5. Add manual muxes - if needed

6. Scan for services

7. Map services to channels

8. Watch TV channels!

General

If you use the packaged version of tvheadend, make sure that you use the debug version of tvheadend (with the debugging symbols). For debian/ubuntu these packages have -dbg suffix, for rpm packages, these symbols are in debuginfo rpm files.

If you're going to be regularly trying development versions of Tvheadend or need to report a crash or deadlock then you should really read this page!

If you are investigating problems within Tvheadend then its worth being familiar with tools such as gdb and valgrind or clang, although these are not covered here.

However one thing that can be useful in investigating crashes within Tvheadend is to ensure that coredumps are generated, this will allow post analysis in gdb without having to actual run Tvheadend within gdb.

You can enable temporarily by running:

ulimit -c unlimited

To make this permanent put this somewhere in your shell environment setup (.bashrc, .profile, etc...) Firstly I'd recommend that if you're specifically trying to investigate an issue then you should consider running Tvheadend manually, rather than as a service, as documented below.

Logging

I'd strongly recommend that if you're specifically trying to investigate a crash or other problem in Tvheadend that you enable debugging:

• -s will output debug info to syslog

• --debug allows you to specify which subsystem to debug

• --trace allows you to enable trace (more in-depth) logging on specific subsystems

You can also get Tvheadend to log to it's own file using:

-l FILE

You may also modify the debug settings using WEB GUI as admin - Configuration/Debugging. Note that the information is not saved, it is just set for run-time (current task).

• Debug log path - filename to store log

• Debug trace - enable traces

• Debug subsystems - comma separated list of subsystems

• Trace subsystems - comma separated list of subsystems

The traces must be compiled to the tvheadend binary (see below).

Trace Options

The following options can be passed to tvheadend to provide detailed debugging information while the application is running. Trace debugging has to be enabled at build time with--enable-debugging and can be specified in a CLI command, e.g. tvheadend -u hts -g video --trace <module> or in the web interface (Configuration -> Debugging).

Multiple options can be used, e.g. –-trace cwc,dvr,linuxdvb

START
STOP
CRASH
main
tprof
qprof
CPU
thread
tvhpoll
time
spawn
fsmonitor
lock
uuid
idnode
url
tcp
rtsp
upnp
settings
config
access
cron
dbus
avahi
bonjour
api
http
httpc
htsp
htsp-sub
htsp-req
htsp-ans
imagecache
tbl
tbl-base
tbl-csa
tbl-eit
tbl-time
tbl-atsc
tbl-pass
tbl-satip
fastscan
pcr
parser
TS
globalheaders
tsfix
hevc
muxer
pass
audioes
mkv
service
channel
subscription
service-mapper
bouquet
esfilter
profile
descrambler
descrambler-emm
caclient
csa
capmt
cwc
cccam
dvbcam
dvr
dvr-inotify
epg
epgdb
epggrab
charset
dvb
mpegts
muxsched
libav
transcode
iptv
iptv-pcr
iptv-sub
linuxdvb
diseqc
en50221
en50494
satip
satips
tvhdhomerun
psip
opentv
pyepg
xmltv
webui
timeshift
scanfile
tsfile
tsdebug
codec
vaapi
ddci
udp
ratinglabels

Crash reports

Incorrect (not useable) crash reports

Jun  6 15:01:08 srv tvheadend[10808]: CRASH: Signal: 11 in PRG: /usr/bin/tvheadend (4.3-193~ga4ff519) [15a15a895adaf9c5760b80707f582c2d60cfab01] CWD: /
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: Fault address 0x90 (Address not mapped)
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: STACKTRACE
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x555558549eba 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x7f3d97c0c0c0 0x7f3d97bfb000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x555558525620 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x5555585257a8 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:? 0x5555585db371 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:? 0x5555585dc1f2 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:? 0x5555585c3212 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:? 0x5555585bb71d 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:? 0x5555585bb8d1 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x5555585b4589 0x555558350000
Jun  6 15:01:08 srv tvheadend[10808]: CRASH: ??:0 0x5555585b4796 0x555558350000
Jun  6 15:01:09 srv tvheadend[10808]: CRASH: ??:0 0x555558511e44 0x555558350000
Jun  6 15:01:09 srv tvheadend[10808]: CRASH: ??:0 0x7f3d97c02494 0x7f3d97bfb000
Jun  6 15:01:09 srv kernel: [2320412.837462] tvh:mi-table[11208]: segfault at 90 ip 0000555558525620 sp 00007f3d85ff0b98 error 4 in tvheadend[555558350000+10d1000]

In this case, the debug symbols are missing (look to the top of this page). Install the debug version of the tvheadend package.

Correct crash reports

2017-06-06 17:36:53.626 [  ALERT] CRASH: Signal: 6 in PRG: ./build.linux/tvheadend (4.3-195~gf476b37-dirty) [d761557cdfcd10940d79f8758376fadda7e49e8c] CWD: /home/tvheadend/git/tvheadend  
2017-06-06 17:36:53.626 [  ALERT] CRASH: Fault address 0x311100002adf (N/A)
2017-06-06 17:36:53.626 [  ALERT] CRASH: STACKTRACE
2017-06-06 17:36:53.626 [  ALERT] CRASH: backtrace+0x41  (./build.linux/tvheadend)
2017-06-06 17:36:53.643 [  ALERT] CRASH: /home/tvheadend/git/tvheadend/src/trap.c:148 0x5584f45ad4ef 0x5584f3d72000
2017-06-06 17:36:53.666 [  ALERT] CRASH: ??:0 0x7f1afde155c0 0x7f1afde04000
2017-06-06 17:36:53.666 [  ALERT] CRASH: gsignal+0x9f  (/lib64/libc.so.6)
2017-06-06 17:36:53.666 [  ALERT] CRASH: abort+0x16a  (/lib64/libc.so.6)
2017-06-06 17:36:53.690 [  ALERT] CRASH: /home/tvheadend/git/tvheadend/src/main.c:1267 0x5584f4462996 0x5584f3d72000
2017-06-06 17:36:53.690 [  ALERT] CRASH: __libc_start_main+0xf1  (/lib64/libc.so.6)

Basic crash debug

You may run tvh in gdb directly using command:

gdb --args /the standard tvh command line/

(gdb) run

Or attach gdb to the running process:

gdb tvheadend pid

(gdb) continue

The 'continue' command will continue the execution of the program. If you need to break the execution and return to gdb, just use 'Ctrl-C'.

You may need to replace tvheadend with the full path to the binary and you will need to replace pid with the PID of the running process. To find that run:

ps -C tvheadend

Once you have gdb attached grab a stack trace from every thread using the following command:

(gdb) set logging on
(gdb) set pagination off
(gdb) bt full

Note: "set logging on" will cause GDB to write its output to a file, by default this will be gdb.txt in the current directory.

Enabling coredumps

If you need to investigate some running problem you can always attach (see below) later and if you need to trap crashes, then you can configure your system to generate a core file and then retrospectively analyse this with gdb.

If you're running manually you should enable coredumps in your environment:

ulimit -c unlimited

I'd recommend you enable this permanently by putting this command in your shell initialisation scripts (.bashrc etc..).

If you're running as a daemon then you should use the -D command line option, this will enable coredumps from the daemon. If you start using sysvinit, upstart etc... then you will need to put this in the configuration file, e.g.:

TVH_ARGS="-D" 

Finally it's probably worth changing the coredump file format, personally I use the following configuration:

echo core.%h.%e.%t | sudo tee /proc/sys/kernel/core_pattern
echo 0 | sudo tee /proc/sys/kernel/core_uses_pid

Or put the following in /etc/sysctl.conf:

kernel.core_pattern = core.%h.%e.%t
kernel.core_uses_pid = 0

If you're using a system like Ubuntu that uses apport (and cripples the ability to change the core format) just set core_uses_pid=1 instead.

Note: coredumps are (by default) stored in the current working directory, to make it possible for the daemon to write files the current working directory is set to /tmp when using -D, so check there for core files.

To verify that you have everything configured properly you can use the -A option to force a crash on startup. Do this from the command line or add to /etc/default/tvheadend:

TVH_ARGS="-D -A" 

Note: remember to remove the option after you've tested it!

Processing core file.

Once you have a core file you can start up gdb with that coredump, just as if you'd caught the crash while running under gdb:

gdb tvheadend core

You may need to replace tvheadend and core above with the proper paths.

For most crashes the most useful information is the back trace, this will provide a stack trace showing where the code crashed and the stack information at the time of the crash:

(gdb) set logging on
(gdb) set pagination off
(gdb) bt full
#0  0x00007f5b10cc1425 in __GI_raise (sig=<optimised out>)
    at ../nptl/sysdeps/unix/sysv/linux/raise.c:64
        resultvar = 0
        pid = <optimised out>
        selftid = 7517
#1  0x00007f5b10cc4b10 in __GI_abort () at abort.c:120
        act = {__sigaction_handler = {sa_handler = 0, sa_sigaction = 0}, 
          sa_mask = {__val = {18446744073709551615 <repeats 16 times>}}, 
          sa_flags = 0, sa_restorer = 0}
        sigs = {__val = {32, 0 <repeats 15 times>}}
#2  0x000000000040744e in main (argc=<optimised out>, argv=<optimised out>)
    at src/main.c:810
        i = <optimised out>
        set = {__val = {16386, 0 <repeats 15 times>}}
        adapter_mask = <optimised out>
        log_level = <optimised out>
        log_options = <optimised out>
        log_debug = <optimised out>
        log_trace = <optimised out>
        buf = "/tmp\000\000\000\000\360\350\364\023[\177\000\000\000\320\365\023[\177\000\000t\n\327\023[\177\000\000\370\271\311\020[\177\000\000\017\000\000\000\000\000\000\000:\000\000\000\000\000\000\000h\344\364\023[\177\000\000.N=\366\000\000\000\000\236\022\327\023[\177\000\000\300\304S\205\377\177\000\000.\000\000\000\000\000\000\000 \305S\205\377\177\000\000\377\377\377\377\000\000\000\000\264\352\310\020[\177\000\000\250\354\310\020[\177\000\000\360\304S\205\377\177\000\000\360\350\364\023[\177\000\000@\256\311\020[\177", '\000' <repeats 18 times>"\340, \346\364\023[\177\000\000\000\320\365\023[\177\000\000\231,@\000\000\000\000\000\370\271\311\020[\177\000\000\340\033@\000\000\000\000\000\000\000\000\000\001\000\000\000\021\b\000\000\001", '\000' <repeats 11 times>, " \266\370\023[\177\000\000`\305S\205\377\177\000\000.N=\366\000\000\000\000\340\346\364\023[\177\000\000\200\305S\205\377\177\000\000"...
        opt_help = 0
        opt_version = 0
        opt_fork = 1
        opt_firstrun = 0
        opt_stderr = 0
        opt_syslog = 0
        opt_uidebug = 0

Note: "set logging on" will cause GDB to write its output to a file, by default this will be gdb.txt in the current directory.

However I'd strongly recommend that you keep a copy of tvheadend binary and core file in case further analysis is required.

Dead or Live Lock

If Tvheadend appears to die but the process is still running, then its quite possible that the process is deadlocked (or possibly live locked).

Buildin deadlock mutex checker (since latest 4.3 version)

Use '--thrdebug 1' as the command line option. The deadlock will be printed to the tvheadend's configuration directory to file mutex-deadlock.txt and to the standard task error output (so you can see it through the systemctl service log for example).

GDB

The best way to help investigate such a problem is to get a full stack trace from every thread in the system.

First attach gdb to the running process:

gdb tvheadend pid

(gdb) continue

The 'continue' command will continue the execution of the program. If you need to break the execution and return to gdb, just use 'Ctrl-C'.

You may need to replace tvheadend with the full path to the binary and you will need to replace pid with the PID of the running process. To find that run:

ps -C tvheadend

Once you have gdb attached grab a stack trace from every thread using the following command:

(gdb) set logging on
(gdb) set pagination off
(gdb) thread apply all bt full

Note: "set logging on" will cause GDB to write its output to a file, by default this will be gdb.txt in the current directory.

It might also be useful to generate a core file for good measure:

(gdb) generate-core-file

This information may give an indication as to why things are locked, often 2 threads are stuck trying to lock a mutex (probably each holds the opposite lock).

Reporting crash (or lock)

If you're going to report a crash (or lockup) then please try to provide the above information, including a debug log (or whatever logging you have), a core file and the tvheadend binary and basic information about the platform (distribution, version and architecture) you're running on.

Memory leaks or corruption

It may be really difficult to track these problems. There are basically two tools which may help to discover the memory leaks or memory corruptions.

Valgrind

It is very slow, but it may be useable for things which are triggered everytime:

valgrind --suppressions=support/valgrind.supp --leak-check=full --show-reachable=yes /tvh_command_line/

clang

There is address and leak sanitizer in the clang toolkit.

The clang / llvm tools are usually split to multiple packages, here is list of required packages for Fedora 26:

llvm
clang
libasan
liblsan

The binary must be rebuild using the clang compiler and libraries:

ARGS="/your_configure_arguments/" 
SANITIZER=leak # or address
export CFLAGS="-fsanitize=$SANITIZER" 
export LDFLAGS="-fsanitize=$SANITIZER" 
./configure $ARGS --disable-pie --enable-ccdebug python=python3 cc=clang ld=clang nowerror
make -j4

Example build script (build_with_clang.sh):

#!/bin/sh
make distclean
ARGS="--enable-libffmpeg_static --disable-hdhomerun_static" 
SANITIZER=leak # or address
export CFLAGS="-fsanitize=$SANITIZER" 
export LDFLAGS="-fsanitize=$SANITIZER" 
./configure $ARGS --disable-pie --enable-ccdebug python=python3 cc=clang ld=clang nowerror
make -j4

Make sure to make your script executable.

If you do not see resolved the function names like:

==16673==WARNING: Trying to symbolize code, but external symbolizer is not initialized!
    #0 0x7fcda9407680 (/home/tvh/src/tvheadend/build.linux/tvheadend+0x65b680)
    #1 0x7fcda943b115 (/home/tvh/src/tvheadend/build.linux/tvheadend+0x68f115)

get the correct path for the llvm-symbolizer, i.e. with

whereis llvm-symbolizer

then make sure that you set the external symbolizer like:

ASAN_OPTIONS=symbolize=1 ASAN_SYMBOLIZER_PATH=/usr/bin/llvm-symbolizer /home/ts/workspace/tvheadend/build.linux/tvheadend -l thv.log

The error log should be like:

==27911==ERROR: AddressSanitizer: heap-use-after-free on address 0x60700000d928 at pc 0x56409f916af4 bp 0x7ffc463d6670 sp 0x7ffc463d6668
READ of size 8 at 0x60700000d928 thread T0
    #0 0x56409f916af3 in idnode_unlink /home/tvh/git/tvheadend/src/idnode.c:164:94
    #1 0x56409f9c9f8a in memoryinfo_unregister /home/tvh/git/tvheadend/src/memoryinfo.h:52:3
    #2 0x56409f9c9de2 in streaming_done /home/tvh/git/tvheadend/src/streaming.c:597:3

Mutex profiling

The code blocks are protected using mutexes. Tvheadend has the debug interface to show locks which took too much time now (latest 4.3 code). Use '--thrdebug 10020' where 20 means 20 millisecond threshold to show the problematic mutexes. The output is printed to standard error file descriptor (stderr) by default. If you run tvheadend using systemctl or initd, you may send those messages to a UDP port. Set the TVHEADEND_RTLOG_UDP_PORT environment variable like:

... console 1
$ export TVHEADEND_RTLOG_UDP_PORT=7777
$ ./build.linux/tvheadend --thrdebug 10020 <more-options>
... console 2
$ nc -lu -p 7777

The result should look like:

thread: mutex 0x5562f9f859e0 at src/api/api_idnode.c:134 took 43ms
thread: mutex 0x5562f9f859e0 at src/api/api_idnode.c:134 took 31ms

Before you install Tvheadend software you need to have a working tuner device. There are four types of tuner hardware that Tvheadend can use:

• Internal PCI/PCIe tuners

• Internal i2s tuners

• External USB tuners

• Network tuners

IP sources can also be used. These are discussed elsewhere in our documentation.

PCI/PCIe Tuners

Internal PCI/PCIe tuner cards require support for the tuner in the host OS. Most cards require a driver and separate firmware to work. Some cards will be supported through drivers and firmware available in the upstream Linux kernel and will be able to run on any current Linux distro and version. Other cards require downstream/vendor drivers and these may dictate which distro and version must be used to have support. How to install the right drivers and firmware for your hardware is beyond the scope of this guide so please follow the instructions of the tuner card manufacturer.

Tvheadend can do nothing if tuners are not installed working properly. If you have problems, most original card manufacturers (but not cheap clone-card manufacturers) have active forums where you can report issues and ask for assistance.

i2s Tuners

Internal i2s tuners are normally found in Android or Linux set-top box devices with the required drivers and firmware embedded in the OS image that runs on the device. In theory this means the box requires no hardware setup: which is appealing to users. In practice you may need to update the device to the lastest available firmware to ensure best performance, and client software options may be limited to specific pre-installed or embedded versions of popular apps.

Firmware update options for Android set-top boxes are often limited. If you have problems with internal i2s tuners the original box manufacturer must resolve them.

USB Tuners

External USB tuners are often cheap, work well, and are well-matched to smaller boards and boxes that lack internal PCI slots. However, most USB tuners need more than 500mA so will need external direct power or an external USB hub that supports higher current loads to work properly. Bandwidth can also be a problem and even fast USB3 ports can experience bandwidth problems with mulitple USB devices chained from a single port (and USB bus).

Raspberry Pi 0/1/2/3/4 boards internally share USB bus bandwidth with Ethernet. Multiple USB tuner configs and higher-bandwidth HD streams often run into bandwidth issues.

Network Tuners

External network tuners (SAT>IP devices and similar) cost more than internal PCI/PCIe cards and USB devices but are the firm recommendation of the project team: they are easier to configure and require no fiddling with Linux kernel drivers/firmware to create and maintain a working and reliable system.

The extra up-front cost is saved over time with easier maintenance, and the devices typically have excellent and long-term support from their manufacturers.

This information may be outdated. If you have some spare time, please to through the commit History and add the changes to the documentation.

v42

• added comment field to addDvrEntry, updateDvrEntry, autorecEntryAdd, autorecEntryUpdate, timerecEntryAdd, timerecEntryUpdate

v41

• added full UUID to channelAdd, tagAdd and dvrEntryAdd

• added ratingAuthority and ratingCountry to dvrEntryAdd and eventAdd

v40

• added DVR configuration UUID to dvrEntryAdd, dvrEntryUpdate, autorecEntryAdd, autorecEntryUpdate, timerecEntryAdd, timerecEntryUpdate

v39

• added broadcast type to autorec DVR entry

v38

• added service provider name to channelAdd -> services

v37

• added ratingLabel to EPG & DVR entries

• added ratingIcon to EPG & DVR entries

v36

• added ageRating to DVR entries

v26..35

TODO

v25

• added updateAutorecEntry and updateTimerecEntry

• (and other changes not yet documented here)

v23..24

• added descrambleInfo (not yet documented here)

v22..23

• extended addDvrEntry, updateDvrEntry, dvrEntryAdd method

  • added enabled

• extended getSysTime

  • added gmtoffset

v21..22

• extended updateDvrEntry method

  • added channelId

v20..v21

• dvrEntry structures

  • added files msg (multiple files) to the files field

  • added dataSize field to show actual (last) file size in dvrEntry updates

• epg events - added subtitle field

v19..v20

• dvrEntry structures

  • added subscriptionError, streamErrors, dataErrors fields

  • added subtitle fields

• autorecEntry structures

  • added dupDetect and fulltext fields

• added errors fields to the stream status

• added satpos to the subscription start

• added subscriptionError field to subscriptionStatus server-to-client method

v18..v19

• autorec/timerec structures

  • added directory field (forced output directory)

  • added enabled field

v17..v18

• added addTimerecEntry, deleteTimerecEntry methods

• added timerecEntryAdd, timerecEntryUpdate, timerecEntryDelete server-to-client methods

• extended addAutorecEntry method

  • added start/startWindow/name fields

  • added owner/creator fields

  • obsoleted creator field

• extended dvrEntryAdd, dvrEntryUpdate

  • added timerecId field

  • added owner/creator fields

• extended addAutorecEntry, deleteAutorecEntry methods

  • added start/startWindow fields

  • obsoleted approxTime

  • added name/owner/creator fields

• extended autorecEntryAdd, autorecEntryUpdate server-to-client methods

  • fields like for addAutorecEntry

• extended getTag method

  • added tagIndex field

v16..v17

• extended subscriptionStart server-to-client method

  • added meta field

• changed H264 meta data handling (codec meta data are in the meta field only in start message)

• VORBIS and AAC codecs have codec specific meta data in the meta field in start message

• changed subscribe method

  • the normts is always active and the parameter is ignored

v15..v16

• added getProfiles, getDvrConfigs methods

• removed getCodecs methods

• extended subscribe method

  • add profile field

v14..v15

• extended channelAdd, channelUpdate server-to-client methods

  • the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'

• extended getChannel method

  • the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'

v13..v14

• added getChannel method

v12..v13

• added addAutorecEntry method

• added deleteAutorecEntry method

• added autorecEntryAdd, autorecEntryUpdate, autorecEntryDelete server-to-client methods

• extended channelAdd server-to-client method

  • added channelNumberMinor (for {major}.{minor} channel numbers)

• extended dvrEntryAdd and dvrEntryUpdate server-to-client methods

  • added eventId, autorecId, startExtra, stopExtra, retention, priority, contentType fields

• extended addDvrEntry method

  • added retention

• extended updateDvrEntry method

  • added retention, priority

• extended epgQuery method

  • added minduration, maxduration

• added subscriptionGrace server-to-client method

v11..v12

• added subscriptionFilterStream method

• added getDvrCutpoints method

v10..v11

• added audio_type in the subscriptionStart server-to-client method

• added getCodecs method

It helps to understand the basic software concepts for Tvheadend:

Hardware & Software

• Tuner is the chipset/hardware needed to interpret a digital television signal and extract from it the programme stream. Tuner hardware is also responsible for communicating with your satellite dish via the LNB when using DVB-S.

• Driver is software the operating system uses to talk to the tuner hardware. It can be built into the operating system, or might be something you need install, or even compile, separately.

• Firmware is binary microcode that the driver sends to the tuner on initialisation. Card firmware is closed-source software and can be a common cause of problems.

Tvheadend

• Network is a software definition of your carrier network that tells tuner hardware how and where to look for a signal, e.g. the network defines a such as DVB-T or DVB-S2, and how it is scanned, where the DVB-S satellite is in orbit, and similar.

• Muxes are channel frequencies that transmit multiple digital channel signals in the radio frequency space of a single analogue channel. Digitial signals are multiplexed (muxed) together to allow more channels to be broadcast.

• Services are the individual data streams on a Mux. They can be TV or Radio programmes, or they can provide data services such as digital teletext or catch-up IPTV services.

• Channels are mapped against Services. Channels are what client software access when users think “I’d like to watch BBC One now, please”.

Each configuration component supports many-to-many relationships: meaning one component can be related to multiple components of the next type, and vice versa, e.g. one tuner can support multiple networks and one network can exist on multiple tuners.

The following diagram explains the relationship between these components:

Why The Complexity?

Simply, because 'BBC One' probably exists in multiple different places. It has regional variations on multiple frequencies (different services on different muxes) and if often accessible through more than one piece of hardware (two satellite tuners, or one satellite and one terrestrial tuner). When you select a channel to watch or record, Tvheadend needs to know the mapped path to the right service on the right mux .. to ask the right tuner to get the signal for you.

There are three themes that can be used with the TVH Web User Interface.

From Configuration -> General -> Base, in the 'Web Interface Settings' panel, select one of the following themes from the drop‑down list.

Blue (Default)

Grey

Access

This tab shows all finished recordings:

Menu Bar

The following functions are available:

Grid Items

The main grid items have the following functions:

• Details: Shows the status of the recording event:

The detailed information dialog is as follows:

The columns also provide the following details:

• Play: Play the selected recording in your browser via the VLC Plugin or some other external player.

• Title: The title of the recording.

• Subtitle: Text…

• Episode: The episode number of the record.

• Scheduled Start Time: The date and time when the recording was started.

• Scheduled Stop Time: The date and time when the recording was stopped.

• Duration: The total duration of the recording.

• File Size: The size of the recording file on disk.

• Channel Name: The name of the channel from which the recording was made.

• Owner: Text…

• Creator: The name of the user who created the recording.

• DVR Configuration : The DVR configuration to be used for this recording.

• Schedule Status : The status of the recording (completed.

• Errors : Text…

• Data Errors : Text…

• URL : The URL of the recording.

• Comment : Text…

The date and time are shown in many places within the Web User Interface. In most places, the format used is based on the default setting of your Browser and Operating System.

If, for example, the date/time format in your 'Upcoming Recordings' looks something like, 'Fri, 02/08/2024 14:05:00' and you wish to shorten it to something like 'Fri, 02-Aug 14:05', you can do the following:

In the WebUI, navigate to Configuration -> General -> Base.

Ensure that your 'Default view level' is set to at least 'Advanced'.

In the 'Web Interface Settings' panel, the 'Custom date Format' field can be used to override the default date/time format by adding:

%ddd, %dd-%MMM %hh:%mm

Reload your bowser window for this change to be applied.

The following is a list of available formatting code options:

Usage: tvheadend [OPTIONS]

Generic Options

Service Configuration

Server Connectivity

Debug Options

Testing Options

Scan files are used by TVHeadEnd (TVH) during the setup process to create muxes and scan for services available on those muxes. An excerpt from a scan file may look like this:

[CHANNEL] DELIVERY_SYSTEM = DVBT FREQUENCY = 226500000 BANDWIDTH_HZ = 7000000 CODE_RATE_HP = AUTO CODE_RATE_LP = AUTO MODULATION = QAM/64 TRANSMISSION_MODE = 8K GUARD_INTERVAL = 1/16 HIERARCHY = NONE INVERSION = AUTO

The location of the scan files may vary based upon the TVH version. /usr/local/share/tvheadend/data/dvb-scan/ /usr/share/tvheadend/data/dvb-scan/

Depending on the value of the DELIVERY_SYSTEM, TVH recognises the following parameters.

Accepted values

The following values are accepted for the parameter fields. Please note that an 'accepted' value may not always be processed.

DELIVERY_SYSTEM

NONE, DVB-C, DVBC/ANNEX_A, DVBC_ANNEX_A, ATSC-C, CableCARD, DVBC/ANNEX_B, DVBC_ANNEX_B, DVB-C/ANNEX-C, DVBC/ANNEX_C, DVBC_ANNEX_C, DVBC_ANNEX_AC, DVB-T, DVBT, DVB-T2, DVBT2, DVB-S, DVBS, DVB-S2, DVBS2, DVB-H, DVBH, ISDB-T, ISDBT, ISDB-S, ISDBS, ISDB-C, ISDBC, ATSC-T, ATSC, ATSCM-H, ATSCMH, DTMB, DMBTH, CMMB, DAB, DSS, TURBO.

FREQUENCY

Frequency in hertz.

BANDWIDTH_HZ

(Bandwidth in hertz) 1700000, 5000000, 6000000, 7000000, 8000000, 10000000.

CODE_RATE_HP / CODE_RATE_LP / INNER_FEC

1/2, 1/3, 1/4, 1/5, 2/3, 2/5, 2/9, 3/4, 3/5, 4/5, 4/15, 5/6, 5/9, 6/7, 7/8, 7/9, 7/15, 8/9, 8/15, 9/10, 9/20, 11/15, 11/20, 11/45, 13/18, 13/45, 14/45, 23/36, 25/36, 26/45, 28/45, 29/45, 31/45, 32/45, 77/90.

MODULATION

NONE, AUTO, QPSK, QAM4NR, QAM/AUTO, QAM-AUTO, QAM/16, QAM16, QAM/32, QAM32, QAM/64, QAM64, QAM/128, QAM128, QAM/256, QAM256, QAM/1024, QAM1024, QAM/4096, QAM4096,VSB/8, 8VSB, VSB/16, 16VSB, PSK/8, 8PSK, DQPSK, BPSK, BPSK-S, 16APSK, 32APSK, 64APSK, 128APSK, 256APSK,8APSK-L, 16APSK-L, 32APSK-L, 64APSK-L, 128APSK-L, 256APSK-L.

TRANSMISSION_MODE

NONE, AUTO, 1k, 2k, 8k, 4k, 16k, 32k, C1, C3780.

GUARD_INTERVAL

NONE, AUTO, 1/4, 1/8, 1/32, 1/16, 1/128, 19/128, 19/256, PN420, PN595, PN945.

HIERARCHY

NONE, AUTO, 1, 2, 4.

INVERSION

NONE, AUTO, ON, OFF.

ROLLOFF

5, 10, 15, 20, 25, 35.

PILOT

NONE, AUTO, ON, OFF.

PLS_CODE

(Physical Layer Scrambling) ROOT, GOLD, COMBO.

POLARIZATION

V, H, L, R, O.

References

A message can be of either map or list type. In a map each field has a name, in a list the members do not have names, but the order should be preserved.

The field types are:

All in all the message structure is quite similar to JSON but most notably; no boolean nor null type exist and HTSMSG supports binary objects.

HTSMSG Binary Format

The binary format is designed to for back-to-back transmission of messages over a network (TCP) connection.

The root message must always be of type map.

Root body

HTSMSG-Field

Field encoding for type: map and list

The data is repeated HTSMSG-Fields exactly as the root body. Note the subtle difference in that for the root-message the length includes the 4 bytes of length field itself whereas in the field encoding the length written includes just the actual payload.

Field encoding for type: s64

Integers are encoded using a very simple variable length encoding. All leading bytes that are 0 is discarded. So to encode the value 100, datalength should be 1 and the data itself should be just one byte [0x64]. To encode 1337; datalength=2, data=[0x39 0x05].

Note that there is no sign extension in this encoding scheme so if you need to encode -1 you need to set datalength=8 and data = [0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff]. This can certainly be thought of as a bug, but it is the way it is.

Field encoding for type: str

Datalength should be the length of the string (NOT including the null terminating character). Thus the null terminator should not be present in data either.

Field encoding for type: bin

Datalength should be the length of the binary object. Data is the binary object itself.

This communication is currently implemented by using htsmsg's. All strings are encoded as UTF-8.

There are two distinct ways for communication within HTSP.

Apart from this there is a number of messages that needs to be exchanged during login, see the login section below.

RPC Communication

There is a normal RPC way of doing things. I.e. the client sends a request and the server responds with a reply. All the RPC methods are listed below as the 'Client to Server' methods. Apart from all message fields listed within each message type the client can add an additional field:

RPC request extra fields:

The followings field should be used by the client to match the reply with the request. All replies are guaranteed to arrive in the same order as the requests. Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.

RPC reply extra fields:

Streaming Communication

For streaming of live TV and various related messages the server will continuously push data to the client. These messages are referred to as asynchronous messages and always have the 'method' field set and never have the 'seq' field set. Also, the client can enable an additional asyncMetadata mode and by doing so it will be notified by the server when meta data changes. (EPG updates, creation of channels and tags, etc).

Authentication

In Tvheadend, each method has an associated access restriction. Currently there is only one restriction (Streaming). However, this may change in the future.

Privileges for these restrictions may be granted in two ways: Username + Password and/or Source IP address. Therefore it is possible to gain permissions to the system without entering a username and password. While this is really useful it also complicates the authentication schema a bit. Upon connect the initial privileges will be raised based on the source address.

Before any username / password based authentication has taken place the client must have obtained a challenge (which stays fixed for the session). This is done via the 'hello' method.

In principle it's possible to use two different authentication idioms with HTSP. Depending on how your application works one or another may be more suitable. While they do not really differ from a protocol point of view it's worth mentioning a bit about them here:

Initial Login Authentication

The client performs all of its authentication using the 'login' method.

It may choose to send:

• Username and password: Privileges will be raised based on these credentials.

• Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.

• Nothing: Privileges will be based on just the source address.

If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based) the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.

On-Demand Authentication

The client performs all of its authentication when it needs to.

When using this method, the client will check every RPC reply for the 'noaccess' field. If it set to 1 it whould ask the user for username + password and retry the request but also add 'username' and 'digest' to the original message. (See RPC request extra fields above)

Typically it would not send a username or digest during login.

HTSP is a TCP based protocol primarily intended for streaming of live TV and related meta data such as channels, group of channels (called tags in HTSP) and electronic program guide (EPG) information.

The transmission and reception of a channel over HTSP is referred to as a subscription. A single HTSP session can handle as many concurrent subscriptions as the bandwidth and CPU permits.

The HTSP server in tvheadend has a payload-aware scheduler for prioritizing more important packets (such as I-frames) before less important ones (such as B-frames). This makes HTSP suitable for long-distance transmissions and/or paths with non-perfect delivery. (It has been tested with a server in Stockholm and the client in Berlin).

For information about the HTSP wire format please refer to the following page: .

If you're looking to develop a new client, there are several existing client implementations from which you might be able to gain knowledge:

• (This is a demo client and is WIP, it has limited functionality).

If you prefer to build Tvheadend from source, tarballs and

channelAdd

A new channel has been created on the server.

Message fields:

Service fields:

channelUpdate

Same as channelAdd, but all fields (except channelId) are optional.

channelDelete

A channel has been deleted on the server.

Message fields:

tagAdd

A new tag has been created on the server.

Message fields:

tagUpdate

Same as tagAdd, but all fields (except tagId) are optional.

tagDelete

A tag has been deleted from the server.

Message fields:

dvrEntryAdd

(Added in version 4)

A new recording has been created on the server.

Message fields:

Valid values for state:

Valid values for subscriptionError:

dvrEntryUpdate

Message fields:

dvrEntryDelete

(Added in version 4)

A recording has been deleted from the server.

Message fields:

autorecEntryAdd

(Added in version 13)

A new autorec recording has been created on the server.

Message fields:

autorecEntryUpdate

(Added in version 13)

Message fields:

autorecEntryDelete (Added in version 13)

Message fields:

timerecEntryAdd

(Added in version 18)

A new autorec recording has been created on the server.

Message fields:

timerecEntryUpdate

(Added in version 18)

Message fields:

timerecEntryDelete

(Added in version 18)

Message fields:

eventAdd

(Added in version 6)

Message fields:

• *contentType previously had the major DVB category in the bottom 4 bits, however in v6 this has been changed to properly match DVB, so top 4 bits as major category and bottom 4 bits has sub-category. Clients requesting v5 or lower will get the old output.

eventUpdate

(Added in version 6)

Message fields:

eventDelete

(Added in version 6)

Message fields:

initialSyncCompleted

(Added in version 2)

Sent after all the initial metadata has been sent when session has been set to async mode.

Message fields:

subscriptionStart

Asynchronous message output when a new subscription is successfully started.

Message fields:

Stream message fields:

Sourceinfo message fields:

Video Stream types:

Audio Stream types:

Subtitle Stream types:

subscriptionGrace

Notifies client about the grace timeout (timeout for stream activation). It can be issues multiple times. For example a configuration with satellite rotors requires more than 120 seconds to tune, so users should be notified..

Message fields:

subscriptionStop

A subscription has been stopped.

Message fields:

Valid values for subscriptionError:

subscriptionSkip

(Added in version 9)

A subscription has been skipped.

Message fields:

subscriptionSpeed

(Added in version 9)

A subscription's playback speed has changed.

This can happen even without a speed request, should playback reach either end of the buffer.

Message fields:

subscriptionStatus

Subscription status update.

Message fields:

Valid values for subscriptionError:

queueStatus

The queueStatus message is sent every second during normal data delivery.

The transmit scheduler have different drop thresholds for different frame types.

If congestion occurs it will favor dropping B-frames before P-frames before I-frames. All audio is recognized as I-frames.

Message fields:

signalStatus

The signalStatus message is sent every second during normal data delivery.

The optional fields may not have been implemented or may not be supported by the active adapter.

Message fields:

timeshiftStatus

Provide status every second about the timeshift buffer.

Message fields:

muxpkt

Streaming data.

Message fields:

Tvheadend has a built-in Electronic Program Guide (EPG). This is an in-memory database populated with information received over-the-air from DVB networks or from external XMLTV grabbers.

The EPG tab displays a filterable grid containing all events, sorted on start time:

Menu Bar

The following functions are available:

Filtering / Searching

The EPG tool bar shows five input fields which are used to filter/search events. The form uses implicit AND between input fields. This means all filters must match for an event to be displayed.

Title, Channel, Tag and Content Type are dependent on your configuration and on what your broadcaster sends. Options for the Duration are as follows:

For example: if you only want to see Movies from available HD channels you would select ‘HDTV’ in the [Filter tag…] field, and select ‘Movie / Drama’ in the [Filter content type…] field. You could then further limit the search to programmes between 1.5 - 3 hours by selecting ‘01:30:01 to 03:00:00’ in the [Filter duration…] field.

The grid updates dynamically as you change filters. You do not need to press a ‘Search’ button.

You can clear a filter by deleting its contents or by selecting ‘(Clear filter)’ on all filter fields except the Title filter. To clean all filters, press the [Reset All] button.

Buttons

The following buttons are also available:

Grid Items

The main grid items have the following functions:

• Details: Displays the current status of a recording event for the selected programme

• Progress : A bar graph display of how far through a programme we currently are.

• Title: The programme main title. You can automatically set a filter to the value of this field by clicking on it (e.g. click on ‘Daily News’ will automatically filter the whole grid to only show programmes with the same name).

• SubTitle: The programme minor title or subtitle if included with EPG data. Some providers use this for a programme synopsis and not a true subtitle.

• Episode: Episode number, if given by your EPG provider.

• Start Time: The scheduled start time of the programme.

• End Time: The scheduled end time of the programme.

• Duration: The scheduled duration (i.e. start time to end time) of the programme.

• Number: The channel number of the broadcasting channel, if defined.

• Channel: The name of the broadcasting channel. You can automatically set a filter to the value of this field by clicking on it (e.g. click on ‘Channel 4 HD’ will automatically filter the whole grid to only show programmes from that channel).

• Stars: Rating (in stars) of the programme.

• Age: Age rating of the programme.

• Content Type : Any content/genre information as provided by the EPG provider. You can automatically set a filter to the value of this field by clicking on it (e.g. click on ‘Movie/Drama’ will automatically filter the whole grid to only show programmes of the same type).

Event Details & Recording

If you click on a single event, a popup displays detailed information. You can schedule the event for recording by clicking on the [Record program] button. If the EPG provider includes series-link data the [Record series] button allows you to schedule recording of all entries in the series.

For events without any series link information, an [Autorec] button will be provided to create a pseudo-series link using the autorec feature.

When scheduling recording you can choose the DVR profile used for the recording or autorec rule. This will normally show (default) but you can define different profiles in the Configuration -> Recording -> Digital Video Recorder tab. Profiles allow you to set, e.g. post-broadcast padding to accomodate a channel that always runs late, or a post-processing command to strip adverts from recordings made from a commercial channel.

The [Search IMDB] button runs a search against the programme title on on imdb.com, and [Play program] button. This downloads am XSPT or M3U playlist file (depending on startup options) and if your Operating System is correctly configured this will launch an appropriate player application. If not you will need to manually open (double-click) the playlist file to start watching.

Clock on the [X] window button (top-right) to close the popup. The popup is not modal and will remain open and visible. You can open multiple detailed information popups at the same time.

Autorecordings

To record all events matching a specific search query, e.g. to record a favourite show every week, press the [Create AutoRec] button in the top toolbar. A popup with details on the to-be-created "autorec" rule will be shown. To enable the rule, confirm it by clicking the [Yes] button.

Autorec rules are listed in the Digital Video Recorder tab. Edit the rule list if you want to temporarily disable an autorecording or make adjustments to the channel, tag, or similar rule criteria.

Watch TV

Clicking the [Watch TV] button will open an HTML5 player pop-up where you can select the channel to open and stream profile to use. A transcoding stream profile is required to transcode the stream to a format that is supported by your browser, as browsers only support certain formats and codecs.

Supported Container Formats

Supported Video Codecs

Supported Audio Codecs

hello

Used to identify the client toward the server and to get the session challenge used to hash passwords into digests. The client can request a different version of the HTSP protocol with this method. If no 'hello' message is sent the server assumes latest version is to be used.

Client/Server should select lowest common version, if this is not possible connection should be terminated.

Request message fields:

Reply message fields:

Note: possible values for servercapability[]:

authenticate

This can be used to issue authentication without doing anything else. If no privileges are gained it will return with 'noaccess' set to 1.

Request message fields:

Reply message fields:

api

(Added in version 24)

This is a proxy to HTTP API.

Request message fields:

Reply message fields:

getDiskSpace

(Added in version 3)

Return diskspace status from Tvheadend's PVR storage

Request message fields:

Reply message fields:

getSysTime

(Added in version 3)

Return system time on the server.

Request message fields:

Reply message fields:

enableAsyncMetadata

When this is enabled the client will get continuous updates from the server about added, update or deleted channels, tags, dvr and epg entries.

An interactive application that presents the user with information about these things should probably enable this and the implement the various server to client methods.

Request message fields:

Reply message fields:

Once the reply as been sent the initial data set will be provided, and then updates will arrive asynchronously after that. The initial data dump is sent using the following messages:

getChannel

(Added in version 14)

Request information about the given channel.

Request message fields:

Reply message fields:

getEvent

Request information about the given event. An event typically corresponds to a program on a channel.

The language field in the request allows preference for languages to be requested for the various string fields.

Request message fields:

Reply message fields:

getEvents

(Added in version 4)

Request information about a set of events. If no options are specified the entire EPG database will be returned.

Request message fields:

Reply message fields:

epgQuery

(Added in version 4)

Query the EPG (event titles) and optionally restrict to channel/tag/content type.

Request message fields:

Reply message fields:

if full == 1

else

getEpgObject

Get detailed EPG Object info.

Request message fields:

Reply message fields:

getDvrConfigs

(Added in version 16)

Return a list of DVR configurations.

Reply message fields:

Message fields:

addDvrEntry

(Added in version 4)

Create a new DVR entry. Either eventId or channelId, start and stop must be specified.

Request message fields:

Reply message fields:

updateDvrEntry

(Added in version 5)

Update an existing DVR entry.

Request message fields:

Reply message fields:

cancelDvrEntry

(Added in version 5)

Cancel an existing recording, but don't remove the entry from the database.

Request message fields:

Reply message fields:

deleteDvrEntry

(Added in version 4)

Delete an existing DVR entry from the database.

Request message fields:

Reply message fields:

getDvrCutpoints

(Added in version 12)

Get DVR cutpoints.

Request message fields:

Reply message fields:

Cutpoint fields:

addAutorecEntry

(Added in version 13)

Create a new Autorec DVR entry. Title must be specified.

Request message fields:

Reply message fields:

updateAutorecEntry

(Added in version 25)

Update an existing Autorec DVR entry.

Request message fields:

Reply message fields:

deleteAutorecEntry

(Added in version 13)

Delete an existing autorec DVR entry from the database.

Request message fields:

Reply message fields:

addTimerecEntry

(Added in version 18)

Create a new Timerec DVR entry. Title must be specified.

Request message fields:

Reply message fields:

updateTimerecEntry

(Added in version 25)

Update an existing Timerec DVR entry.

Request message fields:

Reply message fields:

deleteTimerecEntry

(Added in version 18)

Delete an existing timerec DVR entry from the database.

Request message fields:

Reply message fields:

getTicket

(Added in version 5)

Get a ticket to allow access to a channel or recording via HTTP

Request message fields:

Reply message fields:

subscribe

Request subscription to the given channel.

Request message fields:

Reply message fields:

unsubscribe

Stop a subscription.

Request message fields:

Reply message fields:

subscriptionChangeWeight

(Added in version 5)

Change the weight of an existing subscription

Request message fields:

Reply message fields:

subscriptionSkip

(Added in version 9)

Skip a timeshift enabled subscription. The response will be asynchronous subscriptionSkip().

Request message fields:

Reply message fields:

subscriptionSeek

(Added in version 9)

Synonym for subscriptionSkip

subscriptionSpeed

(Added in version 9)

Set the playback speed for the subscription. The response will be asynchronous subscriptionSpeed().

Request message fields:

Reply message fields:

subscriptionLive

(Added in version 9)

Return a timeshifted session to live. Reply will be asynchronous subscriptionSkip().

Request message fields:

Reply message fields:

subscriptionFilterStream

(Added in version 12)

Enable or disable specified streams by index.

Request message fields:

Reply message fields:

getProfiles

(Added in version 16)

Return a list of stream profiles (configurations).

Reply message fields:

Message fields:

getCodecs

(Added in version 11, Removed in version 16)

Return a list of encoders (codecs).

Reply message fields:

fileOpen

(Added in version 8)

Open a file within the Tvheadend file system. This is now the preferred method (in place of HTTP) for accessing recordings.

Accessing recordings via HTSP will overcome the limitations of standard HTTP streaming which cannot handle both skipping and growing files (i.e. in-progress recordings) at the same time.

Request message fields:

Valid file paths:

Reply message fields:

fileRead

(Added in version 8)

Read data from a file.

Request message fields:

Reply message fields:

fileClose

(Added in version 8)

Close an opened file.

Request message fields:

Reply message fields:

fileStat

(Added in version 8)

Get status of a file.

Request message fields:

Reply message fields:

fileSeek

(Added in version 8)

Seek to position in a file.

Request message fields:

Note: valid values for whence

Reply message fields:

ADMIN privilege is required for all of these functions.

bouquet/class

Lists the text strings, options and defaults used when configuring bouquets within TVH (ie Configuration -> Channel/EPG -> Bouquets).

bouquet/create

Create a new bouquet.

• conf Object describing the new bouquet. An element ext_url is required; presumably in the format of the source element in bouquet/grid.

bouquet/detach

Removes the link from a channel to the bouquet that it is part of.

• uuid uuid(s) of channels to detach.

bouquet/grid

Lists details of bouquets. For details of the parameters and selection criteria which can be applied, see Common Parameters.

{
   "entries" : [
      "uuid": "0d5677d5c370705f3cd3fb53665bc62c",
      "enabled": false,
      "maptoch": false,
      "mapopt": [],
      "chtag": [],
      "chtag_ref": "",
      "name": "Scotland G2: Scotland/BorderSco",
      "ssl_peer_verify": false,
      "ext_url_period": 60,
      "source": "dvb-freesat://dvbs,28.2E,0119,62",
      "services": {},
      "services_seen": 63,
      "services_count": 0,
      "comment": "11428H in Freesat",
      "lcn_off": 0
    }, ...
  ],
  "total": 303
}

bouquet/list

Lists names and bouquets. The list excerpted below is coded into tvheadend.

{
   "entries" : [
      {
         "key" : "e7ddb611669a6a612846415946272f89",
         "val" : "Canal Digitaal SD"
      }, ...
   ]
}

bouquet/scan

Scan (using an available tuner) one or more bouquets to find their channels. The channel list is NOT returned, just an empty JSON object.

• uuid uuid(s) of bouquet(s) to scan.

The HTSP api method can be used as a proxy to access the HTTP/JSON API. This allows HTSP-only clients access to any JSON feature, including JSON-only features. Data exchanged to and from the TVH server is achieved by encapsulating the required HTTP/JSON parameters within the HTSP message. TVH expects to receive encapsulated JSON data and will respond with a HTSP map representing the JSON data returned.

Also see: JSON API.

HTSP API Syntax Summary

Request:

args               msg[] optional   HTTP arguments
path               str   required   HTTP path

Reply:

response           msg[] required   JSON response 

Simple Request

To execute the HTTP API command: http://TVH:9981/api/channel/grid Set the path field to channel/grid and send the request. The args field is not required. The response will be a HTSP map containing an element named response. This element will be a map containing the the JSON response presented as HTSP elements.

Intermediate Request

To execute the HTTP API command: http://TVH:9981/api/channel/grid?sort=number&dir=desc Set the path to channel/grid as in the previous example. The arg field must be set to type map, and in this example, contain two str elements. Map str element named sort should contain the value number and map str element named dir should contain the value desc.

Advanced Request

To execute the HTTP API command: http://TVH:9981/api/dvr/entry/create Set the path to dvr/entry/create. As with the previous example, the args field must be set to type map. Method 1 - JSON String Create a JSON string containing the properties required to complete the request as detailed in the JSON API documentation. In this example, to create a new DVR entry. Within that map, create a str element named conf that contains the required JSON string. Method 2 - HTSP Map Instead of creating a JSON string, create a HTSP map where each element name matches the name of the JSON property and contains the required property value. args should be a map that contains another map named conf that contains another map with the required JSON data represented as HTSP elements.

API calls related to Conditional Access. ADMIN privilege is necessary for all of these functions.

caclient/builders

Lists the text strings, options and defaults used when configuring Conditional Access devices within TVH (ie Configuration -> CAs -> Add).

caclient/class

Lists the text strings, options and defaults used when configuring Conditional Access within TVH (ie Configuration -> CAs).

caclient/create

Create a new CA instance.

• class Name of the class to create, ie one of the classes listed by caclient/builders.

• conf A JSON object describing the new device.

caclient/list

List CA clients.

{
   "entries" : [
      {
         "title" : "Linux DVB CAM (CI/CI+)",
         "status" : "caclientNone",
         "uuid" : "7f435a73b190419cc6e69e3956c50549"
      }
   ]
}

ADMIN privilege is required for all of these functions except codec_profile/list.

codec/list

Lists available codecs and their properties. This is a very verbose list.

codec_profile/class

Lists the text strings, options and defaults used when configuring codec profiles.

codec_profile/create

Add a new codec profile.

• class The name of the codec profile.

• conf A JSON object describing the codec profile.

codec_profile/list

{
   "entries" : [
      {
         "uuid" : "d3f76d002a895f5c65dd57715d169399",
         "title" : "webtv-vorbis (WEBTV codec Vorbis)",
         "status" : "codecEnabled"
      },
      {
         "status" : "codecEnabled",
         "title" : "webtv-aac (WEBTV codec AAC)",
         "uuid" : "77e7184d6ade386137f553de0687254d"
      },
      {
         "title" : "webtv-h264 (WEBTV codec H264)",
         "status" : "codecEnabled",
         "uuid" : "eb7281ade724c77d23add9223bc2a480"
      }
   ]
}

ADMIN privilege is required for all of these functions except config/capabilities.

config/capabilities

Returns a list of some compile-time options which were used to build the software. Requires either 'Web Interface' or 'HTSP Interface' privilege.

[
   "caclient",
   "tvadapters",
   "imagecache",
   "timeshift",
   "trace",
   "libav"
]

config/load

Lists the details, descriptions, defaults and current values of the items in the GUI screen Configuration -> General -> Base. See Common Parameters for details of selection parameters.

config/save

Untested. Updates the server from an object in the format produced by config/load.

• node The JSON object.

memoryinfo/class

Lists the details and descriptions of items in the TVH GUI screen Configuration -> Debugging -> Memory Information Entries.

memoryinfo/grid

Lists details of in-memory objects. See Common Parameters for details of selection parameters.

{
   "entries" : [
      {
         "peak_count" : 17154,
         "name" : "EPG Broadcasts",
         "uuid" : "a1af1bc4f29ba28104e71a540465f250",
         "count" : 17154,
         "peak_size" : 6235792,
         "size" : 6235792
      },
      {
         "peak_count" : 3285,
         "peak_size" : 369303,
         "count" : 3285,
         "size" : 369303,
         "name" : "EPG Series Links",
         "uuid" : "823a78a3bcd05b688c59871455da6399"
      },
      {
         "count" : 11514,
         "peak_size" : 5015593,
         "size" : 5015593,
         "name" : "EPG Episodes",
         "uuid" : "5c666eea1ec3de4bbb9a11f60116b258",
         "peak_count" : 11514
      }, ...
   ],
   "total" : 19
}

pathlist

Lists all of the api functions supported by the server.