Project

General

Profile

Htsp » History » Version 161

Flole Systems, 2020-07-11 23:19

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