Project

General

Profile

Htsp » History » Version 33

Andreas Smas, 2009-03-03 23:17

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 28 Andreas Smas
=== Login ===
55 1 Andreas Smas
56 28 Andreas Smas
Upon connect the server sends a welcome message looking like this:
57 1 Andreas Smas
58 19 Andreas Smas
{{{
59 28 Andreas Smas
method           str  required   Contains 'welcome'
60
htspversion      int  required   The server supports all versions of the protocol up to and including this number.
61
servername       str  required   Server software name.
62
serverversion    str  required   Server software version.
63
challenge        bin  required   32 bit randomized data used to generate authentication digests
64
}}}
65 19 Andreas Smas
66 28 Andreas Smas
The client is then expected to reply with:
67 19 Andreas Smas
68 1 Andreas Smas
{{{
69 28 Andreas Smas
method           str  required   Contains 'login'
70
htspversion      int  required   HTSP protocol version the client wish to use.
71
username         str  optional   Login username. If omitted the login is considered anonymous.
72 29 Andreas Smas
digest           bin  optional   SHA-1 hash of [password (not including terminating NUL)] + [challenge from welcome message]
73 19 Andreas Smas
}}}
74 1 Andreas Smas
75
The server will in turn reply with:
76
77 19 Andreas Smas
{{{
78 1 Andreas Smas
method           str  required   Contains 'loginAck'
79 29 Andreas Smas
noaccess         int  optional   The initial credentials did not grant access to any methods.
80
                                 If the client employs 'on-demand authentication' it will chose to ignore this.
81
error            str  optional   If set, an error occurred during login. The connection will be terminated by the server.
82 1 Andreas Smas
}}}
83
84
After this procedure normal communication may take place.
85
86 29 Andreas Smas
=== Authentication ===
87 1 Andreas Smas
88 29 Andreas Smas
In Tvheadend, each method has an associated access restriction. Currently there is only on restriction (Streaming). However, this may change in the future.
89 7 Andreas Smas
90 29 Andreas Smas
Privileges for these restrictions may be granted in two ways: Username + Password and/or Source IP address.
91
Therefore it is possible to gain permissions to the system without entering a username and password.
92
While this is really useful it also complicates the authentication schema a bit.
93
Upon connect the initial privileges will be raised based on the source address.
94 7 Andreas Smas
95 29 Andreas Smas
In principle it's possible to use two different authentication idioms with HTSP.
96
Depending on how your application works one or another may be more suitable.
97 31 Andreas Smas
While they do not really differ from a protocol point of view it's worth mentioning a bit about them here:
98 1 Andreas Smas
99 31 Andreas Smas
=== Initial login authentication ===
100 26 Andreas Smas
101 29 Andreas Smas
The client performs all of its authentication using the 'login' method.
102 26 Andreas Smas
103 1 Andreas Smas
It may choose to send:
104 32 Andreas Smas
 * Username and password: Privileges will be raised based on these credentials.
105
 * Username only: Privileges will be based on just the source address. The username will be used for various logging purposes.
106
 * Nothing: Privileges will be based on just the source address.
