Project

General

Profile

Htsp » History » Version 159

Jaroslav Kysela, 2018-10-15 08:52

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