Project

General

Profile

Htsp » History » Version 162

Delta Mike Charlie, 2023-08-03 02:11

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