Project

General

Profile

Htsp » History » Version 72

Adam Sutton, 2013-04-04 22:01

1 71 Adam Sutton
h1. Home Tv Streaming Protocol (HTSP) - Version 8
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 69 Adam Sutton
* "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).
20 1 Andreas Smas
21 22 Andreas Smas
----
22 18 Andreas Smas
23 58 sbi -
h2. Communication
24
25
26 69 Adam Sutton
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 70 Adam Sutton
Note: possible values for servercapability[]:
141
<pre>
142
cwc                Descrambling available
143
v4l                Analogue TV available
144
linuxdvb           Linux DVB API available
145
imagecache         Image caching available
146
</pre>
147
148 58 sbi -
h3. authenticate
149 1 Andreas Smas
150
This can be used to issue authentication without doing anything else.
151
If no privileges are gained it will return with 'noaccess' set to 1.
152
153 33 Andreas Smas
Request message fields:
154 1 Andreas Smas
<pre>
155 66 Adam Sutton
None   
156 33 Andreas Smas
</pre>
157 58 sbi -
158
Reply message fields:
159
<pre>
160 66 Adam Sutton
noaccess           u32   optional   If set to 1, no privileges were granted.
161 33 Andreas Smas
</pre>
162 1 Andreas Smas
163
----
164
165 66 Adam Sutton
h3. getDiskSpace (Added in version 3)
166 58 sbi -
167 66 Adam Sutton
Return diskspace status from Tvheadend's PVR storage
168 1 Andreas Smas
169 66 Adam Sutton
Request message fields:
170
<pre>
171
None
172
</pre>
173 1 Andreas Smas
174 66 Adam Sutton
Reply message fields:
175
<pre>
176
freediskspace      s64   required   Bytes available.
177
totaldiskspace     s64   required   Total capacity.
178
</pre>
179 1 Andreas Smas
180 66 Adam Sutton
h3. getSysTime (Added in version 3)
181 1 Andreas Smas
182 66 Adam Sutton
Return system time on the server.
183
184 1 Andreas Smas
Request message fields:
185
<pre>
186
None
187
</pre>
188
189
Reply message fields:
190 58 sbi -
<pre>
191 66 Adam Sutton
time               s64  required   UNIX time.
192
timezone           s32  required   Minutes west of GMT.
193 1 Andreas Smas
</pre>
194 23 Andreas Smas
195 1 Andreas Smas
----
196
197 66 Adam Sutton
h3. enableAsyncMetadata
198 1 Andreas Smas
199 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.
200 1 Andreas Smas
201 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.
202 1 Andreas Smas
203
Request message fields:
204
<pre>
205 66 Adam Sutton
epg                u32   optional   Set to 1, to include EPG data in async, implied by epgMaxTime (Added in version 6).
206
lastUpdate         s64   optional   Only provide metadata that has changed since this time (Added in version 6).
207
epgMaxTime         s64   optional   Maximum time to return EPG data up to (Added in version 6)
208
language           str   optional   RFC 2616 compatible language list (Added in version 6)
209 1 Andreas Smas
</pre>
210
211
Reply message fields:
212
<pre>
213 66 Adam Sutton
None
214 1 Andreas Smas
</pre>
215
216 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:
217 1 Andreas Smas
218 66 Adam Sutton
<pre>
219
tagAdd                   optional
220
channelAdd               optional
221
tagUpdate                optional
222
dvrEntryAdd              optional
223
eventAdd                 optional   (Added in version 6)
224
initialSyncComplete      required
225
</pre>
226 1 Andreas Smas
227 66 Adam Sutton
----
228 1 Andreas Smas
229 66 Adam Sutton
h3. getEvent
230 1 Andreas Smas
231 66 Adam Sutton
Request information about the given event. An event typically corresponds to a program on a channel.
232 1 Andreas Smas
233 66 Adam Sutton
The language field in the request allows preference for languages to be requested for the various string fields.
234
235 1 Andreas Smas
Request message fields:
236 45 mdd -
<pre>
237 66 Adam Sutton
eventId            u32   required   Event ID.
238
language           str   optional   RFC 2616 compatible language list (Added in version 6)
239 1 Andreas Smas
</pre>
240
241
Reply message fields:
242
<pre>
243 66 Adam Sutton
see eventAdd
244 1 Andreas Smas
</pre>
245
246 66 Adam Sutton
h3. getEvents (Added in version 4)
247 1 Andreas Smas
248 66 Adam Sutton
Request information about a set of events. If no options are specified the entire EPG database will be returned.
249 57 sbi -
250 58 sbi -
Request message fields:
251 1 Andreas Smas
<pre>
252 66 Adam Sutton
eventId            u32   optional   Event ID to begin from (Optional since version 6)
253
channelId          u32   optional   Channel ID to get data for (Added in version 6)
254
numFollowing       u32   optional   Number of events to add (Optional since version 6)
255
maxTime            u64   optional   Maximum time to return data up to (Added in version 6)
256
language           str   optional   RFC 2616 compatible language list (Added in version 6)
257 1 Andreas Smas
</pre>
258
259
Reply message fields:
260
<pre>
261 66 Adam Sutton
events             msg[] required   List of events, using response message fields from eventAdd
262 1 Andreas Smas
</pre>
263 45 mdd -
264 66 Adam Sutton
h3. epgQuery (Added in version 4)
265 1 Andreas Smas
266 66 Adam Sutton
Query the EPG (event titles) and optionally restrict to channel/tag/content type.
267 1 Andreas Smas
268 66 Adam Sutton
Request message fields:
269
<pre>
270
query              str   required  Title regular expression to search for
271
channelId          u32   optional  [[ChannelId]] to restrict search to
272
tagId              u32   optional  [[TagId]] to restrict search to
273
contentType        u32   optional  DVB content type to restrict search to
274
language           str   optional  RFC 2616 compatible language list for title (Added in version 6)
275
full               u32   optional  Output full event list rather than just IDs
276
</pre>
277 1 Andreas Smas
278 66 Adam Sutton
Reply message fields:
279 1 Andreas Smas
280 66 Adam Sutton
if full == 1
281
<pre>
282
events             msg[] optional   List of events, using response message fields from eventAdd
283
</pre>
284
else
285
<pre>
286
eventIds           u32[] optional  List of eventIds that match the query
287
</pre>
288 1 Andreas Smas
289 66 Adam Sutton
h3. getEpgObject
290
291
Get detailed EPG Object info.
292
293 58 sbi -
Request message fields:
294 1 Andreas Smas
<pre>
295 66 Adam Sutton
id                 u32   required  Object ID
296
type               u32   optional  Object type
297 1 Andreas Smas
</pre>
298 58 sbi -
299 1 Andreas Smas
Reply message fields:
300 66 Adam Sutton
301 1 Andreas Smas
<pre>
302 66 Adam Sutton
TODO
303 1 Andreas Smas
</pre>
304
305 58 sbi -
----
306 1 Andreas Smas
307 66 Adam Sutton
h3. addDvrEntry (Added in version 4)
308 1 Andreas Smas
309 66 Adam Sutton
Create a new DVR entry. Either eventId or channelId, start and stop must be specified.
310 1 Andreas Smas
311
Request message fields:
312
<pre>
313 66 Adam Sutton
eventId            u32   optional   Event ID (Optional since version 5).
314
channelId          u32   optional   Channel ID (Added in version 5)
315
start              s64   optional   Time to start recording (Added in version 5)
316
stop               s64   optional   Time to stop recording (Added in version 5)
317
creator            str   optional   Name of the event creator (Added in version 5)
318
priority           u32   optional   Recording priority (Added in version 5)
319
startExtra         s64   optional   Pre-recording buffer in minutes (Added in version 5)
320
stopExtra          s64   optional   Post-recording buffer in minutes (Added in version 5)
321
title              str   optional   Recording title, if no eventId (Added in version 6)
322
description        str   optional   Recording description, if no eventId (Added in version 5)
323
configName         str   optional   DVR configuration name
324 40 Andreas Smas
</pre>
325 1 Andreas Smas
326
Reply message fields:
327
<pre>
328 66 Adam Sutton
success            u32   required   1 if entry was added, 0 otherwise
329
id                 u32   optional   ID of created DVR entry
330
error              str   optional   English clear text of error message
331 1 Andreas Smas
</pre>
332
333 66 Adam Sutton
h3. updateDvrEntry (Added in version 5)
334 1 Andreas Smas
335 66 Adam Sutton
Update an existing DVR entry.
336 1 Andreas Smas
337
Request message fields:
338
<pre>
339 66 Adam Sutton
id                 u32   required   DVR Entry ID
340
start              s64   optional   New start time
341
stop               s64   optional   New stop time
342
title              str   optional   New entry title
343
description        str   optional   New entry description (Added in version 6)
344
startExtra         s64   optional   New pre-record buffer (Added in version 6)
345
stopExtra          s64   optional   New post-record buffer (Added in version 6)
346
configName         str   optional   New DVR configuration name
347 1 Andreas Smas
</pre>
348
349
Reply message fields:
350
<pre>
351 66 Adam Sutton
success            u32   required   1 if update as successful, otherwise 0
352
error              str   optional   Error message if update failed
353 40 Andreas Smas
</pre>
354
355 66 Adam Sutton
h3. cancelDvrEntry (Added in version 5)
356 1 Andreas Smas
357 66 Adam Sutton
Cancel an existing recording, but don't remove the entry from the database.
358 1 Andreas Smas
359 66 Adam Sutton
Request message fields:
360
<pre>
361
id                 u32   required   dvrEnryId to delete
362
</pre>
363 1 Andreas Smas
364 66 Adam Sutton
Reply message fields:
365
<pre>
366
success            int   required   1 if entry was cancelled
367
error              str   optional   Error message if cancellation failed
368
</pre>
369 1 Andreas Smas
370 66 Adam Sutton
h3. deleteDvrEntry (Added in version 4)
371
372
Delete an existing DVR entry from the database.
373
374
Request message fields:
375 1 Andreas Smas
<pre>
376 66 Adam Sutton
id                 u32   required   DVR Entry ID
377 1 Andreas Smas
</pre>
378
379 11 Andreas Smas
Reply message fields:
380 1 Andreas Smas
<pre>
381 66 Adam Sutton
success            u32   required   1 if entry was removed
382
error              str   optional   Error message if the delete fails
383 1 Andreas Smas
</pre>
384
385
----
386
387 66 Adam Sutton
h3. getTicket (Added in version 5)
388 1 Andreas Smas
389 66 Adam Sutton
Get a ticket to allow access to a channel or recording via HTTP
390 1 Andreas Smas
391 66 Adam Sutton
Request message fields:
392 1 Andreas Smas
<pre>
393 66 Adam Sutton
channelId          u32  optional   Channel to gain access for
394
dvrId              u32  optional   DVR file to gain access for
395 1 Andreas Smas
</pre>
396
397
Reply message fields:
398
<pre>
399 66 Adam Sutton
path               str  required   The full path for access URL (no scheme, host or port)
400
ticket             str  required   The ticket to pass in the URL query string
401 1 Andreas Smas
</pre>
402
403 66 Adam Sutton
h3. subscribe
404 1 Andreas Smas
405 66 Adam Sutton
Request subscription to the given channel. 
406 1 Andreas Smas
407 66 Adam Sutton
Request message fields:
408
<pre>
409
channelId          u32   required   ID for channel. 
410
subscriptionId     u32   required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
411
                                    The value is used from now on in all messages related to the subscription.
