Project

General

Profile

Htsp » History » Version 17

Andreas Smas, 2009-02-28 17:25

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