Project

General

Profile

Htsp » History » Version 102

Jaroslav Kysela, 2014-10-19 21:10

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