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

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

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.

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

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:

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

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.

Tvheadend setup normally involves the following stages:

1. Ensure tuners are available for use

2. Install Tvheadend software

3. Create a network

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…

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.

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.

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

Lists the available character sets.

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

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

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

1. Update Apt package list

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

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

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

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

1. Update Apt package list

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

for

for

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)

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.

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

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

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

Further details with examples can be found here.

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

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.

Grid parameters

API calls which end in /grid, with the exception of epg/events/grid, 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).

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:

Reply:

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

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

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.

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.

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

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.

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.

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:

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

Usage: tvheadend [OPTIONS]

Generic Options

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

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

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.

WebUI

The WebUI is built on a 'single page application' framework called . 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:

The WebUI appears to be heavily dependent upon the internal idnode

TVH accepts three episode numbering schemes via XMLTV.

• onscreen

• dd_progid

• xmltv_ns

TVHeadEnd only recognises a subset of the total XMLTV schema.

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

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

(yyyy-mm-dd)

Title of the PR ( yyyy-mm-dd)

Title of another PR ( yyyy-mm-dd)

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.

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 for more information.

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.

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.

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.

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.

Functions controlling the configuration of the Image Cache. ADMIN privilege is required for all of these functions.

Before version 4.3.1660, these functions were only available if Image Cache support was included at compile time.

imagecache/config/load

Lists the current values, defaults and descriptions of the parameters used to configure the image cache.

imagecache/config/save

TODO

imagecache/config/clean

Delete all files from the image cache and re-load, in the same way as Configuration -> General -> Image Cache -> Clean Image (icon) Cache in the GUI.

• clean Required parameter, must be 1 - the value is not used.

imagecache/config/trigger

Trigger a re-load of the image cache, in the same way as Configuration -> General -> Image Cache -> Re-fetch Images in the GUI.

• trigger Required parameter, must be 1 - the value is not used.

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 development and debugging purposes.

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:

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.

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.

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

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.

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: HTSMSG Binary Format.

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

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.

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.

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.

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.

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

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.

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

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.

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

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

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

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.

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.

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:

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

• filter A JSON object describing the filter(s) to be applied. See 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 .

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.

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

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 .

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

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

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

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

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

v19..v20

• dvrEntry structures

  • added subscriptionError, streamErrors, dataErrors fields

  • added subtitle fields

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

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)

v15..v16

• added getProfiles, getDvrConfigs methods

• removed getCodecs methods

• extended subscribe method

v14..v15

• extended channelAdd, channelUpdate server-to-client methods

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

• extended getChannel method

v13..v14