Project

General

Profile

Htsp » History » Version 67

Adam Sutton, 2012-10-12 12:23

1 67 Adam Sutton
h1. Home Tv Streaming Protocol (HTSP) - Version 6
2 1 Andreas Smas
3
h2. General
4 58 sbi -
5
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.
6
7 61 Adam Sutton
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.
8 1 Andreas Smas
9 61 Adam Sutton
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.
10 1 Andreas Smas
(It has been tested with a server in Stockholm and the client in Berlin).
11
12 17 Andreas Smas
For information about the HTSP wire format please read [[htsmsgbinary|HTSMSG binary format]]
13 1 Andreas Smas
14 61 Adam Sutton
If you're looking to develop a new client, there are several existing client implementations from which you might be able to gain knowledge:
15
16
* "XBMC":https://github.com/opdenkamp/xbmc/tree/master/xbmc/pvrclients/tvheadend
17
* "Showtime":https://github.com/andoma/showtime/tree/master/src/backend/htsp
18 65 John Törnblom
* "TVHGuide":https://github.com/john-tornblom/TVHGuide
19 63 Adam Sutton
* "PyHTSP":https://github.com/adamsutton/tvheadend/tree/master/support/htsp.py (This is a demo client and is WIP, it has limited functionality).
20 1 Andreas Smas
21 22 Andreas Smas
----
22 18 Andreas Smas
23 58 sbi -
h2. Communication
24
25
26 17 Andreas Smas
This communication is currently implemented by using htsmsg:s. All strings are encoded as UTF-8.
27 1 Andreas Smas
28
There are two distinct ways for communication within HTSP.
29
30 28 Andreas Smas
Apart from this there is a number of messages that needs to be exchanged during login, see the login section below.
31
32 1 Andreas Smas
33 58 sbi -
h3. RPC communication
34
35
36 1 Andreas Smas
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:
37 18 Andreas Smas
38 17 Andreas Smas
RPC request extra fields:
39 58 sbi -
<pre>
40 28 Andreas Smas
seq              int  optional   Sequence number. This field will be echoed back by the server in the reply.
41 1 Andreas Smas
username         str  optional   Username, in combination with 'digest' this can be used to raise the privileges
42
                                 for the session in combination with invocation of a method. 
43 28 Andreas Smas
digest           bin  optional   Used to raise privileges.
44 58 sbi -
</pre>
45 18 Andreas Smas
46 1 Andreas Smas
The followings field should be used by the client to match the reply with the request.
47
All replies are guaranteed to arrive in the same order as the requests.
48
Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.
49
50
RPC reply extra fields:
51 58 sbi -
<pre>
52 18 Andreas Smas
seq              int  optional   Sequence number. Same as in the request.
53 19 Andreas Smas
error            str  optional   If present an error has occurred and the text describes the error.
54
noaccess         int  optional   If present and set to '1' the user is prohibited from invoking the method due to 
55 1 Andreas Smas
                                 access restrictions. 
