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.

It is possible to compile Tvheadend for Android but the current project team does not test or release Android binaries or .apk files. If you are the Android platform maintainer we are seeking? .. rsvp!

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!

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 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

for Lubuntu 24.04

for Lubuntu 22.04

In order to access Tvheadend behind a reverse proxy server and still be able to stream services or recordings, it is necessary for the reverse proxy server to add or modify some headers in the HTTP request forwarded to TVH.

X-Forwarded-Proto:

Tvheadend currently (as at April 2025) only supports the HTTP protocol natively. To access TVH via HTTPS, an external reverse proxy server is required to convert the incoming HTTPS request to HTTP and forward it to TVH.

In order for TVH to recognise that it is operating behind a HTTPS reverse proxy server, the proxy server must be configured to add the X-Forwarded-Proto: https header to the request forwarded to TVH.

Adding this header will ensure that documents that contain a TVH URL, such as M3U files, will be prefixed with correct protocol identifier.

Host: / X-Forwarded-Host:

The public-facing host name, port number and path returned by TVH within documents such as an M3U can also be modified. As TVH only recognises the X-Forwarded-Host:header when the Host:header is not present, it is recommended that only the Host:header be modified by the proxy in for following format:

Host: <External host>[:<External port>][/<External path>]

If you prefer to build Tvheadend from source, tarballs and instructions are on GitHub

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.

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 configuration 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.

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.

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

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. Digital 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.

Tvheadend binary packages can be downloaded from 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:

RPM Packages (Fedora, RedHat)

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

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

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 -f t parameter is for scanning DVB-T, the -c AU parameter sets to country to Australia and 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.

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.

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).

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:

seq              int  optional   Sequence number. This field will be echoed back by the server in the reply.
username         str  optional   Username, in combination with 'digest' this can be used to raise the privileges
                                 for the session in combination with invocation of a method. 
digest           bin  optional   Used to raise privileges.

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:

seq              int  optional   Sequence number. Same as in the request.
error            str  optional   If present an error has occurred and the text describes the error.
noaccess         int  optional   If present and set to '1' the user is prohibited from invoking the method due to 
                                 access restrictions. 

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.

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:

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…

Usage: tvheadend [OPTIONS]

Generic Options

Service Configuration

Server Connectivity

Debug Options

Testing Options

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)

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 section provides information on the HTTP API for TvHeadend. It was written from the source code of the development version 4.3.

The examples shown were mostly generated from UK Freeview DVB-T / DVB-T2 and Freesat DVB-S / DVB-S2, using a single tuner in each case. Other sources and multiple input devices may give different results.

CAUTION

This API is an advanced feature of TVheadend, and the functionality is unstable and liable to change. The software does not completely validate its inputs and incorrect or unexpected calls may result in undesired behaviour.

If you need to test with a system that you that you don't have access to, for example, testing ATSC functionality on a DVB system, you can use a TS recording to emulate the tuner type.

./tvheadend --tsfile_tuners 1 --tsfile test.ts

The TS file should contain the whole mux and not just one service.

A new 'network' will be created for the file as well as a number of 'mux', 'service' and 'channel' objects matching the services found within the TS file.

The contents of the TS file will be played on a continuous loop.

See the instructions for creating Mux Dump Files for more information.

ADMIN privilege is required for these functions.

timeshift/config/load

Lists the descriptions, options and defaults for configuring the timeshift capability - see Configuration -> Recording -> timeshift.

timeshift/config/save

Untested. Set the timeshift configuration.

• node Unknown.

Front End

When a user clicks on a Help icon, the browser requests the following 2 URLs.

http://[TVH_IP]:9981/markdown/class/[TVH_CLASS]?_dc=[??TIMESTAMP??]

http://[TVH_IP]:9981/markdown/toc?_dc=[??TIMESTAMP??]

Both of these URLs return markdown content. The first URL consists of the md file that matches the URL’s class as well as all of the contents of all of the <tvh_include> files present in the main file followed by an Items section containing a description of the properties of the URL’s class.

The second URL contains the static table-of-contents in md format from /docs/markdown/toc.md.

The markdown data is converted into HTML using the third party marked library. This is called from the tvheadend.mdhelp() method in src/webui/static/app/tvheadend.js.

Build Process

The script support/doc/md_to_c.py is called from the Makefile to create the C file src/docs_inc.c. This script is called multiple times for multiple md file locations with all being centralised into a single src/docs_inc.c file.

Each md file (including the toc) is converted to a C const char array. Each element of the array is a line from the source md files and is wrapped in an i18n translation function. The file names from the <tvh_include> lines are extracted and prefixed with the string \xff\x04 via a the MDINCLUDE compiler preprocessor instruction and added to the array.

At the end of src/docs_inc.c, all of the above arrays are then indexed in a structure called tvh_doc_page.

In src/webui/webui.c’ the /markdown URL path is configured to be handled by page_markdown() in src/webui/doc_md.c. There are various functions that are called within this module, however, the \xff\x04 sequence is interpreted by the function md_render() where the <tvh_include> text is inserted into the content to be returned.

Once the text from the md files has been assembled, the md_props() function in src/webui/doc_md.c appends the Items markdown to the content to be returned.

A typical finally assembled result may look like this:

[Content from first include file] Some text or separator. [Content from second include file] Main body of the md file [Content from third include file] [Content from the internal object class definition]

All text returned to the browser is passed through the C i18n process (JS has its own i18n process) and is capable of being rendered line-by-line into any language supported by TVH provided that a translation for that text exists.

Lists the available character sets.

ADMIN privilege is required to use these functions.

satips/config/load

Lists the descriptions, options, defaults and current settings for configuring the SAT>IP server capability - see Configuration -> General -> SAT>IP server.

satips/config/save

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

• node The JSON structure containing the updates.

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

Functions to report on and control Elementary Stream filters.

There are separate API functions to operate on the different types of filter, but they all work in the same way. In the descriptions below the XXX in the function name can be replaced with video, audio, teletext, subtit (subtitle), ca or other as required.

