Project

General

Profile

Htsp » History » Version 84

Jaroslav Kysela, 2014-10-19 17:40

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