Project

General

Profile

Htsp » History » Version 54

Andreas Smas, 2010-08-19 14:57

1 54 Andreas Smas
[[PageOutline]]
2 17 Andreas Smas
= Home Tv Streaming Protocol (HTSP) =
3 1 Andreas Smas
4 17 Andreas Smas
== General ==
5 1 Andreas Smas
6 17 Andreas Smas
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.
7 1 Andreas Smas
8 17 Andreas Smas
The transmission and reception of a channel over HTSP is referred to a subscription. A single HTSP session can handle as many concurrent subscriptions as the bandwidth and CPU permits.
9 1 Andreas Smas
10
11 17 Andreas Smas
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 is suitable for long-distance transmissions and/or paths with non-perfect delivery.
12
(It has been tested with a server in Stockholm and the client in Berlin).
13
14 52 magnus -
The HTS Showtime client can be found [http://trac.lonelycoder.com/hts/browser/trunk/showtime/src/backend/htsp/htsp.c here].
15 22 Andreas Smas
16 18 Andreas Smas
----
17 17 Andreas Smas
== Communication ==
18
19 23 Andreas Smas
This communication is currently implemented by using htsmsg:s. All strings are encoded as UTF-8.
20
21 17 Andreas Smas
There are two distinct ways for communication within HTSP.
22
23 28 Andreas Smas
Apart from this there is a number of messages that needs to be exchanged during login, see the login section below.
24
25 17 Andreas Smas
=== RPC communication ===
26 1 Andreas Smas
27 18 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:
28
29
RPC request extra fields:
30 17 Andreas Smas
{{{
31 1 Andreas Smas
seq              int  optional   Sequence number. This field will be echoed back by the server in the reply.
32 28 Andreas Smas
username         str  optional   Username, in combination with 'digest' this can be used to raise the privileges
33
                                 for the session in combination with invocation of a method. 
34
digest           bin  optional   Used to raise privileges.
35 1 Andreas Smas
}}}
36 28 Andreas Smas
37
The followings field should be used by the client to match the reply with the request.
38 18 Andreas Smas
All replies are guaranteed to arrive in the same order as the requests.
39
Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.
40 1 Andreas Smas
41 18 Andreas Smas
RPC reply extra fields:
42
{{{
43 19 Andreas Smas
seq              int  optional   Sequence number. Same as in the request.
44
error            str  optional   If present an error has occurred and the text describes the error.
45 18 Andreas Smas
noaccess         int  optional   If present and set to '1' the user is prohibited from invoking the method due to 
46 19 Andreas Smas
                                 access restrictions. 
47 18 Andreas Smas
}}}
48 1 Andreas Smas
49 18 Andreas Smas
=== Streaming communication ===
50 19 Andreas Smas
51 1 Andreas Smas
For streaming of live TV and various related messages the server will continuously push data to the client.
52
These messages are referred to as asynchronous messages and always have the 'method' field set and never have the 'seq' field set.
53
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). 
54
55
=== Authentication ===
56
57 34 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.
58 29 Andreas Smas
59 1 Andreas Smas
Privileges for these restrictions may be granted in two ways: Username + Password and/or Source IP address.
60 29 Andreas Smas
Therefore it is possible to gain permissions to the system without entering a username and password.
61 7 Andreas Smas
While this is really useful it also complicates the authentication schema a bit.
62 29 Andreas Smas
Upon connect the initial privileges will be raised based on the source address.
63 1 Andreas Smas
64 34 Andreas Smas
Before any username / password based authentication has taken place the client must have
65
obtained a challenge (which stays fixed for the session). This is done via the 'hello' method.
66
67 1 Andreas Smas
In principle it's possible to use two different authentication idioms with HTSP.
68
Depending on how your application works one or another may be more suitable.
69
While they do not really differ from a protocol point of view it's worth mentioning a bit about them here:
70
71
=== Initial login authentication ===
72
73
The client performs all of its authentication using the 'login' method.
74
75
It may choose to send:
76
 * Username and password: Privileges will be raised based on these credentials.
