Project

General

Profile

Htsp » History » Version 156

Kai Sommerfeld, 2015-09-22 20:01
new getSysTime reply field: gmtoffset

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