Project

General

Profile

Htsp » History » Version 89

Jaroslav Kysela, 2014-10-19 18:06

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