Project

General

Profile

Htsp » History » Version 124

Jaroslav Kysela, 2015-05-29 22:10

1 117 Jaroslav Kysela
h1. Home Tv Streaming Protocol (HTSP) - Version 21
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 84 Jaroslav Kysela
h2. Protocol Changes
24 83 Jaroslav Kysela
25 119 Jaroslav Kysela
h3. v17..v18
26
27
* added addTimerecEntry, deleteTimerecEntry methods
28
* added timerecEntryAdd, timerecEntryUpdate, timerecEntryDelete server-to-client methods
29
* extended addAutorecEntry method
30
** added start/startWindow/name fields
31
** added owner/creator fields
32
** obsoleted creator field
33
* extended dvrEntryAdd, dvrEntryUpdate
34
** added timerecId field
35
** added owner/creator fields
36
* extended addAutorecEntry, deleteAutorecEntry methods
37
** added start/startWindow fields
38
** obsoleted approxTime
39
** added name/owner/creator fields
40
* extended autorecEntryAdd, autorecEntryUpdate server-to-client methods
41
** fields like for addAutorecEntry
42
* extended getTag method
43
** added tagIndex field
44
45 110 Jaroslav Kysela
h3. v16..v17
46
47
* extended subscriptionStart server-to-client method
48
** added meta field
49
* changed H264 meta data handling (codec meta data are in the meta field only in start message)
50
* VORBIS and AAC codecs have codec specific meta data in the meta field in start message
51 115 Jaroslav Kysela
* changed subscribe method
52
** the normts is always active and the parameter is ignored
53
54 110 Jaroslav Kysela
55 107 Jaroslav Kysela
h3. v15..v16
56
57
* added getProfiles, getDvrConfigs methods
58
* removed getCodecs methods
59
* extended subscribe method
60
** add profile field
61
62 105 Jaroslav Kysela
h3. v14..v15
63
64
* extended channelAdd, channelUpdate server-to-client methods
65 106 Jaroslav Kysela
** the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'
66 1 Andreas Smas
* extended getChannel method
67 106 Jaroslav Kysela
** the channelIcon URL can be relative 'imagecache/%d' or '/imagecache/%d'
68
69 105 Jaroslav Kysela
70 100 Jaroslav Kysela
h3. v13..v14
71
72
* added getChannel method
73
74 85 Jaroslav Kysela
h3. v12..v13
75
76
* added addAutorecEntry method
77
* added deleteAutorecEntry method
78 92 Jaroslav Kysela
* added autorecEntryAdd, autorecEntryUpdate, autorecEntryDelete server-to-client methods
79 85 Jaroslav Kysela
* extended channelAdd server-to-client method
80 87 Jaroslav Kysela
** added channelNumberMinor (for {major}.{minor} channel numbers)
81
* extended dvrEntryAdd and dvrEntryUpdate server-to-client methods
82 88 Jaroslav Kysela
** added eventId, autorecId, startExtra, stopExtra, retention, priority, contentType fields
83 97 Jaroslav Kysela
* extended addDvrEntry method
84
** added retention
85
* extended updateDvrEntry method
86
** added retention, priority
87
* extended epgQuery method
88
** added minduration, maxduration
89 85 Jaroslav Kysela
* added subscriptionGrace server-to-client method
90 97 Jaroslav Kysela
91 85 Jaroslav Kysela
92 83 Jaroslav Kysela
h3. v11..v12
93
94
* added subscriptionFilterStream method
95
* added getDvrCutpoints method
96
97
98
h3. v10..v11
99
100 86 Jaroslav Kysela
* added audio_type in the subscriptionStart server-to-client method
101 83 Jaroslav Kysela
* added getCodecs method
102
103 58 sbi -
h2. Communication
104
105
106 69 Adam Sutton
This communication is currently implemented by using htsmsg's. All strings are encoded as UTF-8.
107 1 Andreas Smas
108
There are two distinct ways for communication within HTSP.
109
110 28 Andreas Smas
Apart from this there is a number of messages that needs to be exchanged during login, see the login section below.
111
112 1 Andreas Smas
113 58 sbi -
h3. RPC communication
114
115
116 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:
117 18 Andreas Smas
118 17 Andreas Smas
RPC request extra fields:
119 58 sbi -
<pre>
120 28 Andreas Smas
seq              int  optional   Sequence number. This field will be echoed back by the server in the reply.
121 1 Andreas Smas
username         str  optional   Username, in combination with 'digest' this can be used to raise the privileges
122
                                 for the session in combination with invocation of a method. 
123 28 Andreas Smas
digest           bin  optional   Used to raise privileges.
124 58 sbi -
</pre>
125 18 Andreas Smas
126 1 Andreas Smas
The followings field should be used by the client to match the reply with the request.
127
All replies are guaranteed to arrive in the same order as the requests.
128
Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.
129
130
RPC reply extra fields:
131 58 sbi -
<pre>
132 18 Andreas Smas
seq              int  optional   Sequence number. Same as in the request.
133 19 Andreas Smas
error            str  optional   If present an error has occurred and the text describes the error.
134
noaccess         int  optional   If present and set to '1' the user is prohibited from invoking the method due to 
135 1 Andreas Smas
                                 access restrictions. 
136 58 sbi -
</pre>
137 1 Andreas Smas
138 18 Andreas Smas
139 58 sbi -
h3. Streaming communication
140
141
142 19 Andreas Smas
For streaming of live TV and various related messages the server will continuously push data to the client.
143 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.
144
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). 
145
146 34 Andreas Smas
147 58 sbi -
h3. Authentication
148
149
150 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.
151 1 Andreas Smas
152
Privileges for these restrictions may be granted in two ways: Username + Password and/or Source IP address.
153
Therefore it is possible to gain permissions to the system without entering a username and password.
154
While this is really useful it also complicates the authentication schema a bit.
155
Upon connect the initial privileges will be raised based on the source address.
156
157
Before any username / password based authentication has taken place the client must have
158 34 Andreas Smas
obtained a challenge (which stays fixed for the session). This is done via the 'hello' method.
159 1 Andreas Smas
160
In principle it's possible to use two different authentication idioms with HTSP.
161
Depending on how your application works one or another may be more suitable.
162
While they do not really differ from a protocol point of view it's worth mentioning a bit about them here:
163
164
165 58 sbi -
h3. Initial login authentication
166
167
168 1 Andreas Smas
The client performs all of its authentication using the 'login' method.
169
170
It may choose to send:
171 58 sbi -
* Username and password: Privileges will be raised based on these credentials.
172
* Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.
173
* Nothing: Privileges will be based on just the source address.
174 1 Andreas Smas
175
If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based)
176
the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the
177
user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.
178
179
180 58 sbi -
h3. On-demand authentication
181
182
183 1 Andreas Smas
The client performs all of its authentication when it needs to.
184
185
When using this method, the client will check every RPC reply for the 'noaccess' field.
186
If it set to 1 it whould ask the user for username + password and retry the request but also
187 58 sbi -
add 'username' and 'digest' to the original message. (See _RPC request extra fields_ above)
188 1 Andreas Smas
189
Typically it would not send a username or digest during login.
190 29 Andreas Smas
191
----
192 34 Andreas Smas
193 66 Adam Sutton
h2. Client to Server (RPC) methods
194 34 Andreas Smas
195
h3. hello
196 58 sbi -
197
Used to identify the client toward the server and to get the session challenge used to
198 1 Andreas Smas
hash passwords into digests. The client can request a different version of the HTSP
199 66 Adam Sutton
protocol with this method. If no 'hello' message is sent the server assumes latest version
200 1 Andreas Smas
is to be used.
201 34 Andreas Smas
202 66 Adam Sutton
Client/Server should select lowest common version, if this is not possible connection should be terminated.
203 1 Andreas Smas
204
Request message fields:
205
<pre>
206 66 Adam Sutton
htspversion        u32   required   Client preferred HTSP version.
207
clientname         str   required   Client software name.
208
clientversion      str   required   Client software version.
209 58 sbi -
</pre>
210 1 Andreas Smas
211
Reply message fields:
212 34 Andreas Smas
<pre>
213 66 Adam Sutton
htspversion        u32   required   The server supports all versions of the protocol up to and including this number.
214
servername         str   required   Server software name.
215
serverversion      str   required   Server software version.
216
servercapability   str[] required   Server capabilities (Added in version 6)
217 1 Andreas Smas
challenge          bin   required   32 bytes randomized data used to generate authentication digests
218 73 Adam Sutton
webroot            str   optional   Server HTTP webroot (Added in version 8)
219
                                    Note: any access to TVH webserver should include this at start of URL path