412
weight             u32   optional   Weighting of this subscription (same as recording priority).
413
</pre>
414 11 Andreas Smas
415 66 Adam Sutton
Reply message fields:
416
<pre>
417
None
418
</pre>
419 1 Andreas Smas
420 66 Adam Sutton
h3. unsubscribe
421
422
Stop a subscription.
423
424
Request message fields:
425 1 Andreas Smas
<pre>
426 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
427 58 sbi -
</pre>
428
429 11 Andreas Smas
Reply message fields:
430 1 Andreas Smas
<pre>
431 66 Adam Sutton
None
432 58 sbi -
</pre>
433 11 Andreas Smas
434 66 Adam Sutton
h3. subscriptionChangeWeight (Added in version 5)
435 1 Andreas Smas
436 66 Adam Sutton
Change the weight of an existing subscription
437 1 Andreas Smas
438 66 Adam Sutton
Request message fields:
439
<pre>
440
subscriptionId     u32   required   Subscription ID.
441
weight             u32   optional   The new subscription weight.
442 1 Andreas Smas
</pre>
443
444
Reply message fields:
445
<pre>
446 69 Adam Sutton
None
447
</pre>
448 1 Andreas Smas
449 70 Adam Sutton
h3. fileOpen (Added in version 8)
450 69 Adam Sutton
451
Open a file within the Tvheadend file system. This is now the preferred method (in place of HTTP) for accessing recordings.
452
453
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.
454
455 1 Andreas Smas
Request message fields:
456 69 Adam Sutton
<pre>
457 70 Adam Sutton
file               str   required   File path to open
458 1 Andreas Smas
</pre>
459
460 70 Adam Sutton
Valid file paths:
461
<pre>
462
/dvrfile/ID        will open the file associated with DVR entry ID
463
/imagecache/ID     will open the file associated with imagecache entry ID
464
</pre>
465
466 69 Adam Sutton
Reply message fields:
467
<pre>
468
id                 u32   required   The file handle used for further file operations
469
size               u64   optional   The size of the file in bytes
470 1 Andreas Smas
mtime              u64   optional   The last time the file was modified
471 69 Adam Sutton
</pre>
472
473 70 Adam Sutton
h3. fileRead (Added in version 8)
474 69 Adam Sutton
475 1 Andreas Smas
Read data from a file.
476
477 69 Adam Sutton
Request message fields:
478
<pre>
479
id                 u32   required   The file handle used for further file operations
480 70 Adam Sutton
size               u64   required   The amount of data to read
481
offset             u64   optional   Offset into the file to read (default is current position)
482 69 Adam Sutton
</pre>
483 1 Andreas Smas
484 69 Adam Sutton
Reply message fields:
485
<pre>
486
data               bin   required   The data read from the file (size may be less than requested)
487
</pre>
488
489 70 Adam Sutton
h3. fileClose (Added in version 8)
490 69 Adam Sutton
491
Close an opened file.
492
493
Request message fields:
494
<pre>
495
id                 u32   required   The file handle to be closed
496 1 Andreas Smas
</pre>
497 69 Adam Sutton
498
Reply message fields:
499
<pre>
500
None
501
</pre>
502
503 70 Adam Sutton
h3. fileStat (Added in version 8)
504 69 Adam Sutton
505
Get status of a file.
506
507
Request message fields:
508
<pre>
509
id                 u32   required   The file handle to be stat'd
510
</pre>
511 1 Andreas Smas
512
Reply message fields:
513
<pre>
514
size               u64   optional   The size of the file in bytes
515
mtime              u64   optional   The last time the file was modified
516
</pre>
517
518 70 Adam Sutton
h3. fileSeek (Added in version 8)
519
520
Seek to position in a file.
521
522
Request message fields:
523
<pre>
524
id                 u32   required   The file handle to be stat'd
525
offset             u64   required   The position to seek in the file
526
whence             str   required   Where to seek relative to (default=SEEK_SET)
527
</pre>
528
529
Note: valid values for whence
530
<pre>
531
SEEK_SET           Seek relative to start of file
532
SEEK_CUR           Seek relative to current position in file
533
SEEK_END           Seek relative (backwards) to end of file
534 72 Adam Sutton
</pre>
535 70 Adam Sutton
536
Reply message fields:
537
<pre>
538
offset             u64   optional   The new absolute position within the file
539
</pre>
540
541 66 Adam Sutton
h1. Server to Client methods
542 1 Andreas Smas
543
----
544
545
h3. channelAdd
546
547
A new channel has been created on the server.
548
549
Message fields:
550
<pre>
551
channelId          u32   required   ID of channel.
552
channelNumber      u32   required   Channel number, 0 means unconfigured.
553 66 Adam Sutton
channelName        str   required   Name of channel.
554 70 Adam Sutton
channelIcon        str   optional   URL to an icon representative for the channel
555
                                    (For v8+ clients this could be a relative /imagecache/ID URL
556
                                     intended to be fed to fileOpen().)
