docs/manual/basics-helloworld.xml

   1 <chapter id="chapter-hello-world">
   2   <title>Your first application</title>
   3   <para>
   4     This chapter describes the most rudimentary aspects of a
   5     <application>GStreamer</application> application, including initializing
   6     the libraries, creating elements, packing them into a pipeline and playing,
   7     pausing and stopping the pipeline.
   8   </para>
   9
  10   <sect1 id="section-hello-world">
  11     <title>Hello world</title>
  12     <para>
  13       We will create a simple first application, a complete MP3 player, using
  14       standard <application>GStreamer</application> components. The player
  15       will read from a file that is given as the first argument to the program.
  16     </para>
  17
  18     <programlisting>
  19 /* example-begin helloworld.c */
  20 #include &lt;gst/gst.h&gt;
  21
  22 int
  23 main (int argc, char *argv[])
  24 {
  25   GstElement *pipeline, *filesrc, *decoder, *audiosink;
  26
  27   gst_init(&amp;argc, &amp;argv);
  28
  29   if (argc != 2) {
  30     g_print ("usage: %s &lt;mp3 filename&gt;\n", argv[0]);
  31     exit (-1);
  32   }
  33
  34   /* create a new pipeline to hold the elements */
  35   pipeline = gst_pipeline_new ("pipeline");
  36
  37   /* create a disk reader */
  38   filesrc = gst_element_factory_make ("filesrc", "disk_source");
  39   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
  40
  41   /* now it's time to get the decoder */
  42   decoder = gst_element_factory_make ("mad", "decoder");
  43
  44   /* and an audio sink */
  45   audiosink = gst_element_factory_make ("osssink", "play_audio");
  46
  47   /* add objects to the main pipeline */
  48   gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
  49
  50   /* link src to sink */
  51   gst_element_link_many (filesrc, decoder, audiosink, NULL);
  52
  53   /* start playing */
  54   gst_element_set_state (pipeline, GST_STATE_PLAYING);
  55
  56   while (gst_bin_iterate (GST_BIN (pipeline)));
  57
  58   /* stop the pipeline */
  59   gst_element_set_state (pipeline, GST_STATE_NULL);
  60
  61   /* we don't need a reference to these objects anymore */
  62   gst_object_unref (GST_OBJECT (pipeline));
  63   /* unreffing the pipeline unrefs the contained elements as well */
  64
  65   exit (0);
  66 }
  67 /* example-end helloworld.c */
  68     </programlisting>
  69
  70     <para>
  71       Let's go through this example step by step.
  72     </para>
  73
  74     <para>
  75       The first thing you have to do is to include the standard
  76       <application>GStreamer</application> headers and
  77       initialize the framework.
  78     </para>
  79     <programlisting>
  80
  81 #include &lt;gst/gst.h&gt;
  82
  83   ...
  84
  85 int
  86 main (int argc, char *argv[])
  87 {
  88   ...
  89   gst_init(&amp;argc, &amp;argv);
  90   ...
  91
  92     </programlisting>
  93
  94     <para>
  95       We are going to create three elements and one pipeline. Since all
  96       elements share the same base type, <ulink type="http"
  97       url="../../gstreamer/html/GstElement.html"><classname>GstElement</classname></ulink>,
  98       we can define them as:
  99     </para>
 100     <programlisting>
 101   ...
 102   GstElement *pipeline, *filesrc, *decoder, *audiosink;
 103   ...
 104     </programlisting>
 105
 106     <para>
 107       Next, we are going to create an empty pipeline. As you have seen in
 108       the basic introduction, this pipeline will hold and manage all the
 109       elements we are going to pack into it.
 110     </para>
 111     <programlisting>
 112   /* create a new pipeline to hold the elements */
 113   pipeline = gst_pipeline_new ("pipeline");
 114     </programlisting>
 115     <para>
 116       We use the standard constructor for a pipeline: gst_pipeline_new ().
 117     </para>
 118
 119     <para>
 120       We then create a disk source element. The disk source element is able to
 121       read from a file.  We use the standard GObject property mechanism to set
 122       a property of the element: the file to read from.
 123     </para>
 124     <programlisting>
 125   /* create a disk reader */
 126   filesrc = gst_element_factory_make ("filesrc", "disk_source");
 127   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
 128     </programlisting>
 129     <note>
 130       <para>
 131         You can check if the filesrc != NULL to verify the creation of the
 132         disk source element.
 133       </para>
 134     </note>
 135
 136     <para>
 137       We now create the MP3 decoder element. This assumes that the 'mad' plugin
 138       is installed on the system where this application is executed.
 139     </para>
 140     <programlisting>
 141   /* now it's time to get the decoder */
 142   decoder = gst_element_factory_make ("mad", "decoder");
 143     </programlisting>
 144     <para>
 145       gst_element_factory_make() takes two arguments: a string that will
 146       identify the element you need and a second argument: how you want
 147       to name the element. The name of the element is something you can
 148       choose yourself and might be used to retrieve the element from a
 149       bin/pipeline.
 150     </para>
 151
 152     <para>
 153       Finally we create our audio sink element. This element will be able
 154       to play back the audio using OSS.
 155     </para>
 156     <programlisting>
 157   /* and an audio sink */
 158   audiosink = gst_element_factory_make ("osssink", "play_audio");
 159     </programlisting>
 160
 161     <para>
 162       We then add the elements to the pipeline.
 163     </para>
 164     <programlisting>
 165   /* add objects to the main pipeline */
 166   gst_bin_add_many (GST_BIN (pipeline), filesrc, decoder, audiosink, NULL);
 167     </programlisting>
 168
 169     <para>
 170       We link the different pads of the elements together like this:
 171     </para>
 172     <programlisting>
 173   /* link src to sink */
 174   gst_element_link_many (filesrc, decoder, audiosink, NULL);
 175     </programlisting>
 176
 177     <para>
 178       We now have created a complete pipeline.  We can visualise the
 179       pipeline as follows:
 180     </para>
 181     <figure float="1" id="section-hello-img">
 182       <title>The "hello world" pipeline</title>
 183       <mediaobject>
 184         <imageobject>
 185           <imagedata fileref="images/hello-world.&image;" format="&IMAGE;" />
 186         </imageobject>
 187       </mediaobject>
 188
 189     </figure>
 190
 191     <para>
 192      Everything is now set up to start streaming. We use the following
 193      statements to change the state of the pipeline:
 194     </para>
 195     <programlisting>
 196   /* start playing */
 197   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 198
 199     </programlisting>
 200     <note>
 201       <para>
 202         <application>GStreamer</application> will take care of the READY and PAUSED state for
 203         you when going from NULL to PLAYING.
 204       </para>
 205     </note>
 206
 207     <para>
 208       Since we do not use threads, nothing will happen yet. We have to
 209       call gst_bin_iterate() to execute one iteration of the pipeline.
 210     </para>
 211     <programlisting>
 212   while (gst_bin_iterate (GST_BIN (pipeline)));
 213     </programlisting>
 214     <para>
 215       The gst_bin_iterate() function will return TRUE as long as something
 216       interesting happened inside the pipeline. When the end-of-file has been
 217       reached the _iterate function will return FALSE and we can end the loop.
 218     </para>
 219     <programlisting>
 220   /* stop the pipeline */
 221   gst_element_set_state (pipeline, GST_STATE_NULL);
 222
 223   gst_object_unref (GST_OBJECT (pipeline));
 224
 225   exit (0);
 226     </programlisting>
 227     <note>
 228       <para>
 229         Don't forget to set the state of the pipeline to NULL. This will free
 230         all of the resources held by the elements.
 231       </para>
 232     </note>
 233
 234   </sect1>
 235
 236   <sect1 id="section-hello-world-compile">
 237     <title>Compiling helloworld.c</title>
 238     <para>
 239       To compile the helloworld example, use:
 240     </para>
 241     <programlisting>
 242        gcc -Wall `pkg-config gstreamer-&GST_MAJORMINOR; --cflags --libs` helloworld.c \
 243              -o helloworld
 244     </programlisting>
 245     <para>
 246       We use pkg-config to get the compiler flags needed to compile
 247       this application.  Make sure to have your PKG_CONFIG_PATH environment
 248       variable set to the correct location if you are building this
 249       application against the uninstalled location.
 250     </para>
 251     <para>
 252       You can run the example with
 253       (substitute helloworld.mp3 with you favorite MP3 file):
 254     </para>
 255     <programlisting>
 256       ./helloworld helloworld.mp3
 257     </programlisting>
 258   </sect1>
 259
 260   <sect1 id="section-hello-world-conclusion">
 261     <title>Conclusion</title>
 262     <para>
 263       This concludes our first example. As you see, setting up a pipeline
 264       is very low-level but powerful. You will see later in this manual how
 265       you can create a custom MP3 element with a higher-level API.
 266     </para>
 267     <para>
 268       It should be clear from the example that we can very easily replace the
 269       filesrc element with the gnomevfssrc element, giving you instant streaming
 270       from any gnomevfs URL.
 271     </para>
 272     <para>
 273       We can also choose to use another type of sink instead of the audiosink.
 274       We could use a filesink to write the raw samples to a file, for example.
 275       It should also be clear that inserting filters, like a stereo effect,
 276       into the pipeline is not that hard to do. The most important thing is
 277       that you can reuse already existing elements.
 278     </para>
 279   </sect1>
 280 </chapter>