220 1 Andreas Smas
</pre>
221
222 70 Adam Sutton
Note: possible values for servercapability[]:
223
<pre>
224
cwc                Descrambling available
225
v4l                Analogue TV available
226
linuxdvb           Linux DVB API available
227 1 Andreas Smas
imagecache         Image caching available
228 73 Adam Sutton
timeshift          Timeshifting available (Added in version 9).
229 70 Adam Sutton
</pre>
230
231 58 sbi -
h3. authenticate
232 1 Andreas Smas
233
This can be used to issue authentication without doing anything else.
234
If no privileges are gained it will return with 'noaccess' set to 1.
235
236 33 Andreas Smas
Request message fields:
237 1 Andreas Smas
<pre>
238 66 Adam Sutton
None   
239 33 Andreas Smas
</pre>
240 58 sbi -
241
Reply message fields:
242
<pre>
243 66 Adam Sutton
noaccess           u32   optional   If set to 1, no privileges were granted.
244 33 Andreas Smas
</pre>
245 1 Andreas Smas
246
----
247
248 66 Adam Sutton
h3. getDiskSpace (Added in version 3)
249 58 sbi -
250 66 Adam Sutton
Return diskspace status from Tvheadend's PVR storage
251 1 Andreas Smas
252 66 Adam Sutton
Request message fields:
253
<pre>
254
None
255
</pre>
256 1 Andreas Smas
257 66 Adam Sutton
Reply message fields:
258
<pre>
259
freediskspace      s64   required   Bytes available.
260
totaldiskspace     s64   required   Total capacity.
261
</pre>
262 1 Andreas Smas
263 66 Adam Sutton
h3. getSysTime (Added in version 3)
264 1 Andreas Smas
265 66 Adam Sutton
Return system time on the server.
266
267 1 Andreas Smas
Request message fields:
268
<pre>
269
None
270
</pre>
271
272
Reply message fields:
273 58 sbi -
<pre>
274 66 Adam Sutton
time               s64  required   UNIX time.
275
timezone           s32  required   Minutes west of GMT.
276 1 Andreas Smas
</pre>
277 23 Andreas Smas
278 1 Andreas Smas
----
279
280 66 Adam Sutton
h3. enableAsyncMetadata
281 1 Andreas Smas
282 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.
283 1 Andreas Smas
284 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.
285 1 Andreas Smas
286
Request message fields:
287
<pre>
288 66 Adam Sutton
epg                u32   optional   Set to 1, to include EPG data in async, implied by epgMaxTime (Added in version 6).
289
lastUpdate         s64   optional   Only provide metadata that has changed since this time (Added in version 6).
290
epgMaxTime         s64   optional   Maximum time to return EPG data up to (Added in version 6)
291
language           str   optional   RFC 2616 compatible language list (Added in version 6)
292 1 Andreas Smas
</pre>
293
294
Reply message fields:
295
<pre>
296 66 Adam Sutton
None
297 1 Andreas Smas
</pre>
298
299 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:
300 1 Andreas Smas
301 66 Adam Sutton
<pre>
302
tagAdd                   optional
303
channelAdd               optional
304
tagUpdate                optional
305
dvrEntryAdd              optional
306
eventAdd                 optional   (Added in version 6)
307
initialSyncComplete      required
308
</pre>
309 1 Andreas Smas
310 66 Adam Sutton
----
311 1 Andreas Smas
312 101 Jaroslav Kysela
h3. getChannel (Added in version 14)
313
314
Request information about the given channel.
315
316
Request message fields:
317
<pre>
318
channelId          u32   required   Channel ID.
319
</pre>
320
321
Reply message fields:
322
<pre>
323
see channelAdd
324
</pre>
325
326
----
327
328 66 Adam Sutton
h3. getEvent
329 1 Andreas Smas
330 66 Adam Sutton
Request information about the given event. An event typically corresponds to a program on a channel.
331 1 Andreas Smas
332 66 Adam Sutton
The language field in the request allows preference for languages to be requested for the various string fields.
333
334 1 Andreas Smas
Request message fields:
335 45 mdd -
<pre>
336 66 Adam Sutton
eventId            u32   required   Event ID.
337
language           str   optional   RFC 2616 compatible language list (Added in version 6)
338 1 Andreas Smas
</pre>
339
340
Reply message fields:
341
<pre>
342 66 Adam Sutton
see eventAdd
343 1 Andreas Smas
</pre>
344
345 66 Adam Sutton
h3. getEvents (Added in version 4)
346 1 Andreas Smas
347 66 Adam Sutton
Request information about a set of events. If no options are specified the entire EPG database will be returned.
348 57 sbi -
349 58 sbi -
Request message fields:
350 1 Andreas Smas
<pre>
351 66 Adam Sutton
eventId            u32   optional   Event ID to begin from (Optional since version 6)
352
channelId          u32   optional   Channel ID to get data for (Added in version 6)
353
numFollowing       u32   optional   Number of events to add (Optional since version 6)
354
maxTime            u64   optional   Maximum time to return data up to (Added in version 6)
355
language           str   optional   RFC 2616 compatible language list (Added in version 6)
356 1 Andreas Smas
</pre>
357
358
Reply message fields:
359
<pre>
360 66 Adam Sutton
events             msg[] required   List of events, using response message fields from eventAdd
361 1 Andreas Smas
</pre>
362 45 mdd -
363 66 Adam Sutton
h3. epgQuery (Added in version 4)
364 1 Andreas Smas
365 66 Adam Sutton
Query the EPG (event titles) and optionally restrict to channel/tag/content type.
366 1 Andreas Smas
367 66 Adam Sutton
Request message fields:
368
<pre>
369
query              str   required  Title regular expression to search for
370
channelId          u32   optional  [[ChannelId]] to restrict search to
371
tagId              u32   optional  [[TagId]] to restrict search to
372
contentType        u32   optional  DVB content type to restrict search to
373 98 Jaroslav Kysela
minduration        u32   optional  Minimal duration in seconds (Added in version 13)
374
maxduration        u32   optional  Maximal duration in seconds (Added in version 13)
375 66 Adam Sutton
language           str   optional  RFC 2616 compatible language list for title (Added in version 6)
376
full               u32   optional  Output full event list rather than just IDs
377
</pre>
378 1 Andreas Smas
379 66 Adam Sutton
Reply message fields:
380 1 Andreas Smas
381 66 Adam Sutton
if full == 1
382
<pre>
383
events             msg[] optional   List of events, using response message fields from eventAdd
384
</pre>
385
else
386
<pre>
387
eventIds           u32[] optional  List of eventIds that match the query
388
</pre>
389 1 Andreas Smas
390 66 Adam Sutton
h3. getEpgObject
391
392
Get detailed EPG Object info.
393
394 58 sbi -
Request message fields:
395 1 Andreas Smas
<pre>
396 66 Adam Sutton
id                 u32   required  Object ID
397
type               u32   optional  Object type
398 1 Andreas Smas
</pre>
399 58 sbi -
400 1 Andreas Smas
Reply message fields:
401 66 Adam Sutton
402 1 Andreas Smas
<pre>
403 66 Adam Sutton
TODO
404 1 Andreas Smas
</pre>
405
406 58 sbi -
----
407 1 Andreas Smas
408 109 Jaroslav Kysela
h3. getDvrConfigs (Added in version 16)
409
410
Return a list of DVR configurations.
411
412
Reply message fields:
413
<pre>
414
dvrconfigs         msg[]      optional   Supported DVR configurations.
415
</pre>
416
417
Message fields:
418
<pre>
419
uuid               str        required   DVR configuration ID
420
name               str        required   DVR configuration Name
421
comment            str        required   DVR configuration Comment
422
</pre>
423
424 66 Adam Sutton
h3. addDvrEntry (Added in version 4)
425
426 1 Andreas Smas
Create a new DVR entry. Either eventId or channelId, start and stop must be specified.
427
428
Request message fields:
429 66 Adam Sutton
<pre>
430
eventId            u32   optional   Event ID (Optional since version 5).
431
channelId          u32   optional   Channel ID (Added in version 5)
432
start              s64   optional   Time to start recording (Added in version 5)
433 96 Jaroslav Kysela
stop               s64   optional   Time to stop recording (Added in version 5)
434 66 Adam Sutton
retention          u32   optional   Retention time in days (Added in version 13)
435 117 Jaroslav Kysela
creator            str   optional   Name of the event creator (Added in version 5, obsoleted in version 18 - applications are not allowed to change credential)
436 66 Adam Sutton
priority           u32   optional   Recording priority (Added in version 5)
437
startExtra         s64   optional   Pre-recording buffer in minutes (Added in version 5)
438
stopExtra          s64   optional   Post-recording buffer in minutes (Added in version 5)
439
title              str   optional   Recording title, if no eventId (Added in version 6)
440 1 Andreas Smas
description        str   optional   Recording description, if no eventId (Added in version 5)
441 109 Jaroslav Kysela
configName         str   optional   DVR configuration name or UUID
442 40 Andreas Smas
</pre>
443 1 Andreas Smas
444
Reply message fields:
445
<pre>
446 66 Adam Sutton
success            u32   required   1 if entry was added, 0 otherwise
447
id                 u32   optional   ID of created DVR entry
448 1 Andreas Smas
error              str   optional   English clear text of error message
449
</pre>
450 66 Adam Sutton
451 1 Andreas Smas
h3. updateDvrEntry (Added in version 5)
452 66 Adam Sutton
453 1 Andreas Smas
Update an existing DVR entry.
454
455
Request message fields:
456 66 Adam Sutton
<pre>
457
id                 u32   required   DVR Entry ID
458
start              s64   optional   New start time
459
stop               s64   optional   New stop time
460
title              str   optional   New entry title
461
description        str   optional   New entry description (Added in version 6)
462 1 Andreas Smas
startExtra         s64   optional   New pre-record buffer (Added in version 6)
463 66 Adam Sutton
stopExtra          s64   optional   New post-record buffer (Added in version 6)
464 109 Jaroslav Kysela
configName         str   optional   New DVR configuration name or UUID
465 99 Jaroslav Kysela
retention          u32   optional   Retention in days (Added in version 13)
466
priority           u32   optional   Recording priority (Added in version 13)
467 1 Andreas Smas
</pre>
468
469
Reply message fields:
470
<pre>
471 66 Adam Sutton
success            u32   required   1 if update as successful, otherwise 0
472
error              str   optional   Error message if update failed
473 40 Andreas Smas
</pre>
474
475 66 Adam Sutton
h3. cancelDvrEntry (Added in version 5)
476 1 Andreas Smas
477 66 Adam Sutton
Cancel an existing recording, but don't remove the entry from the database.
478 1 Andreas Smas
479 66 Adam Sutton
Request message fields:
480
<pre>
481
id                 u32   required   dvrEnryId to delete
482
</pre>
483 1 Andreas Smas
484 66 Adam Sutton
Reply message fields:
485
<pre>
486
success            int   required   1 if entry was cancelled
487
error              str   optional   Error message if cancellation failed
488
</pre>
489 1 Andreas Smas
490 66 Adam Sutton
h3. deleteDvrEntry (Added in version 4)
491
492
Delete an existing DVR entry from the database.
493
494
Request message fields:
495 1 Andreas Smas
<pre>
496 66 Adam Sutton
id                 u32   required   DVR Entry ID
497 1 Andreas Smas
</pre>
498
499 11 Andreas Smas
Reply message fields:
500 1 Andreas Smas
<pre>
501 66 Adam Sutton
success            u32   required   1 if entry was removed
502
error              str   optional   Error message if the delete fails
503 1 Andreas Smas
</pre>
504
505 103 Jaroslav Kysela
h3. getDvrCutpoints (Added in version 12)
506
507
Get DVR cutpoints.
508
509
Request message fields:
510
<pre>
511
id                 u32   required   DVR Entry ID
512
</pre>
513
514
Reply message fields:
515
<pre>
516
cutpoints          msg[] optional   List of cutpoint entries, if a file is found and has some valid data.
517
</pre>
518
519
Cutpoint fields:
520
<pre>
521
start              u32   required   Cut start time in ms.
522
end                u32   required   Cut end time in ms.
523
type               u32   required   Action type: 
524
                                      0=Cut, 1=Mute, 2=Scene, 
