Project

General

Profile

Htsp » History » Version 28

Andreas Smas, 2009-03-03 22:31

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