esfilter/XXX/class

Lists the descriptions, options and defaults for configuring the chosen type of filter, ie Configuration -> Stream -> Stream Filters -> {chosen type} -> Add.

esfilter/XXX/grid

Returns the parameters of the defined filters of the chosen type. The usual selection options are available, see

esfilter/XXX/create

Creates a new filter of the chosen type. ADMIN privilege is required.

• conf A JSON object describing the filter.

Grid parameters

API calls which end in /grid, with the exception of , have a common set of parameters:

• start First entry to include. Default is the first (0).

• limit Number of entries to include. Default is 50 - use a large number to get all.

• filter A JSON object describing the filter(s) to be applied. See Grid Filters below for syntax.

• sort Name of the field to sort the records by. A case-sensitive sort is used.

• dir if sort is specified then dir=desc produces a reverse sort.

Grid filters

A filter can be applied to the output using a JSON object. The syntax is:

The "comparison" field is only used with numeric data. A "gt" comparison actually matches on greater-or-equal, and "lt" on less-or-equal.

Boolean values must be specified as "0" or "1" (NOT "true" or "false"). A (case-insensitive) regular expression match is used for strings.

The "intsplit" field is used for integer variables which are used to store a quotient and remainder, and defines how the bits of the variable are allocated.

Multiple filters can be applied to a query ONLY if they refer to different fields, so for example it is not possible to query for EPG events having start times between two values.

Load parameters

API calls which end in /load, with the exception of , have a common set of parameters:

• meta If > 0 an extra data structure is output, mostly related to the format of the GUI screen where the information is presented. Default is 0.

• list This parameter selects which items in the params array are to be output, based on the value of the 'id' field. Multiple entries can be selected, separated by commas, colons or semicolons. A '-' in front of an entry deselects that item (and implicitly selects all others).

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 .

• conf A JSON object describing the new device.

caclient/list

List CA clients.

language/list

Produces a list of all known languages and their three-letter ISO639-3 codes. The list is hard-coded within the Tvheadend source.

language/locale

Produces a similar list to language/list but also including the full RFC3066 locale reference for those locales which have been compiled into Tvheadend.

language/ui_locale

Produces a list in the same format as language/locale but containing only those locales which are supported by TVHeadend (ie have translations available).

TVHeadend provides the API using the HTTP protocol, by default via port 9981 though this can be changed in the TVH config. API functions appear as pseudo-files under the /api/ root of the server filesystem, with parameters passed to the function via either the GET or POST methods.

The call must include a username and password with access permissions to carry out the requested task. The user must also have the ACCESS_WEB_INTERFACE privilege, either directly or inherited from an earlier '*' user. In other words the "Web interface" box must be ticked on the Access Entries screen; without this all calls will fail with a "403 Forbidden" error.

If TVHeadend has been started with the '--http_root' qualifier, the HTTP root must be included in the URL, thus eg

http://admin:[email protected]:9981/myHttpRoot/api/serverinfo

The server does not check that all parameters supplied are valid in the context of the request; unexpected items are ignored. Parameters not in the expected format or not containing the expected data may also be ignored.

The response from TVH follows the HTTP protocol and includes an HTTP/1.1 header with status code. If an error occurs the response is in HTML, for example:

The error returned is generic and does not indicate the source of the problem. Authentication failures (incorrect user/pass) will return "401 Unauthorized", lack of privilege "403 Forbidden", non-existent API functions "404 Not Found", incorrect or missing parameters generally "400 Bad Request".

Data is usually returned as JSON, without any CR or LF characters - the examples given have been 'prettified' using json_pp or jq to make them easier to read. Functions which perform an action rather than return data will return an empty JSON object on successful completion.

List details of input devices. ADMIN privilege is required for these functions.

hardware/tree

Lists the parameters, options and settings for input devices.

• uuid (Required). If set to 'root', the top-level details of the input device(s) are shown. If the uuid of a device (obtained from the top-level details) is submitted, full information is shown similar to Configuration -> DVB Inputs -> TV Adaptors.

• root Function obscure.

hardware/satip/discover

Triggers a discovery process for SAT>IP servers, as Configuration -> General -> SAT>IP Server -> Discover SAT>IP Servers in the GUI. This function is only available if SAT>IP client functionality has been compiled into TVHeadend.

The op parameter must be set to all.

Example: /api/hardware/satip/discover?op=all

(yyyy-mm-dd)

Title of the PR ( yyyy-mm-dd)

Title of another PR ( yyyy-mm-dd)

(yyyy-mm-dd)

Title of PR ( yyyy-mm-dd)

Yet another PR title ( yyyy-mm-dd)

TVH can serve its own EPG in XMLTV format via HTTP.

http://[TVH_IP]:9981/xmltv/channels

ADMIN privilege is required to use these functions except for profile/list.

profile/list

Lists the available stream profiles (visible in the GUI at Configuration -> Stream -> Stream Profiles) together with their uuids.

• all A user with ADMIN privilege can use this parameter to see details of every profile even if the profile is disabled or they do not have access to them.

• htsp If set to 1, list only HTSP profiles. Default is 0 (list all).

To get the contents of a stream profile use , passing it the stream profile's uuid.

profile/class

Lists the options, defaults and descriptions of configuration parameters (Configuration -> Stream -> Stream Profiles) in the GUI.

profile/builders

Lists the options, defaults and descriptions of configuration parameters when adding a new stream profile (Configuration -> Stream -> Stream Profiles -> Add) in the GUI.

profile/create

Create a new stream profile.

• class

• conf A JSON object containing details of the new profile.

Main Application Language

Although, individual WebUI users can select their own display language, the core application takes its language configuration from the operating system.

When TVH loads, it inspects, in sequence, the following environmental variables: LC_ALL, LANG and LANGUAGE for a recognised language. Should no language information be present, or the language present is not recognised, TVH will default to en_US.

Workflow

