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 decoder 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>new-pad</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 parser and
  41       the Vorbis decoder elements together. At last, we'll also need an
  42       audio output element, we will use <quote>alsasink</quote>, which
  43       outputs sound to an ALSA 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 use the function
  52       <function>gst_bin_sync_children_state ()</function> to synchronize
  53       the state of a bin on all of its contained children.
  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 #include &lt;gst/gst.h&gt;
  61
  62 /*
  63  * Global objects are usually a bad thing. For the purpose of this
  64  * example, we will use them, however.
  65  */
  66
  67 GstElement *pipeline, *source, *parser, *decoder, *sink;
  68
  69 static void
  70 new_pad (GstElement *element,
  71          GstPad     *pad,
  72          gpointer    data)
  73 {
  74   /* We can now link this pad with the audio decoder and
  75    * add both decoder and audio output to the pipeline. */
  76   gst_pad_link (pad, gst_element_get_pad (decoder, "sink"));
  77   gst_bin_add_many (GST_BIN (pipeline), decoder, sink, NULL);
  78
  79   /* This function synchronizes a bins state on all of its
  80    * contained children. */
  81   gst_bin_sync_children_state (GST_BIN (pipeline));
  82 }
  83
  84 int
  85 main (int   argc,
  86       char *argv[])
  87 {
  88   /* initialize GStreamer */
  89   gst_init (&amp;argc, &amp;argv);
  90
  91   /* check input arguments */
  92   if (argc != 2) {
  93     g_print ("Usage: %s &lt;Ogg/Vorbis filename&gt;\n", argv[0]);
  94     return -1;
  95   }
  96
  97   /* create elements */
  98   pipeline = gst_pipeline_new ("audio-player");
  99   source = gst_element_factory_make ("filesrc", "file-source");
 100   parser = gst_element_factory_make ("oggdemux", "ogg-parser");
 101   decoder = gst_element_factory_make ("vorbisdec", "vorbis-decoder");
 102   sink = gst_element_factory_make ("alsasink", "alsa-output");
 103
 104   /* set filename property on the file source */
 105   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
 106
 107   /* link together - note that we cannot link the parser and
 108    * decoder yet, becuse the parser uses dynamic pads. For that,
 109    * we set a new-pad signal handler. */
 110   gst_element_link (source, parser);
 111   gst_element_link (decoder, sink);
 112   g_signal_connect (parser, "new-pad", G_CALLBACK (new_pad), NULL);
 113
 114   /* put all elements in a bin - or at least the ones we will use
 115    * instantly. */
 116   gst_bin_add_many (GST_BIN (pipeline), source, parser, NULL);
 117
 118   /* Now set to playing and iterate. We will set the decoder and
 119    * audio output to ready so they initialize their memory already.
 120    * This will decrease the amount of time spent on linking these
 121    * elements when the Ogg parser emits the new-pad signal. */
 122   gst_element_set_state (decoder, GST_STATE_READY);
 123   gst_element_set_state (sink, GST_STATE_READY);
 124   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 125
 126   /* and now iterate - the rest will be automatic from here on.
 127    * When the file is finished, gst_bin_iterate () will return
 128    * FALSE, thereby terminating this loop. */
 129   while (gst_bin_iterate (GST_BIN (pipeline))) ;
 130
 131   /* clean up nicely */
 132   gst_element_set_state (pipeline, GST_STATE_NULL);
 133   gst_object_unref (GST_OBJECT (pipeline));
 134
 135   return 0;
 136 }
 137     </programlisting>
 138     <!-- FIXME: this image needs updating -->
 139     <para>
 140       We now have created a complete pipeline.  We can visualise the
 141       pipeline as follows:
 142     </para>
 143     <figure float="1" id="section-hello-img">
 144       <title>The "hello world" pipeline</title>
 145       <mediaobject>
 146         <imageobject>
 147           <imagedata fileref="images/hello-world.&image;" format="&IMAGE;" />
 148         </imageobject>
 149       </mediaobject>
 150     </figure>
 151   </sect1>
 152
 153   <sect1 id="section-helloworld-compilerun">
 154     <title>Compiling and Running helloworld.c</title>
 155     <para>
 156       To compile the helloworld example, use: <command>gcc -Wall
 157       $(pkg-config --cflags --libs gstreamer-&GST_MAJORMINOR;)
 158       helloworld.c -o helloworld</command>. &GStreamer; makes use of
 159       <command>pkg-config</command> to get compiler and linker flags
 160       needed to compile this application. If you're running a
 161       non-standard installation, make sure the
 162       <classname>PKG_CONFIG_PATH</classname> environment variable is
 163       set to the correct location (<filename>$libdir/pkgconfig</filename>).
 164       application against the uninstalled location.
 165     </para>
 166     <para>
 167       You can run this example application with <command>./helloworld
 168       file.ogg</command>. Substitute <filename>file.ogg</filename>
 169       with your favourite Ogg/Vorbis file.
 170     </para>
 171   </sect1>
 172
 173   <sect1 id="section-hello-world-conclusion">
 174     <title>Conclusion</title>
 175     <para>
 176       This concludes our first example. As you see, setting up a pipeline
 177       is very low-level but powerful. You will see later in this manual how
 178       you can create a more powerful media player with even less effort
 179       using higher-level interfaces. We will discuss all that in <xref
 180       linkend="part-highlevel"/>. We will first, however, go more in-depth
 181       into more advanced &GStreamer; internals.
 182     </para>
 183     <para>
 184       It should be clear from the example that we can very easily replace
 185       the <quote>filesrc</quote> element with some other element that
 186       reads data from a network, or some other data source element that
 187       is better integrated with your desktop environment. Also, you can
 188       use other decoders and parsers to support other media types. You
 189       can use another audio sink if you're not running Linux, but Mac OS X,
 190       Windows or FreeBSD, or you can instead use a filesink to write audio
 191       files to disk instead of playing them back. By using an audio card
 192       source, you can even do audio capture instead of playback. All this
 193       shows the reusability of &GStreamer; elements, which is its greatest
 194       advantage.
 195     </para>
 196   </sect1>
 197 </chapter>