4 The RTSP source establishes a connection to an RTSP server and sets up
5 the UDP sources and RTP session handlers.
7 An RTSP session is created as follows:
12 rtsp://thread:5454/south-rtsp.mp3
14 - Open a connection to the server with the url. All further conversation with
15 the server should be done with this connection. Each request/reply has
16 a CSeq number added to the header.
18 - Send a DESCRIBE request for the url. We currently support a response in
23 >> DESCRIBE rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
24 >> Accept: application/sdp
29 << Content-Type: application/sdp
31 << Date: Wed May 11 13:09:37 2005 GMT
34 << o=- 0 0 IN IP4 192.168.1.1
36 << m=audio 0 RTP/AVP 14
37 << a=control:streamid=0
39 - Parse the SDP message, for each stream (m=) we create an GstRTPStream. We need
40 to allocate two local UDP ports for receiving the RTP and RTCP data because we
41 need to send the port numbers to the server in the next request.
43 In RTSPSrc we first create an element that can handle the udp://0.0.0.0:0 uri. This
44 will create an udp source element with a random port number. We get the port
45 number by getting the "port" property of the element after setting the element to
46 PAUSED. This element is used for the RTP packets and has to be an even number. If
47 the random port number is not an even number we retry to allocate a new udp source.
49 We then create another UDP source element with the next (uneven) port number to
50 receive the RTCP packet on. After this step we have two udp ports we can use to
64 - Send a SETUP message to the server with the RTP ports. We get the setup URI from
65 the a= attribute in the SDP message. This can be an absolute URL or a relative
70 >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
72 >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
75 << Transport: RTP/AVP/UDP;unicast;client_port=5000-5001;server_port=6000-6001
77 << Date: Wed May 11 13:21:43 2005 GMT
78 << Session: 5d5cb94413288ccd
81 The client needs to send the local ports to the server along with the supported
82 transport types. The server selects the final transport which it returns in the
83 Transport header field. The server also includes its ports where RTP and RTCP
84 messages can be sent to.
86 In the above example UDP was choosen as a transport. At this point the RTSPSrc element
87 will furter configure its elements to process this stream.
89 The RTSPSrc will create and connect an RTP session manager element and will
90 connect it to the src pads of the udp element. The data pad from the RTP session
91 manager is ghostpadded to RTPSrc.
92 The RTCP pad of the rtpdec is routed to a new udpsink that sends data to the RTCP
93 port of the server as returned in the Transport: header field.
95 +---------------------------------------------+
97 | | udpsrc0 | +--------+ |
98 | | port=5000 ----- rtpdec --------------------
99 | +------------+ | | |
100 | +------------+ | | +------------+ |
101 | | udpsrc1 ----- RTCP ---- udpsink | |
102 | | port=5001 | +--------+ | port=6001 | |
103 | +------------+ +------------+ |
104 +---------------------------------------------+
106 The output type of rtpdec is configured as the media type specified in the SDP
109 - All the elements are set to PAUSED/PLAYING and the PLAY RTSP message is
112 >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
114 >> Session: 5d5cb94413288ccd
118 << Date: Wed May 11 13:21:43 2005 GMT
119 << Session: 5d5cb94413288ccd
122 - The udp source elements receive data from that point and the RTP/RTCP messages
123 are processed by the elements.
125 - In the case of interleaved mode, the SETUP method yields:
127 >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
129 >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
132 << Transport: RTP/AVP/TCP;interleaved=0-1
134 << Date: Wed May 11 13:21:43 2005 GMT
135 << Session: 5d5cb94413288ccd
138 This means that RTP/RTCP messages will be sent on channel 0/1 respectively and that
139 the data will be received on the same connection as the RTSP connection.
141 At this point, we remove the UDP source elements as we don't need them anymore. We
142 set up the rtpsess session manager element though as follows:
144 +---------------------------------------------+
146 | | _loop() | +--------+ |
147 | | ----- rtpses --------------------
149 | | | | | +------------+ |
150 | | ----- RTCP ---- udpsink | |
151 | | | +--------+ | port=6001 | |
152 | +------------+ +------------+ |
153 +---------------------------------------------+
155 We start an interal task to start reading from the RTSP connection waiting
156 for data. The received data is then pushed to the rtpdec element.
158 When reading from the RTSP connection we receive data packets in the
159 following layout (see also RFC2326)
161 $<1 byte channel><2 bytes length, big endian><length bytes of data>
167 An RTSP server listen on a port (default 554) for client connections. The client
168 typically keeps this channel open during the RTSP session to instruct the server
169 to pause/play/stop the stream.
171 The server exposes a stream consisting of one or more media streams using an
172 URL. The media streams are typically audio and video.
175 rtsp://thread:5454/alien-rtsp.mpeg
177 exposes an audio/video stream. The video is mpeg packetized in RTP and
178 the audio is mp3 in RTP.
180 The streaming server typically uses a different channel to send the media
181 data to clients, typically using RTP over UDP. It is also possible to stream
182 the data to the client using the initial RTSP TCP session (the interleaved
183 mode). This last mode is usufull when the client is behind a firewall but
184 does not take advantage of the RTP/UDP features.
186 In both cases, media data is send to the clients in an unmultiplexed format
187 packetized as RTP packets.
189 The streaming server has to negotiate a connection protocol for each of the
190 media streams with the client.
192 Minimal server requirements:
194 - The server should copy the CSeq header field in a client request to the
195 response so that the client can match the response to the request.
197 - The server should keep a session for each client after the client issued
198 a SETUP command. The client should use the same session id for all future
199 request to this server.
201 - the server must support an OPTIONS request send over the RTSP connection.
203 >> OPTIONS * RTSP/1.0
208 << Date: Wed May 11 13:21:43 2005 GMT
209 << Session: 5d5cb94413288ccd
210 << Public: DESCRIBE, SETUP, TEARDOWN, PLAY
213 The OPTIONS request should list all supported methods on the server.
215 - The server should support the DESCRIBE method.
217 >> DESCRIBE rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
218 >> Accept: application/sdp
222 << Content-Length: 84
223 << Content-Type: application/sdp
225 << Date: Wed May 11 13:09:37 2005 GMT
228 << o=- 0 0 IN IP4 192.168.1.1
230 << m=audio 0 RTP/AVP 14
231 << a=control:streamid=0
233 The client issues a DESCRIBE command for a specific URL that corresponds
234 to an available stream. The client will also send an Accept header to
235 list its supported formats.
237 The server answers this request with a reply in one of the client supported
238 formats (application/sdp is the most common). The server typically sends a
239 fixed reply to all clients for each configured stream.
241 - The server must support the SETUP command to configure the media streams
242 that were listed in the DESCRIBE command.
244 >> SETUP rtsp://thread:5454/south-rtsp.mp3/streamid=0 RTSP/1.0
246 >> Transport: RTP/AVP/UDP;unicast;client_port=5000-5001,RTP/AVP/UDP;multicast,RTP/AVP/TCP
249 << Transport: RTP/AVP/UDP;unicast;client_port=5000-5001;server_port=6000-6001
251 << Date: Wed May 11 13:21:43 2005 GMT
252 << Session: 5d5cb94413288ccd
254 The client will send a SETUP command for each of the streams listed in the
255 DESCRIBE reply. For sdp will use a URL as listed in the a=control: property.
257 The client will list the supported transports in the Transport: header field.
258 Each transport is separated with a comma (,) and listed in order of preference.
259 The server has to select the first supported transport.
261 In the above example 3 transport are listed:
263 RTP/AVP/UDP;unicast;client_port=5000-5001
265 The client will accept RTP over UDP on the port pair 5000-5001. Port
266 5000 will accept the RTP packets, 5001 the RTSP packets send by the
269 RTP/AVP/UDP;multicast
271 The client can join a multicast group for the specific media stream.
272 The port numbers of the multicast group it will connect to have to
273 be specified by the server in the reply.
277 the client can accept RTP packets interleaved on the RTSP connection.
279 The server selects a supported transport an allocates an RTP port pair to
280 receive RTP and RTSP data from the client. This last step is optional when
281 the server does not accept RTP data.
283 The server should allocate a session for the client and should send the
284 sessionId to the client. The client should use this session id for all
287 The server may refuse a client that does not use the same transport method
288 for all media streams.
290 The server stores all client port pairs in the server client session along
291 with the transport method.
295 For an on-demand stream the server could construct a (minimal) RTP GStreamer
296 pipeline for the client as follows (for an mp3 stream):
298 +---------+ +-----------+ +------------+ +-------------+
299 | filesrc | | rtpmp3enc | | rtpsession | | udpsink |
300 | | | | | | | host=XXX |
301 | | | | | | | port=5000 |
302 | src--sink src--rtpsink rtpsrc--sink |
303 +---------+ +-----------+ | | +-------------+
309 +------------+ +-------------+
311 The server would set the above pipeline to PAUSE to make sure no data
312 is sent to the client yet.
314 optionally udpsrc elements can be configured to receive client RTP and
319 For a live stream the server could construct a (minimal) RTP GStreamer
320 pipeline for the clients as follows (for an mp3 stream):
322 +---------+ +--------+ +-----------+ +------------+ +--------------+
323 | source | | mp3enc | | rtpmp3enc | | rtpsession | | multiudpsink |
324 | | | | | | | | | host=... |
325 | | | | | | | | | port=... |
326 | src--sink src--sink src--rtpsink rtpsrc--sink |
327 +---------+ +--------+ +-----------+ | | +--------------+
333 +------------+ +--------------+
335 Media data is streamed to clients by adding the client host and port numbers
336 to the multiudpsinks.
338 optionally udpsrc elements can be configured to receive client RTP and
341 - The server must support the PLAY command to start playback of the configured
344 >> PLAY rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
346 >> Session: 5d5cb94413288ccd
350 << Date: Wed May 11 13:21:43 2005 GMT
351 << Session: 5d5cb94413288ccd
354 Using the Session: header field, the server finds the pipeline of the session
355 to PLAY and sets the pipeline to PLAYING at which point the client receives
356 the media stream data.
358 In case of a live stream, the server adds the port numbers to a multiudpsink
361 - The server must support the TEARDOWN command to stop playback and free the
364 >> TEARDOWN rtsp://thread:5454/south-rtsp.mp3 RTSP/1.0
366 >> Session: 5d5cb94413288ccd
370 << Date: Wed May 11 13:21:43 2005 GMT
373 The server destroys the client pipeline in case of an on-demand stream or
374 removes the client ports from the multiudpsinks. This effectively stops
375 streaming to the client.