Tvheadend uses English (en_US) as the master langauge for the WebGUI and in-GUI help. Changes to source code that add new features and capabilities must also include updates to the master template .potfiles under the intl directory if existing strings are reused or new strings added.

Merged changes to master template .potfiles are automatically replicated to Transifex where we manage the translation process. Our project is here:

If changes reuse existing strings local language files do not require translation. If they add new strings language contributors will be notified of the changes and can provide translations of the new strings in the language(s) they support. Once translated strings are saved, Transifex will automatically open a new pull-request against our GitHub repository with updates to the language .pofiles. Transifex will continue to push updates and will combine updates to multiple languages into the same pull-request as long as the pull-request remains open.

Languages

Existing languages can be seen here:

Languages can be added by submitting a language request on Transifex. Once the overall translation state exceeds 80% completed Transifex will submit a pull-request to add new language .pofiles to our GitHub repository. The final stage of addition (other than completing translations) is to edit the list of supported languages in Makefile resources.

Do not submit requests for new languages on Transifex unless you are prepared to personally work on the translations. Translations require effort not magic!

The JSON API represents the unique identifier as a 32 byte character hexadecimal string. For example: 90e9361f38c156df654ecd27b92f398c. When proxied via the HTSP api method, the unique identifier is encoded as a 16 byte binary field. When this field is represented as a hexadecimal string, it matches that used by the JSON API. The HTSP API represents the unique identifier of an object using an unsigned 32 bit big-endian integer. When represented as a hexadecimal string, the value matches the first 8 characters of the JSON unique identifier. When evaluated as binary data, it matches the first 4 bytes of the proxied JSON value.

Mixing and Matching API Values The following table summarises UUID handling by API.

Additional Notes

• The 32 bit ID may only contain 31 valid bits under certain circumstances. Based on how TVH creates 32 bit IDs, it is recommended to apply a 0x7fffffff mask for comparison operations between long and short ID forms.

• There appears to be no guarantee that the 32 bit ID will be unique among ALL object types.

TVH accepts three episode numbering schemes via XMLTV.

• onscreen

• dd_progid

• xmltv_ns

Set the 'episodeOnscreen' property of the EPG event to the value provided. TVH treats this value as free-form plain-text and no additional series or episode parsing is performed.

Note: If an 'episode-num' tag exists with a 'system' attribute set to 'onscreen', the tag's value will override the EPG event's 'episodeOnscreen' property regardless of the series or episode numbers parsed from other 'episode-num' tags. However, the other properties, for example 'seasonNumber' are set correctly. The 'onscreen' override occurs regardless of the sequence of the 'episode-num' tags.

Set the 'serieslinkUri' property to "ddprogid://xmltv/SH00012345.0000". No additional series or episode parsing is performed.

Set the 'episodeUri' property to "ddprogid://xmltv/EP00012345.0001". Set the 'serieslinkUri' property to "ddprogid://xmltv/EP00012345". Set the 'episodeNumber' property to 1. Set the 'episodeOnscreen' property to "e01".

Set the 'seasonNumber' property to 2. Set the 'seasonCount' property to 16. Set the 'episodeNumber' property to 4. Set the 'episodeCount' property to 25. Set the 'partNumber' property to 2. Set the 'partCount' property to 2. Set the 'episodeOnscreen' property to "s02.e04".

Note: In a number pair separated by a slash, the first number is zero-based and the second number is 1-based. Episode 8 of 12 is represented by '7/12'. Series/episode/part numbers are always zero-based when appearing alone.

Set the 'seasonNumber' property to 2. Set the 'seasonCount' property to 15. Set the 'episodeNumber' property to 4. Set the 'episodeCount' property to 24. Set the 'episodeOnscreen' property to "s02.e04".

Set the 'seasonNumber' property to 3. Set the 'episodeNumber' property to 5. Set the 'episodeOnscreen' property to "s03.e05".

Note: The property names in the above examples refer to the HTML/JSON API.

More details on the XMLTV format can be found here: and here: .

TVHeadEnd only recognises a subset of the total XMLTV schema.

Multiple instances of some tags like 'actor' or 'category' or 'rating' may be present.

Although no special privilege is needed to use these functions, access control is applied at the inode database level.

classes

Returns a list of all data classes together with readable titles. Requires version 4.3-406 or later.

raw/export

• class One of the class names returned by .

• uuid A single uuid or JSON array of uuids.

Returns data about the selected object(s). The information is the same as returned by the corresponding grid function (where available) but without the selection and filtering options provided by that function.

raw/import

• node A JSON object or array of objects.

Objects being imported must have a uuid and must already exist in the database.

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 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.

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.

These function provide direct access to the internal data structures of TVHeadend. Attempting to modify these internal structures may have unwanted effects including loss of data.

Information is held within TVHeadend in a key-value database. The key for each record is a random 128-bit value called a uuid. The value is a data structure which can be represented in JSON format. The record is called an idnode.

The content of each idnode depends on what it represents; this is indicated by the value of the class parameter.

Although no special privilege is required to call these functions, access control is applied to the data items being referenced.

idnode/load

Read the value of one or more idnode records. One (and only one) of these parameters must be specified:

• uuid The uuid (or JSON-structured list of uuids) to read.

• class The class of records to read, ie one of the classes returned by classes.

If uuid is given, the data to be returned may be qualified by setting one of these parameters to an integer greater than zero:

• meta Include meta-data (default values and descriptions of the data items).

• grid Return a brief summary of the records.

If class is given, setting the parameter enum to an integer value greater than zero returns only a set of key-value pairs.

In both cases the list parameter can be used to select which items are to be output, based on the value of the 'id' field. Multiple entries can be selected, separated by commas, colons or semicolons. A '-' in front of an entry deselects that item (and implicitly selects all others).

idnode/save

Update an existing idnode.

• node The JSON object (or array of objects) containing the update.

Each update must contain the uuid item. Other items supplied replace those in the idnode; they are not merged.

