1 of 8

HTSP

General

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:

Kodi
Showtime
TVHGuide
PyHTSP (This is a demo client and is WIP, it has limited functionality).

HTSMSG Binary Format

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:

Name

Description

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

HTSMSG Binary Format

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

The root message must always be of type map.

Root body

HTSMSG-Field

Field encoding for type: map and list

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

Field encoding for type: s64

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

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

Field encoding for type: str

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

Field encoding for type: bin

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

Communication

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

There are two distinct ways for communication within HTSP.

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

RPC Communication

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

RPC request extra fields:

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

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

RPC reply extra fields:

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

Streaming Communication

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

Authentication

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

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

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

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

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

It may choose to send:

Username and password: Privileges will be raised based on these credentials.
Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.
Nothing: Privileges will be based on just the source address.

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

On-Demand Authentication

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

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

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

Client to Server (RPC) methods

hello

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

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

Request message fields:

Reply message fields:

Note: possible values for servercapability[]:

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

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

Request message fields:

Reply message fields:

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

getChannel

(Added in version 14)

Request information about the given channel.

Request message fields:

Reply message fields:

getEvent

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

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

Request message fields:

Reply message fields:

getEvents

(Added in version 4)

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

Request message fields:

Reply message fields:

epgQuery

(Added in version 4)

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

Request message fields:

Reply message fields:

if full == 1

else

(Added in version 12)

Request message fields:

Reply message fields:

(Added in version 9)

Synonym for subscriptionSkip

subscriptionSpeed

(Added in version 9)

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

Request message fields:

Reply message fields:

subscriptionLive

(Added in version 9)

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

Request message fields:

Reply message fields:

subscriptionFilterStream

(Added in version 12)

Enable or disable specified streams by index.

Request message fields:

Reply message fields:

getProfiles

(Added in version 16)

Return a list of stream profiles (configurations).

Reply message fields:

Message fields:

getCodecs

(Added in version 11, Removed in version 16)

Return a list of encoders (codecs).

Reply message fields:

fileOpen

(Added in version 8)

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

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

Request message fields:

Valid file paths:

Reply message fields:

fileRead

(Added in version 8)

Read data from a file.

Request message fields:

Reply message fields:

fileClose

(Added in version 8)

Close an opened file.

Request message fields:

Reply message fields:

fileStat

(Added in version 8)

Get status of a file.

Request message fields:

Reply message fields:

fileSeek

(Added in version 8)

Seek to position in a file.

Request message fields:

Note: valid values for whence

Reply message fields:

Server to Client methods

channelAdd

A new channel has been created on the server.

Message fields:

channelId          u32   required   ID of channel.
channelIdStr       str   required   Full UUID of channel (Added in version 41).
channelNumber      u32   required   Channel number, 0 means unconfigured.
channelNumberMinor u32   optional   Minor channel number (Added in version 13).
channelName        str   required   Name of channel.
channelIcon        str   optional   URL to an icon representative for the channel
                                    (For v8+ clients this could be a relative /imagecache/ID URL
                                     intended to be fed to fileOpen() or HTTP server)
                                    (For v15+ clients this could be a relative imagecache/ID URL
                                     intended to be fed to fileOpen() or HTTP server)
eventId            u32   optional   ID of the current event on this channel.
nextEventId        u32   optional   ID of the next event on the channel.
tags               u32[] optional   Tags this channel is mapped to.
services           msg[] optional   List of available services (Added in version 5)

Service fields:

name               str   required   Service name
type               str   required   Service type
caid               u32   optional   Encryption CA ID
caname             str   optional   Encryption CA name
providername       str   optional   Service provider (Added in version 38)

channelUpdate

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

channelDelete

A channel has been deleted on the server.

Message fields:

channelId          u32   required   ID of channel.

tagAdd

A new tag has been created on the server.

Message fields:

tagId              u32   required   ID of tag.
tagIdStr           str   required   Full UUID of tag (Added in version 41).
tagName            str   required   Name of tag.
tagIndex           u32   optional   Index value for sorting (default by from min to max) (Added in version 18).
tagIcon            str   optional   URL to an icon representative for the channel.
tagTitledIcon      u32   optional   Icon includes a title
members            u32[] optional   Channel IDs of those that belong to the tag

tagUpdate

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

tagDelete

A tag has been deleted from the server.

Message fields:

tagId              u32   required   ID of tag.

dvrEntryAdd

(Added in version 4)

A new recording has been created on the server.

Message fields:

id                 u32   required   ID of dvrEntry.
idStr              str   required   Full UUID of dvrEntry (Added in version 41).
channel            u32   optional   Channel of dvrEntry.
start              s64   required   Time of when this entry was scheduled to start recording.
stop               s64   required   Time of when this entry was scheduled to stop recording.
startExtra         s64   required   Extra start time (pre-time) in minutes (Added in version 13).
stopExtra          s64   required   Extra stop time (post-time) in minutes (Added in version 13).
retention          s64   required   DVR Entry retention time in days (Added in version 13).
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set) (Added in version 13).
eventId            u32   optional   Associated EPG Event ID (Added in version 13).
autorecId          str   optional   Associated Autorec UUID (Added in version 13).
timerecId          str   optional   Associated Timerec UUID (Added in version 18).
contentType        u32   optional   Content Type (like in the DVB standard) (Added in version 13).
title              str   optional   Title of recording
subtitle           str   optional   Subtitle of recording (Added in version 20).
summary            str   optional   Short description of the recording (Added in version 6).
description        str   optional   Long description of the recording.
state              str   required   Recording state
error              str   optional   Plain english error description (e.g. "Aborted by user").
owner              str   optional   Name of the entry owner (Added in version 18).
creator            str   optional   Name of the entry creator (Added in version 18).
subscriptionError  str   optional   Subscription error string (Added in version 20).
streamErrors       str   optional   Number of recording errors (Added in version 20).
dataErrors         str   optional   Number of stream data errors (Added in version 20).
path               str   optional   Recording path for playback.
files              msg   optional   All recorded files for playback (Added in version 21).
dataSize           s64   optional   Actual file size of the last recordings (Added in version 21).
enabled            u32   optional   Enabled flag (Added in version 23).
ageRating          u32   optional   Minimum age rating (Added in version 36).
ratingLabel        str   optional   Parental rating label text (Added in version 37).
ratingIcon         str   optional   Parental rating label icon (Added in version 37).
ratingCountry      str   optional   Parental rating label country (Added in version 41).
ratingAuthority    str   optional   Parental rating label authority (Added in version 41).
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

Valid values for state:

