docs/README

   1 README
   2 ------
   3
   4 (Last updated on Fri 30 jan 2009, version 0.10.1.1)
   5
   6 This HOWTO describes the basic usage of the GStreamer RTSP libraries and how you
   7 can build simple server applications with it.
   8
   9 * General
  10
  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 gstrtpbin 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.
  16
  17  The result is that the server is rather small (a few 1000 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.
  21
  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.
  25
  26  The server currently integrates with the glib mainloop nicely. It is also a
  27  heavy user of multiple threads. It's currently not meant to be used in
  28  high-load scenarios and you should probably not put it on a public IP address.
  29
  30 * Initialisation
  31
  32  You need to initialize GStreamer before using any of the RTSP server functions.
  33
  34    #include <gst/gst.h>
  35
  36    int
  37    main (int argc, char *argv[])
  38    {
  39      gst_init (&argc, &argv);
  40
  41      ...
  42    }
  43
  44  The server itself currently does not have any specific initialisation function
  45  but that might change in the future.
  46
  47
  48 * Creating the server
  49
  50  The first thing you want to do is create a new GstRTSPServer object. This object
  51  will handle all the new client connections to your server once it is added to a
  52  GMainLoop. You can create a new server object like this:
  53
  54    #include <gst/rtsp-server/rtsp-server.h>
  55
  56    GstRTSPServer *server;
  57
  58    server = gst_rtsp_server_new ();
  59
  60  The server will by default listen on port 8554 for new connections. This can be
  61  changed by calling gst_rtsp_server_set_port() or with the 'port' GObject
  62  property. This makes it possible to run multiple server instances listening on
  63  multiple ports on one machine.
  64
  65  We can make the server start listening on its default port by attaching it to a
  66  mainloop. The following example shows how this is done and will start a server
  67  on the default 8554 port. For any request we make, we will get a NOT_FOUND
  68  error code because we need to configure more things before the server becomes
  69  useful.
  70
  71    #include <gst/gst.h>
  72    #include <gst/rtsp-server/rtsp-server.h>
  73
  74    int
  75    main (int argc, char *argv[])
  76    {
  77      GstRTSPServer *server;
  78      GMainLoop *loop;
  79
  80      gst_init (&argc, &argv);
  81
  82      server = gst_rtsp_server_new ();
  83
  84      /* make a mainloop for the default context */
  85      loop = g_main_loop_new (NULL, FALSE);
  86
  87      /* attach the server to the default maincontext */
  88      gst_rtsp_server_attach (server, NULL);
  89
  90      /* start serving */
  91      g_main_loop_run (loop);
  92    }
  93
  94  The server manages two other objects: GstRTSPSessionPool and
  95  GstRTSPMediaMapping.
  96
  97  The GstRTSPSessionPool is an object that keeps track of all the active sessions
  98  in the server. A session will usually be kept for each client that performed a
  99  SETUP request for a certain media stream. It contains the configuration that
 100  the client negotiated with the server to receive the particular stream, ie. the
 101  transport used and port pairs for UDP along with the state of the streaming.
 102  The default implementation of the session pool is usually sufficient but
 103  alternative implementation can be used by the server.
 104
 105  The GstRTSPMediaMapping object is more interesting and needs more configuration
 106  before the server object is useful. This object manages to mapping from a
 107  request URL to a specific stream and its configuration. We explain in the next
 108  topic how to configure this object.
 109
 110
 111 * Making url mappings
 112
 113  Next we need to define what media is attached to a particular URL. What we want
 114  to achieve is that when the user asks our server for a specific URL, say /test,
 115  that we create (or reuse) a GStreamer pipeline that produces one or more RTP
 116  streams.
 117
 118  The object that can create such pipeline is called a GstRTSPMediaFactory object.
 119  The default implementation of GstRTSPMediaFactory allows you to easily create
 120  GStreamer pipelines using the gst-launch syntax. It possible to create a
 121  GstRTSPMediaFactory subclass that uses different methods for constructing
 122  pipelines.
 123
 124  The default GstRTSPMediaFactory can be configured with a gst-launch line that
 125  produces a toplevel bin (use '(' and ')' around the pipeline description to
 126  force a toplevel GstBin instead of the default GstPipeline toplevel element).
 127  The pipeline description should contain elements named payN, one for each
 128  stream (ex. pay0, pay1, ...). Also, for increased compatibility each stream
 129  should have a different payload type which can be configured on the payloader.
 130
 131  The following code snippet illustrates how to create a media factory that
 132  creates an RTP feed of an H264 encoded test video signal.
 133
 134    GstRTSPMediaFactory *factory;
 135
 136    factory = gst_rtsp_media_factory_new ();
 137
 138    gst_rtsp_media_factory_set_launch (factory,
 139                 "( videotestsrc ! x264enc ! rtph264pay pt=96 name=pay0 )");
 140
 141  Now that we have the media factory, we can attach it to a specific url. To do
 142  this we get the default GstRTSPMediaMapping from our server and add the url to
 143  factory mapping to it like this:
 144
 145    GstRTSPMediaMapping *mapping;
 146
 147    ...create server..create factory..
 148
 149    /* get the default mapping from the server */
 150    mapping = gst_rtsp_server_get_media_mapping (server);
 151
 152    /* attach the video test signal to the "/test" URL */
 153    gst_rtsp_media_mapping_add_factory (mapping, "/test", factory);
 154    g_object_unref (mapping);
 155
 156  When starting the server now and directing an RTP client to the URL (like with
 157  vlc, mplayer or gstreamer):
 158
 159    rtsp://localhost:8554/test
 160
 161  a test signal will be streamed to the client. The full example code can be
 162  found in the examples/test-readme.c file.
 163
 164
 165 * more on GstRTSPMediaFactory
 166
 167  The GstRTSPMediaFactory is responsible for creating and caching GstRTSPMedia
 168  objects.
 169
 170  A freshly created GstRTSPMedia object from the factory initialy only contains a
 171  GstElement containing the elements to produce the RTP streams for the media and
 172  a GArray of GstRTSPMediaStream objects describing the payloader and its source
 173  pad. The media is unprepared in this state.
 174
 175  Usually the url will determine what kind of pipeline should be created. You can
 176  for example use query parameters to configure certain parts of the pipeline or
 177  select encoders and payloaders based on some url pattern.
 178
 179  When dealing with a live stream from, for example, a webcam, it can be
 180  interesting to share the pipeline with multiple clients. This must be done when
 181  only one instance of the video capture element can be used at a time. In this
 182  case, the shared property of GstRTSPMedia must be used to instruct the default
 183  GstRTSPMediaFactory implementation to cache the media.
 184
 185  When all objects created from a factory can be shared, you can set the shared
 186  property directly on the factory.
 187
 188 * more on GstRTSPMedia
 189
 190  After creating the GstRTSPMedia object from the factory, it can be prepared
 191  with gst_rtsp_media_prepare(). This method will put those objects in a
 192  GstPipeline and will construct and link the streaming elements and the
 193  gstrtpbin session manager object.
 194
 195  The _prepare() method will then preroll the pipeline in order to figure out the
 196  caps on the payloaders. After the GstRTSPMedia prerolled it will be in the
 197  prepared state and can be used for creating SDP files or for streaming to
 198  clients.
 199
 200  The prepare method will also create 2 UDP ports for each stream that can be
 201  used for sending and receiving RTP/RTCP from clients. These port numbers will
 202  have to be negotiated with the client in the SETUP requests.
 203
 204  When preparing a GstRTSPMedia, a multifdsink is also constructed for streaming
 205  the stream over TCP^when requested.
 206
 207
 208 * the GstRTSPClient object
 209
 210  When a server detects a new client connection on its port, it will call its
 211  accept_client vmethod. The default implementation of this function will create
 212  a new GstRTCPClient object, will configure the session pool and media mapper
 213  objects in it and will then call the accept function of the client.
 214
 215  The default GstRTSPClient will accept the connection and will start a new
 216  GThread to handle the connection. In RTSP it is usual to keep the connection
 217  open between multiple RTSP requests. The client thread will simply block for a
 218  new GstRTSPMessage, will dispatch it and will send a response.
 219
 220  We will briefly describe how it deals with some common requests.
 221
 222  - DESCRIBE:
 223
 224     locates the GstRTSPMedia for the url, prepares it and asks the sdp helper
 225     function to construct an SDP from the caps of the prepared media pipeline.
 226     It will also cache the url+media object so that it can be reused later.
 227
 228  - SETUP
 229
 230     A new GstRTSPSession object will be created from the GstRTSPSessionPool
 231     object configured in the GstRTSPClient. This session will contain the
 232     configuration of the client regarding the media it is streaming and the
 233     ports/transport it negotiated with the server.
 234
 235     The sessionid is set in the response header. The client will add the
 236     sessionid to any further SETUP/PLAY/PAUSE/TEARDOWN request so that we can
 237     always find the session again.
 238
 239     The session configuration for a sessionid will have a link to the prepared
 240     GstRTSPMedia object of the stream. The port and transport of the client is
 241     stored in the session configuration.
 242
 243  - PLAY
 244
 245     The session configuration is retrieved with the sessionid and the client
 246     ports are configured in the UDP sinks, then the streaming to the client
 247     is started.
 248
 249  - PAUSE
 250
 251     The session configuration is retrieved with the sessionid and the client
 252     ports are removed from the UDP sinks, the streaming to the client
 253     pauses.
 254
 255  - TEARDOWN
 256
 257     The session configuration is released along with its link to the
 258     GstRTSPMedia object. When no more clients are refering to the GstRTSPMedia
 259     object, it can be released as well.
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272