Fields within an idnode may be read-only; for this reason it may not be possible to take the data from idnode/load and use it as input to idnode/save (thanks to Poul Kalff for this information). To check the read-only status of a field, use idnode/class and check for a 'rdonly' flag.

idnode/tree

Read information held in a tree structure (eg for tuner devices).

• uuid The uuid of the starting point in the tree structure, or the special value 'root'.

• root The uuid of the head of the tree structure. Required if uuid = 'root'.

idnode/class

List information about a specified class; mostly metadata used to configure the TVHeadend UI.

• name The name of the class, ie one of the values returned by classes.

idnode/delete

Delete one or more records.

• uuid The uuid (or a JSON-formatted list) of the record(s) to be deleted.

idnode/moveup

idnode/movedown

Functions to query and manipulate the list of parental rating labels ('G', 'M', 'PG', etc).

ratinglabel/class

Lists the text strings, options and defaults used when configuring parental rating labels within TVH (ie Configuration -> Channel/EPG -> Rating Labels -> Add).

ratinglabel/create

Creates a new parental rating label. Requires ADMIN privilege.

• conf A JSON object containing details of the new parental rating label.

ratinglabel/grid

Lists details of parental rating labels. For details of the parameters and selection criteria which can be applied, see Grid Parameters.

{
   "entries" : [
      {
         "uuid : "a82438515ecc857dbf2509517ff3fe40",
         "enabled" : true,
         "country" : "AUS",
         "age" : 8,
         "display_age" : 11,
         "display_label" : "PG",
         "label" : "PG",
         "authority" : "ACMA",
         "icon" : "file:///my/file/location/acma-pg.png",
         "icon_public_url" : "imagecache/37"
      }, ...
   ],
   "total" : 9
}

ratinglabel/list

Lists the names and uuids of all known parental rating labels.

{
   "entries" : [
      {
         "val" : "AUS",
         "key" : "7b1f8773747155ed7341c8328a037f28"
      }, ...
   ]
}

Notes:

• Parental rating labels were added to Tvheadend in December 2023.

• Processing of parental rating labels is disabled by default and can be enabled via Configuration -> Channel/EPG -> EPG Grabber.

• Tvheadend will automatically create a placeholder record as new labels are encountered.

• Parental rating label fields will not appear in other modules, (DVR, EPG) if the processing of parental rating labels is disabled.

TVH has the ability to build a recording file and path name using predefined substitution strings. For example, using $t will include the EPG Title in the file name. Likewise, %t will pass the EPG Title as a command line argument to one of the DVR Profile command scripts.

This feature is implemented in src/dvr/dvr_rec.c.

A number of htsstr_substitute_t arrays contain a list of substitution identifiers and the functions required to perform the required substitution.

The actual substitution is performed by htsstr_substitute (src/htsstr.c) which is passed a substitution array and a substitution key ($ or %) as well as an output variable.

Pathname substitution strings can be applied equally to the file name and to directories in the hierarchy under the base directory specified in the DVR Profile. It should be noted, however, that objects that can provide their own directories, such as AutoRec and Timer DVR objects, must have their directory prefixed with $$ for substitutions to take place. The $$ prefix will be omitted from the final directory name.

WebUI

The WebUI is built on a 'single page application' framework called Ext JS. The version used appears to be 3.4.1.1 which, is considerably outdated (released circa 2009-2011).

A link to the Ext JS documentation can be found here: https://cdn.sencha.com/ext/gpl/3.4.1.1/docs/

The WebUI appears to be heavily dependent upon the internal idnode structures that not only supply the data to the WebUI via JSON, but also data type and formatting information. See the JSON Documentation for more details.

Each page or group of pages in the WebUI has its own JavaScript file, however, these normally contain just some setup and housekeeping functions specific to that area, all of the heaving lifting is done in idnode.js and tvheadend.js based on the idnode(s) in question.

Red Black Trees

Internally, TVH stores many objects in Red-Black tree structures rather than arrays. There are a number of preprocessor macros to support this. All of these macros are named RB_fn, for example, RB_FOREACH. https://github.com/tvheadend/tvheadend/blob/master/src/redblack.h https://en.wikipedia.org/wiki/Red%E2%80%93black_tree

All configuration data within TVHeadEnd (TVH), is stored in object classes. A class may contain multiple objects representing a single configuration item each.

Examples include: channels, recordings, muxes, adapters, autorecs, etc.

Detailing every object class is beyond the scope of this document, however, a list of classes can be obtained via the JSON API as follows: http://[TVH_IP]:9981/api/classes

Any object within TVH can be addressed via its UUID (Universally unique identifier).

The UUID is represented in the JSON API as a 32 hexadecimal character string (128 bit). In the HTSP API, an object’s ID is normally represented as an unsigned 32 bit integer that corresponds to the first four bytes (eight hex characters) of the UUID.

Please note: EPG event data is not stored or addressed using UUIDs, however, EPG event entries can contain links to UUIDs of configuration objects.

Objects can be linked to other objects via their UUIDs.

For example: To record a programme, the EPG entry will be linked to a ‘Channel’ object. That channel object will be linked to one or more ‘Service’ objects. Each service object will be linked to a ‘Mux’ object. Each mux object will be linked to a ‘Network’ object. Finally a network object will be linked to one or more ‘Adaptor’ objects.

The following diagram is not exhaustive, but serves to illustrate the relationship between various common object classes.

Objects are stored on disk in JSON-formatted files. These files are located with the subdirectories representing their configuration function and are named to match their UUID.

It is recommended that these files not be edited directly.

Functions to query and manipulate the list of channels.

A TVH user can only see via the API those channels which have been enabled and to which access has been allowed. However a user with ADMIN privilege can use the parameter all=1 to see details of every channel, channeltag and category even if they do not have access to them.

channel/class

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

channel/create

Creates a new channel. Requires ADMIN privilege.

• conf A JSON object containing details of the new channel.

channel/grid

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

channel/list

