Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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
Tvheadend runs on Intel compatible i386/x86_64 CPUs and ARM SoC arm/aarch64 processor. 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.
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.
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.
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
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.
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.
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.
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.
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 can run isolated from other host processes in a Docker container. The official Tvheadend container can be pulled from the GitHub container repo:
There is also an established community container from the linuxserver.io team:
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.
* IMPORTANT *
Please do not be concerned about your English language skills when contributing changes to our documentation. It is easier for a native speaker to merge your content and then make corrections than to write everything themselves. And if there is no obvious place to put content (the current structure is sparse and incomplete) please create pages under the section. It can be merged and moved later as the documentation structure evolves.
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!
Community created and supported Tvheadend packages for Synology and QNAP users are available from community package repositories. See below for more information:
https://synocommunity.com/package/tvheadend
https://www.myqnap.org/product/tvheadend
Please note that General support issues with Tvheadend are welcome in our forum but installation issues with these packages are best directed to NAS vendor forums.
Tvheadend setup normally involves the following stages:
Ensure tuners are available for use
Install Tvheadend software
Create a network
Associate the network with tuners
Add manual muxes - if needed
Scan for services
Map services to channels
Watch TV channels!
Tvheadend binary packages can be downloaded from https://apt.tvheadend.org or you can configure a local package repo to install and update from by running the following shell commands:
Run the following shell command to setup a local apt
repo:
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.
Please refer to development documentation on compiling Tvheadend from source
Tvheadend is operated primarily through a tabbed web interface. There are some basic navigation concepts that will help you use it effectively:
The web interface uses tabs with similar functions grouped together. Tabs for major configuration functions are located on the top row, with tabs for configuration items related to the currently selected major function located on the row below. In some cases a third row of config options will be shown.
Most tabs have display a menu bar with Add, Save, Edit, Undo functions and a spreadsheet-like grid below. Grid items are frequently editable.
Most configuration items are in this grid. However, some item-specific configuraiton is accessed through the Add and Edit dialog boxes. For example: the main network configuration tab grid covers parameters common to DVB-S, DVB-T, DVB-C and IPTV networks, but configuration like FEC rolloff or mux URL is only present in dialogs for networks that need these values.
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.
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.
It helps to understand the basic software concepts for Tvheadend:
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.
Network is a software definition of your carrier network that tells tuner hardware how and where to look for a signal, e.g. the network defines a such as DVB-T or DVB-S2, and how it is scanned, where the DVB-S satellite is in orbit, and similar.
Muxes are channel frequencies that transmit multiple digital channel signals in the radio frequency space of a single analogue channel. Digitial signals are multiplexed (muxed) together to allow more channels to be broadcast.
Services are the individual data streams on a Mux. They can be TV or Radio programmes, or they can provide data services such as digital teletext or catch-up IPTV services.
Channels are mapped against Services. Channels are what client software access when users think “I’d like to watch BBC One now, please”.
Each configuration component supports many-to-many relationships: meaning one component can be related to multiple components of the next type, and vice versa, e.g. one tuner can support multiple networks and one network can exist on multiple tuners.
The following diagram explains the relationship between these components:
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 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:
The following functions are available:
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.
The following buttons are also available:
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).
If you click on a single event, a popup displays detailed information. You can schedule the event for recording by clicking on the [Record program] button. If the EPG provider includes series-link data the [Record series] button allows you to schedule recording of all entries in the series.
For events without any series link information, an [Autorec] button will be provided to create a pseudo-series link using the autorec feature.
When scheduling recording you can choose the DVR profile used for the recording or autorec rule. This will normally show (default) but you can define different profiles in the Configuration -> Recording -> Digital Video Recorder tab. Profiles allow you to set, e.g. post-broadcast padding to accomodate a channel that always runs late, or a post-processing command to strip adverts from recordings made from a commercial channel.
The [Search IMDB] button runs a search against the programme title on on imdb.com, and [Play program] button. This downloads am XSPT or M3U playlist file (depending on startup options) and if your Operating System is correctly configured this will launch an appropriate player application. If not you will need to manually open (double-click) the playlist file to start watching.
Clock on the [X] window button (top-right) to close the popup. The popup is not modal and will remain open and visible. You can open multiple detailed information popups at the same time.
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.
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.
Filter | Function |
---|---|
Filter Range | Example Purpose |
---|---|
Button | Function |
---|---|
Icon | Description |
---|---|
Browser | MPEG-TS | MPEG-PS | Matroska | WebM |
---|---|---|---|---|
Browser | MPEG2 | H.264 | VP8 |
---|---|---|---|
Browser | MPEG2 | DD (AC3) | AAC | Vorbis |
---|---|---|---|---|
Search Title
Display events that match the given title. The filter uses case-insensitive regular expressions. If you don’t know what a regular expression is, this simply means that you can type just parts of the title and filter on that - there’s no need for full, exact matching. If the fulltext checkbox is checked, the title text is matched against title, subtitle, summary and description.
Filter Channel
Display events from the selected channel. Channels in the drop down are ordered by name and can be filtered (by name) by typing in the box.
Filter Tag
Display events from channels which are included in the selected tag. Tags are used for grouping channels together - such as ‘Radio’ or ‘HDTV’ and are configured by the admin. Start typing a tag name to filter the list.
Filter Content Type
Display events that match the given content type tag. Most DVB networks classify their events into content groups. This field allows you to filter based on content type (e.g. “Sports” or “Game Show”). Supported tags are determined by your broadcaster. Again, simply start typing to filter the entries if you have a long list to choose from.
Filter Duration
Display events that fall between the given minimum and maximum durations. This allows you to filter for or against, say, a daily broadcast and a weekly omnibus edition of a programme, or only look for short news bulletins and not the 24-hour rolling broadcasts.
00:00:01 to 00:15:00
Very short news bulletins, children’s programmes, etc.
00:15:01 to 00:30:00
Short programmes, e.g. daily soap operas
00:30:01 to 01:30:00
Medium-length programmes, e.g. documentaries
01:30:01 to 03:00:00
Longer programmes, e.g. films
03:00:00 to no maximum
Very long programmes, e.g. major sporting events
Reset All
Clears all search filters
Watch TV
Launches Live TV via HTML5 video
Create Autorec
Creates an auto-recording rule based on the current filter criteria
Help
Display this help page
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
.
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.
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.
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.
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.
The programme is scheduled for recording
The programme is currently recording
Click to call up more detailed information about an event
Google Chrome
Mozilla Firefox
Google Chrome
Mozilla Firefox
Google Chrome
Mozilla Firefox
This tab shows all finished recordings:
The following functions are available:
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…
Button | Function |
---|---|
Icon | Description |
---|---|
Delete
Delete the selected finished recording records and associated files. You will be prompted for confirmation.
Download
Download the selected finished recordings to local disk. You will be prompted to select the path for the saved file(s).
Help
Display this help page.
If you prefer to build Tvheadend from source, tarballs and instructions are on GitHub
The recording has completed
Click to display detailed information about the selected recording
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:
PyHTSP (This is a demo client and is WIP, it has limited functionality).
The following options can be passed to tvheadend to provide detailed debugging information while the application is running. Trace debugging has to be enabled at build time with--enable-debugging
and can be specified in a CLI command, e.g. tvheadend -u hts -g video --trace <module>
or in the web interface (Configuration -> Debugging).
Multiple options can be used, e.g. –-trace cwc,dvr,linuxdvb
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.
There is a normal RPC way of doing things. I.e. the client sends a request and the server responds with a reply. All the RPC methods are listed below as the 'Client to Server' methods. Apart from all message fields listed within each message type the client can add an additional field:
RPC request extra fields:
The followings field should be used by the client to match the reply with the request. All replies are guaranteed to arrive in the same order as the requests. Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.
RPC reply extra fields:
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).
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:
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.
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.
Message Structure
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.
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.
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.
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.
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.
Datalength should be the length of the binary object. Data is the binary object itself.
Name | ID | Description |
---|---|---|
Map
1
Sub message of type map
S64
2
Signed 64bit integer
Str
3
UTF-8 encoded string
Bin
4
Binary blob
List
5
Sub message of type list
Dbl
6
Double precision floating point
Bool
7
Boolean
UUID
8
64 bit UUID in binary format
Length
4 byte integer
Total length of message (not including this length field itself)
Body
HTSMSG-Field * N
Fields in the root body
Type
1 byte integer
Type of field (see field type IDs above)
Namelength
1 byte integer
Length of name of field. If a field is part of a list message this must be 0
Datalength
4 byte integer
Length of field data
Name
N bytes
Field name, length as specified by Namelength
Data
N bytes
Field payload, for details see below
Used to identify the client toward the server and to get the session challenge used to hash passwords into digests. The client can request a different version of the HTSP protocol with this method. If no 'hello' message is sent the server assumes latest version is to be used.
Client/Server should select lowest common version, if this is not possible connection should be terminated.
Request message fields:
Reply message fields:
Note: possible values for servercapability[]:
This can be used to issue authentication without doing anything else. If no privileges are gained it will return with 'noaccess' set to 1.
Request message fields:
Reply message fields:
(Added in version 24)
This is a proxy to HTTP API.
Request message fields:
Reply message fields:
Also see: JSON API and Proxy Examples.
(Added in version 3)
Return diskspace status from Tvheadend's PVR storage
Request message fields:
Reply message fields:
Also see: JSON API 'comet/poll'.
(Added in version 3)
Return system time on the server.
Request message fields:
Reply message fields:
When this is enabled the client will get continuous updates from the server about added, update or deleted channels, tags, dvr and epg entries.
An interactive application that presents the user with information about these things should probably enable this and the implement the various server to client methods.
Request message fields:
Reply message fields:
Once the reply as been sent the initial data set will be provided, and then updates will arrive asynchronously after that. The initial data dump is sent using the following messages:
(Added in version 14)
Request information about the given channel.
Request message fields:
Reply message fields:
Also see: JSON API Channel
Request information about the given event. An event typically corresponds to a program on a channel.
The language field in the request allows preference for languages to be requested for the various string fields.
Request message fields:
Reply message fields:
Also see: JSON API EPG
(Added in version 4)
Request information about a set of events. If no options are specified the entire EPG database will be returned.
Request message fields:
Reply message fields:
(Added in version 4)
Query the EPG (event titles) and optionally restrict to channel/tag/content type.
Request message fields:
Reply message fields:
if full == 1
else
Get detailed EPG Object info.
Request message fields:
Reply message fields:
(Added in version 16)
Return a list of DVR configurations.
Reply message fields:
Message fields:
Also see: JSON API DVR
(Added in version 4)
Create a new DVR entry. Either eventId or channelId, start and stop must be specified.
Request message fields:
Reply message fields:
(Added in version 5)
Update an existing DVR entry.
Request message fields:
Reply message fields:
(Added in version 5)
Cancel an existing recording, but don't remove the entry from the database.
Request message fields:
Reply message fields:
(Added in version 4)
Delete an existing DVR entry from the database.
Request message fields:
Reply message fields:
(Added in version 12)
Get DVR cutpoints.
Request message fields:
Reply message fields:
Cutpoint fields:
(Added in version 13)
Create a new Autorec DVR entry. Title must be specified.
Request message fields:
Reply message fields:
(Added in version 13)
Delete an existing autorec DVR entry from the database.
Request message fields:
Reply message fields:
(Added in version 18)
Create a new Timerec DVR entry. Title must be specified.
Request message fields:
Reply message fields:
(Added in version 18)
Delete an existing timerec DVR entry from the database.
Request message fields:
Reply message fields:
(Added in version 5)
Get a ticket to allow access to a channel or recording via HTTP
Request message fields:
Reply message fields:
Request subscription to the given channel.
Request message fields:
Reply message fields:
Stop a subscription.
Request message fields:
Reply message fields:
(Added in version 5)
Change the weight of an existing subscription
Request message fields:
Reply message fields:
(Added in version 9)
Skip a timeshift enabled subscription. The response will be asynchronous subscriptionSkip().
Request message fields:
Reply message fields:
(Added in version 9)
Synonym for subscriptionSkip
(Added in version 9)
Set the playback speed for the subscription. The response will be asynchronous subscriptionSpeed().
Request message fields:
Reply message fields:
(Added in version 9)
Return a timeshifted session to live. Reply will be asynchronous subscriptionSkip().
Request message fields:
Reply message fields:
(Added in version 12)
Enable or disable specified streams by index.
Request message fields:
Reply message fields:
(Added in version 16)
Return a list of stream profiles (configurations).
Reply message fields:
Message fields:
(Added in version 11, Removed in version 16)
Return a list of encoders (codecs).
Reply message fields:
(Added in version 8)
Open a file within the Tvheadend file system. This is now the preferred method (in place of HTTP) for accessing recordings.
Accessing recordings via HTSP will overcome the limitations of standard HTTP streaming which cannot handle both skipping and growing files (i.e. in-progress recordings) at the same time.
Request message fields:
Valid file paths:
Reply message fields:
(Added in version 8)
Read data from a file.
Request message fields:
Reply message fields:
(Added in version 8)
Close an opened file.
Request message fields:
Reply message fields:
(Added in version 8)
Get status of a file.
Request message fields:
Reply message fields:
(Added in version 8)
Seek to position in a file.
Request message fields:
Note: valid values for whence
Reply message fields:
added ratingLabel to EPG & DVR entries
added ratingIcon to EPG & DVR entries
added ageRating to DVR entries
added descrambleInfo (not yet documented below)
extended addDvrEntry, updateDvrEntry, dvrEntryAdd method
added enabled
extended getSysTime
added gmtoffset
extended updateDvrEntry method
added channelId
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
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
autorec/timerec structures
added directory field (forced output directory)
added enabled field
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
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
added getProfiles, getDvrConfigs methods
removed getCodecs methods
extended subscribe method
add profile field
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'
added getChannel method
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
added subscriptionFilterStream method
added getDvrCutpoints method
added audio_type in the subscriptionStart server-to-client method
added getCodecs method
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.
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.
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.
API
Syntax SummaryRequest:
Reply:
To execute the HTTP API command:
http://TVH:9981/api/channel/grid
Set the path
field to channel/grid
and send the request. The args
field is not required.
The response will be a HTSP map
containing an element named response
. This element will be a map
containing the the JSON response presented as HTSP elements.
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
.
A new channel has been created on the server.
Message fields:
Service fields:
Same as channelAdd, but all fields (except channelId) are optional.
A channel has been deleted on the server.
Message fields:
A new tag has been created on the server.
Message fields:
Same as tagAdd, but all fields (except tagId) are optional.
A tag has been deleted from the server.
Message fields:
(Added in version 4)
A new recording has been created on the server.
Message fields:
Valid values for state:
Valid values for subscriptionError:
Message fields:
(Added in version 4)
A recording has been deleted from the server.
Message fields:
(Added in version 13)
A new autorec recording has been created on the server.
Message fields:
(Added in version 13)
Message fields:
Message fields:
(Added in version 18)
A new autorec recording has been created on the server.
Message fields:
(Added in version 18)
Message fields:
(Added in version 18)
Message fields:
(Added in version 6)
Message fields:
*contentType previously had the major DVB category in the bottom 4 bits, however in v6 this has been changed to properly match DVB, so top 4 bits as major category and bottom 4 bits has sub-category. Clients requesting v5 or lower will get the old output.
(Added in version 6)
Message fields:
(Added in version 6)
Message fields:
(Added in version 2)
Sent after all the initial metadata has been sent when session has been set to async mode.
Message fields:
Asynchronous message output when a new subscription is successfully started.
Message fields:
Stream message fields:
Sourceinfo message fields:
Video Stream types:
Audio Stream types:
Subtitle Stream types:
Notifies client about the grace timeout (timeout for stream activation). It can be issues multiple times. For example a configuration with satellite rotors requires more than 120 seconds to tune, so users should be notified..
Message fields:
A subscription has been stopped.
Message fields:
Valid values for subscriptionError:
(Added in version 9)
A subscription has been skipped.
Message fields:
(Added in version 9)
A subscription's playback speed has changed.
This can happen even without a speed request, should playback reach either end of the buffer.
Message fields:
Subscription status update.
Message fields:
Valid values for subscriptionError:
The queueStatus message is sent every second during normal data delivery.
The transmit scheduler have different drop thresholds for different frame types.
If congestion occurs it will favor dropping B-frames before P-frames before I-frames. All audio is recognized as I-frames.
Message fields:
The signalStatus message is sent every second during normal data delivery.
The optional fields may not have been implemented or may not be supported by the active adapter.
Message fields:
Provide status every second about the timeshift buffer.
Message fields:
Streaming data.
Message fields:
Also see: .
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
that contains another map
named conf
that contains another map
with the required JSON data represented as HTSP elements.
Functions to list and manipulate access controls. With the exception of access/entry/userlist, ADMIN privilege is required to use these functions.
Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Access Entries).
Creates a new user from a JSON object.
conf
The JSON object describing the new user.
Lists users and their privileges. See Common Parameters for details of selection parameters.
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.
Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> IP Blocking Records).
Creates a new IP-based access record.
conf
The JSON object describing the access record.
Lists IP-block records. See Common Parameters for details of selection parameters.
Lists the text strings, options and defaults used when configuring access controls within the TVH GUI (ie Configuration -> Users -> Passwords).
Creates a new password record.
conf
The JSON object describing the record.
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.
If authentication for the user is by persistent token (requires TVHeadend > 4.3.1500) the entry has some extra fields:
ADMIN privilege is required for all of these functions.
Lists the text strings, options and defaults used when configuring bouquets within TVH (ie Configuration -> Channel/EPG -> Bouquets).
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.
Removes the link from a channel to the bouquet that it is part of.
uuid
uuid(s) of channels to detach.
Lists details of bouquets. For details of the parameters and selection criteria which can be applied, see Common Parameters.
Lists names and bouquets. The list excerpted below is coded into tvheadend.
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.
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.
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.
API calls which end in /load
, with the exception of epg/events/load, 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.
Lists the text strings, options and defaults used when configuring Conditional Access devices within TVH (ie Configuration -> CAs -> Add).
Lists the text strings, options and defaults used when configuring Conditional Access within TVH (ie Configuration -> CAs).
Create a new CA instance.
class
Name of the class to create, ie one of the classes listed by caclient/builders.
conf
A JSON object describing the new device.
List CA clients.
ADMIN privilege is required for all of these functions except codec_profile/list.
Lists available codecs and their properties. This is a very verbose list.
Lists the text strings, options and defaults used when configuring codec profiles.
Add a new codec profile.
class
The name of the codec profile.
conf
A JSON object describing the codec profile.
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.
Lists the text strings, options and defaults used when configuring channels within TVH (ie Configuration -> Channel/EPG -> Channel -> Add).
Creates a new channel. Requires ADMIN privilege.
conf
A JSON object containing details of the new channel.
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.
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.
Lists the text strings, options and defaults used when configuring channels within TVH (ie Configuration -> Channel/EPG -> Channel Tags -> Add).
Creates a new channel tag. Requires ADMIN privilege.
conf
A JSON object containing details of the new channel tag.
Lists the names and uuids of all channel tags.
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.
Lists details of channels. For details of the parameters and selection criteria which can be applied, see .
Lists details of channel tags. For details of the parameters and selection criteria which can be applied, see .
ADMIN privilege is required for all of these functions except 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.
Lists the details, descriptions, defaults and current values of the items in the GUI screen Configuration -> General -> Base. See Common Parameters for details of selection parameters.
Untested. Updates the server from an object in the format produced by config/load.
node
The JSON object.
Lists the details and descriptions of items in the TVH GUI screen Configuration -> Debugging -> Memory Information Entries.
Lists details of in-memory objects. See Common Parameters for details of selection parameters.
Lists all of the api functions supported by the server.
Lists information about the server including the software version number.
This section includes functions to manipulate recorder objects; timers, autorecs and recordings. Unless noted otherwise, RECORDER privilege is required for all these functions - the 'Basic' tick-box in the 'Video Recorder' drop-down on the Access Entry screen. Other tick-boxes will be needed for some functions.
Lists the text strings, options and defaults used when configuring the DVR capability within TVH (ie Configuration -> Recording). Requires either RECORDER or ADMIN privilege.
Lists the configuration sets available for the TVH server together with their options. Configurations are identified by their name
parameter; the default config has the name blank. Requires either RECORDER or ADMIN privilege.
Creates a new configuration set. Requires ADMIN privilege.
name
configuration name. Must be supplied and cannot be blank
conf
parameter set, passed as a JSON object
Lists the text strings, options and defaults used when editing an upcoming recording.
Lists all of the recordings that TVH knows about, ie it combines the output of grid_upcoming
, grid_finished
, grid_failed
and grid_removed
. Use the status
parameter to tell them apart.
See Grid Parameters for parameter details, and note the default is to return only the first 50 items.
Lists all of the currently-scheduled recordings. See Grid Parameters for parameter details, and note the default is to return only the first 50 items.
duplicates
Set to 0 to exclude duplicate timers. Default is 1.
The data is derived from the EPG when the timer was scheduled. From version 4.3.1013 the item "disp_extratext" is included to deal with the inconsistent use of "subtitle" and "summary" fields by broadcasters.
The values of start_real
and stop_real
take into account the recorder padding and warm-up time currently set.
The value of rating_label_uuid
points to a current parental rating label record.
Lists recordings which have completed and which are still in the TVH logs. See Grid Parameters for parameter details, and note the default is to return only the first 50 items.
The values of start_real
and stop_real
take into account the recorder padding and warm-up time currently set - not the values which were set when the recording was made. If this is a segmented recording (a programme split into two or more parts with for example a news bulletin in between) the value of stop_real
is the end time of the final segment, while stop
is the end time of he first segment.
Because legislation can change over time, the value of rating_label_uuid
is blank for finished DVR entries, the 'saved' tags should be used instead.
Lists failed recordings. See Grid Parameters for parameter details.
If you merge the 'failed' and 'completed' recordings into a single list, the only way to tell which list the entries originally came from is by using the status
field.
Lists removed recordings. See Grid Parameters for parameter details.
Under some circumstances an unsuccessful recording may appear here rather than under failed recordings. For example when EIT-based accurate recording is being used and the 'running' status is never received.
If TVH is configured to delete the log record when a recording is deleted this function will not return them.
Creates a new timer from a JSON object.
conf
The JSON object describing the timer. Items not specified are derived from the default profile of the user. An example of the minimum useful JSON is shown below.
The function returns the uuid of the created timer on success.
It is also possible using this function to add a file created elsewhere into the TVH database as a completed recording. Items needed in the JSON are:
It is important that the start and stop times are in the past, otherwise TVH will try to create a timer to record the event. (Thanks to "ullix tv" for this information.) Also note that the ability to add a pre-recorded file is unintended behaviour - see Caution.
Creates a new timer using details from the EPG. Input parameters are:
config_uuid
this is the uuid
parameter from the output of dvr/config/grid
event_id
this is the eventId
parameter for the event, taken from epg/events/grid
These functions provide the same capability as the Re-record button in Digital Video Recorder -> Finished Recordings. "Allow" sets the recording to be re-done, "deny" cancels a scheduled rerecording, "toggle" reverses the rerecord state.
uuid
the uuid
of the finished or failed recording, or a JSON object containing an array of uuids.
Gracefully stops a running recording.
uuid
The uuid
value from the timer's entry in dvr/entry/grid.
Deletes a timer or aborts a running recording.
uuid
The uuid
value from the timer's entry in dvr/entry/grid.
If the timer is running, the recording is kept on disk but classified as a 'failed' recording.
NOTE To delete a series use idnode/delete, passing parameter uuid
from the entry in dvr/timerec/grid. As with the UI, deleting a series deletes all pending timers for that series.
These three functions affect the "previously recorded" status of a timer. If set, either directly or via a call to the toggle function, the timer is marked as completed and the file flagged as deleted. If unset, a new timer is created.
These functions provide the same capability as the Previously Recorded button in Digital Video Recorder -> Upcoming/Current Recordings. It can be used to 'hide' re-runs to prevent them being re-recorded.
Removes a completed recording from storage.
uuid
The recording's uuid
value from dvr/entry/grid_finished.
Informs TVH that a recording has been relocated (by external means) within the filesystem. Requires ADMIN privilege.
src
The original full path to the file
dst
The new full path to the file
Move a finished recording entry to the "Finished Recordings" category, presumably from "Failed Recordings". The actual file is not moved.
uuid
The uuid
of the entry, or an array of entries passed as a JSON object.
Move a finished recording entry to the "Failed Recordings" category, presumably from "Finished Recordings". The actual file is not moved.
uuid
The uuid
of the entry, or an array of entries passed as a JSON object.
Lists the text strings, options and defaults used when creating or editing a series timer.
Lists autorecs (series timers). See Grid Parameters for parameter details.
Create a new series timer by specifying search parameters. To create a timer using CRIDs use dvr/autorec/create_by_series.
conf
A JSON object specifying the selection parameters for the timer.
config_uuid
The uuid
parameter from the output of dvr/config/grid. Parameter config_name
may be passed instead.
Creates a new series timer using CRIDs. Input parameters are:
config_uuid
The uuid
parameter from the output of dvr/config/grid
event_id
The eventId
parameter for one event in the series, taken from epg/events/grid
NOTE To delete a series use idnode/delete, passing parameter uuid
from the entry in dvr/autorec/grid. As with the UI, deleting a series deletes all pending timers for that series.
Lists the text strings, options and defaults used when creating or editing a time-based recording.
Lists time-based recordings. See Grid Parameters for parameter details.
Create a new time-based timer.
conf
A JSON object specifying the selection parameters for the timer.
A JSON object is returned containing the UUID of the timerec.
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.
Lists the descriptions, options and defaults for configuring the chosen type of filter, ie Configuration -> Stream -> Stream Filters -> {chosen type} -> Add.
Creates a new filter of the chosen type. ADMIN privilege is required.
conf
A JSON object describing the filter.
Functions to query the Electronic Program(me) Guide.
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.
durationMin
Shortest event to be listed (seconds).
durationMax
Longest event to be listed (seconds).
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.
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.
Lists alternative broadcasts of the same event.
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.
Lists broadcasts related to the given event.
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.
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.
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.
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.
Manipulate EPG grabbers. ADMIN privilege is required for these functions except for 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.
Lists the parameters, descriptions, options and defaults for the GUI screen Configuration -> Channel/EPG -> EPG Grabber Channels.
List EPG Grabber Modules, as shown in the GUI screen Configuration -> Channel/EPG -> EPG Grabber Modules.
node
The JSON object.
Queues a run of the OTA EPG grabber.
trigger
Delay in seconds before the run starts. Minimum is one second, maximum is one week.
Run the internal EPG grabbers immediately.
rerun
Not used but must be an integer greater than zero.
Returns the parameters of the defined filters of the chosen type. The usual selection options are available, see
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.
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.
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 .
eventId
Identifier of the event, eg taken from .
eventId
Identifier of the event, eg taken from .
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.
Gives details of the EPG grabber channels, ie from Configuration -> Channel / EPG -> EPG Grabber Channels. See for parameter details.
Lists the parameters, options, defaults and current settings for the EPG grabber, ie Configuration -> Channel / EPG -> EPG Grabber. See for parameter details.
Updates the EPG Grabber configuration from an object in the same format as provided by .
Lists the available character sets.
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.
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).
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.
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'.
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.
Delete one or more records.
uuid
The uuid (or a JSON-formatted list) of the record(s) to be deleted.
List details of input devices. ADMIN privilege is required for these functions.
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.
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.
Functions relating to DVB networks, multiplexes and services. Further service functions can be found in the Service section. ADMIN privilege is required for all these functions.
Lists the network(s) associated with a given input device.
uuid
The uuid of the specific hardware device.
Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Networks).
Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Network -> Add).
Create a new network.
conf
Required. A JSON object containing the settings for this network.
Lists the text strings, options and defaults used when editing a multiplex using Configuration -> DVB Inputs -> Muxes -> Edit.
Create a mux for an existing network.
uuid
The uuid of the network containing this mux.
conf
A JSON object containing the settings for this mux. The contents will depend on the type of network.
A JSON object containing the UUID of the new mux is returned.
Triggers a scan of the requested network(s).
uuid
uuid(s) of the network(s) to scan. More than one may be given; they will be scanned in sequence.
hidemode
If set to all
, only enabled multiplexes are listed. The default is to show all multiplexes.
Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Muxes).
Lists available mpegts services. The standard parameters listed in Grid Parameters may be used.
hidemode
The default is to show only services where the multiplex is enabled and the service has been verified. Setting this parameter to all
also hides services which are not enabled, setting it to none
shows all services.
dvb_servicetype
can be used to determine what kind of service is being broadcast. The possibilities are:
Radio: 0x02
SD TV: 0x01, 0x16, 0x17, 0x18, 0x80, 0x96, 0xa8, 0xd3
HD TV: 0x11, 0x19 - 0x1e, 0x91, 0xa0, 0xa4, 0xa6
UHDTV: 0x1f
Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Services).
Lists the text strings, options and defaults used when configuring the DVB capability within TVH (ie Configuration -> DVB Inputs -> Mux Schedulers).
Lists orbital positions and the satellites occupying them. The list is distributed with tvheadend; satellite reception is not necessary to use this API.
Lists the available frequency scan tables.
type
One of 'dvb-s', 'dvb-t', 'dvb-c', 'atsc-t', 'atsc-c', 'isdb-t'.
satpos
For dvb-s, the satellite position in degrees multiplied by 10 with East positive (so 28.2E is written as 282). The position must be accurate within +/- 0.2 degrees.
This function requires the dvb-scan files to be present on the server. They are installed by default (in /usr/share/tvheadend/data/) but are omitted if configure argument '--disable-dvbscan' is used. Distributions may also choose to package them separately.
To find the input device uuid, use hardware/tree?uuid=root
, then take the id
value from the output and use it as the value of uuid
in another call to . From the output of this function select the id
corresponding to the specific front-end device required.
Lists available networks. The standard parameters listed in may be used. The items returned depend on the type of network - terrestrial, satellite, IPTV etc.
class
Required. The class name matching the class
item obtained from a call to .
uuid
The value of network_uuid
from a call to .
Lists available multiplexes. The standard parameters listed in may be used.
List the entries as found under Configuration -> DVB Inputs -> Mux Schedulers. The standard parameters listed in may be used.
Untested. Create a mux schedule, presumably from a structure similar to that from .
Functions to query and manipulate the list of parental rating labels ('G', 'M', 'PG', etc).
Lists the text strings, options and defaults used when configuring parental rating labels within TVH (ie Configuration -> Channel/EPG -> Rating Labels -> Add).
Creates a new parental rating label. Requires ADMIN privilege.
conf
A JSON object containing details of the new parental rating label.
Lists details of parental rating labels. For details of the parameters and selection criteria which can be applied, see Grid Parameters.
Lists the names and uuids of all known parental rating labels.
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.
ADMIN privilege is required to use these functions except for 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 raw/export, passing it the stream profile's uuid.
Lists the options, defaults and descriptions of configuration parameters (Configuration -> Stream -> Stream Profiles) in the GUI.
Lists the options, defaults and descriptions of configuration parameters when adding a new stream profile (Configuration -> Stream -> Stream Profiles -> Add) in the GUI.
Create a new stream profile.
class
conf
A JSON object containing details of the new profile.
Lists statistics of input sources and connections. ADMIN privilege is required for all these functions.
Lists currently-connected client devices.
Lists currently-active subscriptions.
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.
Resets the input counters to zero.
Disconnects one or more clients.
uuid
The uuid of the input device from . More than one uuid can be specified - syntax?
id
ids of the connections, obtained from . If set to 'all' then all connections are cancelled (new in 4.3.1680).
ber | Bit Error Rate |
bps | Bandwidth (bits/second) |
cc | Continuity Errors |
ec_bit | Bit Error Count |
ec_block | Block Error Count |
pids | List of pids present in the stream |
signal | Signal Strength (see below) |
signal_scale | See below |
snr | Signal/Noise Ratio (see below) |
snr_scale | See below |
stream | Stream (multiplex) name |
subs | Subscribers |
tc_bit | Total Bit Error Count |
tc_block | Total Block Error Count |
te | Transport Errors |
unc | Uncorrected Blocks |
weight | Weight |
Although no special privilege is needed to use these functions, access control is applied at the inode database level.
Returns a list of all data classes together with readable titles. Requires version 4.3-406 or later.
class
One of the class names returned by classes.
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.
node
A JSON object or array of objects.
Objects being imported must have a uuid and must already exist in the database.
ADMIN privilege is required to use all of these functions.
Lists the descriptions, options, current values and defaults of the GUI screen Configuration -> DVB Inputs -> Services. -> Map Services.
Further API functions for manipulating DVB services are in the MPEGts section.
Untested. Set the Service Mapper options.
node
Unknown, possibly the value of class
.
Stops a running service mapper operation.
Provides the same output as Status -> Service Mapper in the TVH GUI.
Lists available services. "Available" services includes those which are disabled or encrypted.
enum
If set to 1 (as an integer without quotes) a short-form list is output containing each service's uuid and name. If set to 0 (the default) a verbose list is generated.
list
If enum
is not 1 this parameter selects which items in the params
array are to be output, based on the value of the 'id' field. Multiple ids can be selected, separated by commas, colons or semicolons. A '-' in front of an id deselects that item (and implicitly selects all others).
raw/export?class=service
provides a simpler version of the same information (but including the streams data), however the API call is about 50% slower.
Lists the streams comprising the service.
uuid
uuid of the service. This parameter is mandatory; it is not possible to list all services.
Remove services which have not been seen recently. This call carries out the same action as Configuration -> DVB Inputs -> Services -> Maintenance in the TVH GUI.
days
The number of unseen days before deletion. The default is 7 days, the minimum is 5 days.
type
If set to pat
the action is the same as "Remove unseen services (PAT/SDT)" in the GUI. Otherwise the action is the same as "Remove all unseen services".
An empty JSON object is always returned.
ADMIN privilege is required to use these functions.
Lists the descriptions, options, defaults and current settings for configuring the SAT>IP server capability - see Configuration -> General -> SAT>IP server.
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 these functions.
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.
Untested. Updates the server from an object in the format produced by tvhlog/config/load.
node
The JSON object.
List the subsystems available for trace and debug operations.
Also see Debugging / Trace options and CLI / Debug Options.
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 2014, the id
field is informational only. It is provided to facilitate future API development.
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.
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.
The example below creates a WebSocket connection to the Tvheadend server and listens for updates.
Tvheadend transmits messages on the Websocket interface asynchronously, when either a 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.
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.
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.
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.
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:pass@your.server: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.
This example produces the same output as the previous ones.
This section describes other functions which can be accessed via HTTP. They are not part of the HTTP API and so are not preceded by 'api'.
Unless otherwise stated no special privilege is needed to use these functions.
Returns a JSON object containing data used by the Tvheadend UI, including the disk space utilisation.
The "freediskspace" and "totaldiskspace" figures relate to the disk partition holding the recorder Storage Path, "useddiskspace" is the total size of all files stored below that point. These figures may not give the actual storage situation if there are multiple storage devices and mount points.
Downloads a previously-recorded file. Called with the UUID of the recording. Requires appropriate privilege (DVR or streaming).
Flushes the contents of the EPG to disk.
Used by simple.html.
Downloads an icon file. The filename is hard-coded in the source; on installation it is usually placed at /usr/share/tvheadend/src/webui/static/img/logo.png
.
Outputs an image from the image cache. Requires streaming, recording or web interface privilege.
Used to download help files.
Available on version 4.3-2124 and later. Provides a simple way to check that the server is alive. No authentication is needed to use this function.
This function acts as a front-end to the dvrfile
and stream
functions. It is invoked using the following forms:
The function examines the 'User-Agent' string sent by the client. If the user-agent is on a preset list (or is not present), data transfer starts immediately; if not then a playlist is returned to the client.
The User-Agent list is "MPlayer", "curl/", "wget/", "TVHeadend", "Lavf" and any string containing "shoutcastsource".
If ticket
is added to the URL, for example:
the url in the returned playlist will contain an authentication ticket, removing any need to enter credentials in order to access the data. However the ticket is only valid for five minutes so the playlist cannot be re-used after that time.
When playing streams, the parameters for the underlying stream function can also be used.
This is a complex function which outputs lists of content available from the server, in various formats and filtered in several ways. The syntax for invoking the function depends on the required output and not all combinations of inputs are valid.
See below for sample output.
The value of <x> in the URL specifies the format of the output. The options are e2
, m3u
or satip
, with m3u
the default if the item is omitted. For recordings only m3u
is available.
For channels, a parameter sort
can be added. This can take the value 'name' or 'numname', to sort the output by channel name or channel number respectively.
See below for notes including the values of <y> in the URL, and sample outputs.
The value of <x> in the URL specifies the format of the output. The options are e2
, m3u
or satip
, with m3u
the default if the item is omitted. For recordings only m3u
is available.
See below for notes including the values of <y> in the URL, and sample outputs.
The list of recordings includes all entries in the DVR logs, including failed and missed recordings and recordings to be made in the future (ie timers). Unplayable recordings have 'bandwidth=0' in the output.
The value of <y> in the URLs, if supplied, specifies whether the channel list or playlist should include authentication in the URL. If <y> is ticket
, each entry includes an access-control 'ticket' - these tickets are only valid for five minutes, they are different for each channel/recording listed, and calling the playlist again will output a different set of tickets.
Alternatively, if Persistent Authentication is in use (TVHeadend versions > 4.3.1485), the value of <y> may be set to auth
. The auth code must be appended to the URL as a parameter, eg.
$ curl http://192.168.0.1:9981/playlist/auth/tags?auth=8ef7aa08e516060ca4330730c60e00d5b5174920
Used by simple.html.
Used internally for theme selection?
Outputs one of two files describing the SAT>IP server and the services available from it.
A rudimentary user interface to TVHeadend. It shows the contents of the recorder log (both completed and future recordings) and allows entries to be cancelled or deleted. A search box allows the EPG to be scanned for matching entries; clicking on an entry opens an information page which contains a button allowing the event to be recorded. Requires RECORDER privilege.
Outputs details of encrypted services. Each item contains:
Service ID
CA ID
CA provider ID
Service name
Service type
Service provider name
Outputs the TVHeadend version number and a (text) list of channels. This function requires Admin privilege.
The binary hash is only filled-in if the server runs on an x86 processor.
Outputs the current status of the server, including CPU load average, recordings in progress (or minutes to the next recording) and the number of active subscriptions. Needs 'Web interface' or 'Recorder' privilege.
Starts the streaming of live data from a channel, service or mux. The parameters which can be applied depend on the source:
profile
. The streaming profile to use. If the specified profile does not exist or can not be used the 'htsp' profile is used if available.
qsize
. Streaming buffer size. Default is 1500000 bytes.
User-Agent
. Use unknown.
profile
. The streaming profile to use. If the specified profile does not exist or can not be used the 'htsp' profile is used if available.
qsize
. Streaming buffer size. Default is 1500000 bytes.
descramble
. If set to 0 Tvheadend does not descramble the service.
emm
. Unknown. Default is 0, set to 1 to activate.
User-Agent
. Use unknown.
qsize
. Streaming buffer size. Default is 10000000 bytes.
pids
. A comma-separated list of pids to stream, or the word 'all' to stream the raw mux. The default is to stream all.
Controls the streaming of live data from a channel or service to a UDP address and port. This function requires Tvheadend version 4.3.2038 or later.
The following parameters are mandatory:
address
. The IP address of the device to receive the UDP stream.
port
. The destination port address.
The remaining parameters for the start
function depend on the source:
profile
. The streaming profile to use. If the specified profile does not exist or can not be used a 'Not Allowed' error is output.
qsize
. Streaming buffer size. Default is 1500000 bytes.
User-Agent
. Use unknown.
profile
. The streaming profile to use. If the specified profile does not exist or can not be used a 'Not Allowed' error is output.
qsize
. Streaming buffer size. Default is 1500000 bytes.
descramble
. If set to 0 Tvheadend does not descramble the service.
emm
. Default is 0, set to 1 to activate.
User-Agent
. Use unknown.
Outputs the EPG in XML format, filtered in various ways.
The final variation lists the complete EPG together with a channel list. Example:
If Persistent Authentication is in use (TVHeadend versions > 4.3.1485), the auth code must be appended to the URL as a parameter.
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 only recognises a subset of the total XMLTV schema.
Multiple instances of some tags like 'actor' or 'category' or 'rating' may be present.
Tvheadend uses English (en_GB) 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 .pot
files under the intl
directory if existing strings are reused or new strings added.
Merged changes to master template .pot
files are automatically replicated to Transifex where we manage the translation process. Our project is here: https://www.transifex.com/projects/p/tvheadend/
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 .po
files. 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.
Existing languages can be seen here: https://app.transifex.com/tvheadend/tvheadend/languages/
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 .po
files 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!
Snippets of stuff that developers have learned that may be useful to other developers but is not yet sufficiently complete or structured for a dedicated page.
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.
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.
API Used | UUID Value Returned | Encoding |
---|
JSON |
| String |
Proxied JSON |
| Binary |
HTSP |
| Binary |
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:admin@192.168.3.45: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.
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: https://wiki.xmltv.org/index.php/XMLTVFormat and here: https://github.com/XMLTV/xmltv/blob/master/xmltv.dtd.