docs/manual/basics-helloworld.xml

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