Lists the names and uuids of all known channels. For disabled channels the channel name is enclosed in braces.

These parameters were added at version 4.3-905:

• numbers If non-zero, the LCN appears before the channel name, separated by a space. Default is zero.

• sources If non-zero, the source appears after the channel name, in square brackets and separated by a space. Default is zero.

• sort Either name to sort by channel name, or numname to sort by LCN then by name (default). The name sort is case-sensitive.

channel/rename

Renames a channel. Only available from version 4.3.652. Requires ADMIN privilege.

• from The current name of the channel.

• to The new name of the channel.

channeltag/class

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

channeltag/create

Creates a new channel tag. Requires ADMIN privilege.

• conf A JSON object containing details of the new channel tag.

channeltag/grid

Lists details of channel tags. For details of the parameters and selection criteria which can be applied, see .

channeltag/list

Lists the names and uuids of all channel tags.

channelcategory/list

Untested. Return a list of the categories of events which appear in the current EPG and which the user is permitted to see. Used internally to populate the 'Category 1-3' drop-down boxes in DVR -> Autorecs -> Add (Expert view only). The function only works if the EPG is sourced from XMLTV.

ADMIN privilege is required for these functions.

tvhlog/config/load

Lists the details, descriptions, defaults and current values of the items in the GUI screen Configuration -> Debugging -> Configuration -> Settings. See for details of selection parameters.

tvhlog/config/save

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

• node The JSON object.

tvhlog/subsystem/grid

List the subsystems available for trace and debug operations.

Also see and .

• id - The internal enum for this subsystem. These values may change between systems depending upon the application version and the options used at compile-time but are otherwise constant.

• subsystem - The name of the subsystem. These values are to be used in the WebUI when enabling trace/debug operations.

• description - The locale-aware description of the subsystem.

• trace - True if this subsystem is currently being traced.

• debug - True if this subsystem is currently being debugged.

• traceCount - The number of subsystems with trace currently set to true.

• debugCount - The number of subsystems with debug currently set to true.

• totalCount - The total number of subsystems.

Note 1: Users may enter a special all subsystem (not listed) instead of nominating each subsystem individually in the WebUI. This condition can be detected if traceCoount and/or debugCount is equal to totalCount.

Note 2: As at April 2024, the id field is informational only. It is provided to facilitate future API development.

Tvheadend has a WebSocket interface on port 9981. It is used by the UI to provide 'live' actions and updates, avoiding the need to refresh the screen.

Example Code

The example below creates a WebSocket connection to the Tvheadend server and listens for updates.

Output

Tvheadend transmits messages on the Websocket interface asynchronously, when either an event occurs or in some cases at scheduled intervals. The output format is JSON.

Each message contains a key "messages" whose value is an array of message objects. Each message object contains a key "notificationClass" which specifies the source of the message, and a series of message-specific key-value pairs.

Object Changes

Some "notificationClass" messages may optionally contain one or more of the following arrays: "create", "change" and "delete". When present, these arrays will contain lists of UUIDs that have been created, modified or deleted as part of the scope of the current notification.

When a "notificationClass" is "epg", the arrays described above will contain EventIds rather than UUIDs and the 'update" array will be present rather than "change". Two additional arrays ('dvr_delete' and 'dvr_update') may also be present to indicate a change in recording status of the EPG event.

With regards to "create" and "change"/"update" notifications, the UUID/EventID will need to be explicitly fetched to obtain the new object property values.

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

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.

config/load

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

config/save

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

• 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 for details of selection parameters.

pathlist

Lists all of the api functions supported by the server.

serverinfo

Lists information about the server including the software version number.

Background

Translatable texts within TVH are divided into 3 areas:

Text used within the application to describe object properties and values, etc. Text used within the main web user interface (WebUI). Text used within the 'Help' system of the WebUI (Documentation).

All text is entered in English into the program/documentation source files. For successful translation, the English text also must be added to the master language translation files.

There are 3 master translation files.

intl/tvheadend.pot intl/js/tvheadend.js.pot intl/docs/tvheadend.doc.pot

These master translation .pot files are converted into various language-specific po files .

After translation, the language-specific .po files are used to build TVH. For example (where XX represents the language code):

intl/tvheadend.XX.po intl/js/tvheadend.js.XX.po intl/docs/tvheadend.doc.XX.po

This system is very similar to where a msgid tag contains the original English text and a msgstr tag contains the translated text.

msgid "Yes" msgstr "Oui

Programmer Usage

Within program code written in the 'C' programming language, the N_() macro is used to identify English text that can be translated into another language.

_() is used to return translated text at runtime based on the core application's language setting (from the OS).

tvh_gettext_lang() can be used at runtime to translate a string to any TVH language, not just the current language.

Within the WebUI code written in the 'JavaScript' programming language, the _() function is used to indicate that translation is required.

All of the help system are converted from markdown text files into C static arrays that also eventually use the N_() function before display.

If no translation is available, the original English text passed to N_() or _()will be returned.

Building the .pot Files

The 3 .pot files are updated by running the make intl command which searches the source files for translatable strings and updates the 3 .pot files accordingly.

Build Process

Although there is a single unified build process, translations for each programming language or area referred to above are described separately for clarity.

The list of languages to be processed is determined by the LANGUAGES_ALL variable set in Makefile.common.

Build Process - Main Application (C code) and WebUI Help (Markdown)

Called from the main Makefile, the script support/poc.py processes the intl/tvheadend.XX.po (main application) and intl/docs/tvheadend.doc.XX.po (documentation) files and produces a consolidated tvh_locale_inc.c file containing all of the text as static C char arrays plus an index array. This file will be compiled into the final application binary.

Build Process - WebUI (JavaScript)

Called from Makefile.webui, the script, support/pojs.py converts all of the individual intl/js/tvheadend.js.XX.po files into individual webui/static/intl/tvh.XX.js.gz files. These files are loaded dynamically at runtime by the WebUI based on the user's linguistic preferences.

Introduction