77
 * Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.
78
 * Nothing: Privileges will be based on just the source address.
79
80
If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based)
81
the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the
82
user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.
83
84
=== On-demand authentication ===
85
86
The client performs all of its authentication when it needs to.
87
88
When using this method, the client will check every RPC reply for the 'noaccess' field.
89
If it set to 1 it whould ask the user for username + password and retry the request but also
90
add 'username' and 'digest' to the original message. (See ''RPC request extra fields'' above)
91
92
Typically it would not send a username or digest during login.
93 29 Andreas Smas
94
----
95
= Client to Server (RPC) methods =
96 34 Andreas Smas
97
98
99
----
100
=== hello ===
101
102
Used to identify the client toward the server and to get the session challenge used to
103
hash passwords into digests. The client can request a different version of the HTSP
104
protocol with this method. If no 'hello' message is sent the server assumes version 1
105
is to be used.
106
107
108
Request message fields:
109
{{{
110
htspversion      int  required   Client preferred HTSP version. If the server does not support this version
111
                                 it will respond with an error and also set the 'invalidversion' field in the reply. 
112
clientname       str  required   Client software name.
113
clientversion    str  required   Client software version.
114
}}}
115
116
117
Reply message fields:
118
{{{
119
htspversion      int  required   The server supports all versions of the protocol up to and including this number.
120
servername       str  required   Server software name.
121
serverversion    str  required   Server software version.
122
challenge        bin  required   32 bytes randomized data used to generate authentication digests
123
invalidversion   int  optional   If set, this means that the server does not understand the requested version.
124
                                 The 'error' field is also set to indicate an error.
125
}}}
126 33 Andreas Smas
127
128
----
129
=== authenticate ===
130
131
This can be used to issue authentication without doing anything else.
132
If no privileges are gained it will return with 'noaccess' set to 1.
133
134
Request message fields:
135
{{{
136
None
137
}}}
138
139
Reply message fields:
140
{{{
141
None
142
}}}
143 10 Andreas Smas
144
----
145
=== enableAsyncMetadata ===
146
147
When this is enabled the client will get continuous updates from the server about channels and tags.
148
This also includes creation and deletion of channels and tags. 
149
150
An interactive application that presents the user with information about channels and tags would probably want to switch to this mode.
151
152
153
Request message fields:
154
{{{
155
None
156
}}}
157
158 1 Andreas Smas
Reply message fields:
159 5 Andreas Smas
{{{
160 1 Andreas Smas
None
161 6 Andreas Smas
}}}
162 23 Andreas Smas
163
164
165
----
166
=== getEvent ===
167
168
Request information about the given event. An event typically corresponds to a program on a channel.
169
170
Request message fields:
171
{{{
172
eventId          int  required   Event ID.
173
}}}
174
175
Reply message fields:
176
{{{
177
start            int  required   Start time of event (Seconds since the epoch, in UTC)
178 6 Andreas Smas
stop             int  required   Ending time of event (Seconds since the epoch, in UTC)
179 47 mdd -
title            str  optional   Title of event.
180
description      str  optional   Description of event. This can be quite huge and may also contain newlines.
181 1 Andreas Smas
channelId        int  required   ID of channel (introduced in HTSP version 4)
182 43 mdd -
nextEventId      int  optional   ID of next event on the same channel.
183 49 mdd -
contentType      int  optional   dvb content code (introduced in HTSP version 4)
184 25 Andreas Smas
}}}
185 1 Andreas Smas
186
----
187 44 mdd -
=== getEvents ===
188
189
Introduced in HTSP version 4.
190
191
Request information about numFollowing events, starting with the given event
192
193
Request message fields:
194
{{{
195
eventId          int   required   Event ID.
196 45 mdd -
numFollowing     int   required   Number of events to add
197 44 mdd -
}}}
198
199
Reply message fields:
200 1 Andreas Smas
{{{
201 45 mdd -
events           msg[] required   List of events, using response message fields from getEvent
202
}}}
203
204
----
205
=== addDvrEntry ===
206
207
Introduced in HTSP version 4.
208
209
Adds an dvr entry for the given eventId.
210
211
Request message fields:
212
{{{
213
eventId          int   required   Event ID.
214
}}}
215
216
Reply message fields:
217
{{{
218
success          int   required   1 if entry was added, 0 otherwise
219
error            str   optional   English clear text of error message
220
}}}
221
222
----
223
=== deleteDvrEntry ===
224
225
Introduced in HTSP version 4.
226
227
Delete a dvr entry with the given id.
228
229
Request message fields:
230
{{{
231
dvrEntryId       int   required   dvrEnryId to delete
232
}}}
233
234
Reply message fields:
235
{{{
236
success          int   required   1 if entry was removed
237 44 mdd -
}}}
238
239
----
240 46 mdd -
=== epgQuery ===
241
242
Introduced in HTSP version 4.
243
244
query the epg, optionally restrict to channels/tags/dvb content type
245
246
Request message fields:
247
{{{
248
query            str   required  String to query epg for
249
channelId        int   optional  ChannelId to restrict search to
250
tagId            int   optional  TagId to restrict search to
251
contentType      int   optional  Dvb epg content type to restrict search to
252
}}}
253
254
Reply message fields:
255
{{{
256
eventIds         int[] optional  List of eventIds that match the query
257
}}}
258
259
----
260 8 Andreas Smas
=== subscribe ===
261
262
Request subscription to the given channel. 
263 1 Andreas Smas
264 6 Andreas Smas
Request message fields:
265
{{{
266
channelId        int  required   ID for channel. 
267
subscriptionId   int  required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
268 4 Andreas Smas
                                 The value is used from now on in all messages related to the subscription.
269 6 Andreas Smas
}}}
270 5 Andreas Smas
271 1 Andreas Smas
Reply message fields:
272 5 Andreas Smas
{{{
273 1 Andreas Smas
None.
274 5 Andreas Smas
}}}
275
276 1 Andreas Smas
277
----
278 6 Andreas Smas
=== unsubscribe ===
279
280
Stop a subscription.
281
Attributes
282 2 Andreas Smas
{{{
283
subscriptionId   int  required   Subscription ID.
284
}}}
285
286
Reply message fields:
287
{{{
288 12 Andreas Smas
None.
289 2 Andreas Smas
}}}
290 1 Andreas Smas
291 40 Andreas Smas
----
292
=== getDiskSpace ===
293
294
Introduced in HTSP version 3.
295
296
Return diskspace status from Tvheadend's PVR storage
297
Attributes
298
{{{
299
}}}
300
301
Reply message fields:
302
{{{
303
freediskspace   int  required   Bytes available.
304
totaldiskspace  int  required   Total capacity.
305
}}}
306
307
----
308
=== getSysTime ===
309
310
Introduced in HTSP version 3.
311
312
Return system time on server
313
Attributes
314
{{{
315
}}}
316
317
Reply message fields:
318
{{{
319
time            int  required   Seconds since the unix epoch.
320
timezone        int  required   Minutes west of GMT.
321
}}}
322 11 Andreas Smas
323
----
324
325
= Server to Client methods =
326
327
----
328
=== channelAdd ===
329
330 13 Andreas Smas
A new channel has been created on the server.
331 11 Andreas Smas
332
Message fields:
333 12 Andreas Smas
{{{
334 1 Andreas Smas
channelId        int   required   ID of channel.
335
channelName      str   required   Name of channel.
336 42 Andreas Smas
channelNumber    int   required   Channel number. 0 means unconfigured
337 11 Andreas Smas
channelIcon      str   required   URL to an icon representative for the channel.
338
eventId          int   optional   ID of the current (or next to be) event on this channel.
339 1 Andreas Smas
tags             int[] optional   Tags this channel is mapped to.
340 11 Andreas Smas
}}}
341
342
----
343
=== channelUpdate ===
344
345 41 Andreas Smas
A channel has been updated on the server. If a field is not present it has not changed. Most clients can process this and the 'channelAdd' message
346 11 Andreas Smas
with the very same code.
347
348 13 Andreas Smas
Message fields:
349 12 Andreas Smas
{{{
350 3 Andreas Smas
channelId        int   required   ID of channel.
351 41 Andreas Smas
channelName      str   optional   Name of channel.
352 42 Andreas Smas
channelNumber    int   optional   Channel number. 0 means unconfigured
353 11 Andreas Smas
channelIcon      str   optioanl   URL to an icon representative for the channel.
354 1 Andreas Smas
eventId          int   optional   ID of the current (or next to be) event on this channel.
355 11 Andreas Smas
tags             int[] required   Tags this channel is mapped to.
356
}}}
357
358
----
359
=== channelDelete ===
360
361
A channel has been deleted on the server.
362 12 Andreas Smas
363 11 Andreas Smas
This message is only sent if session is in asynchronous mode.
364 1 Andreas Smas
365 11 Andreas Smas
Message fields:
366
{{{
367
channelId        int   required   ID of channel.
368
}}}
369 13 Andreas Smas
370 11 Andreas Smas
----
371
=== tagAdd ===
372
373
A new tag has been created on the server.
374
375 1 Andreas Smas
Message fields:
376 11 Andreas Smas
{{{
377 1 Andreas Smas
tagId            int   required   ID of tag.
378 11 Andreas Smas
tagName          str   required   Name of tag.
379
tagIcon          str   optional   URL to an icon representative for the channel.
380 39 elupus -
members          int[] required   Channels this tag is mapped to.
381 11 Andreas Smas
}}}
382 13 Andreas Smas
383 11 Andreas Smas
----
384
=== tagUpdate ===
385
386
A tag has been updated on the server.
387
388 12 Andreas Smas
Message fields:
389 1 Andreas Smas
{{{
390
tagId            int   required   ID of tag.
391 11 Andreas Smas
tagName          str   required   Name of tag.
392
tagIcon          str   optional   URL to an icon representative for the channel.
393 39 elupus -
members          int[] required   Channels this tag is mapped to.
394 1 Andreas Smas
}}}
395 11 Andreas Smas
396
----
397 1 Andreas Smas
=== tagDelete ===
398 11 Andreas Smas
399
A tag has been deleted from the server.
400 12 Andreas Smas
401 11 Andreas Smas
Message fields:
402 2 Andreas Smas
{{{
403 14 Andreas Smas
tagId            str   required   ID of tag.
404
}}}
405
406
----
407 48 mdd -
=== dvrEntryAdd ===
408
409
A new recording has been created on the server.
410
411
Added in HTSP version 4.
412
413
Message fields:
414
{{{
415
id               int   required   ID of dvrEntry.
416
channel          int   required   Channel of dvrEntry.
417 51 elupus -
start            int   required   Time of when this entry was scheduled to start recording.
418
stop             int   required   Time of when this entry was scheduled to stop recording.
419 48 mdd -
title            str   optional   Title of recording
420
description      str   optional   Description of recording. This can be quite huge and may also contain newlines.
421
state            str   required   Plain english status of recoding {scheduled, recording, completed, invalid}.
422
error            str   optional   Plain english error description (e.g. "Aborted by user").
423
}}}
424
425
----
426
=== dvrEntryUpdate ===
427
428
A recording has been updated on the server
429
430
Added in HTSP version 4.
431
432
Message fields:
433
{{{
434
id               int   required   ID of dvrEntry.
435
channel          int   required   Channel of dvrEntry.
436 51 elupus -
start            int   required   Time of when this entry was scheduled to start recording.
437
stop             int   required   Time of when this entry was scheduled to stop recording.
438 48 mdd -
title            str   optional   Title of recording
439
description      str   optional   Description of recording. This can be quite huge and may also contain newlines.
440
state            str   required   Plain english status of recoding {scheduled, recording, completed, invalid}.
441
error            str   optional   Plain english error description (e.g. "Aborted by user").
442
}}}
443
444
----
445
=== dvrEntryDelete ===
446
447
A recording has been deleted from the server.
448
449
Added in HTSP version 4.
450
451
Message fields:
452
{{{
453
id               int   required   ID of recording to delete.
454
}}}
455
456
----
457 35 Andreas Smas
=== initialSyncCompleted ===
458
459
Sent after all the initial channel and tag messages has been sent when session has been set to async mode.
460
461
Added in HTSP version 2.
462
463
Message fields:
464
{{{
465
}}}
466
467
----
468 14 Andreas Smas
=== subscriptionStart ===
469
470
Message fields:
471
{{{
472
subscriptionId   int   required   Subscription ID.
473
streams          msg[] required   Array of messages with stream information
474 38 Andreas Smas
sourceinfo       msg   optional   Message with strings in it. Each string is a descriptive
475
                                  entity about the source. All strings are optional any should
476
                                  only be thought of as informational.
477 14 Andreas Smas
478
'streams' message:
479
480
index            int   required   Index for this stream
481
type             str   required   Type of stream
482
language         str   optional   Language for stream
483 53 Andreas Smas
width            int   optional   Width of video in pixels (Video components only)
484
height           int   optional   Height of video in pixels (Video components only)
485 14 Andreas Smas
486
487 1 Andreas Smas
Stream types:
488 14 Andreas Smas
    AC3                           AC3 audio
489
    MPEG2AUDIO                    MPEG2 audio (MP2)
490 21 Andreas Smas
    MPEG2VIDEO                    MPEG2 video
491 12 Andreas Smas
    H264                          H264 video
492 37 Andreas Smas
    AAC                           ADTS framed AAC (one AAC packet per ADTS frame)
493 15 Andreas Smas
}}}
494
495
496
----
497
=== subscriptionStop ===
498
499 12 Andreas Smas
Message fields:
500 2 Andreas Smas
{{{
501
subscriptionId   int   required   Subscription ID.
502 15 Andreas Smas
reason           str   optional   Reason for subscription stop.
503
}}}
504
505
----
506
=== subscriptionStatus ===
507
508
Message fields:
509 1 Andreas Smas
{{{
510 2 Andreas Smas
subscriptionId   int   required   Subscription ID.
511 37 Andreas Smas
status           str   optional   English clear text of error status. Absence of this field means that the status is OK. 
512 15 Andreas Smas
}}}
513
514
515
----
516
=== queueStatus ===
517
518
The queueStatus message is sent every second during normal data delivery.
519
520
The transmit scheduler have different drop thresholds for different frame types.
521
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
522
All audio is recognized as I-frames. 
523
524
Message fields:
525
{{{
526
subscriptionId   int   required   Subscription ID.
527
packets          int   required   Number of data packets in queue.
528 16 Andreas Smas
bytes            int   required   Number of bytes in queue.
529
delay            int   required   Estimated delay of queue (in µs)
530
Bdrops           int   required   Number of B-frames dropped
531
Pdrops           int   required   Number of P-frames dropped
532
Idrops           int   required   Number of I-frames dropped
533
}}}
534
535
----
536
=== muxpkt ===
537
538
Streaming data.
539
540
Message fields:
541
{{{
542
subscriptionId   int   required   Subscription ID.
543
frametype        int   required   Type of frame as ASCII value: 'I', 'P', 'B'
544
stream           int   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
545 1 Andreas Smas
dts              int   required   Decode Time Stamp in µs.
546
pts              int   required   Presentation Time Stamp in µs.
547
duration         int   required   Duration of frame in µs.
548
payload          bin   required   Actual frame data.
549
550
}}}