Project

General

Profile

Htsp » History » Version 140

Jaroslav Kysela, 2015-05-29 22:35

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