56 58 sbi -
</pre>
57 1 Andreas Smas
58 18 Andreas Smas
59 58 sbi -
h3. Streaming communication
60
61
62 19 Andreas Smas
For streaming of live TV and various related messages the server will continuously push data to the client.
63 1 Andreas Smas
These messages are referred to as asynchronous messages and always have the 'method' field set and never have the 'seq' field set.
64
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). 
65
66 34 Andreas Smas
67 58 sbi -
h3. Authentication
68
69
70 29 Andreas Smas
In Tvheadend, each method has an associated access restriction. Currently there is only one restriction (Streaming). However, this may change in the future.
71 1 Andreas Smas
72
Privileges for these restrictions may be granted in two ways: Username + Password and/or Source IP address.
73
Therefore it is possible to gain permissions to the system without entering a username and password.
74
While this is really useful it also complicates the authentication schema a bit.
75
Upon connect the initial privileges will be raised based on the source address.
76
77
Before any username / password based authentication has taken place the client must have
78 34 Andreas Smas
obtained a challenge (which stays fixed for the session). This is done via the 'hello' method.
79 1 Andreas Smas
80
In principle it's possible to use two different authentication idioms with HTSP.
81
Depending on how your application works one or another may be more suitable.
82
While they do not really differ from a protocol point of view it's worth mentioning a bit about them here:
83
84
85 58 sbi -
h3. Initial login authentication
86
87
88 1 Andreas Smas
The client performs all of its authentication using the 'login' method.
89
90
It may choose to send:
91 58 sbi -
* Username and password: Privileges will be raised based on these credentials.
92
* Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.
93
* Nothing: Privileges will be based on just the source address.
94 1 Andreas Smas
95
If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based)
96
the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the
97
user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.
98
99
100 58 sbi -
h3. On-demand authentication
101
102
103 1 Andreas Smas
The client performs all of its authentication when it needs to.
104
105
When using this method, the client will check every RPC reply for the 'noaccess' field.
106
If it set to 1 it whould ask the user for username + password and retry the request but also
107 58 sbi -
add 'username' and 'digest' to the original message. (See _RPC request extra fields_ above)
108 1 Andreas Smas
109
Typically it would not send a username or digest during login.
110 29 Andreas Smas
111
----
112 34 Andreas Smas
113 66 Adam Sutton
h2. Client to Server (RPC) methods
114 34 Andreas Smas
115
h3. hello
116 58 sbi -
117
Used to identify the client toward the server and to get the session challenge used to
118 1 Andreas Smas
hash passwords into digests. The client can request a different version of the HTSP
119 66 Adam Sutton
protocol with this method. If no 'hello' message is sent the server assumes latest version
120 1 Andreas Smas
is to be used.
121 34 Andreas Smas
122 66 Adam Sutton
Client/Server should select lowest common version, if this is not possible connection should be terminated.
123 1 Andreas Smas
124
Request message fields:
125
<pre>
126 66 Adam Sutton
htspversion        u32   required   Client preferred HTSP version.
127
clientname         str   required   Client software name.
128
clientversion      str   required   Client software version.
129 58 sbi -
</pre>
130 1 Andreas Smas
131
Reply message fields:
132 34 Andreas Smas
<pre>
133 66 Adam Sutton
htspversion        u32   required   The server supports all versions of the protocol up to and including this number.
134
servername         str   required   Server software name.
135
serverversion      str   required   Server software version.
136
servercapability   str[] required   Server capabilities (Added in version 6)
137
challenge          bin   required   32 bytes randomized data used to generate authentication digests
138 1 Andreas Smas
</pre>
139
140 58 sbi -
h3. authenticate
141 1 Andreas Smas
142
This can be used to issue authentication without doing anything else.
143
If no privileges are gained it will return with 'noaccess' set to 1.
144
145 33 Andreas Smas
Request message fields:
146 1 Andreas Smas
<pre>
147 66 Adam Sutton
None   
148 33 Andreas Smas
</pre>
149 58 sbi -
150
Reply message fields:
151
<pre>
152 66 Adam Sutton
noaccess           u32   optional   If set to 1, no privileges were granted.
153 33 Andreas Smas
</pre>
154 1 Andreas Smas
155
----
156
157 66 Adam Sutton
h3. getDiskSpace (Added in version 3)
158 58 sbi -
159 66 Adam Sutton
Return diskspace status from Tvheadend's PVR storage
160 1 Andreas Smas
161 66 Adam Sutton
Request message fields:
162
<pre>
163
None
164
</pre>
165 1 Andreas Smas
166 66 Adam Sutton
Reply message fields:
167
<pre>
168
freediskspace      s64   required   Bytes available.
169
totaldiskspace     s64   required   Total capacity.
170
</pre>
171 1 Andreas Smas
172 66 Adam Sutton
h3. getSysTime (Added in version 3)
173 1 Andreas Smas
174 66 Adam Sutton
Return system time on the server.
175
176 1 Andreas Smas
Request message fields:
177
<pre>
178
None
179
</pre>
180
181
Reply message fields:
182 58 sbi -
<pre>
183 66 Adam Sutton
time               s64  required   UNIX time.
184
timezone           s32  required   Minutes west of GMT.
185 1 Andreas Smas
</pre>
186 23 Andreas Smas
187 1 Andreas Smas
----
188
189 66 Adam Sutton
h3. enableAsyncMetadata
190 1 Andreas Smas
191 66 Adam Sutton
When this is enabled the client will get continuous updates from the server about added, update or deleted channels, tags, dvr and epg entries.
192 1 Andreas Smas
193 66 Adam Sutton
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.
194 1 Andreas Smas
195
Request message fields:
196
<pre>
197 66 Adam Sutton
epg                u32   optional   Set to 1, to include EPG data in async, implied by epgMaxTime (Added in version 6).
198
lastUpdate         s64   optional   Only provide metadata that has changed since this time (Added in version 6).
199
epgMaxTime         s64   optional   Maximum time to return EPG data up to (Added in version 6)
200
language           str   optional   RFC 2616 compatible language list (Added in version 6)
201 1 Andreas Smas
</pre>
202
203
Reply message fields:
204
<pre>
205 66 Adam Sutton
None
206 1 Andreas Smas
</pre>
207
208 66 Adam Sutton
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:
209 1 Andreas Smas
210 66 Adam Sutton
<pre>
211
tagAdd                   optional
212
channelAdd               optional
213
tagUpdate                optional
214
dvrEntryAdd              optional
215
eventAdd                 optional   (Added in version 6)
216
initialSyncComplete      required
217
</pre>
218 1 Andreas Smas
219 66 Adam Sutton
----
220 1 Andreas Smas
221 66 Adam Sutton
h3. getEvent
222 1 Andreas Smas
223 66 Adam Sutton
Request information about the given event. An event typically corresponds to a program on a channel.
224 1 Andreas Smas
225 66 Adam Sutton
The language field in the request allows preference for languages to be requested for the various string fields.
226
227 1 Andreas Smas
Request message fields:
228 45 mdd -
<pre>
229 66 Adam Sutton
eventId            u32   required   Event ID.
230
language           str   optional   RFC 2616 compatible language list (Added in version 6)
231 1 Andreas Smas
</pre>
232
233
Reply message fields:
234
<pre>
235 66 Adam Sutton
see eventAdd
236 1 Andreas Smas
</pre>
237
238 66 Adam Sutton
h3. getEvents (Added in version 4)
239 1 Andreas Smas
240 66 Adam Sutton
Request information about a set of events. If no options are specified the entire EPG database will be returned.
241 57 sbi -
242 58 sbi -
Request message fields:
243 1 Andreas Smas
<pre>
244 66 Adam Sutton
eventId            u32   optional   Event ID to begin from (Optional since version 6)
245
channelId          u32   optional   Channel ID to get data for (Added in version 6)
246
numFollowing       u32   optional   Number of events to add (Optional since version 6)
247
maxTime            u64   optional   Maximum time to return data up to (Added in version 6)
248
language           str   optional   RFC 2616 compatible language list (Added in version 6)
249 1 Andreas Smas
</pre>
250
251
Reply message fields:
252
<pre>
253 66 Adam Sutton
events             msg[] required   List of events, using response message fields from eventAdd
254 1 Andreas Smas
</pre>
255 45 mdd -
256 66 Adam Sutton
h3. epgQuery (Added in version 4)
257 1 Andreas Smas
258 66 Adam Sutton
Query the EPG (event titles) and optionally restrict to channel/tag/content type.
259 1 Andreas Smas
260 66 Adam Sutton
Request message fields:
261
<pre>
262
query              str   required  Title regular expression to search for
263
channelId          u32   optional  [[ChannelId]] to restrict search to
264
tagId              u32   optional  [[TagId]] to restrict search to
265
contentType        u32   optional  DVB content type to restrict search to
266
language           str   optional  RFC 2616 compatible language list for title (Added in version 6)
267
full               u32   optional  Output full event list rather than just IDs
268
</pre>
269 1 Andreas Smas
270 66 Adam Sutton
Reply message fields:
271 1 Andreas Smas
272 66 Adam Sutton
if full == 1
273
<pre>
274
events             msg[] optional   List of events, using response message fields from eventAdd
275
</pre>
276
else
277
<pre>
278
eventIds           u32[] optional  List of eventIds that match the query
279
</pre>
280 1 Andreas Smas
281 66 Adam Sutton
h3. getEpgObject
282
283
Get detailed EPG Object info.
284
285 58 sbi -
Request message fields:
286 1 Andreas Smas
<pre>
287 66 Adam Sutton
id                 u32   required  Object ID
288
type               u32   optional  Object type
289 1 Andreas Smas
</pre>
290 58 sbi -
291 1 Andreas Smas
Reply message fields:
292 66 Adam Sutton
293 1 Andreas Smas
<pre>
294 66 Adam Sutton
TODO
295 1 Andreas Smas
</pre>
296
297 58 sbi -
----
298 1 Andreas Smas
299 66 Adam Sutton
h3. addDvrEntry (Added in version 4)
300 1 Andreas Smas
301 66 Adam Sutton
Create a new DVR entry. Either eventId or channelId, start and stop must be specified.
302 1 Andreas Smas
303
Request message fields:
304
<pre>
305 66 Adam Sutton
eventId            u32   optional   Event ID (Optional since version 5).
306
channelId          u32   optional   Channel ID (Added in version 5)
307
start              s64   optional   Time to start recording (Added in version 5)
308
stop               s64   optional   Time to stop recording (Added in version 5)
309
creator            str   optional   Name of the event creator (Added in version 5)
310
priority           u32   optional   Recording priority (Added in version 5)
311
startExtra         s64   optional   Pre-recording buffer in minutes (Added in version 5)
312
stopExtra          s64   optional   Post-recording buffer in minutes (Added in version 5)
313
title              str   optional   Recording title, if no eventId (Added in version 6)
314
description        str   optional   Recording description, if no eventId (Added in version 5)
315
configName         str   optional   DVR configuration name
316 40 Andreas Smas
</pre>
317 1 Andreas Smas
318
Reply message fields:
319
<pre>
320 66 Adam Sutton
success            u32   required   1 if entry was added, 0 otherwise
321
id                 u32   optional   ID of created DVR entry
322
error              str   optional   English clear text of error message
323 1 Andreas Smas
</pre>
324
325 66 Adam Sutton
h3. updateDvrEntry (Added in version 5)
326 1 Andreas Smas
327 66 Adam Sutton
Update an existing DVR entry.
328 1 Andreas Smas
329
Request message fields:
330
<pre>
331 66 Adam Sutton
id                 u32   required   DVR Entry ID
332
start              s64   optional   New start time
333
stop               s64   optional   New stop time
334
title              str   optional   New entry title
335
description        str   optional   New entry description (Added in version 6)
336
startExtra         s64   optional   New pre-record buffer (Added in version 6)
337
stopExtra          s64   optional   New post-record buffer (Added in version 6)
338
configName         str   optional   New DVR configuration name
339 1 Andreas Smas
</pre>
340
341
Reply message fields:
342
<pre>
343 66 Adam Sutton
success            u32   required   1 if update as successful, otherwise 0
344
error              str   optional   Error message if update failed
345 40 Andreas Smas
</pre>
346
347 66 Adam Sutton
h3. cancelDvrEntry (Added in version 5)
348 1 Andreas Smas
349 66 Adam Sutton
Cancel an existing recording, but don't remove the entry from the database.
350 1 Andreas Smas
351 66 Adam Sutton
Request message fields:
352
<pre>
353
id                 u32   required   dvrEnryId to delete
354
</pre>
355 1 Andreas Smas
356 66 Adam Sutton
Reply message fields:
357
<pre>
358
success            int   required   1 if entry was cancelled
359
error              str   optional   Error message if cancellation failed
360
</pre>
361 1 Andreas Smas
362 66 Adam Sutton
h3. deleteDvrEntry (Added in version 4)
363
364
Delete an existing DVR entry from the database.
365
366
Request message fields:
367 1 Andreas Smas
<pre>
368 66 Adam Sutton
id                 u32   required   DVR Entry ID
369 1 Andreas Smas
</pre>
370
371 11 Andreas Smas
Reply message fields:
372 1 Andreas Smas
<pre>
373 66 Adam Sutton
success            u32   required   1 if entry was removed
374
error              str   optional   Error message if the delete fails
375 1 Andreas Smas
</pre>
376
377
----
378
379 66 Adam Sutton
h3. getTicket (Added in version 5)
380 1 Andreas Smas
381 66 Adam Sutton
Get a ticket to allow access to a channel or recording via HTTP
382 1 Andreas Smas
383 66 Adam Sutton
Request message fields:
384 1 Andreas Smas
<pre>
385 66 Adam Sutton
channelId          u32  optional   Channel to gain access for
386
dvrId              u32  optional   DVR file to gain access for
387 1 Andreas Smas
</pre>
388
389
Reply message fields:
390
<pre>
391 66 Adam Sutton
path               str  required   The full path for access URL (no scheme, host or port)
392
ticket             str  required   The ticket to pass in the URL query string
393 1 Andreas Smas
</pre>
394
395 66 Adam Sutton
h3. subscribe
396 1 Andreas Smas
397 66 Adam Sutton
Request subscription to the given channel. 
398 1 Andreas Smas
399 66 Adam Sutton
Request message fields:
400
<pre>
401
channelId          u32   required   ID for channel. 
402
subscriptionId     u32   required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
403
                                    The value is used from now on in all messages related to the subscription.