525
                                      3=Commercial break.
526
</pre>
527
528 102 Jaroslav Kysela
---
529
530 91 Jaroslav Kysela
h3. addAutorecEntry (Added in version 13)
531
532
Create a new Autorec DVR entry. Title must be specified.
533
534
Request message fields:
535
<pre>
536
title              str   required   Title for the recordings.
537 121 Jaroslav Kysela
directory          str   optional   Forced directory name - missing or empty = auto (Added in version 19).
538 120 Jaroslav Kysela
name               str   optional   Name of this autorec entry (Added in version 18).
539 91 Jaroslav Kysela
configName         str   optional   DVR Configuration Name / UUID.
540
channelId          u32   optional   Channel ID.
541
minDuration        u32   optional   Minimal duration in seconds (0 = Any).
542
maxDuration        u32   optional   Maximal duration in seconds (0 = Any).
543 1 Andreas Smas
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
544
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
545 117 Jaroslav Kysela
approxTime         u32   optional   Minutes from midnight (up to 24*60) (window +- 15 mintes) (Obsoleted from version 18).
546
start              s32   optional   Minutes from midnight (up to 24*60) for the start of the time window (including) (Added in version 18).
547
startWindow        s32   optional   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed) (Added in version 18).
548 91 Jaroslav Kysela
startExtra         s64   optional   Extra start minutes (pre-time).
549
stopExtra          s64   optional   Extra stop minutes (post-time).
550
comment            str   optional   User Comment.
551
</pre>
552 83 Jaroslav Kysela
553
Reply message fields:
554
<pre>
555
success            u32   required   1 if entry was added, 0 otherwise
556
id                 str   optional   ID (string!) of created autorec DVR entry
557
error              str   optional   English clear text of error message
558
</pre>
559
560
h3. deleteAutorecEntry (Added in version 13)
561
562
Delete an existing autorec DVR entry from the database.
563
564
Request message fields:
565
<pre>
566
id                 str   required   Autorec DVR Entry ID (string!)
567
</pre>
568
569
Reply message fields:
570
<pre>
571
success            u32   required   1 if entry was removed
572
error              str   optional   Error message if the delete fails
573 1 Andreas Smas
</pre>
574 83 Jaroslav Kysela
575 1 Andreas Smas
----
576 117 Jaroslav Kysela
---
577 1 Andreas Smas
578 117 Jaroslav Kysela
h3. addTimerecEntry (Added in version 18)
579
580
Create a new Timerec DVR entry. Title must be specified.
581
582
Request message fields:
583
<pre>
584
title              str   required   Title for the recordings.
585 124 Jaroslav Kysela
directory          str   optional   Forced directory name (Added in version 19).
586 117 Jaroslav Kysela
name               str   optional   Name for this timerec entry.
587
configName         str   optional   DVR Configuration Name / UUID.
588
channelId          u32   required   Channel ID.
589
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
590
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
591
start              u32   required   Minutes from midnight (up to 24*60) for the start of the time window (including)
592
stop               u32   required   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed)
593
retention          u32   optional   Retention in days. 
594
comment            str   optional   User Comment.
595
</pre>
596
597
Reply message fields:
598
<pre>
599
success            u32   required   1 if entry was added, 0 otherwise
600
id                 str   optional   ID (string!) of created timerec DVR entry
601
error              str   optional   English clear text of error message
602
</pre>
603
604
h3. deleteTimerecEntry (Added in version 18)
605
606
Delete an existing timerec DVR entry from the database.
607
608
Request message fields:
609
<pre>
610
id                 str   required   Timerec DVR Entry ID (string!)
611
</pre>
612
613
Reply message fields:
614
<pre>
615
success            u32   required   1 if entry was removed
616
error              str   optional   Error message if the delete fails
617
</pre>
618
619
----
620
621 66 Adam Sutton
h3. getTicket (Added in version 5)
622 1 Andreas Smas
623 66 Adam Sutton
Get a ticket to allow access to a channel or recording via HTTP
624 1 Andreas Smas
625 66 Adam Sutton
Request message fields:
626 1 Andreas Smas
<pre>
627 66 Adam Sutton
channelId          u32  optional   Channel to gain access for
628
dvrId              u32  optional   DVR file to gain access for
629 1 Andreas Smas
</pre>
630
631
Reply message fields:
632
<pre>
633 66 Adam Sutton
path               str  required   The full path for access URL (no scheme, host or port)
634
ticket             str  required   The ticket to pass in the URL query string
635 1 Andreas Smas
</pre>
636
637 66 Adam Sutton
h3. subscribe
638 1 Andreas Smas
639 66 Adam Sutton
Request subscription to the given channel. 
640 1 Andreas Smas
641 66 Adam Sutton
Request message fields:
642
<pre>
643
channelId          u32   required   ID for channel. 
644
subscriptionId     u32   required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
645
                                    The value is used from now on in all messages related to the subscription.