TODO

Valid values for subscriptionError:

noFreeAdapter            No free adapter for this service.
scrambled                Service is scrambled.
badSignal                Bad signal status.
tuningFailed             Tuning of this service failed.
subscriptionOverridden   Subscription overridden by another one.
muxNotEnabled            No mux enabled for this service.
invalidTarget            Recording/livestream cannot be saved to filesystem or recording/streaming configuration is incorrect.
userAccess               User does not have access rights for this service.
userLimit                Maximum number of streaming connections set in user's profile reached.

dvrEntryUpdate

Message fields:

Same as dvrEntryAdd, but all fields (except id) are optional.

dvrEntryDelete

(Added in version 4)

A recording has been deleted from the server.

Message fields:

id                 u32   required   ID of recording to delete.

autorecEntryAdd

(Added in version 13)

A new autorec recording has been created on the server.

Message fields:

id                 str   required   ID (string!) of dvrAutorecEntry.
enabled            u32   required   If autorec entry is enabled (activated).
name               str   required   Name of the autorec entry (Added in version 18).
minDuration        u32   required   Minimal duration in seconds (0 = Any).
maxDuration        u32   required   Maximal duration in seconds (0 = Any).
retention          u32   required   Retention time (in days).
daysOfWeek         u32   required   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
approxTime         u32   required   Minutes from midnight (up to 24*60).
start              s32   required   Exact start time (minutes from midnight) (Added in version 18).
startWindow        s32   required   Exact stop time (minutes from midnight) (Added in version 18).
startExtra         s64   required   Extra start minutes (pre-time).
stopExtra          s64   required   Extra stop minutes (post-time).
title              str   optional   Title.
fulltext           u32   optional   Fulltext flag (Added in version 20).
directory          str   optional   Forced directory name (Added in version 19).
channel            u32   optional   Channel ID.
owner              str   optional   Owner of this autorec entry (Added in version 18).
creator            str   optional   Creator of this autorec entry (Added in version 18).
dupDetect          u32   optional   Duplicate detection (see addAutorecEntry) (Added in version 20).
broadcastType      u32   optional   Broadcast type (0 = any, 1 = new/premiere/unknown, 2 = repeated, 3 = new/premiere) (Added in version 39).
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

autorecEntryUpdate

(Added in version 13)

Message fields:

Same as autorecEntryAdd but all fields (except id) are optional.

autorecEntryDelete (Added in version 13)

Message fields:

id                 str   required   Autorec Entry ID (string!)

timerecEntryAdd

(Added in version 18)

A new autorec recording has been created on the server.

Message fields:

title              str   required   Title for the recordings.
directory          str   optional   Forced directory name (Added in version 19).
enabled            u32   required   Title for the recordings.
name               str   required   Name for this timerec entry.
channel            u32   required   Channel ID.
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
start              u32   required   Minutes from midnight (up to 24*60) for the start of the time window (including)
stop               u32   required   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed)
retention          u32   optional   Retention in days.
owner              str   optional   Owner of this timerec entry.
creator            str   optional   Creator of this timerec entry.
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

timerecEntryUpdate

(Added in version 18)

Message fields:

Same as timerecEntryAdd but all fields (except id) are optional.

timerecEntryDelete

(Added in version 18)

Message fields:

id                 str   required   Timerec Entry ID (string!)

eventAdd

(Added in version 6)

Message fields:

eventId            u32   required   Event ID
channelId          u32   required   The channel this event is related to.
start              u64   required   Start time of event, UNIX time.
stop               u64   required   Ending time of event, UNIX time.
title              str   optional   Title of event.
summary            str   optional   Short description of the event (Added in version 6).
description        str   optional   Long description of the event.
serieslinkId       u32   optional   Series Link ID (Added in version 6).
episodeId          u32   optional   Episode ID (Added in version 6).
seasonId           u32   optional   Season ID (Added in version 6).
brandId            u32   optional   Brand ID (Added in version 6).
contentType        u32   optional   DVB content code (Added in version 4, Modified in version 6*).
ageRating          u32   optional   Minimum age rating (Added in version 6).
starRating         u32   optional   Star rating (1-5) (Added in version 6).
firstAired         s64   optional   Original broadcast time, UNIX time (Added in version 6).
seasonNumber       u32   optional   Season number (Added in version 6).
seasonCount        u32   optional   Show season count (Added in version 6).
episodeNumber      u32   optional   Episode number (Added in version 6).
episodeCount       u32   optional   Season episode count (Added in version 6).
partNumber         u32   optional   Multi-part episode part number (Added in version 6).
partCount          u32   optional   Multi-part episode part count (Added in version 6).
episodeOnscreen    str   optional   Textual representation of episode number (Added in version 6).
image              str   optional   URL to a still capture from the episode (Added in version 6).
dvrId              u32   optional   ID of a recording (Added in version 5).
nextEventId        u32   optional   ID of next event on the same channel.
ratingLabel        str   optional   Parental rating label text (Added in version 37).
ratingIcon         str   optional   Parental rating label icon (Added in version 37).
ratingCountry      str   optional   Parental rating label country (Added in version 41).
ratingAuthority    str   optional   Parental rating label authority (Added in version 41).

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

eventUpdate

(Added in version 6)

Message fields:

Same as eventAdd but all fields (except eventId) are optional.

eventDelete

(Added in version 6)

Message fields:

eventId            u32   required   Event ID

initialSyncCompleted

(Added in version 2)

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

Message fields:

subscriptionStart

Asynchronous message output when a new subscription is successfully started.

Message fields:

subscriptionId     u32   required   Subscription ID.
streams            msg[] required   Array of messages with stream information
sourceinfo         msg   optional   Source information.

Stream message fields:

index              u32   required   Index for this stream
type               str   required   Type of stream
meta               bin   optional   Codec metadata (private data, libav - extradata) (Added in version 17)
language           str   optional   Language for stream
Video components only:
width              u32   optional   Width of video in pixels
height             u32   optional   Height of video in pixels
aspect_num         u32   optional   Aspect ratio numerator (Added in version 5) *Can be incorrect and should not be relied upon*
aspect_den         u32   optional   Aspect ratio denonminator (Added in version 5) *Can be incorrect and should not be relied upon*
Audio components only:
audio_type         u32   optional   Audio type - 0=Normal; 1=Clean effects; 2=Hearing impaired; 3=Visually impaired commentary; 4-255=Reserved (Added in version 11)
channels           u32   optional   Number of audio channels (Added in version 5)
rate               u32   optional   Audio bitrate (Added in version 5)
Subtitle components only:
composition_id     u32   optional   ??? (Added in version 5)
ancillary_id       u32   optional   ??? (Added in version 5)

