Project

General

Profile

Htsp » History » Version 157

Kai Sommerfeld, 2015-09-26 18:39

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