Project

General

Profile

Htsp » History » Version 85

Jaroslav Kysela, 2014-10-19 17:51

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