Project

General

Profile

Htsp » History » Version 97

Jaroslav Kysela, 2014-10-19 21:02

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