Project

General

Profile

Htsp » History » Version 117

Jaroslav Kysela, 2015-05-29 21:53

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