Project

General

Profile

Htsp » History » Version 109

Jaroslav Kysela, 2014-10-19 21:31

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