Tvheadend

h1. Home Tv Streaming Protocol (HTSP)

h2. 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 read [[htsmsgbinary|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:

* "XBMC":https://github.com/opdenkamp/xbmc/tree/master/xbmc/pvrclients/tvheadend

* "Showtime":https://github.com/andoma/showtime/tree/master/src/backend/htsp

* "PyHTSP":https://github.com/adamsutton/tvheadend/tree/master/support/htsp.py (This is a demo client and is WIP, it has limited functionality).

----

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

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

<pre>

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.

</pre>

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:

<pre>

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. 

</pre>

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

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

h3. Initial login authentication

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

It may choose to send:

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

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

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

If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based)

the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the

user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.

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

----

h1. Client to Server (RPC) methods

----

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

is to be used.

Request message fields:

<pre>

htspversion      int  required   Client preferred HTSP version. If the server does not support this version

                                 it will respond with an error and also set the 'invalidversion' field in the reply. 

clientname       str  required   Client software name.

clientversion    str  required   Client software version.

</pre>

Reply message fields:

<pre>

htspversion      int  required   The server supports all versions of the protocol up to and including this number.

servername       str  required   Server software name.

serverversion    str  required   Server software version.

challenge        bin  required   32 bytes randomized data used to generate authentication digests

invalidversion   int  optional   If set, this means that the server does not understand the requested version.

                                 The 'error' field is also set to indicate an error.

</pre>

----

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

<pre>

None

</pre>

Reply message fields:

<pre>

None

</pre>

----

h3. enableAsyncMetadata

When this is enabled the client will get continuous updates from the server about channels and tags.

This also includes creation and deletion of channels and tags. 

An interactive application that presents the user with information about channels and tags would probably want to switch to this mode.

Request message fields:

<pre>

None

</pre>

Reply message fields:

<pre>

None

</pre>

----

h3. getEvent

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

Request message fields:

<pre>

eventId          int  required   Event ID.

</pre>

Reply message fields:

<pre>

start            int  required   Start time of event (Seconds since the epoch, in UTC)

stop             int  required   Ending time of event (Seconds since the epoch, in UTC)

title            str  optional   Title of event.

description      str  optional   Description of event. This can be quite huge and may also contain newlines.

channelId        int  required   ID of channel (introduced in HTSP version 4)

nextEventId      int  optional   ID of next event on the same channel.

contentType      int  optional   dvb content code (introduced in HTSP version 4)

dvrId            int  optional   ID of a recording (introduced in HTSP version 5)

</pre>

----

h3. getEvents

Introduced in HTSP version 4.

Request information about numFollowing events, starting with the given event

Request message fields:

<pre>

eventId          int   required   Event ID.

numFollowing     int   required   Number of events to add

</pre>

Reply message fields:

<pre>

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

</pre>

----

h3. addDvrEntry

Introduced in HTSP version 4.

Adds an dvr entry for the given eventId.

Request message fields:

<pre>

eventId          int   required   Event ID.

configName       str   optional   dvr configuration name

</pre>

Reply message fields:

<pre>

success          int   required   1 if entry was added, 0 otherwise

error            str   optional   English clear text of error message

</pre>

----

h3. deleteDvrEntry

Introduced in HTSP version 4.

Delete a dvr entry with the given id.

Request message fields:

<pre>

dvrEntryId       int   required   dvrEnryId to delete

</pre>

Reply message fields:

<pre>

success          int   required   1 if entry was removed

</pre>

----

h3. epgQuery

Introduced in HTSP version 4.

query the epg, optionally restrict to channels/tags/dvb content type

Request message fields:

<pre>

query            str   required  String to query epg for

channelId        int   optional  [[ChannelId]] to restrict search to

tagId            int   optional  [[TagId]] to restrict search to

contentType      int   optional  Dvb epg content type to restrict search to

</pre>

Reply message fields:

<pre>

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

</pre>

----

h3. subscribe

Request subscription to the given channel. 

Request message fields:

<pre>

channelId        int  required   ID for channel. 

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

</pre>

Reply message fields:

<pre>

None.

</pre>

----

h3. unsubscribe

Stop a subscription.

Attributes

<pre>

subscriptionId   int  required   Subscription ID.

</pre>

Reply message fields:

<pre>

None.

</pre>

----

h3. getDiskSpace

Introduced in HTSP version 3.

Return diskspace status from Tvheadend's PVR storage

Attributes

<pre>

</pre>

Reply message fields:

<pre>

freediskspace   int  required   Bytes available.

totaldiskspace  int  required   Total capacity.

</pre>

----

h3. getSysTime

Introduced in HTSP version 3.

Return system time on server

Attributes

<pre>

</pre>

Reply message fields:

<pre>

time            int  required   Seconds since the unix epoch.

timezone        int  required   Minutes west of GMT.

</pre>

----

h1. Server to Client methods

----

h3. channelAdd

A new channel has been created on the server.

Message fields:

<pre>

channelId        int   required   ID of channel.

channelName      str   required   Name of channel.

channelNumber    int   required   Channel number. 0 means unconfigured

channelIcon      str   required   URL to an icon representative for the channel.

eventId          int   optional   ID of the current (or next to be) event on this channel.

tags             int[] optional   Tags this channel is mapped to.

</pre>

----

h3. channelUpdate

A channel has been updated on the server. If a field is not present it has not changed. Most clients can process this and the 'channelAdd' message

with the very same code.

Message fields:

<pre>

channelId        int   required   ID of channel.

channelName      str   optional   Name of channel.

channelNumber    int   optional   Channel number. 0 means unconfigured

channelIcon      str   optioanl   URL to an icon representative for the channel.

eventId          int   optional   ID of the current (or next to be) event on this channel.

tags             int[] required   Tags this channel is mapped to.

</pre>

----

h3. channelDelete

A channel has been deleted on the server.

This message is only sent if session is in asynchronous mode.

Message fields:

<pre>

channelId        int   required   ID of channel.

</pre>

----

h3. tagAdd

A new tag has been created on the server.

Message fields:

<pre>

tagId            int   required   ID of tag.

tagName          str   required   Name of tag.

tagIcon          str   optional   URL to an icon representative for the channel.

members          int[] required   Channels this tag is mapped to.

</pre>

----

h3. tagUpdate

A tag has been updated on the server.

Message fields:

<pre>

tagId            int   required   ID of tag.

tagName          str   required   Name of tag.

tagIcon          str   optional   URL to an icon representative for the channel.

members          int[] required   Channels this tag is mapped to.

</pre>

----

h3. tagDelete

A tag has been deleted from the server.

Message fields:

<pre>

tagId            str   required   ID of tag.

</pre>

----

h3. dvrEntryAdd

A new recording has been created on the server.

Added in HTSP version 4.

Message fields:

<pre>

id               int   required   ID of dvrEntry.

channel          int   required   Channel of dvrEntry.

start            int   required   Time of when this entry was scheduled to start recording.

stop             int   required   Time of when this entry was scheduled to stop recording.

title            str   optional   Title of recording

description      str   optional   Description of recording. This can be quite huge and may also contain newlines.

state            str   required   Plain english status of recoding {scheduled, recording, completed, invalid}.

error            str   optional   Plain english error description (e.g. "Aborted by user").

</pre>

----

h3. dvrEntryUpdate

A recording has been updated on the server

Added in HTSP version 4.

Message fields:

<pre>

id               int   required   ID of dvrEntry.

channel          int   required   Channel of dvrEntry.

start            int   required   Time of when this entry was scheduled to start recording.

stop             int   required   Time of when this entry was scheduled to stop recording.

title            str   optional   Title of recording

description      str   optional   Description of recording. This can be quite huge and may also contain newlines.

state            str   required   Plain english status of recoding {scheduled, recording, completed, invalid}.

error            str   optional   Plain english error description (e.g. "Aborted by user").

</pre>

----

h3. dvrEntryDelete

A recording has been deleted from the server.

Added in HTSP version 4.

Message fields:

<pre>

id               int   required   ID of recording to delete.

</pre>

----

h3. initialSyncCompleted

Sent after all the initial channel and tag messages has been sent when session has been set to async mode.

Added in HTSP version 2.

Message fields:

<pre>

</pre>

----

h3. subscriptionStart

Message fields:

<pre>

subscriptionId   int   required   Subscription ID.

streams          msg[] required   Array of messages with stream information

sourceinfo       msg   optional   Message with strings in it. Each string is a descriptive

                                  entity about the source. All strings are optional any should

                                  only be thought of as informational.

'streams' message:

index            int   required   Index for this stream

type             str   required   Type of stream

language         str   optional   Language for stream

width            int   optional   Width of video in pixels (Video components only)

height           int   optional   Height of video in pixels (Video components only)

Stream types:

    AC3                           AC3 audio

    MPEG2AUDIO                    MPEG2 audio (MP2)

    MPEG2VIDEO                    MPEG2 video

    H264                          H264 video

    AAC                           ADTS framed AAC (one AAC packet per ADTS frame)

</pre>

----

h3. subscriptionStop

Message fields:

<pre>

subscriptionId   int   required   Subscription ID.

reason           str   optional   Reason for subscription stop.

</pre>

----

h3. subscriptionStatus

Message fields:

<pre>

subscriptionId   int   required   Subscription ID.

status           str   optional   English clear text of error status. Absence of this field means that the status is OK. 

</pre>

----

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

<pre>

subscriptionId   int   required   Subscription ID.

packets          int   required   Number of data packets in queue.

bytes            int   required   Number of bytes in queue.

delay            int   optional   Estimated delay of queue (in µs).

Bdrops           int   required   Number of B-frames dropped

Pdrops           int   required   Number of P-frames dropped

Idrops           int   required   Number of I-frames dropped

</pre>

----

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

<pre>

subscriptionId   int   required   Subscription ID.

feStatus         str   required   Frontend status.

feSNR            int   optional   Signal to noise ratio.

feSignal         int   optional   Signal status percentage.

feBER            int   optional   Bit error rate.

feUNC            int   optional   Uncorrected blocks.

</pre>

----

h3. muxpkt

Streaming data.

Message fields:

<pre>

subscriptionId   int   required   Subscription ID.

frametype        int   required   Type of frame as ASCII value: 'I', 'P', 'B'

stream           int   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.

dts              int   optional   Decode Time Stamp in µs.

pts              int   optional   Presentation Time Stamp in µs.

duration         int   required   Duration of frame in µs.

payload          bin   required   Actual frame data.

</pre>