Sourceinfo message fields:

adapter            str   optional   Adapter name
mux                str   optional   Transponder name
network            str   optional   Network name
provider           str   optional   Provide name (like 'Sky UK')
service            str   optional   Service name
satpos             str   optional   Satellite position name (Added in version 20).

Video Stream types:

MPEG2VIDEO                    MPEG2 video, meta field is present (configuration blocks)
H264                          H264 video, meta field is present (configuration blocks)
HEVC                          HEVC video, meta field is present (configuration blocks)

Audio Stream types:

MPEG2AUDIO                    MPEG2 audio (MP2)
AC3                           AC3 audio
AAC                           ADTS framed AAC (one AAC packet per ADTS frame), meta field is present (MPEG4 config)
EAC3                          Enhanced AC3 audio
VORBIS                        Vorbis audio, meta field is present with the main vorbis header

Subtitle Stream types:

TELETEXT                      ???
DVBSUB                        ???

subscriptionGrace

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

Message fields:

subscriptionId     u32   required   Subscription ID.
graceTimeout       u32   required   Grace timeout in seconds.

subscriptionStop

A subscription has been stopped.

Message fields:

subscriptionId     u32   required   Subscription ID.
status             str   optional   Error message if subscription stopped unexpectedly.
subscriptionError  str   optional   Subscription error code (Added in version 20).

Valid values for subscriptionError:

see dvrEntryAdd

subscriptionSkip

(Added in version 9)

A subscription has been skipped.

Message fields:

subscriptionId     u32   required   Subscription ID.
error              u32   optional   The last skip command caused an error.
absolute           u32   optional   Indicates the output is absolute (Note: should always be 1 at the moment)
time               u64   optional   The time the subscription has skipped to.
size               u64   optional   The position in the file we've skipped to (Note: not currently used).

subscriptionSpeed

(Added in version 9)

A subscription's playback speed has changed.

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

Message fields:

subscriptionId     u32   required   Subscription ID.
speed              u32   required   The new speed of the subscription

subscriptionStatus

Subscription status update.

Message fields:

subscriptionId     u32   required   Subscription ID.
status             str   optional   English clear text of error status. Absence of this field means that the status is OK. 
subscriptionError  str   optional   Subscription error code (Added in version 20).

Valid values for subscriptionError:

see dvrEntryAdd

queueStatus

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

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

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

Message fields:

subscriptionId     u32   required   Subscription ID.
packets            u32   required   Number of data packets in queue.
bytes              u32   required   Number of bytes in queue.
delay              u32   optional   Estimated delay of queue (in µs).
Bdrops             u32   required   Number of B-frames dropped
Pdrops             u32   required   Number of P-frames dropped
Idrops             u32   required   Number of I-frames dropped
delay              s64   required   Delta between first and last DTS (Added in version 9)

signalStatus

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

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

Message fields:

subscriptionId     u32   required   Subscription ID.
feStatus           str   required   Frontend status.
feSNR              u32   optional   Signal to noise ratio.
feSignal           u32   optional   Signal status percentage.
feBER              u32   optional   Bit error rate.
feUNC              u32   optional   Uncorrected blocks.

timeshiftStatus

Provide status every second about the timeshift buffer.

Message fields:

subscriptionId     u32   required   Subscription ID.
full               u32   required   Indicates whether the buffer is full
shift              s64   required   Current position relative to live
start              s64   optional   PTS of the first frame in the buffer
end                s64   optional   PTS of the last frame in the buffer

muxpkt

Streaming data.

Message fields:

subscriptionId     u32   required   Subscription ID.
frametype          u32   required   Type of frame as ASCII value: 'I', 'P', 'B'
stream             u32   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
dts                s64   optional   Decode Time Stamp in µs.
pts                s64   optional   Presentation Time Stamp in µs.
duration           u32   required   Duration of frame in µs.
payload            bin   required   Actual frame data.

Protocol Changes

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

v42

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

v41

added full UUID to channelAdd, tagAdd and dvrEntryAdd
added ratingAuthority and ratingCountry to dvrEntryAdd and eventAdd

v40

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

v39

added broadcast type to autorec DVR entry

v38

added service provider name to channelAdd -> services

v37

added ratingLabel to EPG & DVR entries
added ratingIcon to EPG & DVR entries

v36

added ageRating to DVR entries

v26..35

TODO

v25

added updateAutorecEntry and updateTimerecEntry
(and other changes not yet documented here)

v23..24

added descrambleInfo (not yet documented here)

v22..23

extended addDvrEntry, updateDvrEntry, dvrEntryAdd method
- added enabled
extended getSysTime
- added gmtoffset

v21..22

extended updateDvrEntry method
- added channelId

v20..v21

dvrEntry structures
- added files msg (multiple files) to the files field
- added dataSize field to show actual (last) file size in dvrEntry updates
epg events - added subtitle field

v19..v20

dvrEntry structures
- added subscriptionError, streamErrors, dataErrors fields
- added subtitle fields
autorecEntry structures
- added dupDetect and fulltext fields
added errors fields to the stream status
added satpos to the subscription start
added subscriptionError field to subscriptionStatus server-to-client method

v18..v19

autorec/timerec structures
- added directory field (forced output directory)
- added enabled field

v17..v18

added addTimerecEntry, deleteTimerecEntry methods
added timerecEntryAdd, timerecEntryUpdate, timerecEntryDelete server-to-client methods
extended addAutorecEntry method
- added start/startWindow/name fields
- added owner/creator fields
- obsoleted creator field
extended dvrEntryAdd, dvrEntryUpdate
- added timerecId field
- added owner/creator fields
extended addAutorecEntry, deleteAutorecEntry methods
- added start/startWindow fields
- obsoleted approxTime
- added name/owner/creator fields
extended autorecEntryAdd, autorecEntryUpdate server-to-client methods
- fields like for addAutorecEntry
extended getTag method
- added tagIndex field

v16..v17

extended subscriptionStart server-to-client method
- added meta field
changed H264 meta data handling (codec meta data are in the meta field only in start message)
VORBIS and AAC codecs have codec specific meta data in the meta field in start message
changed subscribe method
- the normts is always active and the parameter is ignored

v15..v16

added getProfiles, getDvrConfigs methods
removed getCodecs methods
extended subscribe method
- add profile field

v14..v15

extended channelAdd, channelUpdate server-to-client methods
- the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'
extended getChannel method
- the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'

v13..v14

