Project

General

Profile

Htsp » History » Version 18

Andreas Smas, 2009-02-28 17:37

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 18 Andreas Smas
----
14 17 Andreas Smas
== Communication ==
15
16
There are two distinct ways for communication within HTSP.
17
18
=== RPC communication ===
19 1 Andreas Smas
20 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:
21
22
RPC request extra fields:
23 17 Andreas Smas
{{{
24
seq              int  optional   Sequence number. This field will be echoed back by the server in the reply.
25 1 Andreas Smas
}}}
26
This field should be used by the client to match the reply with the request.
27 18 Andreas Smas
All replies are guaranteed to arrive in the same order as the requests.
28
Even so, probably the best way to implement the request-reply client is by taking advantage of the 'seq' field.
29 1 Andreas Smas
30 18 Andreas Smas
RPC reply extra fields:
31
{{{
32
seq              int  optional   Sequence number. Same as in the request.
33
error            str  optional   If present an error has occurred and the text describes the error.
34
noaccess         int  optional   If present and set to '1' the user is prohibited from invoking the method due to access restrictions. 
35
                                 The client should first try to authenticate and then try to re-invoke the method.
36
challenge        bin  optional   If 'noaccess' is set the server also provides a challenge to be used in the (if the user decides so) upcoming 
37
                                 'authentication' request.
38
}}}
39 1 Andreas Smas
40
41 17 Andreas Smas
42 18 Andreas Smas
=== Streaming communication ===
43 1 Andreas Smas
44 17 Andreas Smas
For streaming of live TV and various related messages the server will continuously push data to the client. 
45 18 Andreas Smas
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). These messages 
46 17 Andreas Smas
47
48
49 18 Andreas Smas
----
50 17 Andreas Smas
== Flow of a subscription ==
51
52
When the client wish to receive a channel it starts by sending a 'subscribe' request. The server responds
53
54
55
56 1 Andreas Smas
----
57
58 17 Andreas Smas
= Client to Server (RPC) methods =
59 1 Andreas Smas
60 5 Andreas Smas
----
61 1 Andreas Smas
=== getChallenge ===
62
63 7 Andreas Smas
Request a 32 byte challenge used to generate a authentication digest.
64
65
Request message fields:
66
{{{
67
None
68
}}}
69
70
Reply message fields:
71
{{{
72 9 Andreas Smas
challenge        bin  required   32 bytes of random challenge to be used in next authentication request from client.
73 7 Andreas Smas
}}}
74
75
76 5 Andreas Smas
----
77 1 Andreas Smas
=== authenticate ===
78 8 Andreas Smas
79
Request message fields:
80 7 Andreas Smas
{{{
81
username         str  required   Username.
82
digest           bin  required   SHA-1 hash of [password (not including terminating NUL)] + [challenge]
83
}}}
84 1 Andreas Smas
85 9 Andreas Smas
Reply message fields:
86
{{{
87
noaccess         int  optional   Set to '1' if access was denied.
88 1 Andreas Smas
challenge        bin  optional   32 bytes of random challenge to be used in next authentication request from client.
89 7 Andreas Smas
                                 Always present if 'noaccess' is set. This is supplied so the client does not have
90
                                 to issue an extra 'getChallenge' request.
91
}}}
92 5 Andreas Smas
93 10 Andreas Smas
94
----
95 18 Andreas Smas
=== enableAsyncMetadata ===
96 10 Andreas Smas
97 18 Andreas Smas
When this is enabled the client will get continuous updates from the server about channels and tags.
98 10 Andreas Smas
This also includes creation and deletion of channels and tags. 
99
100
An interactive application that presents the user with information about channels and tags would probably want to switch to this mode.
101
102
103
Request message fields:
104
{{{
105
None
106
}}}
107
108
Reply message fields:
109
{{{
110
None
111
}}}
112
113 1 Andreas Smas
114 5 Andreas Smas
115 1 Andreas Smas
----
116 6 Andreas Smas
=== getEvent ===
117
118 1 Andreas Smas
----
119 6 Andreas Smas
=== subscribe ===
120
121
Request subscription to the given channel. A request for a subscription is always successful.
122 4 Andreas Smas
When the server is ready to transmit data it will first send a 'subscriptionStart' message.
123
124 1 Andreas Smas
125
126
Request message fields:
127 8 Andreas Smas
{{{
128
channelId        int  required   ID for channel. 
129
subscriptionId   int  required   Subscription ID. Selected by client. This value is not interpreted by the server in any form. 
130 1 Andreas Smas
                                 The value is used from now on in all messages related to the subscription.
131 6 Andreas Smas
}}}
132
133
Reply message fields:
134
{{{
135 4 Andreas Smas
None.
136 6 Andreas Smas
}}}
137 5 Andreas Smas
138 1 Andreas Smas
139 5 Andreas Smas
----
140 1 Andreas Smas
=== unsubscribe ===
141 5 Andreas Smas
142
Stop a subscription.
143 1 Andreas Smas
Attributes
144
{{{
145 6 Andreas Smas
subscriptionId   int  required   Subscription ID.
146
}}}
147
148
Reply message fields:
149 2 Andreas Smas
{{{
150
None.
151
}}}
152
153
154
----
155 12 Andreas Smas
156 2 Andreas Smas
= Server to Client methods =
157 1 Andreas Smas
158 11 Andreas Smas
----
159
=== channelAdd ===
160
161
A new channel has been created on the server.
162
163
Message fields:
164
{{{
165
channelId        int   required   ID of channel.
166 13 Andreas Smas
channelName      str   required   Name of channel.
167 11 Andreas Smas
channelIcon      str   required   URL to an icon representative for the channel.
168
eventId          int   optional   ID of the current (or next to be) event on this channel.
169 12 Andreas Smas
tags             int[] optional   Tags this channel is mapped to.
170 1 Andreas Smas
}}}
171
172 11 Andreas Smas
----
173
=== channelUpdate ===
174 1 Andreas Smas
175 11 Andreas Smas
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
176
with the very same code.
177
178
Message fields:
179
{{{
180
channelId        int   required   ID of channel.
181
channelName      str   required   Name of channel.
182
channelIcon      str   optioanl   URL to an icon representative for the channel.
183 13 Andreas Smas
eventId          int   optional   ID of the current (or next to be) event on this channel.
184 12 Andreas Smas
tags             int[] required   Tags this channel is mapped to.
185 3 Andreas Smas
}}}
186 1 Andreas Smas
187 11 Andreas Smas
----
188 1 Andreas Smas
=== channelDelete ===
189 11 Andreas Smas
190
A channel has been deleted on the server.
191
192
This message is only sent if session is in asynchronous mode.
193
194
Message fields:
195
{{{
196 12 Andreas Smas
channelId        int   required   ID of channel.
197 11 Andreas Smas
}}}
198 1 Andreas Smas
199 11 Andreas Smas
----
200
=== tagAdd ===
201
202
A new tag has been created on the server.
203 13 Andreas Smas
204 11 Andreas Smas
Message fields:
205
{{{
206
tagId            int   required   ID of tag.
207
tagName          str   required   Name of tag.
208
tagIcon          str   optional   URL to an icon representative for the channel.
209 1 Andreas Smas
channels         int[] required   Channels this tag is mapped to.
210 11 Andreas Smas
}}}
211 1 Andreas Smas
212 11 Andreas Smas
----
213
=== tagUpdate ===
214
215
A tag has been updated on the server.
216 13 Andreas Smas
217 11 Andreas Smas
Message fields:
218
{{{
219
tagId            int   required   ID of tag.
220
tagName          str   required   Name of tag.
221
tagIcon          str   optional   URL to an icon representative for the channel.
222 12 Andreas Smas
channels         int[] required   Channels this tag is mapped to.
223 1 Andreas Smas
}}}
224
225 11 Andreas Smas
----
226
=== tagDelete ===
227
228 1 Andreas Smas
A tag has been deleted from the server.
229 11 Andreas Smas
230
Message fields:
231 1 Andreas Smas
{{{
232 11 Andreas Smas
tagId            str   required   ID of tag.
233
}}}
234 12 Andreas Smas
235 11 Andreas Smas
----
236 2 Andreas Smas
=== subscriptionStart ===
237 14 Andreas Smas
238
Message fields:
239
{{{
240
subscriptionId   int   required   Subscription ID.
241
streams          msg[] required   Array of messages with stream information
242
243
244
'streams' message:
245
246
index            int   required   Index for this stream
247
type             str   required   Type of stream
248
language         str   optional   Language for stream
249
250
251
Stream types:
252
    AC3                           AC3 audio
253
    MPEG2AUDIO                    MPEG2 audio (MP2)
254
    MPEG2VIDEO                    MPEG2 video
255
    H264                          H264 video
256
257
258
}}}
259 12 Andreas Smas
260 2 Andreas Smas
----
261
=== subscriptionStop ===
262 15 Andreas Smas
263
Message fields:
264
{{{
265
subscriptionId   int   required   Subscription ID.
266
reason           str   optional   Reason for subscription stop.
267
}}}
268 12 Andreas Smas
269 2 Andreas Smas
----
270
=== subscriptionStatus ===
271 15 Andreas Smas
272
Message fields:
273
{{{
274
subscriptionId   int   required   Subscription ID.
275
status           str   optional   English clear text of status. Absence of this field means that the status is OK. 
276
}}}
277
278 12 Andreas Smas
279 2 Andreas Smas
----
280 15 Andreas Smas
=== queueStatus ===
281
282
The queueStatus message is sent every second during normal data delivery.
283
284
The transmit scheduler have different drop thresholds for different frame types.
285
If congestion occurs it will favor dropping B-frames before P-frames before I-frames.
286
All audio is recognized as I-frames. 
287
288
Message fields:
289
{{{
290
subscriptionId   int   required   Subscription ID.
291
packets          int   required   Number of data packets in queue.
292
bytes            int   required   Number of bytes in queue.
293
delay            int   required   Estimated delay of queue (in µs)
294
Bdrops           int   required   Number of B-frames dropped
295
Pdrops           int   required   Number of P-frames dropped
296
Idrops           int   required   Number of I-frames dropped
297 16 Andreas Smas
}}}
298
299
----
300
=== muxpkt ===
301
302
Streaming data.
303
304
Message fields:
305
{{{
306
subscriptionId   int   required   Subscription ID.
307
frametype        int   required   Type of frame as ASCII value: 'I', 'P', 'B'
308
stream           int   required   Stream index. Corresponds to the streams reported in the subscriptionStart message.
309
dts              int   required   Decode Time Stamp in µs.
310
pts              int   required   Presentation Time Stamp in µs.
311
duration         int   required   Duration of frame in µs.
312
payload          bin   required   Actual frame data.
313
314 1 Andreas Smas
}}}