Tvheadend

h1. Home Tv Streaming Protocol (HTSP) - Version 21

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

* "TVHGuide":https://github.com/john-tornblom/TVHGuide

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

----

h2. Protocol Changes

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

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

h3. v18..v19

* autorec/timerec structures

** added directory field (forced output directory)

** added enabled field

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

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

h3. v15..v16

* added getProfiles, getDvrConfigs methods

* removed getCodecs methods

* extended subscribe method

** add profile field

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

h3. v13..v14

* added getChannel method

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

h3. v11..v12

* added subscriptionFilterStream method

* added getDvrCutpoints method

h3. v10..v11

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

* added getCodecs method

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.

----

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

<pre>

htspversion        u32   required   Client preferred HTSP version.

clientname         str   required   Client software name.

clientversion      str   required   Client software version.

</pre>

Reply message fields:

<pre>

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

servercapability   str[] required   Server capabilities (Added in version 6)

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

webroot            str   optional   Server HTTP webroot (Added in version 8)

                                    Note: any access to TVH webserver should include this at start of URL path

</pre>

Note: possible values for servercapability[]:

<pre>

cwc                Descrambling available

v4l                Analogue TV available

linuxdvb           Linux DVB API available

imagecache         Image caching available

timeshift          Timeshifting available (Added in version 9).

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

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

</pre>

----

h3. getDiskSpace (Added in version 3)

Return diskspace status from Tvheadend's PVR storage

Request message fields:

<pre>

None

</pre>

Reply message fields:

<pre>

freediskspace      s64   required   Bytes available.

totaldiskspace     s64   required   Total capacity.

</pre>

h3. getSysTime (Added in version 3)

Return system time on the server.

Request message fields:

<pre>

None

</pre>

Reply message fields:

<pre>

time               s64  required   UNIX time.

timezone           s32  required   Minutes west of GMT.

</pre>

----

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

<pre>

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)

</pre>

Reply message fields:

<pre>

None

</pre>

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:

<pre>

tagAdd                   optional

channelAdd               optional

tagUpdate                optional

dvrEntryAdd              optional

eventAdd                 optional   (Added in version 6)

initialSyncComplete      required

</pre>

----

h3. getChannel (Added in version 14)

Request information about the given channel.

Request message fields:

<pre>

channelId          u32   required   Channel ID.

</pre>

Reply message fields:

<pre>

see channelAdd

</pre>

----

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

<pre>

eventId            u32   required   Event ID.

language           str   optional   RFC 2616 compatible language list (Added in version 6)

</pre>

Reply message fields:

<pre>

see eventAdd

</pre>

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

<pre>

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)

</pre>

Reply message fields:

<pre>

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

</pre>

h3. epgQuery (Added in version 4)

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

Request message fields:

<pre>

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

</pre>

Reply message fields:

if full == 1

<pre>

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

</pre>

else

<pre>

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

</pre>

h3. getEpgObject

Get detailed EPG Object info.

Request message fields:

<pre>

id                 u32   required  Object ID

type               u32   optional  Object type

</pre>

Reply message fields:

<pre>

TODO

</pre>

----

h3. getDvrConfigs (Added in version 16)

Return a list of DVR configurations.

Reply message fields:

<pre>

dvrconfigs         msg[]      optional   Supported DVR configurations.

</pre>

Message fields:

<pre>

uuid               str        required   DVR configuration ID

name               str        required   DVR configuration Name

comment            str        required   DVR configuration Comment

</pre>

h3. addDvrEntry (Added in version 4)

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

Request message fields:

<pre>

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

</pre>

Reply message fields:

<pre>

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

</pre>

h3. updateDvrEntry (Added in version 5)

Update an existing DVR entry.

Request message fields:

<pre>

id                 u32   required   DVR Entry ID

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)

</pre>

Reply message fields:

<pre>

success            u32   required   1 if update as successful, otherwise 0

error              str   optional   Error message if update failed

</pre>

h3. cancelDvrEntry (Added in version 5)

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

Request message fields:

<pre>

id                 u32   required   dvrEnryId to delete

</pre>