added getChannel method

v12..v13

added addAutorecEntry method
added deleteAutorecEntry method
added autorecEntryAdd, autorecEntryUpdate, autorecEntryDelete server-to-client methods
extended channelAdd server-to-client method
- added channelNumberMinor (for {major}.{minor} channel numbers)
extended dvrEntryAdd and dvrEntryUpdate server-to-client methods
- added eventId, autorecId, startExtra, stopExtra, retention, priority, contentType fields
extended addDvrEntry method
- added retention
extended updateDvrEntry method
- added retention, priority
extended epgQuery method
- added minduration, maxduration
added subscriptionGrace server-to-client method

v11..v12

added subscriptionFilterStream method
added getDvrCutpoints method

v10..v11

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

HTTP Proxy Examples

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

Also see: JSON API.

HTSP `API` Syntax Summary

Request:

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

Reply:

response           msg[] required   JSON response

Simple Request

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

Intermediate Request

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

Advanced Request

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

Server to Client methods

channelAdd

A new channel has been created on the server.

Message fields:

channelId          u32   required   ID of channel.
channelIdStr       str   required   Full UUID of channel (Added in version 41).
channelNumber      u32   required   Channel number, 0 means unconfigured.
channelNumberMinor u32   optional   Minor channel number (Added in version 13).
channelName        str   required   Name of channel.
channelIcon        str   optional   URL to an icon representative for the channel
                                    (For v8+ clients this could be a relative /imagecache/ID URL
                                     intended to be fed to fileOpen() or HTTP server)
                                    (For v15+ clients this could be a relative imagecache/ID URL
                                     intended to be fed to fileOpen() or HTTP server)
eventId            u32   optional   ID of the current event on this channel.
nextEventId        u32   optional   ID of the next event on the channel.
tags               u32[] optional   Tags this channel is mapped to.
services           msg[] optional   List of available services (Added in version 5)

Service fields:

name               str   required   Service name
type               str   required   Service type
caid               u32   optional   Encryption CA ID
caname             str   optional   Encryption CA name
providername       str   optional   Service provider (Added in version 38)

channelUpdate

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

channelDelete

A channel has been deleted on the server.

Message fields:

channelId          u32   required   ID of channel.

tagAdd

A new tag has been created on the server.

Message fields:

tagId              u32   required   ID of tag.
tagIdStr           str   required   Full UUID of tag (Added in version 41).
tagName            str   required   Name of tag.
tagIndex           u32   optional   Index value for sorting (default by from min to max) (Added in version 18).
tagIcon            str   optional   URL to an icon representative for the channel.
tagTitledIcon      u32   optional   Icon includes a title
members            u32[] optional   Channel IDs of those that belong to the tag

tagUpdate

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

tagDelete

A tag has been deleted from the server.

Message fields:

tagId              u32   required   ID of tag.

dvrEntryAdd

(Added in version 4)

A new recording has been created on the server.

Message fields:

id                 u32   required   ID of dvrEntry.
idStr              str   required   Full UUID of dvrEntry (Added in version 41).
channel            u32   optional   Channel of dvrEntry.
start              s64   required   Time of when this entry was scheduled to start recording.
stop               s64   required   Time of when this entry was scheduled to stop recording.
startExtra         s64   required   Extra start time (pre-time) in minutes (Added in version 13).
stopExtra          s64   required   Extra stop time (post-time) in minutes (Added in version 13).
retention          s64   required   DVR Entry retention time in days (Added in version 13).
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set) (Added in version 13).
eventId            u32   optional   Associated EPG Event ID (Added in version 13).
autorecId          str   optional   Associated Autorec UUID (Added in version 13).
timerecId          str   optional   Associated Timerec UUID (Added in version 18).
contentType        u32   optional   Content Type (like in the DVB standard) (Added in version 13).
title              str   optional   Title of recording
subtitle           str   optional   Subtitle of recording (Added in version 20).
summary            str   optional   Short description of the recording (Added in version 6).
description        str   optional   Long description of the recording.
state              str   required   Recording state
error              str   optional   Plain english error description (e.g. "Aborted by user").
owner              str   optional   Name of the entry owner (Added in version 18).
creator            str   optional   Name of the entry creator (Added in version 18).
subscriptionError  str   optional   Subscription error string (Added in version 20).
streamErrors       str   optional   Number of recording errors (Added in version 20).
dataErrors         str   optional   Number of stream data errors (Added in version 20).
path               str   optional   Recording path for playback.
files              msg   optional   All recorded files for playback (Added in version 21).
dataSize           s64   optional   Actual file size of the last recordings (Added in version 21).
enabled            u32   optional   Enabled flag (Added in version 23).
ageRating          u32   optional   Minimum age rating (Added in version 36).
ratingLabel        str   optional   Parental rating label text (Added in version 37).
ratingIcon         str   optional   Parental rating label icon (Added in version 37).
ratingCountry      str   optional   Parental rating label country (Added in version 41).
ratingAuthority    str   optional   Parental rating label authority (Added in version 41).
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

Valid values for state:

TODO

Valid values for subscriptionError:

noFreeAdapter            No free adapter for this service.
scrambled                Service is scrambled.
badSignal                Bad signal status.
tuningFailed             Tuning of this service failed.
subscriptionOverridden   Subscription overridden by another one.
muxNotEnabled            No mux enabled for this service.
invalidTarget            Recording/livestream cannot be saved to filesystem or recording/streaming configuration is incorrect.
userAccess               User does not have access rights for this service.
userLimit                Maximum number of streaming connections set in user's profile reached.

dvrEntryUpdate

Message fields:

Same as dvrEntryAdd, but all fields (except id) are optional.

dvrEntryDelete

(Added in version 4)

A recording has been deleted from the server.

Message fields:

id                 u32   required   ID of recording to delete.

autorecEntryAdd

(Added in version 13)

A new autorec recording has been created on the server.

Message fields:

id                 str   required   ID (string!) of dvrAutorecEntry.
enabled            u32   required   If autorec entry is enabled (activated).
name               str   required   Name of the autorec entry (Added in version 18).
minDuration        u32   required   Minimal duration in seconds (0 = Any).
maxDuration        u32   required   Maximal duration in seconds (0 = Any).
retention          u32   required   Retention time (in days).
daysOfWeek         u32   required   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
approxTime         u32   required   Minutes from midnight (up to 24*60).
start              s32   required   Exact start time (minutes from midnight) (Added in version 18).
startWindow        s32   required   Exact stop time (minutes from midnight) (Added in version 18).
startExtra         s64   required   Extra start minutes (pre-time).
stopExtra          s64   required   Extra stop minutes (post-time).
title              str   optional   Title.
fulltext           u32   optional   Fulltext flag (Added in version 20).
directory          str   optional   Forced directory name (Added in version 19).
channel            u32   optional   Channel ID.
owner              str   optional   Owner of this autorec entry (Added in version 18).
creator            str   optional   Creator of this autorec entry (Added in version 18).
dupDetect          u32   optional   Duplicate detection (see addAutorecEntry) (Added in version 20).
broadcastType      u32   optional   Broadcast type (0 = any, 1 = new/premiere/unknown, 2 = repeated, 3 = new/premiere) (Added in version 39).
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