404
weight             u32   optional   Weighting of this subscription (same as recording priority).
405
</pre>
406 11 Andreas Smas
407 66 Adam Sutton
Reply message fields:
408
<pre>
409
None
410
</pre>
411 1 Andreas Smas
412 66 Adam Sutton
h3. unsubscribe
413
414
Stop a subscription.
415
416
Request message fields:
417 1 Andreas Smas
<pre>
418 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
419 58 sbi -
</pre>
420
421 11 Andreas Smas
Reply message fields:
422 1 Andreas Smas
<pre>
423 66 Adam Sutton
None
424 58 sbi -
</pre>
425 11 Andreas Smas
426 66 Adam Sutton
h3. subscriptionChangeWeight (Added in version 5)
427 1 Andreas Smas
428 66 Adam Sutton
Change the weight of an existing subscription
429 1 Andreas Smas
430 66 Adam Sutton
Request message fields:
431
<pre>
432
subscriptionId     u32   required   Subscription ID.
433
weight             u32   optional   The new subscription weight.
434
</pre>
435 1 Andreas Smas
436 66 Adam Sutton
Reply message fields:
437
<pre>
438
None
439
</pre>
440 1 Andreas Smas
441 66 Adam Sutton
h1. Server to Client methods
442
443 1 Andreas Smas
----
444
445
h3. channelAdd
446
447
A new channel has been created on the server.
448
449
Message fields:
450
<pre>
451 66 Adam Sutton
channelId          u32   required   ID of channel.
452
channelNumber      u32   required   Channel number, 0 means unconfigured.
453
channelName        str   required   Name of channel.
454
channelIcon        str   optional   URL to an icon representative for the channel.
455
eventId            u32   optional   ID of the current event on this channel.
456
nextEventId        u32   optional   ID of the next event on the channel.
457
tags               u32[] optional   Tags this channel is mapped to.
458
services           msg[] optional   List of available services (Added in version 5)
459 13 Andreas Smas
</pre>
460 1 Andreas Smas
461 66 Adam Sutton
Service fields:
462 1 Andreas Smas
<pre>
463 66 Adam Sutton
name               str   required   Service name
464
type               str   required   Service type
465
caid               u32   optional   Encryption CA ID
466
caname             str   optional   Encryption CA name
467 11 Andreas Smas
</pre>
468 1 Andreas Smas
469 66 Adam Sutton
h3. channelUpdate
470 11 Andreas Smas
471 66 Adam Sutton
Same as channelAdd, but all fields (except channelId) are optional.
472
473 58 sbi -
h3. channelDelete
474 1 Andreas Smas
475
A channel has been deleted on the server.
476 58 sbi -
477
Message fields:
478 1 Andreas Smas
<pre>
479 66 Adam Sutton
channelId          u32   required   ID of channel.
480 1 Andreas Smas
</pre>
481
482
----
483
484
h3. tagAdd
485 11 Andreas Smas
486 1 Andreas Smas
A new tag has been created on the server.
487
488
Message fields:
489
<pre>
490 66 Adam Sutton
tagId              u32   required   ID of tag.
491
tagName            str   required   Name of tag.
492
tagIcon            str   optional   URL to an icon representative for the channel.
493
tagTitledIcon      u32   optional   Icon includes a title
494
members            u32[] optional   Channel IDs of those that belong to the tag
495 1 Andreas Smas
</pre>
496 11 Andreas Smas
497 39 elupus -
h3. tagUpdate
498 58 sbi -
499 66 Adam Sutton
Same as tagAdd, but all fields (except tagId) are optional.
500 11 Andreas Smas
501
h3. tagDelete
502 1 Andreas Smas
503 58 sbi -
A tag has been deleted from the server.
504 1 Andreas Smas
505
Message fields:
506
<pre>
507 66 Adam Sutton
tagId              u32   required   ID of tag.
508 58 sbi -
</pre>
509
510 12 Andreas Smas
----
511 1 Andreas Smas
512 66 Adam Sutton
h3. dvrEntryAdd (Added in version 4)
513 58 sbi -
514 1 Andreas Smas
A new recording has been created on the server.
515 58 sbi -
516 1 Andreas Smas
Message fields:
517 2 Andreas Smas
<pre>
518 66 Adam Sutton
id                 u32   required   ID of dvrEntry.
519
channel            u32   required   Channel of dvrEntry.
520
start              s64   required   Time of when this entry was scheduled to start recording.
521
stop               s64   required   Time of when this entry was scheduled to stop recording.
522
eventId            u32   optional   Associated EPG Event ID.
523
title              str   optional   Title of recording
524
summary            str   optional   Short description of the recording (Added in version 6).
525
description        str   optional   Long description of the recording.
526
state              str   required   Recording state
527
error              str   optional   Plain english error description (e.g. "Aborted by user").
528 48 mdd -
</pre>
529 1 Andreas Smas
530 66 Adam Sutton
TODO: recording states
531 48 mdd -
532
h3. dvrEntryUpdate
533
534 66 Adam Sutton
Message fields:
535
<pre>
536
Same as dvrEntryAdd, but all fields (except id) are optional.
537
</pre>
538 51 elupus -
539 66 Adam Sutton
h3. dvrEntryDelete (Added in version 4)
540 58 sbi -
541 66 Adam Sutton
A recording has been deleted from the server.
542 58 sbi -
543 48 mdd -
Message fields:
544
<pre>
545 66 Adam Sutton
id                 u32   required   ID of recording to delete.
546 1 Andreas Smas
</pre>
547 48 mdd -
548 58 sbi -
----
549 48 mdd -
550 66 Adam Sutton
h3. eventAdd (Added in version 6)
551 48 mdd -
552 66 Adam Sutton
Message fields:
553
<pre>
554
eventId            u32   required   Event ID
555
channelId          u32   required   The channel this event is related to.
556
start              u64   required   Start time of event, UNIX time.
557
stop               u64   required   Ending time of event, UNIX time.
558
title              str   optional   Title of event.
559
summary            str   optional   Short description of the event (Added in version 6).
560
description        str   optional   Long description of the event.
561
serieslinkId       u32   optional   Series Link ID (Added in version 6).
562
episodeId          u32   optional   Episode ID (Added in version 6).
563
seasonId           u32   optional   Season ID (Added in version 6).
564
brandId            u32   optional   Brand ID (Added in version 6).
565
contentType        u32   optional   DVB content code (Added in version 4, Modified in version 6*).
566
ageRating          u32   optional   Minimum age rating (Added in version 6).
567
starRating         u32   optional   Star rating (1-5) (Added in version 6).
568
firstAired         s64   optional   Original broadcast time, UNIX time (Added in version 6).
569
seasonNumber       u32   optional   Season number (Added in version 6).
570
seasonCount        u32   optional   Show season count (Added in version 6).
571
episodeNumber      u32   optional   Episode number (Added in version 6).
572
episodeCount       u32   optional   Season episode count (Added in version 6).
573
partNumber         u32   optional   Multi-part episode part number (Added in version 6).
574
partCount          u32   optional   Multi-part episode part count (Added in version 6).
575
episodeOnscreen    str   optional   Textual representation of episode number (Added in version 6).
576
image              str   optional   URL to a still capture from the episode (Added in version 6).
577
dvrId              u32   optional   ID of a recording (Added in version 5).
578
nextEventId        u32   optional   ID of next event on the same channel.
579
</pre>
580 48 mdd -
581 66 Adam Sutton
* *contentType previously had the major DVB category in the bottom 4 bits, 
582
  however in v6 this has been changed to properly match DVB, so top 4 bits
