Project

General

Profile

Htsp » History » Version 82

Jaroslav Kysela, 2014-10-19 12:40

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