autorecEntryUpdate

(Added in version 13)

Message fields:

Same as autorecEntryAdd but all fields (except id) are optional.

autorecEntryDelete (Added in version 13)

Message fields:

id                 str   required   Autorec Entry ID (string!)

timerecEntryAdd

(Added in version 18)

A new autorec recording has been created on the server.

Message fields:

title              str   required   Title for the recordings.
directory          str   optional   Forced directory name (Added in version 19).
enabled            u32   required   Title for the recordings.
name               str   required   Name for this timerec entry.
channel            u32   required   Channel ID.
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
start              u32   required   Minutes from midnight (up to 24*60) for the start of the time window (including)
stop               u32   required   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed)
retention          u32   optional   Retention in days.
owner              str   optional   Owner of this timerec entry.
creator            str   optional   Creator of this timerec entry.
configId           str   optional   DVR Configuration UUID (Added in version 40).
comment            str   optional   User Comment (Added in version 42).

timerecEntryUpdate

(Added in version 18)

Message fields:

Same as timerecEntryAdd but all fields (except id) are optional.

timerecEntryDelete

(Added in version 18)

Message fields:

id                 str   required   Timerec Entry ID (string!)

eventAdd

(Added in version 6)

Message fields:

eventId            u32   required   Event ID
channelId          u32   required   The channel this event is related to.
start              u64   required   Start time of event, UNIX time.
stop               u64   required   Ending time of event, UNIX time.
title              str   optional   Title of event.
summary            str   optional   Short description of the event (Added in version 6).
description        str   optional   Long description of the event.
serieslinkId       u32   optional   Series Link ID (Added in version 6).
episodeId          u32   optional   Episode ID (Added in version 6).
seasonId           u32   optional   Season ID (Added in version 6).
brandId            u32   optional   Brand ID (Added in version 6).
contentType        u32   optional   DVB content code (Added in version 4, Modified in version 6*).
ageRating          u32   optional   Minimum age rating (Added in version 6).
starRating         u32   optional   Star rating (1-5) (Added in version 6).
firstAired         s64   optional   Original broadcast time, UNIX time (Added in version 6).
seasonNumber       u32   optional   Season number (Added in version 6).
seasonCount        u32   optional   Show season count (Added in version 6).
episodeNumber      u32   optional   Episode number (Added in version 6).
episodeCount       u32   optional   Season episode count (Added in version 6).
partNumber         u32   optional   Multi-part episode part number (Added in version 6).
partCount          u32   optional   Multi-part episode part count (Added in version 6).
episodeOnscreen    str   optional   Textual representation of episode number (Added in version 6).
image              str   optional   URL to a still capture from the episode (Added in version 6).
dvrId              u32   optional   ID of a recording (Added in version 5).
nextEventId        u32   optional   ID of next event on the same channel.
ratingLabel        str   optional   Parental rating label text (Added in version 37).
ratingIcon         str   optional   Parental rating label icon (Added in version 37).
ratingCountry      str   optional   Parental rating label country (Added in version 41).
ratingAuthority    str   optional   Parental rating label authority (Added in version 41).

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

eventUpdate

(Added in version 6)

Message fields:

Same as eventAdd but all fields (except eventId) are optional.

eventDelete

(Added in version 6)

Message fields:

eventId            u32   required   Event ID

initialSyncCompleted

(Added in version 2)

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

Message fields:

subscriptionStart

Asynchronous message output when a new subscription is successfully started.

Message fields:

subscriptionId     u32   required   Subscription ID.
streams            msg[] required   Array of messages with stream information
sourceinfo         msg   optional   Source information.

Stream message fields:

index              u32   required   Index for this stream
type               str   required   Type of stream
meta               bin   optional   Codec metadata (private data, libav - extradata) (Added in version 17)
language           str   optional   Language for stream
Video components only:
width              u32   optional   Width of video in pixels
height             u32   optional   Height of video in pixels
aspect_num         u32   optional   Aspect ratio numerator (Added in version 5) *Can be incorrect and should not be relied upon*
aspect_den         u32   optional   Aspect ratio denonminator (Added in version 5) *Can be incorrect and should not be relied upon*
Audio components only:
audio_type         u32   optional   Audio type - 0=Normal; 1=Clean effects; 2=Hearing impaired; 3=Visually impaired commentary; 4-255=Reserved (Added in version 11)
channels           u32   optional   Number of audio channels (Added in version 5)
rate               u32   optional   Audio bitrate (Added in version 5)
Subtitle components only:
composition_id     u32   optional   ??? (Added in version 5)
ancillary_id       u32   optional   ??? (Added in version 5)

Sourceinfo message fields:

adapter            str   optional   Adapter name
mux                str   optional   Transponder name
network            str   optional   Network name
provider           str   optional   Provide name (like 'Sky UK')
service            str   optional   Service name
satpos             str   optional   Satellite position name (Added in version 20).

Video Stream types:

MPEG2VIDEO                    MPEG2 video, meta field is present (configuration blocks)
H264                          H264 video, meta field is present (configuration blocks)
HEVC                          HEVC video, meta field is present (configuration blocks)

Audio Stream types:

MPEG2AUDIO                    MPEG2 audio (MP2)
AC3                           AC3 audio
AAC                           ADTS framed AAC (one AAC packet per ADTS frame), meta field is present (MPEG4 config)
EAC3                          Enhanced AC3 audio
VORBIS                        Vorbis audio, meta field is present with the main vorbis header

Subtitle Stream types:

TELETEXT                      ???
DVBSUB                        ???

subscriptionGrace

Message fields:

subscriptionId     u32   required   Subscription ID.
graceTimeout       u32   required   Grace timeout in seconds.

subscriptionStop

A subscription has been stopped.

Message fields:

subscriptionId     u32   required   Subscription ID.
status             str   optional   Error message if subscription stopped unexpectedly.
subscriptionError  str   optional   Subscription error code (Added in version 20).

