Project

General

Profile

Htsp » History » Version 106

Jaroslav Kysela, 2014-10-19 21:20

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