Reply message fields:

<pre>

success            int   required   1 if entry was cancelled

error              str   optional   Error message if cancellation failed

</pre>

h3. deleteDvrEntry (Added in version 4)

Delete an existing DVR entry from the database.

Request message fields:

<pre>

id                 u32   required   DVR Entry ID

</pre>

Reply message fields:

<pre>

success            u32   required   1 if entry was removed

error              str   optional   Error message if the delete fails

</pre>

h3. getDvrCutpoints (Added in version 12)

Get DVR cutpoints.

Request message fields:

<pre>

id                 u32   required   DVR Entry ID

</pre>

Reply message fields:

<pre>

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

</pre>

Cutpoint fields:

<pre>

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.

</pre>

---

h3. addAutorecEntry (Added in version 13)

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

Request message fields:

<pre>

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.

</pre>

Reply message fields:

<pre>

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

</pre>

h3. deleteAutorecEntry (Added in version 13)

Delete an existing autorec DVR entry from the database.

Request message fields:

<pre>

id                 str   required   Autorec DVR Entry ID (string!)

</pre>

Reply message fields:

<pre>

success            u32   required   1 if entry was removed

error              str   optional   Error message if the delete fails

</pre>

---

h3. addTimerecEntry (Added in version 18)

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

Request message fields:

<pre>

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.

</pre>

Reply message fields:

<pre>

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

</pre>

h3. deleteTimerecEntry (Added in version 18)

Delete an existing timerec DVR entry from the database.

Request message fields:

<pre>

id                 str   required   Timerec DVR Entry ID (string!)

</pre>

Reply message fields:

<pre>

success            u32   required   1 if entry was removed

error              str   optional   Error message if the delete fails

</pre>

----

h3. getTicket (Added in version 5)

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

Request message fields:

<pre>

channelId          u32  optional   Channel to gain access for

dvrId              u32  optional   DVR file to gain access for

</pre>

Reply message fields:

<pre>

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

</pre>

h3. subscribe

Request subscription to the given channel. 

Request message fields:

<pre>

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

</pre>

Reply message fields:

<pre>

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

</pre>

h3. unsubscribe

Stop a subscription.

Request message fields:

<pre>

subscriptionId     u32   required   Subscription ID.

</pre>

Reply message fields:

<pre>

None

</pre>

h3. subscriptionChangeWeight (Added in version 5)

Change the weight of an existing subscription

Request message fields:

<pre>

subscriptionId     u32   required   Subscription ID.

weight             u32   optional   The new subscription weight.

</pre>

Reply message fields:

<pre>

None

</pre>

h3. subscriptionSkip (Added in version 9)

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

Request message fields:

<pre>

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)

</pre>

Reply message fields:

<pre>

None

</pre>

h3. subscriptionSeek (Added in version 9)

Synonym for subscriptionSkip

h3. subscriptionSpeed (Added in version 9)

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

Request message fields:

<pre>

subscriptionId     u32   required   Subscription ID.

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

</pre>

Reply message fields:

<pre>

None

</pre>

h3. subscriptionLive (Added in version 9)

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

Request message fields:

<pre>

subscriptionId     u32   required   Subscription ID.

</pre>

Reply message fields:

<pre>

None

</pre>

h3. subscriptionFilterStream (Added in version 12)

Enable or disable specified streams by index.

Request message fields:

<pre>

subscriptionId     u32        required   Subscription ID.

enable             list[u32]  optional   Enable stream indexes

disable            list[u32]  optional   Disable (filter out) stream indexes

</pre>

Reply message fields:

<pre>

None

</pre>

---

h3. getProfiles (Added in version 16)

Return a list of stream profiles (configurations).

Reply message fields:

<pre>

profiles           msg[]      optional   Supported profiles

</pre>

Message fields:

<pre>

uuid               str        required   Profile ID

name               str        required   Profile Name

comment            str        required   Profile Comment

</pre>

h3. getCodecs (Added in version 11, Removed in version 16)

Return a list of encoders (codecs).

Reply message fields:

<pre>

encoders           list[str]  optional   Supported encoders