107 1 Andreas Smas
108 30 Andreas Smas
If no privileges are granted after the login message has been received by the server (i.e. both network and username + password based)
109
the server will reply with 'noaccess' set to 1. A client that only employs initial login should honor this flag and ask the
110 33 Andreas Smas
user for a username + password and retry by using the 'authenticate' method. I.e. it should not send the 'login' method again.
111 1 Andreas Smas
112 30 Andreas Smas
=== On-demand authentication ===
113 1 Andreas Smas
114 30 Andreas Smas
The client performs all of its authentication when it needs to.
115 1 Andreas Smas
116 30 Andreas Smas
When using this method, the client will check every RPC reply for the 'noaccess' field.
117
If it set to 1 it whould ask the user for username + password and retry the request but also
118
add 'username' and 'digest' to the original message. (See ''RPC request extra fields'' above)
119 10 Andreas Smas
120 30 Andreas Smas
Typically it would not send a username or digest during login.
121 29 Andreas Smas
122
----
123 1 Andreas Smas
= Client to Server (RPC) methods =
124 33 Andreas Smas
125
126
----
127
=== authenticate ===
128
129
This can be used to issue authentication without doing anything else.
130
If no privileges are gained it will return with 'noaccess' set to 1.
131
132
Request message fields:
133
{{{
134
None
135
}}}
136
137
Reply message fields:
138
{{{
139
None
140
}}}
141 10 Andreas Smas
142
----
143
=== enableAsyncMetadata ===
144
145
When this is enabled the client will get continuous updates from the server about channels and tags.
146
This also includes creation and deletion of channels and tags. 
147
148
An interactive application that presents the user with information about channels and tags would probably want to switch to this mode.
149
150
151
Request message fields:
152
{{{
153
None
154
}}}
155
156 1 Andreas Smas
Reply message fields:
157 5 Andreas Smas
{{{
158 1 Andreas Smas
None
159 6 Andreas Smas
}}}
160 23 Andreas Smas
161
162
163
----
164
=== getEvent ===
165
166
Request information about the given event. An event typically corresponds to a program on a channel.
167
168
Request message fields:
169
{{{
170
eventId          int  required   Event ID.
171
}}}
172
173
Reply message fields:
174
{{{
175
start            int  required   Start time of event (Seconds since the epoch, in UTC)
176 6 Andreas Smas
stop             int  required   Ending time of event (Seconds since the epoch, in UTC)
177 1 Andreas Smas
title            str  required   Title of event.
178 6 Andreas Smas
description      str  required   Description of event. This can be quite huge and may also contain newlines.
179
nextEventId      int  optional   ID of next event on the same channel.
180 25 Andreas Smas
}}}
181 1 Andreas Smas
182
----
183 8 Andreas Smas
=== subscribe ===
184
185
Request subscription to the given channel. 
186 1 Andreas Smas
187 6 Andreas Smas
Request message fields:
188
{{{
189
channelId        int  required   ID for channel. 
190
subscriptionId   int  required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
191 4 Andreas Smas
                                 The value is used from now on in all messages related to the subscription.
192 6 Andreas Smas
}}}
193 5 Andreas Smas
194 1 Andreas Smas
Reply message fields:
195 5 Andreas Smas
{{{
196 1 Andreas Smas
None.
197 5 Andreas Smas
}}}
198
199 1 Andreas Smas
200
----
201 6 Andreas Smas
=== unsubscribe ===
202
203
Stop a subscription.
204
Attributes
205 2 Andreas Smas
{{{
206
subscriptionId   int  required   Subscription ID.
207
}}}
208
209
Reply message fields:
210
{{{
211 12 Andreas Smas
None.
212 2 Andreas Smas
}}}
213 1 Andreas Smas
214 11 Andreas Smas
215
----
216
217
= Server to Client methods =
218
219
----
220
=== channelAdd ===
221
222 13 Andreas Smas
A new channel has been created on the server.
223 11 Andreas Smas
224
Message fields:
225 12 Andreas Smas
{{{
226 1 Andreas Smas
channelId        int   required   ID of channel.
227
channelName      str   required   Name of channel.
228 11 Andreas Smas
channelIcon      str   required   URL to an icon representative for the channel.
229
eventId          int   optional   ID of the current (or next to be) event on this channel.
230 1 Andreas Smas
tags             int[] optional   Tags this channel is mapped to.
231 11 Andreas Smas
}}}
232
233
----
234
=== channelUpdate ===
235
236
A channel has been updated on the server. All fields will be sent even if they are not changed. Most clients can process this and the 'channelAdd' message
237
with the very same code.
238
239 13 Andreas Smas
Message fields:
240 12 Andreas Smas
{{{
241 3 Andreas Smas
channelId        int   required   ID of channel.
242 1 Andreas Smas
channelName      str   required   Name of channel.
243 11 Andreas Smas
channelIcon      str   optioanl   URL to an icon representative for the channel.
244 1 Andreas Smas
eventId          int   optional   ID of the current (or next to be) event on this channel.
245 11 Andreas Smas
tags             int[] required   Tags this channel is mapped to.
246
}}}
247
248
----
249
=== channelDelete ===
250
251
A channel has been deleted on the server.
252 12 Andreas Smas
253 11 Andreas Smas
This message is only sent if session is in asynchronous mode.
254 1 Andreas Smas
255 11 Andreas Smas
Message fields:
256
{{{
257
channelId        int   required   ID of channel.
258
}}}
259 13 Andreas Smas
260 11 Andreas Smas
----
261
=== tagAdd ===
262
263
A new tag has been created on the server.
264
265 1 Andreas Smas
Message fields:
266 11 Andreas Smas
{{{
267 1 Andreas Smas
tagId            int   required   ID of tag.
268 11 Andreas Smas
tagName          str   required   Name of tag.
269
tagIcon          str   optional   URL to an icon representative for the channel.
270
channels         int[] required   Channels this tag is mapped to.
271
}}}
272 13 Andreas Smas
273 11 Andreas Smas
----
274
=== tagUpdate ===
275
276
A tag has been updated on the server.
277
278 12 Andreas Smas
Message fields:
279 1 Andreas Smas
{{{
280
tagId            int   required   ID of tag.
281 11 Andreas Smas
tagName          str   required   Name of tag.
282
tagIcon          str   optional   URL to an icon representative for the channel.
283
channels         int[] required   Channels this tag is mapped to.
284 1 Andreas Smas
}}}
285 11 Andreas Smas
286
----
287 1 Andreas Smas
=== tagDelete ===
288 11 Andreas Smas
289
A tag has been deleted from the server.
290 12 Andreas Smas
291 11 Andreas Smas
Message fields:
292 2 Andreas Smas
{{{
293 14 Andreas Smas
tagId            str   required   ID of tag.
294
}}}
295
296
----
297
=== subscriptionStart ===
298
299
Message fields:
300
{{{
301
subscriptionId   int   required   Subscription ID.
302
streams          msg[] required   Array of messages with stream information
303
304
305
'streams' message:
306
307
index            int   required   Index for this stream
308
type             str   required   Type of stream
309
language         str   optional   Language for stream
310
311
312 1 Andreas Smas
Stream types:
313 14 Andreas Smas
    AC3                           AC3 audio
314
    MPEG2AUDIO                    MPEG2 audio (MP2)
315 21 Andreas Smas
    MPEG2VIDEO                    MPEG2 video
316 12 Andreas Smas
    H264                          H264 video
317 2 Andreas Smas
318
319 15 Andreas Smas
}}}
320
321
322
----
323
=== subscriptionStop ===
324
325 12 Andreas Smas
Message fields:
326 2 Andreas Smas
{{{
327
subscriptionId   int   required   Subscription ID.
328 15 Andreas Smas
reason           str   optional   Reason for subscription stop.
329
}}}
330
331
----
332
=== subscriptionStatus ===
333
334
Message fields:
335 12 Andreas Smas
{{{
336 2 Andreas Smas
subscriptionId   int   required   Subscription ID.
337 15 Andreas Smas
status           str   optional   English clear text of status. Absence of this field means that the status is OK. 
338
}}}
339
340
341
----
342
=== queueStatus ===
343
344
The queueStatus message is sent every second during normal data delivery.
345
346
The transmit scheduler have different drop thresholds for different frame types.
347
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
348
All audio is recognized as I-frames. 
349
350
Message fields:
351
{{{
352
subscriptionId   int   required   Subscription ID.
353
packets          int   required   Number of data packets in queue.
354 16 Andreas Smas
bytes            int   required   Number of bytes in queue.
355
delay            int   required   Estimated delay of queue (in µs)
356
Bdrops           int   required   Number of B-frames dropped
357
Pdrops           int   required   Number of P-frames dropped
358
Idrops           int   required   Number of I-frames dropped
359
}}}
360
361
----
362
=== muxpkt ===
363
364
Streaming data.
365
366
Message fields:
367
{{{
368
subscriptionId   int   required   Subscription ID.
369
frametype        int   required   Type of frame as ASCII value: 'I', 'P', 'B'
370
stream           int   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
371 1 Andreas Smas
dts              int   required   Decode Time Stamp in µs.
372
pts              int   required   Presentation Time Stamp in µs.
373
duration         int   required   Duration of frame in µs.
374
payload          bin   required   Actual frame data.
375
376
}}}