Project

General

Profile

Htsp » History » Version 163

Delta Mike Charlie, 2023-12-09 07:39

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