Project

General

Profile

Htsp » History » Version 129

Jaroslav Kysela, 2015-05-29 22:13

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