</pre>

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

<pre>

file               str   required   File path to open

</pre>

Valid file paths:

<pre>

/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+)

</pre>

Reply message fields:

<pre>

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

</pre>

h3. fileRead (Added in version 8)

Read data from a file.

Request message fields:

<pre>

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)

</pre>

Reply message fields:

<pre>

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

</pre>

h3. fileClose (Added in version 8)

Close an opened file.

Request message fields:

<pre>

id                 u32   required   The file handle to be closed

</pre>

Reply message fields:

<pre>

None

</pre>

h3. fileStat (Added in version 8)

Get status of a file.

Request message fields:

<pre>

id                 u32   required   The file handle to be stat'd

</pre>

Reply message fields:

<pre>

size               u64   optional   The size of the file in bytes

mtime              u64   optional   The last time the file was modified

</pre>

h3. fileSeek (Added in version 8)

Seek to position in a file.

Request message fields:

<pre>

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)

</pre>

Note: valid values for whence

<pre>

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

</pre>

Reply message fields:

<pre>

offset             u64   optional   The new absolute position within the file

</pre>

h1. Server to Client methods

----

h3. channelAdd

A new channel has been created on the server.

Message fields:

<pre>

channelId          u32   required   ID of channel.

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)

</pre>

Service fields:

<pre>

name               str   required   Service name

type               str   required   Service type

caid               u32   optional   Encryption CA ID

caname             str   optional   Encryption CA name

</pre>

h3. channelUpdate

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

h3. channelDelete

A channel has been deleted on the server.

Message fields:

<pre>

channelId          u32   required   ID of channel.

</pre>

----

h3. tagAdd

A new tag has been created on the server.

Message fields:

<pre>

tagId              u32   required   ID of tag.

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

</pre>

h3. tagUpdate

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

h3. tagDelete

A tag has been deleted from the server.

Message fields:

<pre>

tagId              u32   required   ID of tag.

</pre>

----

h3. dvrEntryAdd (Added in version 4)

A new recording has been created on the server.

Message fields:

<pre>

id                 u32   required   ID of dvrEntry.

channel            u32   required   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.

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

</pre>

TODO: recording states

h3. dvrEntryUpdate

Message fields:

<pre>

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

</pre>

h3. dvrEntryDelete (Added in version 4)

A recording has been deleted from the server.

Message fields:

<pre>

id                 u32   required   ID of recording to delete.

</pre>

----

h3. autorecEntryAdd (Added in version 13)

A new autorec recording has been created on the server.

Message fields:

<pre>

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

</pre>

h3. autorecEntryUpdate (Added in version 13)

Message fields:

<pre>

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

</pre>

h3. autorecEntryDelete (Added in version 13)

Message fields:

<pre>

id                 str   required   Autorec Entry ID (string!)

</pre>

----

h3. timerecEntryAdd (Added in version 18)

A new autorec recording has been created on the server.

Message fields:

<pre>

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.

configName         str   required   DVR Configuration Name / UUID.

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.

</pre>

h3. timerecEntryUpdate (Added in version 18)

Message fields:

<pre>

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

</pre>

h3. timerecEntryDelete (Added in version 18)

Message fields:

<pre>

id                 str   required   Timerec Entry ID (string!)

</pre>

----

h3. eventAdd (Added in version 6)

Message fields:

<pre>

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.

</pre>

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

h3. eventUpdate (Added in version 6)

Message fields:

<pre>

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

</pre>

h3. eventDelete (Added in version 6)

Message fields:

<pre>

eventId            u32   required   Event ID

</pre>

---

h3. initialSyncCompleted (Added in version 2)

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

Message fields:

<pre>

</pre>

----

h3. subscriptionStart

Asynchronous message output when a new subscription is successfully started.

Message fields:

<pre>

subscriptionId     u32   required   Subscription ID.

streams            msg[] required   Array of messages with stream information

sourceinfo         msg   optional   Source information.

</pre>

Stream message fields:

<pre>

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)

</pre>

Sourceinfo message fields:

<pre>

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

</pre>

Video Stream types:

<pre>

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)

</pre>