From: Wim Taymans Date: Fri, 30 Jan 2009 12:24:04 +0000 (+0100) Subject: Add a README and more example code X-Git-Tag: 1.6.0~996 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=031791ddd2aef4135fba3e965eb233317084103d;p=platform%2Fupstream%2Fgst-rtsp-server.git Add a README and more example code Add a README file that contains a small introduction on how to use the server along with the example code explained in the readme. --- diff --git a/docs/README b/docs/README new file mode 100644 index 0000000..06a28c7 --- /dev/null +++ b/docs/README @@ -0,0 +1,175 @@ +README +------ + +(Last updated on Fri 30 jan 2009, version 0.10.1.1) + +This HOWTO describes the basic usage of the GStreamer RTSP libraries and how you +can build simple server applications with it. + +* General + + The server relies heavily on the RTSP infrastructure of GStreamer. This includes + all of the media acquisition, decoding, encoding, payloading and UDP/TCP + streaming. We use the gstrtpbin element for all the session management. Most of + the RTSP message parsing and construction in the server is done using the RTSP + library that comes with gst-plugins-base. + + The result is that the server is rather small (a few 1000 lines of code) and easy + to understand and extend. In its current state of development, things change + fast, API and ABI are unstable. We encourage people to use it for their various + use cases and participate by suggesting changes/features. + + Most of the server is built as a library containing a bunch of GObject objects + that provide reasonable default functionality but has a fair amount of hooks + to override the default behaviour. + + The server currently integrates with the glib mainloop nicely. It is also a + heavy user of multiple threads. It's currently not meant to be used in + high-load scenarios and you should probably not put it on a public IP address. + +* Initialisation + + You need to initialize GStreamer before using any of the RTSP server functions. + + #include + + int + main (int argc, char *argv[]) + { + gst_init (&argc, &argv); + + ... + } + + The server itself currently does not have any specific initialisation function + but that might change in the future. + + +* Creating the server + + The first thing you want to do is create a new GstRTSPServer object. This object + will handle all the new client connections to your server once it is added to a + GMainLoop. You can create a new server object like this: + + #include + + GstRTSPServer *server; + + server = gst_rtsp_server_new (); + + The server will by default listen on port 8554 for new connections. This can be + changed by calling gst_rtsp_server_set_port() or with the 'port' GObject + property. This makes it possible to run multiple server instances listening on + multiple ports on one machine. + + We can make the server start listening on its default port by attaching it to a + mainloop. The following example shows how this is done and will start a server + on the default 8554 port. For any request we make, we will get a NOT_FOUND + error code because we need to configure more things before the server becomes + useful. + + #include + #include + + int + main (int argc, char *argv[]) + { + GstRTSPServer *server; + GMainLoop *loop; + + gst_init (&argc, &argv); + + server = gst_rtsp_server_new (); + + /* make a mainloop for the default context */ + loop = g_main_loop_new (NULL, FALSE); + + /* attach the server to the default maincontext */ + gst_rtsp_server_attach (server, NULL); + + /* start serving */ + g_main_loop_run (loop); + } + + The server manages two other objects: GstRTSPSessionPool and + GstRTSPMediaMapping. + + The GstRTSPSessionPool is an object that keeps track of all the active sessions + in the server. A session will usually be kept for each client that performed a + SETUP request for a certain media stream. It contains the configuration that + the client negotiated with the server to receive the particular stream, ie. the + transport used and port pairs for UDP along with the state of the streaming. + The default implementation of the session pool is usually sufficient but + alternative implementation can be used by the server. + + The GstRTSPMediaMapping object is more interesting and needs more configuration + before the server object is useful. This object manages to mapping from a + request URL to a specific stream and its configuration. We explain in the next + topic how to configure this object. + +* Making url mappings + + Next we need to define what media is attached to a particular URL. What we want + to achieve is that when the user asks our server for a specific URL, say /test, + that we create (or reuse) a GStreamer pipeline that produces one or more RTP + streams. + + The object that can create such pipeline is called a GstRTSPMediaFactory object. + The default implementation of GstRTSPMediaFactory allows you to easily create + GStreamer pipelines using the gst-launch syntax. It possible to create a + GstRTSPMediaFactory subclass that uses different methods for constructing + pipelines. + + The default GstRTSPMediaFactory can be configured with a gst-launch line that + produces a toplevel bin (use '(' and ')' around the pipeline description to + force a toplevel GstBin instead of the default GstPipeline toplevel element). + The pipeline description should contain elements named payN, one for each + stream (ex. pay0, pay1, ...). Also, for increased compatibility each stream + should have a different payload type which can be configured on the payloader. + + The following code snippet illustrates how to create a media factory that + creates an RTP feed of an H264 encoded test video signal. + + GstRTSPMediaFactory *factory; + + factory = gst_rtsp_media_factory_new (); + + gst_rtsp_media_factory_set_launch (factory, + "( videotestsrc ! x264enc ! rtph264pay pt=96 name=pay0 )"); + + Now that we have the media factory, we can attach it to a specific url. To do + this we get the default GstRTSPMediaMapping from our server and add the url to + factory mapping to it like this: + + GstRTSPMediaMapping *mapping; + + ...create server..create factory.. + + /* get the default mapping from the server */ + mapping = gst_rtsp_server_get_media_mapping (server); + + /* attach the video test signal to the "/test" URL */ + gst_rtsp_media_mapping_add_factory (mapping, "/test", factory); + g_object_unref (mapping); + + When starting the server now and directing an RTP client to the URL (like with + vlc, mplayer or gstreamer): + + rtsp://localhost:8554/test + + a test signal will be streamed to the client. The full example code can be + found in the examples/test-readme.c file. + + + + + + + + + + + + + + diff --git a/examples/Makefile.am b/examples/Makefile.am index 1241eda..c8196d1 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -1,4 +1,4 @@ -noinst_PROGRAMS = test-video test-ogg test-mp4 +noinst_PROGRAMS = test-video test-ogg test-mp4 test-readme INCLUDES = -I$(top_srcdir) -I$(srcdir) diff --git a/examples/test-readme.c b/examples/test-readme.c new file mode 100644 index 0000000..880b6d2 --- /dev/null +++ b/examples/test-readme.c @@ -0,0 +1,64 @@ +/* GStreamer + * Copyright (C) 2008 Wim Taymans + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Library General Public + * License as published by the Free Software Foundation; either + * version 2 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Library General Public License for more details. + * + * You should have received a copy of the GNU Library General Public + * License along with this library; if not, write to the + * Free Software Foundation, Inc., 59 Temple Place - Suite 330, + * Boston, MA 02111-1307, USA. + */ + +#include + +#include + +int +main (int argc, char *argv[]) +{ + GMainLoop *loop; + GstRTSPServer *server; + GstRTSPMediaMapping *mapping; + GstRTSPMediaFactory *factory; + + gst_init (&argc, &argv); + + loop = g_main_loop_new (NULL, FALSE); + + /* create a server instance */ + server = gst_rtsp_server_new (); + + /* get the mapping for this server, every server has a default mapper object + * that be used to map uri mount points to media factories */ + mapping = gst_rtsp_server_get_media_mapping (server); + + /* make a media factory for a test stream. The default media factory can use + * gst-launch syntax to create pipelines. + * any launch line works as long as it contains elements named pay%d. Each + * element with pay%d names will be a stream */ + factory = gst_rtsp_media_factory_new (); + gst_rtsp_media_factory_set_launch (factory, + "( videotestsrc ! x264enc ! rtph264pay name=pay0 pt=96 )"); + + /* attach the test factory to the /test url */ + gst_rtsp_media_mapping_add_factory (mapping, "/test", factory); + + /* don't need the ref to the mapper anymore */ + g_object_unref (mapping); + + /* attach the server to the default maincontext */ + gst_rtsp_server_attach (server, NULL); + + /* start serving */ + g_main_loop_run (loop); + + return 0; +}