4 (Last updated on Fri 26 oct 2012, version 0.11.89.1)
6 This HOWTO describes the basic usage of the GStreamer RTSP libraries and how you
7 can build simple server applications with it.
11 The server relies heavily on the RTSP infrastructure of GStreamer. This includes
12 all of the media acquisition, decoding, encoding, payloading and UDP/TCP
13 streaming. We use the rtpbin element for all the session management. Most of
14 the RTSP message parsing and construction in the server is done using the RTSP
15 library that comes with gst-plugins-base.
17 The result is that the server is rather small (a few 6000 lines of code) and easy
18 to understand and extend. In its current state of development, things change
19 fast, API and ABI are unstable. We encourage people to use it for their various
20 use cases and participate by suggesting changes/features.
22 Most of the server is built as a library containing a bunch of GObject objects
23 that provide reasonable default functionality but has a fair amount of hooks
24 to override the default behaviour.
26 The server currently integrates with the glib mainloop nicely. The network part
27 is currently single threaded but the GStreamer bits are a heavy user of multiple
28 threads. It's currently not meant to be used in high-load scenarios and because
29 no security audit has been done, you should probably not put it on a public
34 You need to initialize GStreamer before using any of the RTSP server functions.
39 main (int argc, char *argv[])
41 gst_init (&argc, &argv);
46 The server itself currently does not have any specific initialisation function
47 but that might change in the future.
52 The first thing you want to do is create a new GstRTSPServer object. This object
53 will handle all the new client connections to your server once it is added to a
54 GMainLoop. You can create a new server object like this:
56 #include <gst/rtsp-server/rtsp-server.h>
58 GstRTSPServer *server;
60 server = gst_rtsp_server_new ();
62 The server will by default listen on port 8554 for new connections. This can be
63 changed by calling gst_rtsp_server_set_service() or with the 'service' GObject
64 property. This makes it possible to run multiple server instances listening on
65 multiple ports on one machine.
67 We can make the server start listening on its default port by attaching it to a
68 mainloop. The following example shows how this is done and will start a server
69 on the default 8554 port. For any request we make, we will get a NOT_FOUND
70 error code because we need to configure more things before the server becomes
74 #include <gst/rtsp-server/rtsp-server.h>
77 main (int argc, char *argv[])
79 GstRTSPServer *server;
82 gst_init (&argc, &argv);
84 server = gst_rtsp_server_new ();
86 /* make a mainloop for the default context */
87 loop = g_main_loop_new (NULL, FALSE);
89 /* attach the server to the default maincontext */
90 gst_rtsp_server_attach (server, NULL);
93 g_main_loop_run (loop);
96 The server manages two other objects: GstRTSPSessionPool and
99 The GstRTSPSessionPool is an object that keeps track of all the active sessions
100 in the server. A session will usually be kept for each client that performed a
101 SETUP request for a certain media stream. It contains the configuration that
102 the client negotiated with the server to receive the particular stream, ie. the
103 transport used and port pairs for UDP along with the state of the streaming.
104 The default implementation of the session pool is usually sufficient but
105 alternative implementation can be used by the server.
107 The GstRTSPMountPoints object is more interesting and needs more configuration
108 before the server object is useful. This object manages the mapping from a
109 request URL to a specific stream and its configuration. We explain in the next
110 topic how to configure this object.
113 * Making url mount points
115 Next we need to define what media is attached to a particular URL. What we want
116 to achieve is that when the user asks our server for a specific URL, say /test,
117 that we create (or reuse) a GStreamer pipeline that produces one or more RTP
120 The object that can create such pipeline is called a GstRTSPMediaFactory object.
121 The default implementation of GstRTSPMediaFactory allows you to easily create
122 GStreamer pipelines using the gst-launch syntax. It is possible to create a
123 GstRTSPMediaFactory subclass that uses different methods for constructing
126 The default GstRTSPMediaFactory can be configured with a gst-launch line that
127 produces a toplevel bin (use '(' and ')' around the pipeline description to
128 force a toplevel GstBin instead of the default GstPipeline toplevel element).
129 The pipeline description should contain elements named payN, one for each
130 stream (ex. pay0, pay1, ...). Also, for increased compatibility each stream
131 should have a different payload type which can be configured on the payloader.
133 The following code snippet illustrates how to create a media factory that
134 creates an RTP feed of an H264 encoded test video signal.
136 GstRTSPMediaFactory *factory;
138 factory = gst_rtsp_media_factory_new ();
140 gst_rtsp_media_factory_set_launch (factory,
141 "( videotestsrc ! x264enc ! rtph264pay pt=96 name=pay0 )");
143 Now that we have the media factory, we can attach it to a specific url. To do
144 this we get the default GstRTSPMountPoints from our server and add the url to
145 factory mount points to it like this:
147 GstRTSPMountPoints *mounts;
149 ...create server..create factory..
151 /* get the default mount points from the server */
152 mounts = gst_rtsp_server_get_mount_points (server);
154 /* attach the video test signal to the "/test" URL */
155 gst_rtsp_mount_points_add_factory (mounts, "/test", factory);
156 g_object_unref (mounts);
158 When starting the server now and directing an RTP client to the URL (like with
159 vlc, mplayer or gstreamer):
161 rtsp://localhost:8554/test
163 a test signal will be streamed to the client. The full example code can be
164 found in the examples/test-readme.c file.
166 Note that by default the factory will create a new pipeline for each client. If
167 you want to share a pipeline between clients, use
168 gst_rtsp_media_factory_set_shared().
171 * more on GstRTSPMediaFactory
173 The GstRTSPMediaFactory is responsible for creating and caching GstRTSPMedia
176 A freshly created GstRTSPMedia object from the factory initially only contains a
177 GstElement containing the elements to produce the RTP streams for the media and
178 a GPtrArray of GstRTSPStream objects describing the payloader and its source
179 pad. The media is unprepared in this state.
181 Usually the url will determine what kind of pipeline should be created. You can
182 for example use query parameters to configure certain parts of the pipeline or
183 select encoders and payloaders based on some url pattern.
185 When dealing with a live stream from, for example, a webcam, it can be
186 interesting to share the pipeline with multiple clients. This must be done when
187 only one instance of the video capture element can be used at a time. In this
188 case, the shared property of GstRTSPMedia must be used to instruct the default
189 GstRTSPMediaFactory implementation to cache the media.
191 When all objects created from a factory can be shared, you can set the shared
192 property directly on the factory.
194 * more on GstRTSPMedia
196 After creating the GstRTSPMedia object from the factory, it can be prepared
197 with gst_rtsp_media_prepare(). This method will put those objects in a
198 GstPipeline and will construct and link the streaming elements and the
199 rtpbin session manager object.
201 The _prepare() method will then preroll the pipeline in order to figure out the
202 caps on the payloaders. After the GstRTSPMedia prerolled it will be in the
203 prepared state and can be used for creating SDP files or for streaming to
206 The prepare method will also create 2 UDP ports for each stream that can be
207 used for sending and receiving RTP/RTCP from clients. These port numbers will
208 have to be negotiated with the client in the SETUP requests.
210 When preparing a GstRTSPMedia, an appsink and asppsrc is also constructed
211 for streaming the stream over TCP when requested.
214 * the GstRTSPClient object
216 When a server detects a new client connection on its port, it will call its
217 accept_client vmethod. The default implementation of this function will create
218 a new GstRTCPClient object, will configure the session pool and media mapper
219 objects in it and will then call the accept function of the client.
221 The default GstRTSPClient will accept the connection and will attach a watch to
222 the server mainloop. In RTSP it is usual to keep the connection
223 open between multiple RTSP requests. The client watch will be dispatched by the
224 server mainloop when a new GstRTSPMessage is received, which will then be
225 handled and a response will be sent.
227 The GstRTSPClient object remains alive for as long as a client has a TCP
228 connection open with the server. Since is possible for a client to open and close
229 the TCP connection between requests, we cannot store the state related
230 to the configured RTSP session in the GstRTSPClient object. This server state
231 is instead stored in the GstRTSPSession object, identified with the session
237 This object contains state about a specific RTSP session identified with a
238 session id. This state contains the configured streams and their associated
241 When a GstRTSPClient performs a SETUP request, the server will allocate a new
242 GstRTSPSession with a unique session id from the GstRTSPSessionPool. The pool
243 maintains a list of all existing sessions and makes sure that no session id is
244 used multiple times. The session id is sent to the client so that the client
245 can refer to its previously configured state by sending the session id in
248 A client will then use the session id to configure one or more
249 GstRTSPSessionMedia objects, identified by their url. This SessionMedia object
250 contains the configuration of a GstRTSPMedia and its configured
251 GstRTSPStreamTransport.
254 * GstRTSPSessionMedia and GstRTSPStreamTransport
256 A GstRTSPSessionMedia is identified by a URL and is referenced by a
257 GstRTSPSession. It is created as soon as a client performs a SETUP operation on
258 a particular URL. It will contain a link to the GstRTSPMedia object associated
259 with the URL along with the state of the media and the configured transports
260 for each of the streams in the media.
262 Each SETUP request performed by the client will configure a
263 GstRTSPStreamTransport object linked to by the GstRTSPSessionMedia structure.
264 It will contain the transport information needed to send this stream to the
265 client. The GstRTSPStreamTransport also contains a link to the GstRTSPStream
266 object that generates the actual data to be streamed to the client.
268 Note how GstRTSPMedia and GstRTSPStream (the providers of the data to
269 stream) are decoupled from GstRTSPSessionMedia and GstRTSPStreamTransport (the
270 configuration of how to send this stream to a client) in order to be able to
271 send the data of one GstRTSPMedia to multiple clients.
276 After a client has configured the transports for a GstRTSPMedia and its
277 GstRTSPStreams, the client can play/pause/stop the stream.
279 The GstRTSPMedia object was prepared in the DESCRIBE call (or during SETUP when
280 the client skipped the DESCRIBE request). As seen earlier, this configures a
281 couple of udpsink and udpsrc elements to respectively send and receive the
284 When a client performs a PLAY request, its configured destination UDP ports are
285 added to the GstRTSPStream target destinations, at which point data will
286 be sent to the client. The corresponding GstRTSPMedia object will be set to the
287 PLAYING state if it was not allready in order to send the data to the
290 The server needs to prepare an RTP-Info header field in the PLAY response,
291 which consists of the sequence number and the RTP timestamp of the next RTP
292 packet. In order to achive this, the server queries the payloaders for this
293 information when it prerolled the pipeline.
295 When a client performs a PAUSE request, the destination UDP ports are removed
296 from the GstRTSPStream object and the GstRTSPMedia object is set to PAUSED
297 if no other destinations are configured anymore.
302 A seek is performed when a client sends a Range header in the PLAY request.
303 This only works when not dealing with shared (live) streams.
305 The server performs a GStreamer flushing seek on the media, waits for the
306 pipeline to preroll again and then responds to the client after collecting the
307 new RTP sequence number and timestamp from the payloaders.
312 The server has to react to clients that suddenly disappear because of network
313 problems or otherwise. It needs to make sure that it can reasonable free the
314 resources that are used by the various objects in use for streaming when the
315 client appears to be gone.
317 Each of the GstRTSPSession objects managed by a GstRTSPSessionPool has
318 therefore a last_access field that contains the timestamp of when activity from
319 a client was last recorded.
321 Various ways exist to detect activity from a client:
323 - RTSP keepalive requests. When a client is receiving RTP data, the RTSP TCP
324 connection is largely unused. It is the client's responsability to
325 periodically send keep-alive requests over the TCP channel.
327 Whenever a keep-alive request is received by the server (any request that
328 contains a session id, usually an OPTION or GET_PARAMETER request) the
329 last_access of the session is updated.
331 - Since it is not required for a client to keep the RTSP TCP connection open
332 while streaming, gst-rtsp-server also detects activity from clients by
333 looking at the RTCP messages it receives.
335 When an RTCP message is received from a client, the server looks in its list
336 of active ports if this message originates from a known host/port pair that
337 is currently active in a GstRTSPSession. If this is the case, the session is
340 Since the server does not know anything about the port number that will be
341 used by the client to send RTCP, this method does not always work. Later
342 RTSP RFCs will include support for negotiating this port number with the
343 server. Most clients however use the same port number for sending and
344 receiving RTCP exactly for this reason.
346 If there was no activity in a particular session for a long time (by default 60
347 seconds), the application should remove the session from the pool. For this,
348 the application should periodically (say every 2 seconds) check if no sessions
349 expired and call gst_rtsp_session_pool_cleanup() to remove them.
351 When a session is removed from the sessionpool and its last reference is
352 unreffef, all related objects and media are destroyed as if a TEARDOWN happened
358 A TEARDOWN request will first locate the GstRTSPSessionMedia of the URL. It
359 will then remove all transports from the streams, making sure that streaming
360 stops to the clients. It will then remove the GstRTSPSessionMedia and
361 GstRTSPStreamTransport objects. Finally the GstRTSPSession is released back
364 When there are no more references to the GstRTSPMedia, the media pipeline is
365 shut down (with _unprepare) and destroyed. This will then also destroy the
366 GstRTSPStream objects.
373 - Toplevel object listening for connections and creating new
374 GstRTSPClient objects
377 - Handle RTSP Requests from connected clients. All other objects
378 are called by this object.
381 - Helper structure contaning the current state of the request
382 handled by the client.
385 - Hooks for checking authorizations, all client activity will call this
386 object with the GstRTSPClientState structure. By default it supports
387 basic authentication.
391 - Maps a url to a GstRTSPMediaFactory implementation. The default
392 implementation uses a simple hashtable to map a url to a factory.
395 - Creates and caches GstRTSPMedia objects. The default implementation
396 can create GstRTSPMedia objects based on gst-launch syntax.
398 GstRTSPMediaFactoryURI
399 - Specialized GstRTSPMediaFactory that can stream the content of any
403 - The object that contains the media pipeline and various GstRTSPStream
404 objects that produce RTP packets
407 - Manages the elements to stream a stream of a GstRTSPMedia to one or
408 more GstRTSPStreamTransports.
412 - Creates and manages GstRTSPSession objects identified by an id.
415 - An object containing the various GstRTSPSessionMedia objects managed
419 - The state of a GstRTSPMedia and the configuration of a GstRTSPStream
420 objects. The configuration for the GstRTSPStream is stored in
421 GstRTSPStreamTransport objects.
423 GstRTSPStreamTransport
424 - Configuration of how a GstRTSPStream is send to a particular client. It
425 contains the transport that was negotiated with the client in the SETUP