583
  as major category and bottom 4 bits has sub-category. Clients requesting
584
  v5 or lower will get the old output.
585 48 mdd -
586 66 Adam Sutton
h3. eventUpdate (Added in version 6)
587 35 Andreas Smas
588 58 sbi -
Message fields:
589
<pre>
590 66 Adam Sutton
Same as eventAdd but all fields (except eventId) are optional.
591 35 Andreas Smas
</pre>
592 58 sbi -
593 66 Adam Sutton
h3. eventDeleted (Added in version 6)
594 35 Andreas Smas
595 66 Adam Sutton
Message fields:
596
<pre>
597
eventId            u32   required   Event ID
598
</pre>
599 14 Andreas Smas
600 66 Adam Sutton
---
601 14 Andreas Smas
602 66 Adam Sutton
h3. initialSyncCompleted (Added in version 2)
603 14 Andreas Smas
604 66 Adam Sutton
Sent after all the initial metadata has been sent when session has been set to async mode.
605 38 Andreas Smas
606
Message fields:
607 14 Andreas Smas
<pre>
608
</pre>
609
610
----
611
612
h3. subscriptionStart
613 53 Andreas Smas
614 66 Adam Sutton
Asynchronous message output when a new subscription is successfully started.
615 14 Andreas Smas
616
Message fields:
617 1 Andreas Smas
<pre>
618 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
619
streams            msg[] required   Array of messages with stream information
620
sourceinfo         msg   optional   Source information.
621
</pre>
622 37 Andreas Smas
623 66 Adam Sutton
Stream message fields:
624
<pre>
625
index              u32   required   Index for this stream
626
type               str   required   Type of stream
627
language           str   optional   Language for stream
628
Video components only:
629
width              u32   optional   Width of video in pixels
630
height             u32   optional   Height of video in pixels
631
aspect_num         u32   optional   Aspect ratio numerator (Added in version 5)
632
aspect_den         u32   optional   Aspect ratio denonminator (Added in version 5)
633
Audio components only:
634
channels           u32   optional   Number of audio channels (Added in version 5)
635
rate               u32   optional   Audio bitrate (Added in version 5)
636
Subtitle components only:
637
composition_id     u32   optional   ??? (Added in version 5)
638
ancillary_id       u32   optional   ??? (Added in version 5)
639
</pre>
640 2 Andreas Smas
641 66 Adam Sutton
Sourceinfo message fields:
642
<pre>
643
adapter            str   optional   Adapter name
644
mux                str   optional   Transponder name
645
network            str   optional   Network name
646
provider           str   optional   ???
647
service            str   optional   Service name
648
</pre>
649 15 Andreas Smas
650 66 Adam Sutton
Video Stream types:
651
<pre>
652
MPEG2VIDEO                    MPEG2 video
653
H264                          H264 video
654
</pre>
655 15 Andreas Smas
656 66 Adam Sutton
Audio Stream types:
657
<pre>
658
MPEG2AUDIO                    MPEG2 audio (MP2)
659
AC3                           AC3 audio
660
AAC                           ADTS framed AAC (one AAC packet per ADTS frame)
661
EAC3                          Enhanced AC3 audio
662 16 Andreas Smas
</pre>
663
664 66 Adam Sutton
Subtitle Stream types:
665
<pre>
666
TELETEXT                      ???
667
DVBSUB                        ???
668
</pre>
669 55 Lars Op den Kamp -
670
h3. subscriptionStop
671
672 66 Adam Sutton
A subscription has been stopped.
673 55 Lars Op den Kamp -
674
Message fields:
675
<pre>
676 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
677
status             str   optional   Error message if subscription stopped unexpectedly.
678 55 Lars Op den Kamp -
</pre>
679 58 sbi -
680 55 Lars Op den Kamp -
h3. subscriptionStatus
681
682 66 Adam Sutton
Subscription status update.
683 58 sbi -
684
Message fields:
685
<pre>
686 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
687
status             str   optional   English clear text of error status. Absence of this field means that the status is OK. 
688 16 Andreas Smas
</pre>
689 58 sbi -
690 16 Andreas Smas
h3. queueStatus
691
692 1 Andreas Smas
The queueStatus message is sent every second during normal data delivery.
693 60 John Törnblom
694
The transmit scheduler have different drop thresholds for different frame types.
695 66 Adam Sutton
696 1 Andreas Smas
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
697
All audio is recognized as I-frames. 
698 58 sbi -
699 1 Andreas Smas
Message fields:
700
<pre>
701 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
702
packets            u32   required   Number of data packets in queue.
703
bytes              u32   required   Number of bytes in queue.
704
delay              u32   optional   Estimated delay of queue (in µs).
705
Bdrops             u32   required   Number of B-frames dropped
706
Pdrops             u32   required   Number of P-frames dropped
707
Idrops             u32   required   Number of I-frames dropped
708 1 Andreas Smas
</pre>
709
710
h3. signalStatus
711
712
The signalStatus message is sent every second during normal data delivery.
713
714
The optional fields may not have been implemented or may not be supported by the active adapter.
715
716
Message fields:
717
<pre>
718 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
719
feStatus           str   required   Frontend status.
720
feSNR              u32   optional   Signal to noise ratio.
721
feSignal           u32   optional   Signal status percentage.
722
feBER              u32   optional   Bit error rate.
723
feUNC              u32   optional   Uncorrected blocks.
724 1 Andreas Smas
</pre>
725
726
h3. muxpkt
727
728
Streaming data.
729
730
Message fields:
731
<pre>
732 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
733
frametype          u32   required   Type of frame as ASCII value: 'I', 'P', 'B'
734
stream             u32   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
735
dts                s64   optional   Decode Time Stamp in µs.
736
pts                s64   optional   Presentation Time Stamp in µs.
737
duration           u32   required   Duration of frame in µs.
738
payload            bin   required   Actual frame data.
739 1 Andreas Smas
</pre>