Project

General

Profile

Htsp » History » Version 110

Jaroslav Kysela, 2014-10-19 21:36

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