manual-helloworld.md

   1 ---
   2 title: Your first application
   3 ...
   4
   5 # Your first application
   6
   7 This chapter will summarize everything you've learned in the previous
   8 chapters. It describes all aspects of a simple GStreamer application,
   9 including initializing libraries, creating elements, packing elements
  10 together in a pipeline and playing this pipeline. By doing all this, you
  11 will be able to build a simple Ogg/Vorbis audio player.
  12
  13 ## Hello world
  14
  15 We're going to create a simple first application, a simple Ogg/Vorbis
  16 command-line audio player. For this, we will use only standard GStreamer
  17 components. The player will read a file specified on the command-line.
  18 Let's get started\!
  19
  20 We've learned, in [Initializing GStreamer](manual-init.md), that the
  21 first thing to do in your application is to initialize GStreamer by
  22 calling `gst_init ()`. Also, make sure that the application includes
  23 `gst/gst.h` so all function names and objects are properly defined. Use
  24 `#include
  25 <gst/gst.h>` to do that.
  26
  27 Next, you'll want to create the different elements using
  28 `gst_element_factory_make ()`. For an Ogg/Vorbis audio player, we'll
  29 need a source element that reads files from a disk. GStreamer includes
  30 this element under the name “filesrc”. Next, we'll need something to
  31 parse the file and decode it into raw audio. GStreamer has two elements
  32 for this: the first parses Ogg streams into elementary streams (video,
  33 audio) and is called “oggdemux”. The second is a Vorbis audio decoder,
  34 it's conveniently called “vorbisdec”. Since “oggdemux” creates dynamic
  35 pads for each elementary stream, you'll need to set a “pad-added” event
  36 handler on the “oggdemux” element, like you've learned in [Dynamic (or
  37 sometimes) pads](manual-pads.md#dynamic-or-sometimes-pads), to link the
  38 Ogg demuxer and the Vorbis decoder elements together. At last, we'll
  39 also need an audio output element, we will use “autoaudiosink”, which
  40 automatically detects your audio device.
  41
  42 The last thing left to do is to add all elements into a container
  43 element, a `GstPipeline`, and wait until we've played the whole song.
  44 We've previously learned how to add elements to a container bin in
  45 [Bins](manual-bins.md), and we've learned about element states in
  46 [Element States](manual-elements.md#element-states). We will also
  47 attach a message handler to the pipeline bus so we can retrieve errors
  48 and detect the end-of-stream.
  49
  50 Let's now add all the code together to get our very first audio player:
  51
  52 ``` c
  53
  54 #include <gst/gst.h>
  55 #include <glib.h>
  56
  57
  58 static gboolean
  59 bus_call (GstBus     *bus,
  60           GstMessage *msg,
  61           gpointer    data)
  62 {
  63   GMainLoop *loop = (GMainLoop *) data;
  64
  65   switch (GST_MESSAGE_TYPE (msg)) {
  66
  67     case GST_MESSAGE_EOS:
  68       g_print ("End of stream\n");
  69       g_main_loop_quit (loop);
  70       break;
  71
  72     case GST_MESSAGE_ERROR: {
  73       gchar  *debug;
  74       GError *error;
  75
  76       gst_message_parse_error (msg, &error, &debug);
  77       g_free (debug);
  78
  79       g_printerr ("Error: %s\n", error->message);
  80       g_error_free (error);
  81
  82       g_main_loop_quit (loop);
  83       break;
  84     }
  85     default:
  86       break;
  87   }
  88
  89   return TRUE;
  90 }
  91
  92
  93 static void
  94 on_pad_added (GstElement *element,
  95               GstPad     *pad,
  96               gpointer    data)
  97 {
  98   GstPad *sinkpad;
  99   GstElement *decoder = (GstElement *) data;
 100
 101   /* We can now link this pad with the vorbis-decoder sink pad */
 102   g_print ("Dynamic pad created, linking demuxer/decoder\n");
 103
 104   sinkpad = gst_element_get_static_pad (decoder, "sink");
 105
 106   gst_pad_link (pad, sinkpad);
 107
 108   gst_object_unref (sinkpad);
 109 }
 110
 111
 112
 113 int
 114 main (int   argc,
 115       char *argv[])
 116 {
 117   GMainLoop *loop;
 118
 119   GstElement *pipeline, *source, *demuxer, *decoder, *conv, *sink;
 120   GstBus *bus;
 121   guint bus_watch_id;
 122
 123   /* Initialisation */
 124   gst_init (&argc, &argv);
 125
 126   loop = g_main_loop_new (NULL, FALSE);
 127
 128
 129   /* Check input arguments */
 130   if (argc != 2) {
 131     g_printerr ("Usage: %s <Ogg/Vorbis filename>\n", argv[0]);
 132     return -1;
 133   }
 134
 135
 136   /* Create gstreamer elements */
 137   pipeline = gst_pipeline_new ("audio-player");
 138   source   = gst_element_factory_make ("filesrc",       "file-source");
 139   demuxer  = gst_element_factory_make ("oggdemux",      "ogg-demuxer");
 140   decoder  = gst_element_factory_make ("vorbisdec",     "vorbis-decoder");
 141   conv     = gst_element_factory_make ("audioconvert",  "converter");
 142   sink     = gst_element_factory_make ("autoaudiosink", "audio-output");
 143
 144   if (!pipeline || !source || !demuxer || !decoder || !conv || !sink) {
 145     g_printerr ("One element could not be created. Exiting.\n");
 146     return -1;
 147   }
 148
 149   /* Set up the pipeline */
 150
 151   /* we set the input filename to the source element */
 152   g_object_set (G_OBJECT (source), "location", argv[1], NULL);
 153
 154   /* we add a message handler */
 155   bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
 156   bus_watch_id = gst_bus_add_watch (bus, bus_call, loop);
 157   gst_object_unref (bus);
 158
 159   /* we add all elements into the pipeline */
 160   /* file-source | ogg-demuxer | vorbis-decoder | converter | alsa-output */
 161   gst_bin_add_many (GST_BIN (pipeline),
 162                     source, demuxer, decoder, conv, sink, NULL);
 163
 164   /* we link the elements together */
 165   /* file-source -> ogg-demuxer ~> vorbis-decoder -> converter -> alsa-output */
 166   gst_element_link (source, demuxer);
 167   gst_element_link_many (decoder, conv, sink, NULL);
 168   g_signal_connect (demuxer, "pad-added", G_CALLBACK (on_pad_added), decoder);
 169
 170   /* note that the demuxer will be linked to the decoder dynamically.
 171      The reason is that Ogg may contain various streams (for example
 172      audio and video). The source pad(s) will be created at run time,
 173      by the demuxer when it detects the amount and nature of streams.
 174      Therefore we connect a callback function which will be executed
 175      when the "pad-added" is emitted.*/
 176
 177
 178   /* Set the pipeline to "playing" state*/
 179   g_print ("Now playing: %s\n", argv[1]);
 180   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 181
 182
 183   /* Iterate */
 184   g_print ("Running...\n");
 185   g_main_loop_run (loop);
 186
 187
 188   /* Out of the main loop, clean up nicely */
 189   g_print ("Returned, stopping playback\n");
 190   gst_element_set_state (pipeline, GST_STATE_NULL);
 191
 192   g_print ("Deleting pipeline\n");
 193   gst_object_unref (GST_OBJECT (pipeline));
 194   g_source_remove (bus_watch_id);
 195   g_main_loop_unref (loop);
 196
 197   return 0;
 198 }
 199
 200
 201 ```
 202
 203 We now have created a complete pipeline. We can visualise the pipeline
 204 as follows:
 205
 206 ![The "hello world" pipeline](images/hello-world.png "fig:")
 207
 208 ## Compiling and Running helloworld.c
 209
 210 To compile the helloworld example, use: `gcc -Wall
 211 helloworld.c -o helloworld
 212 $(pkg-config --cflags --libs gstreamer-1.0)`. GStreamer makes use of
 213 `pkg-config` to get compiler and linker flags needed to compile this
 214 application.
 215
 216 If you're running a non-standard installation (ie. you've installed
 217 GStreamer from source yourself instead of using pre-built packages),
 218 make sure the `PKG_CONFIG_PATH` environment variable is set to the
 219 correct location (`$libdir/pkgconfig`).
 220
 221 In the unlikely case that you are using an uninstalled GStreamer setup
 222 (ie. gst-uninstalled), you will need to use libtool to build the hello
 223 world program, like this: `libtool --mode=link gcc -Wall
 224 helloworld.c -o helloworld
 225 $(pkg-config --cflags --libs gstreamer-1.0)`.
 226
 227 You can run this example application with `./helloworld
 228 file.ogg`. Substitute `file.ogg` with your favourite Ogg/Vorbis file.
 229
 230 ## Conclusion
 231
 232 This concludes our first example. As you see, setting up a pipeline is
 233 very low-level but powerful. You will see later in this manual how you
 234 can create a more powerful media player with even less effort using
 235 higher-level interfaces. We will discuss all that in [Higher-level
 236 interfaces for GStreamer applications](manual-highlevel.md). We will
 237 first, however, go more in-depth into more advanced GStreamer internals.
 238
 239 It should be clear from the example that we can very easily replace the
 240 “filesrc” element with some other element that reads data from a
 241 network, or some other data source element that is better integrated
 242 with your desktop environment. Also, you can use other decoders and
 243 parsers/demuxers to support other media types. You can use another audio
 244 sink if you're not running Linux, but Mac OS X, Windows or FreeBSD, or
 245 you can instead use a filesink to write audio files to disk instead of
 246 playing them back. By using an audio card source, you can even do audio
 247 capture instead of playback. All this shows the reusability of GStreamer
 248 elements, which is its greatest advantage.
 249