646 1 Andreas Smas
weight             u32   optional   Weighting of this subscription (same as recording priority).
647 73 Adam Sutton
90khz              u32   optional   Request PTS/DTS in default 90kHz timebase, default is 1MHz (Added in version 7)
648
normts             u32   optional   Request PTS/DTS normalisation (Added in version 7)
649
                                    Note: this will mean missing timestamps are added, first packet should be ~0 and will always be an i-frame.
650
                                    Note: this is implied if timeshiftPeriod is enabled
651 114 Jaroslav Kysela
                                    Note: from version 17, this is always enabled and this parameter is ignored.
652 73 Adam Sutton
queueDepth         u32   optional   Change the default packet queue lengths, default 500000 bytes (Added in version 7)
653
                                    Note: I-frame depth is 3*queueDepth, P-frame is 2*queueDepth and B-frame is queueDepth
654
timeshiftPeriod    u32   optional   The number of seconds to keep in the timeshift buffer (Added in version 9)
655
                                    Note: this may be bounded by server configuration settings
656 108 Jaroslav Kysela
profile            str   optional   Select stream profile (Added in version 16).
657 11 Andreas Smas
</pre>
658 66 Adam Sutton
659 1 Andreas Smas
Reply message fields:
660
<pre>
661 73 Adam Sutton
90khz              u32   optional   Indicates 90khz timestamps will be used
662
normts             u32   optional   Indicates timestamps will be normalised (and fixed)
663
timeshiftPeriod    u32   optional   The actual timeshiftPeriod to be used
664 66 Adam Sutton
</pre>
665 1 Andreas Smas
666 66 Adam Sutton
h3. unsubscribe
667
668
Stop a subscription.
669
670
Request message fields:
671 1 Andreas Smas
<pre>
672 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
673 58 sbi -
</pre>
674
675 11 Andreas Smas
Reply message fields:
676 1 Andreas Smas
<pre>
677 66 Adam Sutton
None
678 58 sbi -
</pre>
679 11 Andreas Smas
680 66 Adam Sutton
h3. subscriptionChangeWeight (Added in version 5)
681 1 Andreas Smas
682 66 Adam Sutton
Change the weight of an existing subscription
683 1 Andreas Smas
684 66 Adam Sutton
Request message fields:
685
<pre>
686
subscriptionId     u32   required   Subscription ID.
687
weight             u32   optional   The new subscription weight.
688 1 Andreas Smas
</pre>
689
690
Reply message fields:
691
<pre>
692 69 Adam Sutton
None
693 1 Andreas Smas
</pre>
694
695 73 Adam Sutton
h3. subscriptionSkip (Added in version 9)
696
697
Skip a timeshift enabled subscription. The response will be asynchronous subscriptionSkip().
698
699
Request message fields:
700
<pre>
701
subscriptionId     u32   required   Subscription ID.
702
absolute           u32   optional   The skip request is absolute
703
time               u64   optional   Specify skip using time (units are as for PTS)
704
size               u64   optional   Specify skip using size (Not currently used)
705
</pre>
706
707
Reply message fields:
708
<pre>
709
None
710
</pre>
711
712
h3. subscriptionSeek (Added in version 9)
713
714
Synonym for subscriptionSkip
715
716
h3. subscriptionSpeed (Added in version 9)
717
718
Set the playback speed for the subscription. The response will be asynchronous subscriptionSpeed().
719
720
Request message fields:
721
<pre>
722
subscriptionId     u32   required   Subscription ID.
723
speed              u32   required   Specify speed (0=pause, 100=1x fwd, -100=1x backward)
724
</pre>
725
726
Reply message fields:
727
<pre>
728
None
729
</pre>
730
731
h3. subscriptionLive (Added in version 9)
732
733
Return a timeshifted session to live. Reply will be asynchronous subscriptionSkip().
734
735
Request message fields:
736
<pre>
737
subscriptionId     u32   required   Subscription ID.
738
</pre>
739
740
Reply message fields:
741
<pre>
742
None
743 82 Jaroslav Kysela
</pre>
744 1 Andreas Smas
745 83 Jaroslav Kysela
h3. subscriptionFilterStream (Added in version 12)
746 1 Andreas Smas
747 83 Jaroslav Kysela
Enable or disable specified streams by index.
748
749
Request message fields:
750
<pre>
751
subscriptionId     u32        required   Subscription ID.
752
enable             list[u32]  optional   Enable stream indexes
753
disable            list[u32]  optional   Disable (filter out) stream indexes
754
</pre>
755
756
Reply message fields:
757 1 Andreas Smas
<pre>
758
None
759 109 Jaroslav Kysela
</pre>
760
761
---
762
763
h3. getProfiles (Added in version 16)
764
765
Return a list of stream profiles (configurations).
766
767
Reply message fields:
768
<pre>
769
profiles           msg[]      optional   Supported profiles
770
</pre>
771
772
Message fields:
773
<pre>
774
uuid               str        required   Profile ID
775
name               str        required   Profile Name
776
comment            str        required   Profile Comment
777 83 Jaroslav Kysela
</pre>
778
779
h3. getCodecs (Added in version 11, Removed in version 16)
780
781 82 Jaroslav Kysela
Return a list of encoders (codecs).
782
783 1 Andreas Smas
Reply message fields:
784 82 Jaroslav Kysela
<pre>
785 83 Jaroslav Kysela
encoders           list[str]  optional   Supported encoders
786 82 Jaroslav Kysela
</pre>
787
788 70 Adam Sutton
h3. fileOpen (Added in version 8)
789 69 Adam Sutton
790
Open a file within the Tvheadend file system. This is now the preferred method (in place of HTTP) for accessing recordings.
791
792
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.
793
794 1 Andreas Smas
Request message fields:
795 69 Adam Sutton
<pre>
796 70 Adam Sutton
file               str   required   File path to open
797 1 Andreas Smas
</pre>
798
799 70 Adam Sutton
Valid file paths:
800
<pre>
801
/dvrfile/ID        will open the file associated with DVR entry ID
802 74 Adam Sutton
/imagecache/ID     will open the file associated with imagecache entry ID (Note: only works for HTSPv10+)
803 70 Adam Sutton
</pre>
804
805 69 Adam Sutton
Reply message fields:
806
<pre>
807
id                 u32   required   The file handle used for further file operations
808
size               u64   optional   The size of the file in bytes
809 1 Andreas Smas
mtime              u64   optional   The last time the file was modified
810 69 Adam Sutton
</pre>
811
812 70 Adam Sutton
h3. fileRead (Added in version 8)
813 69 Adam Sutton
814 1 Andreas Smas
Read data from a file.
815
816 69 Adam Sutton
Request message fields:
817
<pre>
818
id                 u32   required   The file handle used for further file operations
819 70 Adam Sutton
size               u64   required   The amount of data to read
820
offset             u64   optional   Offset into the file to read (default is current position)
821 69 Adam Sutton
</pre>
822 1 Andreas Smas
823 69 Adam Sutton
Reply message fields:
824
<pre>
825
data               bin   required   The data read from the file (size may be less than requested)
826
</pre>
827
828 70 Adam Sutton
h3. fileClose (Added in version 8)
829 69 Adam Sutton
830
Close an opened file.
831
832
Request message fields:
833
<pre>
834 1 Andreas Smas
id                 u32   required   The file handle to be closed
835 69 Adam Sutton
</pre>
836
837
Reply message fields:
838
<pre>
839
None
840
</pre>
841 70 Adam Sutton
842 69 Adam Sutton
h3. fileStat (Added in version 8)
843
844
Get status of a file.
845
846
Request message fields:
847
<pre>
848
id                 u32   required   The file handle to be stat'd
849 1 Andreas Smas
</pre>
850
851
Reply message fields:
852
<pre>
853
size               u64   optional   The size of the file in bytes
854
mtime              u64   optional   The last time the file was modified
855
</pre>
856 70 Adam Sutton
857
h3. fileSeek (Added in version 8)
858
859
Seek to position in a file.
860
861
Request message fields:
862
<pre>
863
id                 u32   required   The file handle to be stat'd
864
offset             u64   required   The position to seek in the file
865
whence             str   required   Where to seek relative to (default=SEEK_SET)
866
</pre>
867
868
Note: valid values for whence
869
<pre>
870
SEEK_SET           Seek relative to start of file
871
SEEK_CUR           Seek relative to current position in file
872 72 Adam Sutton
SEEK_END           Seek relative (backwards) to end of file
873 70 Adam Sutton
</pre>
874
875
Reply message fields:
876
<pre>
877
offset             u64   optional   The new absolute position within the file
878
</pre>
879 66 Adam Sutton
880 1 Andreas Smas
h1. Server to Client methods
881
882
----
883
884
h3. channelAdd
885
886
A new channel has been created on the server.
887
888
Message fields:
889
<pre>
890
channelId          u32   required   ID of channel.
891 66 Adam Sutton
channelNumber      u32   required   Channel number, 0 means unconfigured.
892 90 Jaroslav Kysela
channelNumberMinor u32   optional   Minor channel number (Added in version 13).
893 1 Andreas Smas
channelName        str   required   Name of channel.
894 70 Adam Sutton
channelIcon        str   optional   URL to an icon representative for the channel
895
                                    (For v8+ clients this could be a relative /imagecache/ID URL
896 73 Adam Sutton
                                     intended to be fed to fileOpen() or HTTP server)