557 66 Adam Sutton
eventId            u32   optional   ID of the current event on this channel.
558
nextEventId        u32   optional   ID of the next event on the channel.
559
tags               u32[] optional   Tags this channel is mapped to.
560
services           msg[] optional   List of available services (Added in version 5)
561 13 Andreas Smas
</pre>
562 1 Andreas Smas
563 66 Adam Sutton
Service fields:
564 1 Andreas Smas
<pre>
565 66 Adam Sutton
name               str   required   Service name
566
type               str   required   Service type
567
caid               u32   optional   Encryption CA ID
568
caname             str   optional   Encryption CA name
569 11 Andreas Smas
</pre>
570 1 Andreas Smas
571 66 Adam Sutton
h3. channelUpdate
572 11 Andreas Smas
573 66 Adam Sutton
Same as channelAdd, but all fields (except channelId) are optional.
574
575 58 sbi -
h3. channelDelete
576 1 Andreas Smas
577
A channel has been deleted on the server.
578 58 sbi -
579
Message fields:
580 1 Andreas Smas
<pre>
581 66 Adam Sutton
channelId          u32   required   ID of channel.
582 1 Andreas Smas
</pre>
583
584
----
585
586
h3. tagAdd
587 11 Andreas Smas
588 1 Andreas Smas
A new tag has been created on the server.
589
590
Message fields:
591
<pre>
592 66 Adam Sutton
tagId              u32   required   ID of tag.
593
tagName            str   required   Name of tag.
594
tagIcon            str   optional   URL to an icon representative for the channel.
595
tagTitledIcon      u32   optional   Icon includes a title
596
members            u32[] optional   Channel IDs of those that belong to the tag
597 1 Andreas Smas
</pre>
598 11 Andreas Smas
599 39 elupus -
h3. tagUpdate
600 58 sbi -
601 66 Adam Sutton
Same as tagAdd, but all fields (except tagId) are optional.
602 11 Andreas Smas
603
h3. tagDelete
604 1 Andreas Smas
605 58 sbi -
A tag has been deleted from the server.
606 1 Andreas Smas
607
Message fields:
608
<pre>
609 66 Adam Sutton
tagId              u32   required   ID of tag.
610 58 sbi -
</pre>
611
612 12 Andreas Smas
----
613 1 Andreas Smas
614 66 Adam Sutton
h3. dvrEntryAdd (Added in version 4)
615 58 sbi -
616 1 Andreas Smas
A new recording has been created on the server.
617 58 sbi -
618 1 Andreas Smas
Message fields:
619 2 Andreas Smas
<pre>
620 66 Adam Sutton
id                 u32   required   ID of dvrEntry.
621
channel            u32   required   Channel of dvrEntry.
622
start              s64   required   Time of when this entry was scheduled to start recording.
623
stop               s64   required   Time of when this entry was scheduled to stop recording.
624
eventId            u32   optional   Associated EPG Event ID.
625
title              str   optional   Title of recording
626
summary            str   optional   Short description of the recording (Added in version 6).
627
description        str   optional   Long description of the recording.
628
state              str   required   Recording state
629
error              str   optional   Plain english error description (e.g. "Aborted by user").
630 48 mdd -
</pre>
631 1 Andreas Smas
632 66 Adam Sutton
TODO: recording states
633 48 mdd -
634
h3. dvrEntryUpdate
635
636 66 Adam Sutton
Message fields:
637
<pre>
638
Same as dvrEntryAdd, but all fields (except id) are optional.
639
</pre>
640 51 elupus -
641 66 Adam Sutton
h3. dvrEntryDelete (Added in version 4)
642 58 sbi -
643 66 Adam Sutton
A recording has been deleted from the server.
644 58 sbi -
645 48 mdd -
Message fields:
646
<pre>
647 66 Adam Sutton
id                 u32   required   ID of recording to delete.
648 1 Andreas Smas
</pre>
649 48 mdd -
650 58 sbi -
----
651 48 mdd -
652 66 Adam Sutton
h3. eventAdd (Added in version 6)
653 48 mdd -
654 66 Adam Sutton
Message fields:
655
<pre>
656
eventId            u32   required   Event ID
657
channelId          u32   required   The channel this event is related to.
658
start              u64   required   Start time of event, UNIX time.
659
stop               u64   required   Ending time of event, UNIX time.
660
title              str   optional   Title of event.
661
summary            str   optional   Short description of the event (Added in version 6).
662
description        str   optional   Long description of the event.
663
serieslinkId       u32   optional   Series Link ID (Added in version 6).
664
episodeId          u32   optional   Episode ID (Added in version 6).
665
seasonId           u32   optional   Season ID (Added in version 6).
666
brandId            u32   optional   Brand ID (Added in version 6).
667
contentType        u32   optional   DVB content code (Added in version 4, Modified in version 6*).
668
ageRating          u32   optional   Minimum age rating (Added in version 6).
669
starRating         u32   optional   Star rating (1-5) (Added in version 6).
670
firstAired         s64   optional   Original broadcast time, UNIX time (Added in version 6).
671
seasonNumber       u32   optional   Season number (Added in version 6).
672
seasonCount        u32   optional   Show season count (Added in version 6).
673
episodeNumber      u32   optional   Episode number (Added in version 6).
674
episodeCount       u32   optional   Season episode count (Added in version 6).
675
partNumber         u32   optional   Multi-part episode part number (Added in version 6).
676
partCount          u32   optional   Multi-part episode part count (Added in version 6).
677
episodeOnscreen    str   optional   Textual representation of episode number (Added in version 6).
678
image              str   optional   URL to a still capture from the episode (Added in version 6).
679
dvrId              u32   optional   ID of a recording (Added in version 5).
680
nextEventId        u32   optional   ID of next event on the same channel.
681
</pre>
682 48 mdd -
683 66 Adam Sutton
* *contentType previously had the major DVB category in the bottom 4 bits, 
684
  however in v6 this has been changed to properly match DVB, so top 4 bits