A 'Mux Dump' is a special recording where Tvheadend records the entire transmission of a single broadcaster rather than just a specific channel. Mux dumps can be useful for .

For most purposes, a mux dump lasting between 1 and 2 minutes should be suitable, however, if you are requested to provide a mux dump, ask the requester to indicate how long the mux dump should be for their purposes.

Performing a Mux Dump

In order to perform a mux dump, you first have to obtain the UUID of the mux that you wish to dump. The is a block of text, 32 characters long, containing only numbers and lower case letters.

Finding the UUID

WebUI Methods

There are many ways to do this, however, one of the easiest is to use the WebUI to navigate to 'Configuration - DVB Inputs - Muxes'. For each mux listed, there will be a 'Play' icon, on the left side of each row.

The process will be different between specific browsers, however, the 'Play' icon will always point to a link that contains the UUID of the mux somewhere.

• Simply moving your mouse cursor over this icon should show the link destination, containing the mux UUID, somewhere in the browser window.

• Right-clicking on the icon and selection 'Copy link' (or similar) should place some text into your clipboard that contains the UUID. For example: http://<TVH_IP>:9981/play/ticket/stream/mux/176838fd011c233adfa42d8a07f9ddba?title=177.5MHz%20%2F%20DVB-T%20Network Using this method, the UUID '176838fd011c233adfa42d8a07f9ddba' can be located between '/mux/' and the question mark.

• Also, right-clicking on the icon and selecting 'Save link as' (or similar) should provide you with a prompt for a file name. The default file name provided by your browser should contain the UUID of the mux. For example: d32ef9ef9c67e0552465f6a86caf1d77.m3u Using this method, the UUID is 'd32ef9ef9c67e0552465f6a86caf1d77' and consists of all of the characters before the '.m3u' in the file name.

• If you already receiving functioning services from the mux in question, you can navigate to 'Configuration - DVB Inputs - Services', select one of those functioning services and press the 'Edit' button. Within the edit window, press the 'Read-only Info' drop-down button and copy the value shown in the 'Mux UUID' text box. Press 'Cancel' to close the edit window.

API Direct Method

A list (in JSON format) of all muxes known to the system can be obtained by issuing the following command:

http://<TVH_IP>:9981/api/mpegts/mux/grid

This list will contain all muxes, enabled and disabled, successfully tuned or not. Each JSON object will represent one mux. You will need to search through this list for the mux on the frequency that you seek and then take note of the UUID associate with that frequency.

Creating the Mux Dump

VLC

If you already have VLC configured as your default m3u application, simply click on the 'Play' icon described above and once VLC starts, press the 'Record' icon in VLC. Manually stop the recording after the required duration has elapsed.

Even if VLC is not your default m3u application, you can still use VLC by opening the 'Media - Open Network Stream' and pasting the link to the mux that you wish to dump as follows:

http://<TVH_IP>:9981/stream/mux/<MUX_UUID>

Hint: If you used the 'Copy link' method described above, you can simply paste that link directly into the 'Network URL' requested by VLC.

Linux Command Line - curl

The following curl command will dump 90 seconds of the specified mux.

curl -m 90 http://<TVH_IP>:9981/stream/mux/<MUX_UUID> > sample_file.ts

Linux Command Line - wget

The following wget command initiate a dump of the specified mux. However, the dump will have to be manually stopped using CTRL-C when the required time has elapsed.

wget http://<TVH_IP>:9981/stream/mux/<MUX_UUID> -O sample_file.ts

Transferring the Mux Dump

A mux dump file is normally too large to email or post to the forum. It is up to the requester and user to agree a method for transferring the file. There are, however, several free peer-to-peer file transfer options to choose from.

Functions to list and manipulate access controls. With the exception of access/entry/userlist, ADMIN privilege is required to use these functions.

access/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Access Entries).

access/entry/create

Creates a new user from a JSON object.

• conf The JSON object describing the new user.

access/entry/grid

Lists users and their privileges. See Common Parameters for details of selection parameters.

{
  "entries": [
    {
      "uuid": "59c300295cbf01e53f096242fd5b8ffc",
      "index": 1,
      "enabled": true,
      "username": "*",
      "prefix": "192.168.1.0/24,127.0.0.1/32",
      "change": [
        "change_rights",
        "change_chrange",
        "change_chtags",
        "change_dvr_configs",
        "change_profiles",
        "change_conn_limit",
        "change_lang",
        "change_lang_ui",
        "change_theme",
        "change_uilevel"
      ],
      "uilevel": -1,
      "uilevel_nochange": -1,
      "lang": "eng_GB",
      "langui": "eng_GB",
      "themeui": "blue",
      "streaming": [
        "basic",
        "advanced",
        "htsp"
      ],
      "profile": [],
      "dvr": [
        "basic",
        "htsp",
        "all",
        "all_rw",
        "failed"
      ],
      "htsp_anonymize": false,
      "dvr_config": [
        "4e3a1e13acd2d5a9c129e7b00f6c986e"
      ],
      "webui": true,
      "admin": false,
      "conn_limit_type": 0,
      "conn_limit": 0,
      "channel_min": 0,
      "channel_max": 0,
      "channel_tag_exclude": false,
      "channel_tag": [],
      "comment": "Wildcard",
      "wizard": false
    },
  ]
}

access/entry/userlist

Outputs a list of usernames. The "*" user and any users with a zero-length name are excluded.

The function is used internally to populate the "Owner" dropdown in Digital Video Recorder -> Finished Recordings -> Edit. It MUST be called by a user without ADMIN privileges, otherwise an empty list is returned.

{
   "entries" : [
      {
         "key" : "myUserName",
         "val" : "myUserName"
      }, ...
   ]
}

ipblock/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> IP Blocking Records).

ipblock/entry/create

Creates a new IP-based access record.

• conf The JSON object describing the access record.

ipblock/entry/grid

Lists IP-block records. See Common Parameters for details of selection parameters.

