Project

General

Profile

Htsp » History » Version 126

Jaroslav Kysela, 2015-05-29 22:11

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