685
  as major category and bottom 4 bits has sub-category. Clients requesting
686
  v5 or lower will get the old output.
687 48 mdd -
688 66 Adam Sutton
h3. eventUpdate (Added in version 6)
689 35 Andreas Smas
690 58 sbi -
Message fields:
691
<pre>
692 66 Adam Sutton
Same as eventAdd but all fields (except eventId) are optional.
693 35 Andreas Smas
</pre>
694 58 sbi -
695 66 Adam Sutton
h3. eventDeleted (Added in version 6)
696 35 Andreas Smas
697 66 Adam Sutton
Message fields:
698
<pre>
699
eventId            u32   required   Event ID
700
</pre>
701 14 Andreas Smas
702 66 Adam Sutton
---
703 14 Andreas Smas
704 66 Adam Sutton
h3. initialSyncCompleted (Added in version 2)
705 14 Andreas Smas
706 66 Adam Sutton
Sent after all the initial metadata has been sent when session has been set to async mode.
707 38 Andreas Smas
708
Message fields:
709 14 Andreas Smas
<pre>
710
</pre>
711
712
----
713
714
h3. subscriptionStart
715 53 Andreas Smas
716 66 Adam Sutton
Asynchronous message output when a new subscription is successfully started.
717 14 Andreas Smas
718
Message fields:
719 1 Andreas Smas
<pre>
720 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
721
streams            msg[] required   Array of messages with stream information
722
sourceinfo         msg   optional   Source information.
723
</pre>
724 37 Andreas Smas
725 66 Adam Sutton
Stream message fields:
726
<pre>
727
index              u32   required   Index for this stream
728
type               str   required   Type of stream
729
language           str   optional   Language for stream
730
Video components only:
731
width              u32   optional   Width of video in pixels
732
height             u32   optional   Height of video in pixels
733 68 Andreas Smas
aspect_num         u32   optional   Aspect ratio numerator (Added in version 5) *Can be incorrect and should not be relied upon*
734
aspect_den         u32   optional   Aspect ratio denonminator (Added in version 5) *Can be incorrect and should not be relied upon*
735 66 Adam Sutton
Audio components only:
736
channels           u32   optional   Number of audio channels (Added in version 5)
737
rate               u32   optional   Audio bitrate (Added in version 5)
738
Subtitle components only:
739
composition_id     u32   optional   ??? (Added in version 5)
740
ancillary_id       u32   optional   ??? (Added in version 5)
741
</pre>
742 2 Andreas Smas
743 66 Adam Sutton
Sourceinfo message fields:
744
<pre>
745
adapter            str   optional   Adapter name
746
mux                str   optional   Transponder name
747
network            str   optional   Network name
748
provider           str   optional   ???
749
service            str   optional   Service name
750
</pre>
751 15 Andreas Smas
752 66 Adam Sutton
Video Stream types:
753
<pre>
754
MPEG2VIDEO                    MPEG2 video
755
H264                          H264 video
756
</pre>
757 15 Andreas Smas
758 66 Adam Sutton
Audio Stream types:
759
<pre>
760
MPEG2AUDIO                    MPEG2 audio (MP2)
761
AC3                           AC3 audio
762
AAC                           ADTS framed AAC (one AAC packet per ADTS frame)
763
EAC3                          Enhanced AC3 audio
764 16 Andreas Smas
</pre>
765
766 66 Adam Sutton
Subtitle Stream types:
767
<pre>
768
TELETEXT                      ???
769
DVBSUB                        ???
770
</pre>
771 55 Lars Op den Kamp -
772
h3. subscriptionStop
773
774 66 Adam Sutton
A subscription has been stopped.
775 55 Lars Op den Kamp -
776
Message fields:
777
<pre>
778 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
779
status             str   optional   Error message if subscription stopped unexpectedly.
780 55 Lars Op den Kamp -
</pre>
781 58 sbi -
782 55 Lars Op den Kamp -
h3. subscriptionStatus
783
784 66 Adam Sutton
Subscription status update.
785 58 sbi -
786
Message fields:
787
<pre>
788 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
789
status             str   optional   English clear text of error status. Absence of this field means that the status is OK. 
790 16 Andreas Smas
</pre>
791 58 sbi -
792 16 Andreas Smas
h3. queueStatus
793
794 1 Andreas Smas
The queueStatus message is sent every second during normal data delivery.
795 60 John Törnblom
796
The transmit scheduler have different drop thresholds for different frame types.
797 66 Adam Sutton
798 1 Andreas Smas
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
799
All audio is recognized as I-frames. 
800 58 sbi -
801 1 Andreas Smas
Message fields:
802
<pre>
803 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
804
packets            u32   required   Number of data packets in queue.
805
bytes              u32   required   Number of bytes in queue.
806
delay              u32   optional   Estimated delay of queue (in µs).
807
Bdrops             u32   required   Number of B-frames dropped
808
Pdrops             u32   required   Number of P-frames dropped
809
Idrops             u32   required   Number of I-frames dropped
810 1 Andreas Smas
</pre>
811
812
h3. signalStatus
813
814
The signalStatus message is sent every second during normal data delivery.
815
816
The optional fields may not have been implemented or may not be supported by the active adapter.
817
818
Message fields:
819
<pre>
820 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
821
feStatus           str   required   Frontend status.
822
feSNR              u32   optional   Signal to noise ratio.
823
feSignal           u32   optional   Signal status percentage.
824
feBER              u32   optional   Bit error rate.
825
feUNC              u32   optional   Uncorrected blocks.
826 1 Andreas Smas
</pre>
827
828
h3. muxpkt
829
830
Streaming data.
831
832
Message fields:
833
<pre>
834 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
835
frametype          u32   required   Type of frame as ASCII value: 'I', 'P', 'B'
836
stream             u32   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
837
dts                s64   optional   Decode Time Stamp in µs.
838
pts                s64   optional   Presentation Time Stamp in µs.
839
duration           u32   required   Duration of frame in µs.
840
payload            bin   required   Actual frame data.
841 1 Andreas Smas
</pre>