897 104 Jaroslav Kysela
                                    (For v15+ clients this could be a relative imagecache/ID URL
898
                                     intended to be fed to fileOpen() or HTTP server)
899 66 Adam Sutton
eventId            u32   optional   ID of the current event on this channel.
900
nextEventId        u32   optional   ID of the next event on the channel.
901
tags               u32[] optional   Tags this channel is mapped to.
902
services           msg[] optional   List of available services (Added in version 5)
903 13 Andreas Smas
</pre>
904 1 Andreas Smas
905 66 Adam Sutton
Service fields:
906 1 Andreas Smas
<pre>
907 66 Adam Sutton
name               str   required   Service name
908
type               str   required   Service type
909
caid               u32   optional   Encryption CA ID
910
caname             str   optional   Encryption CA name
911 11 Andreas Smas
</pre>
912 1 Andreas Smas
913 66 Adam Sutton
h3. channelUpdate
914 11 Andreas Smas
915 66 Adam Sutton
Same as channelAdd, but all fields (except channelId) are optional.
916
917 58 sbi -
h3. channelDelete
918 1 Andreas Smas
919
A channel has been deleted on the server.
920 58 sbi -
921
Message fields:
922 1 Andreas Smas
<pre>
923
channelId          u32   required   ID of channel.
924
</pre>
925
926
----
927
928 11 Andreas Smas
h3. tagAdd
929 1 Andreas Smas
930
A new tag has been created on the server.
931
932
Message fields:
933
<pre>
934 66 Adam Sutton
tagId              u32   required   ID of tag.
935
tagName            str   required   Name of tag.
936 117 Jaroslav Kysela
tagIndex           u32   optional   Index value for sorting (default by from min to max) (Added in version 18).
937 66 Adam Sutton
tagIcon            str   optional   URL to an icon representative for the channel.
938
tagTitledIcon      u32   optional   Icon includes a title
939 1 Andreas Smas
members            u32[] optional   Channel IDs of those that belong to the tag
940 11 Andreas Smas
</pre>
941 39 elupus -
942 58 sbi -
h3. tagUpdate
943 66 Adam Sutton
944 11 Andreas Smas
Same as tagAdd, but all fields (except tagId) are optional.
945
946 1 Andreas Smas
h3. tagDelete
947 58 sbi -
948 1 Andreas Smas
A tag has been deleted from the server.
949
950
Message fields:
951 66 Adam Sutton
<pre>
952 58 sbi -
tagId              u32   required   ID of tag.
953
</pre>
954 12 Andreas Smas
955 1 Andreas Smas
----
956 66 Adam Sutton
957 58 sbi -
h3. dvrEntryAdd (Added in version 4)
958 1 Andreas Smas
959 58 sbi -
A new recording has been created on the server.
960 1 Andreas Smas
961 2 Andreas Smas
Message fields:
962 66 Adam Sutton
<pre>
963
id                 u32   required   ID of dvrEntry.
964
channel            u32   required   Channel of dvrEntry.
965
start              s64   required   Time of when this entry was scheduled to start recording.
966 89 Jaroslav Kysela
stop               s64   required   Time of when this entry was scheduled to stop recording.
967
startExtra         s64   required   Extra start time (pre-time) in minutes (Added in version 13).
968 1 Andreas Smas
stopExtra          s64   required   Extra stop time (post-time) in minutes (Added in version 13).
969
retention          s64   required   DVR Entry retention time in days.
970 89 Jaroslav Kysela
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set) (Added in version 13).
971
eventId            u32   optional   Associated EPG Event ID (Added in version 13).
972 117 Jaroslav Kysela
autorecId          str   optional   Associated Autorec UUID (Added in version 13).
973
timerecId          str   optional   Associated Timerec UUID (Added in version 18).
974 89 Jaroslav Kysela
contentType        u32   optional   Content Type (like in the DVB standard) (Added in version 13).
975 66 Adam Sutton
title              str   optional   Title of recording
976 1 Andreas Smas
summary            str   optional   Short description of the recording (Added in version 6).
977
description        str   optional   Long description of the recording.
978 66 Adam Sutton
state              str   required   Recording state
979
error              str   optional   Plain english error description (e.g. "Aborted by user").
980 117 Jaroslav Kysela
owner              str   optional   Name of the entry owner (Added in version 18).
981
creator            str   optional   Name of the entry creator (Added in version 18).
982 1 Andreas Smas
</pre>
983 66 Adam Sutton
984 48 mdd -
TODO: recording states
985
986
h3. dvrEntryUpdate
987 66 Adam Sutton
988
Message fields:
989
<pre>
990
Same as dvrEntryAdd, but all fields (except id) are optional.
991 51 elupus -
</pre>
992 66 Adam Sutton
993 58 sbi -
h3. dvrEntryDelete (Added in version 4)
994 66 Adam Sutton
995 58 sbi -
A recording has been deleted from the server.
996 48 mdd -
997
Message fields:
998 66 Adam Sutton
<pre>
999 1 Andreas Smas
id                 u32   required   ID of recording to delete.
1000 48 mdd -
</pre>
1001 58 sbi -
1002 48 mdd -
----
1003 95 Jaroslav Kysela
1004
h3. autorecEntryAdd (Added in version 13)
1005
1006
A new autorec recording has been created on the server.
1007
1008 1 Andreas Smas
Message fields:
1009 95 Jaroslav Kysela
<pre>
1010
id                 str   required   ID (string!) of dvrAutorecEntry.
1011
enabled            u32   required   If autorec entry is enabled (activated).
1012 117 Jaroslav Kysela
name               str   required   Name of the autorec entry (Added in version 18).
1013 95 Jaroslav Kysela
minDuration        u32   required   Minimal duration in seconds (0 = Any).
1014
maxDuration        u32   required   Maximal duration in seconds (0 = Any).
1015
retention          u32   required   Retention time (in days).
1016
daysOfWeek         u32   required   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
1017
priority           u32   required   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
1018
approxTime         u32   required   Minutes from midnight (up to 24*60).
1019 1 Andreas Smas
startExtra         s64   required   Extra start minutes (pre-time).
1020
stopExtra          s64   required   Extra stop minutes (post-time).
1021 95 Jaroslav Kysela
title              str   optional   Title.
1022 122 Jaroslav Kysela
directory          str   optional   Forced directory name (Added in version 19).
1023 95 Jaroslav Kysela
channel            u32   optional   Channel ID.
1024 117 Jaroslav Kysela
owner              str   optional   Owner of this autorec entry (Added in version 18).
1025
creator            str   optional   Creator of this autorec entry (Added in version 18).
1026 95 Jaroslav Kysela
</pre>
1027 1 Andreas Smas
1028 95 Jaroslav Kysela
h3. autorecEntryUpdate (Added in version 13)
1029
1030
Message fields:
1031
<pre>
1032 117 Jaroslav Kysela
Same as autorecEntryAdd but all fields (except id) are optional.
1033 95 Jaroslav Kysela
</pre>
1034
1035 1 Andreas Smas
h3. autorecEntryDelete (Added in version 13)
1036
1037
Message fields:
1038
<pre>
1039
id                 str   required   Autorec Entry ID (string!)
1040 117 Jaroslav Kysela
</pre>
1041
1042
----
1043
1044 118 Jaroslav Kysela
h3. timerecEntryAdd (Added in version 18)
1045 117 Jaroslav Kysela
1046
A new autorec recording has been created on the server.
1047
1048
Message fields:
1049
<pre>
1050
title              str   required   Title for the recordings.
1051 123 Jaroslav Kysela
directory          str   optional   Forced directory name (Added in version 19).
1052 117 Jaroslav Kysela
enabled            u32   required   Title for the recordings.
1053
name               str   required   Name for this timerec entry.
1054
configName         str   required   DVR Configuration Name / UUID.
1055
channelId          u32   required   Channel ID.
1056
daysOfWeek         u32   optional   Bitmask - Days of week (0x01 = Monday, 0x40 = Sunday, 0x7f = Whole Week, 0 = Not set).
1057
priority           u32   optional   Priority (0 = Important, 1 = High, 2 = Normal, 3 = Low, 4 = Unimportant, 5 = Not set).
1058
start              u32   required   Minutes from midnight (up to 24*60) for the start of the time window (including)
1059
stop               u32   required   Minutes from modnight (up to 24*60) for the end of the time window (including, cross-noon allowed)
1060
retention          u32   optional   Retention in days. 
1061
comment            str   optional   User Comment.
1062
owner              str   optional   Owner of this timerec entry.
1063
creator            str   optional   Creator of this timerec entry.
1064
</pre>
1065
1066
h3. timerecEntryUpdate (Added in version 18)
1067
1068
Message fields:
1069
<pre>
1070
Same as timerecEntryAdd but all fields (except id) are optional.
1071
</pre>
1072
1073
h3. timerecEntryDelete (Added in version 18)
1074
1075
Message fields:
1076
<pre>
1077
id                 str   required   Timerec Entry ID (string!)
1078 95 Jaroslav Kysela
</pre>
1079
1080
----
1081
1082 66 Adam Sutton
h3. eventAdd (Added in version 6)
1083 48 mdd -
1084 66 Adam Sutton
Message fields:
1085
<pre>
1086
eventId            u32   required   Event ID
1087
channelId          u32   required   The channel this event is related to.
1088
start              u64   required   Start time of event, UNIX time.
1089
stop               u64   required   Ending time of event, UNIX time.
1090
title              str   optional   Title of event.
1091
summary            str   optional   Short description of the event (Added in version 6).
1092
description        str   optional   Long description of the event.
1093
serieslinkId       u32   optional   Series Link ID (Added in version 6).
1094
episodeId          u32   optional   Episode ID (Added in version 6).
1095
seasonId           u32   optional   Season ID (Added in version 6).
1096
brandId            u32   optional   Brand ID (Added in version 6).
1097
contentType        u32   optional   DVB content code (Added in version 4, Modified in version 6*).
1098
ageRating          u32   optional   Minimum age rating (Added in version 6).
1099
starRating         u32   optional   Star rating (1-5) (Added in version 6).
1100
firstAired         s64   optional   Original broadcast time, UNIX time (Added in version 6).
1101
seasonNumber       u32   optional   Season number (Added in version 6).
1102
seasonCount        u32   optional   Show season count (Added in version 6).
1103
episodeNumber      u32   optional   Episode number (Added in version 6).
1104
episodeCount       u32   optional   Season episode count (Added in version 6).
1105
partNumber         u32   optional   Multi-part episode part number (Added in version 6).
1106
partCount          u32   optional   Multi-part episode part count (Added in version 6).
1107
episodeOnscreen    str   optional   Textual representation of episode number (Added in version 6).
1108
image              str   optional   URL to a still capture from the episode (Added in version 6).
1109
dvrId              u32   optional   ID of a recording (Added in version 5).
1110
nextEventId        u32   optional   ID of next event on the same channel.
1111
</pre>
1112 48 mdd -
1113 66 Adam Sutton
* *contentType previously had the major DVB category in the bottom 4 bits, 
1114
  however in v6 this has been changed to properly match DVB, so top 4 bits
