How to develop a RTSP server in Linux using GStreamer
The What, Where and How
In this tutorial I will show you step-by-step how to develop a RTSP server in Linux, using the very powerful GStreamer framework. I will be doing this on Ubuntu 11.10 Oneiric Ocelot. However, the same steps apply running older versions of Ubuntu Linux, although the list of required software packages you have to install then may differ. I have included a second list of software packages that may be helpful for those of you who are running an older version of Ubuntu or for that matter another Linux distro.
First, let’s identify the required software packages
The software packages needed to complete this tutorial for Ubuntu 11.10 Oneiric Ocelot are listed below. Use your favorite packet installer to install these packages. Some of the GStreamer packages are not needed to run the RTSP server but are nice to have if you want to play around with different kinds of video formats and so on.
Ubuntu 11.10 Oneiric Ocelot:
- gstreamer-tools
- gstreamer0.10-ffmpeg
- libgstrtspserver-0.10-0
- libgstrtspserver-0.10-dev
- gstreamer0.10-plugins-bad
- gstreamer0.10-plugins-ugly
- gstreamer0.10-plugins-good-dbg
- libglib2.0
Older versions of Ubuntu or other Linux distros :
- gstreamer
- gstreamer-tools
- gstreamer0.10-alsa
- gstreamer0.10-ffmpeg
- libgstrtspserver-0.10-0
- libgstrtspserver-0.10-dev
- libgstreamer0.10-dev
- gstreamer0.10-plugins-bad
- gstreamer0.10-plugins-ugly
- gstreamer0.10-plugins-good-dbg
- gstreamer0.10-plugins-ugly-multiverse
- libglib2.0
- libglib2.0-dev
- gcc
So, let's look at the actual code for the RTSP server
This code is to 99% taken from the gst-rtsp libraries examples which you can get by downloading the source tarball here. The only thing that I have changed is the media pipeline which is highlighted on line 83-85. The media pipeline defines what shall be streamed to a client upon a client request. Looking at the pipeline, you can see that we have a video source named videotestsrc which contains a video of a TV test pattern. The videotestsrc is first encoded using h.264 and then RTP payloaded. You also have an audio source named audiotestsrc. The audiotestsrc contains a beeping audio track which is first encoded using A-Law (G.711), and then payloaded. The RTP payloader puts the input data into RTP payloads which are then sent to the client. If you want to test out different kinds of media pipelines you use gst-launch, which is a GStreamer tool devised for that purpose and that you installed through the gstreamer-tools software package. The gst-launch syntax is compatible with how gst-rtsp pipelines are defined so that you can cut and paste a gst-launch pipeline into the media pipeline on line 83-85.
So now we know what we are sending out upon a client request, but where are we sending it from? When a client requests a stream from your RTSP server, it uses this URL: rtsp://serveripaddress:8554/test. The server IP address is the address of whatever you are running your server on. The port is the default port used by the gst-rtsp library, which can be changed with a call to gst_rtsp_server_set_port(). The final part of the URL is /test which is set on line 88 in the code. Line 88 in the code maps it all together; the default server mapping (line 64), the /test part of the URL and our media pipeline on line 83-85.
/* GStreamer
* Copyright (C) 2008 Wim Taymans <wim.taymans at gmail.com>
*
* 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 <gst/gst.h>
#include <gst/rtsp-server/rtsp-server.h>
/* define this if you want the resource to only be available when using
* user/admin as the password */
#undef WITH_AUTH
/* this timeout is periodically run to clean up the expired sessions from the
* pool. This needs to be run explicitly currently but might be done
* automatically as part of the mainloop. */
static gboolean
timeout (GstRTSPServer * server, gboolean ignored)
{
GstRTSPSessionPool *pool;
pool = gst_rtsp_server_get_session_pool (server);
gst_rtsp_session_pool_cleanup (pool);
g_object_unref (pool);
return TRUE;
}
int
main (int argc, char *argv[])
{
GMainLoop *loop;
GstRTSPServer *server;
GstRTSPMediaMapping *mapping;
GstRTSPMediaFactory *factory;
#ifdef WITH_AUTH
GstRTSPAuth *auth;
gchar *basic;
#endif
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);
#ifdef WITH_AUTH
/* make a new authentication manager. it can be added to control access to all
* the factories on the server or on individual factories. */
auth = gst_rtsp_auth_new ();
basic = gst_rtsp_auth_make_basic ("user", "admin");
gst_rtsp_auth_set_basic (auth, basic);
g_free (basic);
/* configure in the server */
gst_rtsp_server_set_auth (server, auth);
#endif
/* 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 ! video/x-raw-yuv,width=320,height=240,framerate=10/1 ! "
"x264enc ! queue ! rtph264pay name=pay0 pt=96 ! audiotestsrc ! audio/x-raw-int,rate=8000 ! alawenc ! rtppcmapay name=pay1 pt=97 "")");
/* 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 */
if (gst_rtsp_server_attach (server, NULL) == 0)
goto failed;
/* add a timeout for the session cleanup */
g_timeout_add_seconds (2, (GSourceFunc) timeout, server);
/* start serving, this never stops */
g_main_loop_run (loop);
return 0;
/* ERRORS */
failed:
{
g_print ("failed to attach the server\n");
return -1;
}
}
Finally, let's compile the code and run the RTSP server
Copy the source code from the previous section into a new file, that you name main.c. Use the following gcc command line to compile the source code from main.c into an object file:
$> gcc -I/usr/include/libxml2 -I/usr/include/glib-2.0 -I/usr/include/gstreamer-0.10 -I/usr/lib/arm-linux-gnueabi/glib-2.0/include -O0 -g3 -Wall -c -fmessage-length=0 -MMD -MP -MF"main.d" -MT"main.d" -o"main.o" "main.c"
Next, use the following gcc command line to name the output executable rtsp and link the object file to the necessary libraries:
$> gcc -o"rtsp" ./main.o -lgstrtspserver-0.10 -lgstreamer-0.10 -lglib-2.0
You should now have an executable called rtsp. (If not, there is a problem somewhere: Maybe you are missing one of the required software packages listed above or maybe the libraries needed cannot be found on your computer.) Start the RTSP server by:
$> ./ rtsp
Your RTSP server is now running and will accept requests from a client on the URL defined in the source code of main.c. The complete URL is:
rtsp://localhost:8554/test
Try to access the RTSP stream from VLC by choosing to open an advanced file from the Media menu. Then choose the 'Network' tab and type in the URL above. You should now get a video that looks like a TV test pattern with a beeping sound, like this:
Using VLC as a streaming client for the RTSP server
What to do next?
My suggestion is that you download the source tarball for gst-rtsp, which was one of the libraries we linked to gstrtspserver-0.10. The source for this library contains more in-depth documentation and examples which you should look into if you want to learn more. But hey! don’t forget to play around with different GStreamer pipelines (line 83-85 in source code). Maybe you want to send something else than a TV test pattern? I scouted around for a good tutorial which explains GStreamer pipelines together with gst-launch, and that I could link to here, but I couldn't find a nice one. Maybe this will be the topic for my next post. Or maybe I will try the RTSP server on my Beagleboard-xM.