{
   "entries" : [
      {
         "prefix" : "10.0.0.0/8",
         "enabled" : true,
         "comment" : "Don't allow guests",
         "uuid" : "95a81ed085a1d1a9d8647400a878594d"
      }
   ],
   "total" : 1
}

passwd/entry/class

Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Passwords).

passwd/entry/create

Creates a new password record.

• conf The JSON object describing the record.

passwd/entry/grid

Lists passwords for users. Note that "password" is in clear-text while "password2" is base64-encoded with a static prefix. See Common Parameters for details of selection parameters.

{
   "total" : 1,
   "entries" : [
      {
         "password" : "XxXxXxXx",
         "uuid" : "2fa9ebf7e421a537ac032a6905134137",
         "username" : "xxxxxx",
         "enabled" : true,
         "wizard" : true,
         "password2" : "Base64EncodedPassword"
      }, ...
   ]
}

If authentication for the user is by persistent token (requires TVHeadend > 4.3.1500) the entry has some extra fields:

{
   "total" : 1,
   "entries" : [
      {
         "password" : "",
         "uuid" : "2fa9ebf7e421a537ac032a6905134137",
         "username" : "xxxxxx",
         "enabled" : true,
         "wizard" : true,
         "password2" : "Base64EncodedPassword"
         "auth": [
            "enable"
         ],
         "authcode": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
   ]
}

These examples (and any other use of the API which passes username and password in the URL) will only work if TVheadend is configured to use 'basic' or 'basic and digest' authentication.

curl

Parameters passed to TVH using the GET method must be URI-encoded:

curl 'http://user:pass@localhost:9981/api/epg/events/grid?limit=999&channel=BBC%20ONE'

Alternatively use the POST Method:

curl --data 'limit=999&channel=BBC ONE' 'http://user:pass@localhost:9981/api/epg/events/grid'

To make the output more human-readable, pipe it through json_pp (included in the perl package on many distributions) or jq.

PHP

This simple example lists some details about upcoming timers, sorted in date order. To work through a PHP-enabled web server, the PHP.INI setting "allow_url_fopen" must be ON.

For an example of what can be done with the API in PHP see https://github.com/dave-p/TVHadmin.

Javascript

It is a 'feature' of Javascript that a script can only access remote content from the same source (IP and port number) as the script was loaded from. Hence to call the TVHeadend API from Javascript, the script must be hosted on TVHeadend's built-in web server. To do this, place your script in /usr/share/tvheadend/src/webui/static; it can then be accessed from URL http://user:[email protected]:9981/static/. Note that this is unintended behaviour and may change in the future.

This example carries out the same task as the PHP example above. Your browser will prompt for the TVHeadend user and password.

Python

This example produces the same output as the previous ones.

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

v43

• added isNew field to eventAdd

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

Functions to query the Electronic Program(me) Guide.

epg/events/grid

Query the EPG and optionally apply filters.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

• mode If set to the string now then only events currently playing are listed.

• title A (case-insensitive) string which must appear in the title to be listed.

• fulltext If set to 1 then the title string must match exactly. Default is 0.

• channel The channel to show events from, specified either by channel name or uuid. Must be an exact match to the data from channel/list, otherwise all channels are returned.

• channelTag The (single) channel tag to show events from, specified either by name or uuid. Must be an exact match to the data from channeltag/list, otherwise all tags are returned.

• durationMin Shortest event to be listed (seconds).

• durationMax Longest event to be listed (seconds).

• contentType Integer representing the genre to be listed - see epg/content_type/list.

• filter A JSON object describing the filter(s) to be applied. See Grid Filters for the syntax. String filters can only be applied to the 'channelName', 'title', 'subtitle', 'summary', 'description' and 'extraText' fields.

• sort The key to be sorted by. Default is to sort by 'start'.

• dir If sort is specified, setting 'dir' to 'desc' reverses the sort order

• start First record to be listed from the database, default is 0.

• limit Number of records to list. Default is 50 - use a very large number to get all.

• new If set to 1 then only events marked as 'new' will be included. Default is 0. The EPG source must identify 'new' events for this filter to work.

• cat1, cat2, cat3 XMLTV provides more details of the event category than the OTA EPG, and these parameters can be used to filter by XMLTV category. See Channel-Category.

EPG sources differ in the information which they provide, and there are many more information items possible than are included in the example below. Any items which have no data available will be omitted.

{
   "totalCount" : 18575,
   "entries" : [
      {
         "eventId": 5229882,
         "episodeUri": "crid://www.itv.com/1002485413",
         "serieslinkUri": "crid://www.itv.com/ebshd48582",
         "channelName": "ITV HD",
         "channelUuid": "fd22bbade9093bd1fedf6ce87d75f9a0",
         "channelNumber": "3",
         "start": 1747148400,
         "stop": 1747152000,
         "title": "Tipping Point",
         "summary": "Ben Shephard hosts the quiz show in which three players take on an extraordinary machine in the hope of winning a cash jackpot. [S,HD]",
         "widescreen": 1,
         "subtitled": 1,
         "hd": 1,
         "genre": [
           48
         ],
         "nextEventId": 5229883
         "ageRating" : 9,
         "ratingLabel" : "PG,
         "ratingLabelIcon" : "imagecache/37"
      }, ...
   ]
}

If the event is scheduled to be recorded, these extra items will appear:

      "dvrUuid": "f01433995f76d60f3b32d38fb18f541a",
      "dvrState": "scheduled",

Other possible values for dvrState are "recording", "completed", "completedError", "completedWarning" and "completedRerecord". The 'completed' values can only be present if the recording stopped before the scheduled stop time.

epg/events/alternative

Lists alternative broadcasts of the same event.

• eventId Identifier of the event, eg taken from epg/events/grid.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

The function looks for broadcasts having the same eventId, rather than using event CRIDs. It does not work on UK DVB-T.

This function does not work on TVH versions older than 4.2.4-5 or 4.3-589.

epg/events/related

Lists broadcasts related to the given event.

• eventId Identifier of the event, eg taken from epg/events/grid.

• lang 3-letter ISO639 language code. If not supplied, the language configured for the user is entered; otherwise the system default.

The function looks for events having the same series link ID as the given event, ie part of the same series of broadcasts. It therefore relies on the EPG provider filling in these details.

Note that the series link ID is unique to an individual set of broadcasts; if the series is repeated on a different channel (or at a different time) the series link will be different.

This function does not work on TVH versions older than 4.2.4-5 or 4.3-589.

From version 4.3.1711, if the given event does not have a series link ID, events in the EPG having the same title are returned.

epg/events/load

Lists details of specific event(s).

• eventId Identifier of the event, or a JSON array of event Ids.

The common parameters which apply to other 'load' functions do not work here.

{
   "entries" : [
      {
         "eventId": 5229882,
         "episodeUri": "crid://www.itv.com/1002485413",
         "serieslinkUri": "crid://www.itv.com/ebshd48582",
         "channelName": "ITV HD",
         "channelUuid": "fd22bbade9093bd1fedf6ce87d75f9a0",
         "channelNumber": "3",
         "start": 1747148400,
         "stop": 1747152000,
         "title": "Tipping Point",
         "summary": "Ben Shephard hosts the quiz show in which three players take on an extraordinary machine in the hope of winning a cash jackpot. [S,HD]",
         "widescreen": 1,
         "subtitled": 1,
         "hd": 1,
         "genre": [
           48
         ],
         "nextEventId": 5229883
         "ageRating" : 9,
         "ratingLabel" : "PG,
         "ratingLabelIcon" : "imagecache/37"
      }
   ],
   "totalCount" : 1
}

epg/brand/list

A 'Brand' is a commonly-available show, eg "Simpsons". What constitutes a 'Brand' is up to the EPG provider.

This function was removed in version 4.3.1059.

epg/content_type/list

Lists the Content Type IDs extracted from ETSI EN 300 468 together with their descriptions. The Content Type ID appears in the output of epg/events/grid as "Genre". IDs described as 'Reserved' or 'User Defined' in the specification are given the description of the previous ID instead.

• full If set to 0 (the default) only the broad categories defined by content_nibble_level_1 in the specification are listed. If set to 1 all categories are listed.

{
   "entries" : [
      {
         "val" : "",
         "key" : 0
      },
      {
         "val" : "Movie / Drama",
         "key" : 16
      },
      {
         "key" : 17,
         "val" : "Detective / Thriller"
      }, ...
   ]
}

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 accommodate 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 imdb.com, and [Play program] button. This downloads an 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

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

Manipulate EPG grabbers. ADMIN privilege is required for these functions except for epggrab/channel/list.

epggrab/channel/list

Lists the EPG grabber channels, ie those appearing in Configuration -> Channel / EPG -> EPG Grabber Channels, together with the available option fields and the selections chosen.

epggrab/channel/class

Lists the parameters, descriptions, options and defaults for the GUI screen Configuration -> Channel/EPG -> EPG Grabber Channels.

epggrab/channel/grid

Gives details of the EPG grabber channels, ie from Configuration -> Channel / EPG -> EPG Grabber Channels. See for parameter details.

epggrab/module/list

List EPG Grabber Modules, as shown in the GUI screen Configuration -> Channel/EPG -> EPG Grabber Modules.

epggrab/config/load

Lists the parameters, options, defaults and current settings for the EPG grabber, ie Configuration -> Channel / EPG -> EPG Grabber. See for parameter details.

epggrab/config/save

Updates the EPG Grabber configuration from an object in the same format as provided by .

• node The JSON object.

epggrab/ota/trigger

Queues a run of the OTA EPG grabber.

• trigger Delay in seconds before the run starts. Minimum is one second, maximum is one week.

epggrab/internal/rerun

Run the internal EPG grabbers immediately.

• rerun Not used but must be an integer greater than zero.

Lists statistics of input sources and connections. ADMIN privilege is required for all these functions.

status/connections

Lists currently-connected client devices.

status/subscriptions

Lists currently-active subscriptions.

status/inputs

Lists statistics of input devices.

For DVB-T and DVB-S tuners at least, the signal and SNR values are only non-zero while TVH is actively using the device. Some items may be missing if the device is idle.

The meaning of the statistics is below. Not all input sources provide all of the values.

For signal_scale and snr_scale, a value of 1 indicates that the corresponding signal or SNR reading is relative; 65535 = 100%. A value of 2 indicates the reading is absolute; 1000 = 1dB. A value of 0 indicates that the reading is not available or not valid.

The "pids" data is only present in TVH versions 4.3.1420 and later.

status/inputclrstats

Resets the input counters to zero.

• uuid The uuid of the input device from . More than one uuid can be specified - syntax?

connections/cancel

Disconnects one or more clients.

• id ids of the connections, obtained from . If set to 'all' then all connections are cancelled (new in 4.3.1680).

status/activity

Provide information required for assessing the suitability for entering low-power mode and a suitable time for reawakening. For example, then TVH is used as part of an appliance configuration.

For finer analysis and control, the 'activities' property contains individual scheduling times for the following activities:

• DVR Recordings

• OTA EPG Grabber

• Internal EPG Grabber

• Mux Scheduler

Times are presented as standard Unix epoch values. A value of zero indicates that nothing for that activity type is currently scheduled.

It should be noted that the times provided are strictly from the point of view of TVH internal activities and that the calling program must take into account operating system and hardware boot times when determining the precise time to reawaken the system.

Times are only reported for the EPG grabbers if there are enabled grabbers of that type. Likewise, only enabled mux schedulers are reported.

DVR recordings in progress are also included, therefore, the reported DVR time may be in the past.

The connection and subscription counts are duplications of the summaries provided by the ‘status/connections’ and ‘status/subscriptions’ API calls and are included here in order to provide a single consolidated API call for assessing the suitability for entering low-power mode.

Requires v4.3-2405.