1115
  as major category and bottom 4 bits has sub-category. Clients requesting
1116
  v5 or lower will get the old output.
1117 48 mdd -
1118 66 Adam Sutton
h3. eventUpdate (Added in version 6)
1119 35 Andreas Smas
1120 58 sbi -
Message fields:
1121
<pre>
1122 66 Adam Sutton
Same as eventAdd but all fields (except eventId) are optional.
1123 35 Andreas Smas
</pre>
1124 58 sbi -
1125 77 John Törnblom
h3. eventDelete (Added in version 6)
1126 35 Andreas Smas
1127 66 Adam Sutton
Message fields:
1128
<pre>
1129
eventId            u32   required   Event ID
1130
</pre>
1131 14 Andreas Smas
1132 66 Adam Sutton
---
1133 14 Andreas Smas
1134 66 Adam Sutton
h3. initialSyncCompleted (Added in version 2)
1135 14 Andreas Smas
1136 66 Adam Sutton
Sent after all the initial metadata has been sent when session has been set to async mode.
1137 38 Andreas Smas
1138
Message fields:
1139 14 Andreas Smas
<pre>
1140
</pre>
1141
1142
----
1143
1144
h3. subscriptionStart
1145 53 Andreas Smas
1146 66 Adam Sutton
Asynchronous message output when a new subscription is successfully started.
1147 14 Andreas Smas
1148
Message fields:
1149 1 Andreas Smas
<pre>
1150 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1151
streams            msg[] required   Array of messages with stream information
1152
sourceinfo         msg   optional   Source information.
1153
</pre>
1154 37 Andreas Smas
1155 66 Adam Sutton
Stream message fields:
1156
<pre>
1157
index              u32   required   Index for this stream
1158
type               str   required   Type of stream
1159 113 Jaroslav Kysela
meta               bin   optional   Codec metadata (private data, libav - extradata) (Added in version 17)
1160 66 Adam Sutton
language           str   optional   Language for stream
1161
Video components only:
1162
width              u32   optional   Width of video in pixels
1163
height             u32   optional   Height of video in pixels
1164 68 Andreas Smas
aspect_num         u32   optional   Aspect ratio numerator (Added in version 5) *Can be incorrect and should not be relied upon*
1165
aspect_den         u32   optional   Aspect ratio denonminator (Added in version 5) *Can be incorrect and should not be relied upon*
1166 66 Adam Sutton
Audio components only:
1167 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)
1168 66 Adam Sutton
channels           u32   optional   Number of audio channels (Added in version 5)
1169
rate               u32   optional   Audio bitrate (Added in version 5)
1170
Subtitle components only:
1171
composition_id     u32   optional   ??? (Added in version 5)
1172
ancillary_id       u32   optional   ??? (Added in version 5)
1173
</pre>
1174 2 Andreas Smas
1175 66 Adam Sutton
Sourceinfo message fields:
1176
<pre>
1177
adapter            str   optional   Adapter name
1178
mux                str   optional   Transponder name
1179
network            str   optional   Network name
1180
provider           str   optional   ???
1181
service            str   optional   Service name
1182
</pre>
1183 15 Andreas Smas
1184 66 Adam Sutton
Video Stream types:
1185 1 Andreas Smas
<pre>
1186 79 Jaroslav Kysela
MPEG2VIDEO                    MPEG2 video, meta field is present (configuration blocks)
1187
H264                          H264 video, meta field is present (configuration blocks)
1188
HEVC                          HEVC video, meta field is present (configuration blocks)
1189 66 Adam Sutton
</pre>
1190 15 Andreas Smas
1191 1 Andreas Smas
Audio Stream types:
1192
<pre>
1193 66 Adam Sutton
MPEG2AUDIO                    MPEG2 audio (MP2)
1194
AC3                           AC3 audio
1195 79 Jaroslav Kysela
AAC                           ADTS framed AAC (one AAC packet per ADTS frame), meta field is present (MPEG4 config)
1196 66 Adam Sutton
EAC3                          Enhanced AC3 audio
1197 79 Jaroslav Kysela
VORBIS                        Vorbis audio, meta field is present with the main vorbis header
1198 16 Andreas Smas
</pre>
1199
1200 66 Adam Sutton
Subtitle Stream types:
1201
<pre>
1202
TELETEXT                      ???
1203
DVBSUB                        ???
1204
</pre>
1205 55 Lars Op den Kamp -
1206 112 Jaroslav Kysela
h3. subscriptionGrace
1207
1208
Notifies client about the grace timeout (timeout for stream activation). It can be issues multiple times.
1209
For example a configuration with satellite rotors requires more than 120 seconds to tune, so users
1210
should be notified..
1211
1212
Message fields:
1213
<pre>
1214
subscriptionId     u32   required   Subscription ID.
1215
graceTimeout       u32   required   Grace timeout in seconds.
1216
</pre>
1217
1218 55 Lars Op den Kamp -
h3. subscriptionStop
1219
1220 66 Adam Sutton
A subscription has been stopped.
1221 55 Lars Op den Kamp -
1222
Message fields:
1223
<pre>
1224 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1225 1 Andreas Smas
status             str   optional   Error message if subscription stopped unexpectedly.
1226
</pre>
1227
1228 73 Adam Sutton
h3. subscriptionSkip (Added version 9)
1229
1230
A subscription has been skipped.
1231
1232
Message fields:
1233
<pre>
1234
subscriptionId     u32   required   Subscription ID.
1235
error              u32   optional   The last skip command caused an error.
1236
absolute           u32   optional   Indicates the output is absolute (Note: should always be 1 at the moment)
1237
time               u64   optional   The time the subscription has skipped to.
1238
size               u64   optional   The position in the file we've skipped to (Note: not currently used).
1239
</pre>
1240
1241
h3. subscriptionSpeed (Added version 9)
1242
1243
A subscription's playback speed has changed.
1244
1245
This can happen even without a speed request, should playback reach either end of the buffer.
1246
1247
Message fields:
1248
<pre>
1249
subscriptionId     u32   required   Subscription ID.
1250
speed              u32   required   The new speed of the subscription
1251
</pre>
1252
1253 55 Lars Op den Kamp -
h3. subscriptionStatus
1254
1255 66 Adam Sutton
Subscription status update.
1256 58 sbi -
1257
Message fields:
1258
<pre>
1259 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1260
status             str   optional   English clear text of error status. Absence of this field means that the status is OK. 
1261 16 Andreas Smas
</pre>
1262 58 sbi -
1263 16 Andreas Smas
h3. queueStatus
1264
1265 1 Andreas Smas
The queueStatus message is sent every second during normal data delivery.
1266 60 John Törnblom
1267
The transmit scheduler have different drop thresholds for different frame types.
1268 66 Adam Sutton
1269 1 Andreas Smas
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
1270
All audio is recognized as I-frames. 
1271 58 sbi -
1272 1 Andreas Smas
Message fields:
1273
<pre>
1274 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1275
packets            u32   required   Number of data packets in queue.
1276
bytes              u32   required   Number of bytes in queue.
1277
delay              u32   optional   Estimated delay of queue (in µs).
1278 1 Andreas Smas
Bdrops             u32   required   Number of B-frames dropped
1279 66 Adam Sutton
Pdrops             u32   required   Number of P-frames dropped
1280
Idrops             u32   required   Number of I-frames dropped
1281 73 Adam Sutton
delay              s64   required   Delta between first and last DTS (Added in version 9)
1282 1 Andreas Smas
</pre>
1283
1284
h3. signalStatus
1285
1286
The signalStatus message is sent every second during normal data delivery.
1287
1288
The optional fields may not have been implemented or may not be supported by the active adapter.
1289
1290
Message fields:
1291
<pre>
1292 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1293
feStatus           str   required   Frontend status.
1294
feSNR              u32   optional   Signal to noise ratio.
1295 1 Andreas Smas
feSignal           u32   optional   Signal status percentage.
1296
feBER              u32   optional   Bit error rate.
1297
feUNC              u32   optional   Uncorrected blocks.
1298 73 Adam Sutton
</pre>
1299
1300
h3. timeshiftStatus
1301
1302
Provide status every second about the timeshift buffer.
1303
1304
Message fields:
1305
<pre>
1306
subscriptionId     u32   required   Subscription ID.
1307
full               u32   required   Indicates whether the buffer is full
1308
shift              s64   required   Current position relative to live
1309
start              s64   optional   PTS of the first frame in the buffer
1310
end                s64   optional   PTS of the last frame in the buffer
1311 1 Andreas Smas
</pre>
1312
1313
h3. muxpkt
1314
1315
Streaming data.
1316
1317
Message fields:
1318
<pre>
1319 66 Adam Sutton
subscriptionId     u32   required   Subscription ID.
1320
frametype          u32   required   Type of frame as ASCII value: 'I', 'P', 'B'
1321
stream             u32   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
1322
dts                s64   optional   Decode Time Stamp in µs.
1323
pts                s64   optional   Presentation Time Stamp in µs.
1324
duration           u32   required   Duration of frame in µs.
1325
payload            bin   required   Actual frame data.
1326 1 Andreas Smas
</pre>