Valid values for subscriptionError:

see dvrEntryAdd

subscriptionSkip

(Added in version 9)

A subscription has been skipped.

Message fields:

subscriptionId     u32   required   Subscription ID.
error              u32   optional   The last skip command caused an error.
absolute           u32   optional   Indicates the output is absolute (Note: should always be 1 at the moment)
time               u64   optional   The time the subscription has skipped to.
size               u64   optional   The position in the file we've skipped to (Note: not currently used).

subscriptionSpeed

(Added in version 9)

A subscription's playback speed has changed.

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

Message fields:

subscriptionId     u32   required   Subscription ID.
speed              u32   required   The new speed of the subscription

subscriptionStatus

Subscription status update.

Message fields:

subscriptionId     u32   required   Subscription ID.
status             str   optional   English clear text of error status. Absence of this field means that the status is OK. 
subscriptionError  str   optional   Subscription error code (Added in version 20).

Valid values for subscriptionError:

see dvrEntryAdd

queueStatus

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

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

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

Message fields:

subscriptionId     u32   required   Subscription ID.
packets            u32   required   Number of data packets in queue.
bytes              u32   required   Number of bytes in queue.
delay              u32   optional   Estimated delay of queue (in µs).
Bdrops             u32   required   Number of B-frames dropped
Pdrops             u32   required   Number of P-frames dropped
Idrops             u32   required   Number of I-frames dropped
delay              s64   required   Delta between first and last DTS (Added in version 9)

signalStatus

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

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

Message fields:

subscriptionId     u32   required   Subscription ID.
feStatus           str   required   Frontend status.
feSNR              u32   optional   Signal to noise ratio.
feSignal           u32   optional   Signal status percentage.
feBER              u32   optional   Bit error rate.
feUNC              u32   optional   Uncorrected blocks.

timeshiftStatus

Provide status every second about the timeshift buffer.

Message fields:

subscriptionId     u32   required   Subscription ID.
full               u32   required   Indicates whether the buffer is full
shift              s64   required   Current position relative to live
start              s64   optional   PTS of the first frame in the buffer
end                s64   optional   PTS of the last frame in the buffer

muxpkt

Streaming data.

Message fields:

subscriptionId     u32   required   Subscription ID.
frametype          u32   required   Type of frame as ASCII value: 'I', 'P', 'B'
stream             u32   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
dts                s64   optional   Decode Time Stamp in µs.
pts                s64   optional   Presentation Time Stamp in µs.
duration           u32   required   Duration of frame in µs.
payload            bin   required   Actual frame data.

Client to Server (RPC) methods

hello

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

Request message fields:

Reply message fields:

Note: possible values for servercapability[]:

authenticate

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

Request message fields:

None

Reply message fields:

noaccess           u32   optional   If set to 1, no privileges were granted.

api

(Added in version 24)

This is a proxy to HTTP API.

Request message fields:

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

Reply message fields:

response           msg[] required   Structured response (like in JSON HTTP replies)

Also see: and .

getDiskSpace

(Added in version 3)

Return diskspace status from Tvheadend's PVR storage

Request message fields:

None

Reply message fields:

freediskspace      s64   required   Bytes available.
totaldiskspace     s64   required   Total capacity.

Also see: .

getSysTime

(Added in version 3)

Return system time on the server.

Request message fields:

None

Reply message fields:

time               s64  required   UNIX time.
timezone           s32  required   Hours west of GMT. (deprecated, does not work reliable, use gmtoffset instead)
gmtoffset          s32  optional   Minutes east of GMT.

enableAsyncMetadata

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

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

Request message fields:

epg                u32   optional   Set to 1, to include EPG data in async, implied by epgMaxTime (Added in version 6).
lastUpdate         s64   optional   Only provide metadata that has changed since this time (Added in version 6).
epgMaxTime         s64   optional   Maximum time to return EPG data up to (Added in version 6)
language           str   optional   RFC 2616 compatible language list (Added in version 6)

Reply message fields:

None

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:

tagAdd                   optional
channelAdd               optional
tagUpdate                optional
dvrEntryAdd              optional
eventAdd                 optional   (Added in version 6)
initialSyncComplete      required

getChannel

(Added in version 14)

Request information about the given channel.

Request message fields:

channelId          u32   required   Channel ID.

Reply message fields:

see channelAdd

Also see:

getEvent

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

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

Request message fields:

eventId            u32   required   Event ID.
language           str   optional   RFC 2616 compatible language list (Added in version 6)

Reply message fields:

see eventAdd

Also see:

getEvents

(Added in version 4)

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

Request message fields:

eventId            u32   optional   Event ID to begin from (Optional since version 6)
channelId          u32   optional   Channel ID to get data for (Added in version 6)
numFollowing       u32   optional   Number of events to add (Optional since version 6)
maxTime            u64   optional   Maximum time to return data up to (Added in version 6)
language           str   optional   RFC 2616 compatible language list (Added in version 6)

Reply message fields:

events             msg[] required   List of events, using response message fields from eventAdd

epgQuery

(Added in version 4)

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

Request message fields:

query              str   required  Title regular expression to search for
channelId          u32   optional  [[ChannelId]] to restrict search to
tagId              u32   optional  [[TagId]] to restrict search to
contentType        u32   optional  DVB content type to restrict search to
minduration        u32   optional  Minimal duration in seconds (Added in version 13)
maxduration        u32   optional  Maximal duration in seconds (Added in version 13)
language           str   optional  RFC 2616 compatible language list for title (Added in version 6)
full               u32   optional  Output full event list rather than just IDs

Reply message fields:

if full == 1

events             msg[] optional   List of events, using response message fields from eventAdd

else

eventIds           u32[] optional  List of eventIds that match the query

getEpgObject

Get detailed EPG Object info.

Request message fields:

id                 u32   required  Object ID
type               u32   optional  Object type

Reply message fields:

TODO

getDvrConfigs

(Added in version 16)

Return a list of DVR configurations.

Reply message fields:

dvrconfigs         msg[]      optional   Supported DVR configurations.

Message fields:

uuid               str        required   DVR configuration ID
name               str        required   DVR configuration Name
comment            str        required   DVR configuration Comment

Also see:

addDvrEntry

(Added in version 4)

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

Request message fields:

eventId            u32   optional   Event ID (Optional since version 5).
channelId          u32   optional   Channel ID (Added in version 5)
start              s64   optional   Time to start recording (Added in version 5)
stop               s64   optional   Time to stop recording (Added in version 5)
retention          u32   optional   Retention time in days (Added in version 13)
creator            str   optional   Name of the event creator (Added in version 5, obsoleted in version 18 - applications are not allowed to change credential)
priority           u32   optional   Recording priority (Added in version 5)
startExtra         s64   optional   Pre-recording buffer in minutes (Added in version 5)
stopExtra          s64   optional   Post-recording buffer in minutes (Added in version 5)
title              str   optional   Recording title, if no eventId (Added in version 6)
subtitle           str   optional   Recording subtitle, if no eventId (Added in version 20)
description        str   optional   Recording description, if no eventId (Added in version 5)
configName         str   optional   DVR configuration name or UUID
enabled            u32   optional   Enabled flag (Added in version 23).
ageRating          u32   optional   Minimum age rating (Added in version 36).
comment            str   optional   User Comment (Added in version 42).

Reply message fields:

success            u32   required   1 if entry was added, 0 otherwise
id                 u32   optional   ID of created DVR entry
error              str   optional   English clear text of error message

updateDvrEntry

(Added in version 5)

Update an existing DVR entry.

Request message fields:

id                 u32   required   DVR Entry ID
channelId          u32   optional   New channel ID (Added in version 22)
start              s64   optional   New start time
stop               s64   optional   New stop time
title              str   optional   New entry title
subtitle           str   optional   New entry subtitle (Added in version 21)
description        str   optional   New entry description (Added in version 6)
startExtra         s64   optional   New pre-record buffer (Added in version 6)
stopExtra          s64   optional   New post-record buffer (Added in version 6)
configName         str   optional   New DVR configuration name or UUID
retention          u32   optional   Retention in days (Added in version 13)
priority           u32   optional   Recording priority (Added in version 13)
enabled            u32   optional   Enabled flag (Added in version 23).
comment            str   optional   User Comment (Added in version 42).

Reply message fields:

success            u32   required   1 if update as successful, otherwise 0
error              str   optional   Error message if update failed

cancelDvrEntry

(Added in version 5)

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

Request message fields:

id                 u32   required   dvrEnryId to delete

Reply message fields:

success            int   required   1 if entry was cancelled
error              str   optional   Error message if cancellation failed

deleteDvrEntry

(Added in version 4)

Delete an existing DVR entry from the database.

Request message fields:

id                 u32   required   DVR Entry ID

Reply message fields:

success            u32   required   1 if entry was removed
error              str   optional   Error message if the delete fails

getDvrCutpoints

(Added in version 12)

Get DVR cutpoints.

Request message fields:

id                 u32   required   DVR Entry ID

Reply message fields:

cutpoints          msg[] optional   List of cutpoint entries, if a file is found and has some valid data.

Cutpoint fields:

start              u32   required   Cut start time in ms.
end                u32   required   Cut end time in ms.
type               u32   required   Action type: 
                                      0=Cut, 1=Mute, 2=Scene, 
                                      3=Commercial break.

addAutorecEntry

(Added in version 13)

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

Request message fields:

enabled            u32   optional   Enabled flag (Added in version 19).
title              str   required   Title for the recordings.
fulltext           u32   optional   Full text flag (Added in version 20).
directory          str   optional   Forced directory name - missing or empty = auto (Added in version 19).
name               str   optional   Name of this autorec entry (Added in version 18).
configName         str   optional   DVR Configuration Name / UUID.
channelId          u32   optional   Channel ID.
minDuration        u32   optional   Minimal duration in seconds (0 = Any).
maxDuration        u32   optional   Maximal duration in seconds (0 = Any).
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
approxTime         u32   optional   Minutes from midnight (up to 24*60) (window +- 15 mintes) (Obsoleted from version 18).
start              s32   optional   Minutes from midnight (up to 24*60) for the start of the time window (including) (Added in version 18).
startWindow        s32   optional   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed) (Added in version 18).
startExtra         s64   optional   Extra start minutes (pre-time).
stopExtra          s64   optional   Extra stop minutes (post-time).
dupDetect          u32   optional   Dup Detect (0 = all, 1 = diff episode, 2 = diff subtitle, 3 = diff description, 4 = once per week, 5 = once per day) (Added in version 20).
comment            str   optional   User Comment.
broadcastType      u32   optional   Broadcast type (0 = any, 1 = new/premiere/unknown, 2 = repeated, 3 = new/premiere) (Added in version 39).

Reply message fields:

success            u32   required   1 if entry was added, 0 otherwise
id                 str   optional   ID (string!) of created autorec DVR entry
error              str   optional   English clear text of error message

updateAutorecEntry

(Added in version 25)

Update an existing Autorec DVR entry.

Request message fields:

id                 str   required   Autorec DVR Entry ID (string!)
title              str   optional   Title for the recordings
(Rest same as for addAutorecEntry)

Reply message fields:

None (errors only propagated via HTTP status code)

deleteAutorecEntry

(Added in version 13)

Delete an existing autorec DVR entry from the database.

Request message fields:

id                 str   required   Autorec DVR Entry ID (string!)

Reply message fields:

success            u32   required   1 if entry was removed
error              str   optional   Error message if the delete fails

addTimerecEntry

(Added in version 18)

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

Request message fields:

enabled            u32   optional   Enabled flag (Added in version 19).
title              str   required   Title for the recordings.
directory          str   optional   Forced output directory name (Added in version 19).
name               str   optional   Name for this timerec entry.
configName         str   optional   DVR Configuration Name / UUID.
channelId          u32   optional   Channel ID.
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
start              u32   optional   Minutes from midnight (up to 24*60) for the start of the time window (including)
stop               u32   optional   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed)
retention          u32   optional   Retention in days. 
comment            str   optional   User Comment.

Reply message fields:

success            u32   required   1 if entry was added, 0 otherwise
id                 str   optional   ID (string!) of created timerec DVR entry
error              str   optional   English clear text of error message

updateTimerecEntry

(Added in version 25)

Update an existing Timerec DVR entry.

Request message fields:

id                 str   required   Timerec DVR Entry ID (string!)
title              str   optional   Title for the recordings
(Rest same as for addTimerecEntry)

Reply message fields:

None (errors only propagated via HTTP status code)

deleteTimerecEntry

(Added in version 18)

Delete an existing timerec DVR entry from the database.

Request message fields:

id                 str   required   Timerec DVR Entry ID (string!)

Reply message fields:

success            u32   required   1 if entry was removed
error              str   optional   Error message if the delete fails

getTicket

(Added in version 5)

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

Request message fields:

channelId          u32  optional   Channel to gain access for
dvrId              u32  optional   DVR file to gain access for

