Project

General

Profile

Htsp » History » Version 96

Jaroslav Kysela, 2014-10-19 20:58

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