Project

General

Profile

Htsp » History » Version 44

mdd -, 2009-11-30 20:22
added getEvents RPC

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