Reply message fields:

path               str  required   The full path for access URL (no scheme, host or port)
ticket             str  required   The ticket to pass in the URL query string

Request subscription to the given channel.

Request message fields:

channelId          u32   required   ID for channel. 
subscriptionId     u32   required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
                                    The value is used from now on in all messages related to the subscription.
weight             u32   optional   Weighting of this subscription (same as recording priority).
90khz              u32   optional   Request PTS/DTS in default 90kHz timebase, default is 1MHz (Added in version 7)
normts             u32   optional   Request PTS/DTS normalisation (Added in version 7)
                                    Note: this will mean missing timestamps are added, first packet should be ~0 and will always be an i-frame.
                                    Note: this is implied if timeshiftPeriod is enabled
                                    Note: from version 17, this is always enabled and this parameter is ignored.
queueDepth         u32   optional   Change the default packet queue lengths, default 500000 bytes (Added in version 7)
                                    Note: I-frame depth is 3*queueDepth, P-frame is 2*queueDepth and B-frame is queueDepth
timeshiftPeriod    u32   optional   The number of seconds to keep in the timeshift buffer (Added in version 9)
                                    Note: this may be bounded by server configuration settings
profile            str   optional   Select stream profile (Added in version 16).

Reply message fields:

90khz              u32   optional   Indicates 90khz timestamps will be used
normts             u32   optional   Indicates timestamps will be normalised (and fixed)
timeshiftPeriod    u32   optional   The actual timeshiftPeriod to be used

unsubscribe

Stop a subscription.

Request message fields:

subscriptionId     u32   required   Subscription ID.

Reply message fields:

None

subscriptionChangeWeight

(Added in version 5)

Change the weight of an existing subscription

Request message fields:

subscriptionId     u32   required   Subscription ID.
weight             u32   optional   The new subscription weight.

Reply message fields:

None

subscriptionSkip

(Added in version 9)

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

Request message fields:

subscriptionId     u32   required   Subscription ID.
absolute           u32   optional   The skip request is absolute
time               u64   optional   Specify skip using time (units are as for PTS)
size               u64   optional   Specify skip using size (Not currently used)

Reply message fields:

None

subscriptionSeek

(Added in version 9)

Synonym for subscriptionSkip

subscriptionSpeed

(Added in version 9)

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

Request message fields:

subscriptionId     u32   required   Subscription ID.
speed              u32   required   Specify speed (0=pause, 100=1x fwd, -100=1x backward)

Reply message fields:

None

subscriptionLive

(Added in version 9)

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

Request message fields:

subscriptionId     u32   required   Subscription ID.

Reply message fields:

None

subscriptionFilterStream

(Added in version 12)

Enable or disable specified streams by index.

Request message fields:

subscriptionId     u32        required   Subscription ID.
enable             list[u32]  optional   Enable stream indexes
disable            list[u32]  optional   Disable (filter out) stream indexes

Reply message fields:

None

getProfiles

(Added in version 16)

Return a list of stream profiles (configurations).

Reply message fields:

profiles           msg[]      optional   Supported profiles

Message fields:

uuid               str        required   Profile ID
name               str        required   Profile Name
comment            str        required   Profile Comment

getCodecs

(Added in version 11, Removed in version 16)

Return a list of encoders (codecs).

Reply message fields:

encoders           list[str]  optional   Supported encoders

fileOpen

(Added in version 8)

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

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

Request message fields:

file               str   required   File path to open

Valid file paths:

/dvrfile/ID        will open the file associated with DVR entry ID
/imagecache/ID     will open the file associated with imagecache entry ID (Note: only works for HTSPv10+)

Reply message fields:

id                 u32   required   The file handle used for further file operations
size               u64   optional   The size of the file in bytes
mtime              u64   optional   The last time the file was modified

fileRead

(Added in version 8)

Read data from a file.

Request message fields:

id                 u32   required   The file handle used for further file operations
size               u64   required   The amount of data to read
offset             u64   optional   Offset into the file to read (default is current position)

Reply message fields:

data               bin   required   The data read from the file (size may be less than requested)

fileClose

(Added in version 8)

Close an opened file.

Request message fields:

id                 u32   required   The file handle to be closed

Reply message fields:

None

fileStat

(Added in version 8)

Get status of a file.

Request message fields:

id                 u32   required   The file handle to be stat'd

Reply message fields:

size               u64   optional   The size of the file in bytes
mtime              u64   optional   The last time the file was modified

fileSeek

(Added in version 8)

Seek to position in a file.

Request message fields:

id                 u32   required   The file handle to be stat'd
offset             u64   required   The position to seek in the file
whence             str   required   Where to seek relative to (default=SEEK_SET)

Note: valid values for whence

SEEK_SET           Seek relative to start of file
SEEK_CUR           Seek relative to current position in file
SEEK_END           Seek relative (backwards) to end of file

Reply message fields:

offset             u64   optional   The new absolute position within the file

HTSP

General

HTSMSG Binary Format

HTSMSG Binary Format

Root body

HTSMSG-Field

Field encoding for type: map and list

Field encoding for type: s64

Field encoding for type: str

Field encoding for type: bin

Communication

RPC Communication

Streaming Communication

Authentication

Initial Login Authentication

On-Demand Authentication

Client to Server (RPC) methods

hello

authenticate

api

getDiskSpace

getSysTime

enableAsyncMetadata

getChannel

getEvent

getEvents

epgQuery

getEpgObject

getDvrConfigs

addDvrEntry

updateDvrEntry

cancelDvrEntry

deleteDvrEntry

getDvrCutpoints

addAutorecEntry

updateAutorecEntry

deleteAutorecEntry

addTimerecEntry

updateTimerecEntry

deleteTimerecEntry

getTicket

subscribe

unsubscribe

subscriptionChangeWeight

subscriptionSkip

subscriptionSeek

subscriptionSpeed

subscriptionLive

subscriptionFilterStream

getProfiles

getCodecs

fileOpen

fileRead

fileClose

fileStat

fileSeek

Server to Client methods

channelAdd

channelUpdate

channelDelete

tagAdd

tagUpdate

tagDelete

dvrEntryAdd

dvrEntryUpdate

dvrEntryDelete

autorecEntryAdd

autorecEntryUpdate

autorecEntryDelete (Added in version 13)

timerecEntryAdd

timerecEntryUpdate

timerecEntryDelete

eventAdd

eventUpdate

eventDelete

initialSyncCompleted

subscriptionStart

subscriptionGrace

subscriptionStop

subscriptionSkip

HTSP `API` Syntax Summary