docs/manual/highlevel-components.xml

   1 <chapter id="chapter-components">
   2   <title>Components</title>
   3
   4   <para>
   5     &GStreamer; includes several higher-level components to simplify an
   6     application developer's life. All of the components discussed here (for now) are
   7     targetted at media playback. The idea of each of these components is
   8     to integrate as closely as possible with a &GStreamer; pipeline, but
   9     to hide the complexity of media type detection and several other
  10     rather complex topics that have been discussed in <xref
  11     linkend="part-advanced"/>.
  12   </para>
  13
  14   <para>
  15     We currently recommend people to use either playbin (see <xref
  16     linkend="section-components-playbin"/>) or decodebin (see <xref
  17     linkend="section-components-decodebin"/>), depending on their needs.
  18     Playbin is the recommended solution for everything related to simple
  19     playback of media that should just work. Decodebin is a more flexible
  20     autoplugger that could be used to add more advanced features, such
  21     as playlist support, crossfading of audio tracks and so on. Its
  22     programming interface is more low-level than that of playbin, though.
  23   </para>
  24
  25   <sect1 id="section-components-playbin">
  26     <title>Playbin</title>
  27
  28     <para>
  29       Playbin is an element that can be created using the standard &GStreamer;
  30       API (e.g. <function>gst_element_factory_make ()</function>). The factory
  31       is conveniently called <quote>playbin</quote>. By being a
  32       <classname>GstPipeline</classname> (and thus a
  33       <classname>GstElement</classname>), playbin automatically supports all
  34       of the features of this class, including error handling, tag support,
  35       state handling, getting stream positions, seeking, and so on.
  36     </para>
  37
  38     <para>
  39       Setting up a playbin pipeline is as simple as creating an instance of
  40       the playbin element, setting a file location using the
  41       <quote>uri</quote> property on playbin, and then setting the element
  42       to the <classname>GST_STATE_PLAYING</classname> state (the location has to be a valid
  43       URI, so <quote>&lt;protocol&gt;://&lt;location&gt;</quote>, e.g.
  44       file:///tmp/my.ogg or http://www.example.org/stream.ogg). Internally,
  45       playbin will set up a pipeline to playback the media location.
  46     </para>
  47
  48     <programlisting><!-- example-begin playbin.c a -->
  49 #include &lt;gst/gst.h&gt;
  50 <!-- example-end playbin.c a -->
  51 [.. my_bus_callback goes here ..]<!-- example-begin playbin.c b --><!--
  52 static gboolean
  53 my_bus_callback (GstBus     *bus,
  54                  GstMessage *message,
  55                  gpointer    data)
  56 {
  57   GMainLoop *loop = data;
  58
  59   switch (GST_MESSAGE_TYPE (message)) {
  60     case GST_MESSAGE_ERROR: {
  61       GError *err;
  62       gchar *debug;
  63
  64       gst_message_parse_error (message, &amp;err, &amp;debug);
  65       g_print ("Error: %s\n", err-&gt;message);
  66       g_error_free (err);
  67       g_free (debug);
  68
  69       g_main_loop_quit (loop);
  70       break;
  71     }
  72     case GST_MESSAGE_EOS:
  73       /* end-of-stream */
  74       g_main_loop_quit (loop);
  75       break;
  76     default:
  77       /* unhandled message */
  78       break;
  79   }
  80
  81   /* remove message from the queue */
  82   return TRUE;
  83 }
  84 --><!-- example-end playbin.c b -->
  85 <!-- example-begin playbin.c c -->
  86 gint
  87 main (gint   argc,
  88       gchar *argv[])
  89 {
  90   GMainLoop *loop;
  91   GstElement *play;
  92   GstBus *bus;
  93
  94   /* init GStreamer */
  95   gst_init (&amp;argc, &amp;argv);
  96   loop = g_main_loop_new (NULL, FALSE);
  97
  98   /* make sure we have a URI */
  99   if (argc != 2) {
 100     g_print ("Usage: %s &lt;URI&gt;\n", argv[0]);
 101     return -1;
 102   }
 103
 104   /* set up */
 105   play = gst_element_factory_make ("playbin", "play");
 106   g_object_set (G_OBJECT (play), "uri", argv[1], NULL);
 107
 108   bus = gst_pipeline_get_bus (GST_PIPELINE (play));
 109   gst_bus_add_watch (bus, my_bus_callback, loop);
 110   gst_object_unref (bus);
 111
 112   gst_element_set_state (play, GST_STATE_PLAYING);
 113
 114   /* now run */
 115   g_main_loop_run (loop);
 116
 117   /* also clean up */
 118   gst_element_set_state (play, GST_STATE_NULL);
 119   gst_object_unref (GST_OBJECT (play));
 120
 121   return 0;
 122 }
 123     <!-- example-end playbin.c c --></programlisting>
 124
 125     <para>
 126       Playbin has several features that have been discussed previously:
 127     </para>
 128     <itemizedlist>
 129       <listitem>
 130         <para>
 131           Settable video and audio output (using the <quote>video-sink</quote>
 132           and <quote>audio-sink</quote> properties).
 133         </para>
 134       </listitem>
 135       <listitem>
 136         <para>
 137           Mostly controllable and trackable as a
 138           <classname>GstElement</classname>, including error handling, eos
 139           handling, tag handling, state handling (through the
 140           <classname>GstBus</classname>), media position handling and
 141           seeking.
 142         </para>
 143       </listitem>
 144       <listitem>
 145         <para>
 146           Buffers network-sources, with buffer fullness notifications being
 147           passed through the <classname>GstBus</classname>.
 148         </para>
 149       </listitem>
 150       <listitem>
 151         <para>
 152           Supports visualizations for audio-only media.
 153         </para>
 154       </listitem>
 155       <listitem>
 156         <para>
 157           Supports subtitles, both in the media as well as from separate
 158           files. For separate subtitle files, use the <quote>suburi</quote>
 159           property.
 160         </para>
 161       </listitem>
 162       <listitem>
 163         <para>
 164           Supports stream selection and disabling. If your media has
 165           multiple audio or subtitle tracks, you can dynamically choose
 166           which one to play back, or decide to turn it off alltogther
 167           (which is especially useful to turn off subtitles). For each
 168           of those, use the <quote>current-text</quote> and other related
 169           properties.
 170         </para>
 171       </listitem>
 172     </itemizedlist>
 173     <para>
 174       For convenience, it is possible to test <quote>playbin</quote> on
 175       the commandline, using the command <quote>gst-launch-0.10 playbin
 176       uri=file:///path/to/file</quote>.
 177     </para>
 178     <para>
 179       New applications should use playbin2 instead of the old playbin.
 180     </para>
 181   </sect1>
 182
 183   <sect1 id="section-components-decodebin">
 184     <title>Decodebin</title>
 185
 186     <para>
 187       Decodebin is the actual autoplugger backend of playbin, which was
 188       discussed in the previous section. Decodebin will, in short, accept
 189       input from a source that is linked to its sinkpad and will try to
 190       detect the media type contained in the stream, and set up decoder
 191       routines for each of those. It will automatically select decoders.
 192       For each decoded stream, it will emit the <quote>new-decoded-pad</quote>
 193       signal, to let the client know about the newly found decoded stream.
 194       For unknown streams (which might be the whole stream), it will emit
 195       the <quote>unknown-type</quote> signal. The application is then
 196       responsible for reporting the error to the user.
 197     </para>
 198     <programlisting><!-- example-begin decodebin.c a -->
 199 #include &lt;gst/gst.h&gt;
 200 <!-- example-end decodebin.c a -->
 201 [.. my_bus_callback goes here ..]<!-- example-begin decodebin.c b --><!--
 202 static gboolean
 203 my_bus_callback (GstBus     *bus,
 204                  GstMessage *message,
 205                  gpointer    data)
 206 {
 207   GMainLoop *loop = data;
 208
 209   switch (GST_MESSAGE_TYPE (message)) {
 210     case GST_MESSAGE_ERROR: {
 211       GError *err;
 212       gchar *debug;
 213
 214       gst_message_parse_error (message, &amp;err, &amp;debug);
 215       g_print ("Error: %s\n", err-&gt;message);
 216       g_error_free (err);
 217       g_free (debug);
 218
 219       g_main_loop_quit (loop);
 220       break;
 221     }
 222     case GST_MESSAGE_EOS:
 223       /* end-of-stream */
 224       g_main_loop_quit (loop);
 225       break;
 226     default:
 227       /* unhandled message */
 228       break;
 229   }
 230
 231   /* remove message from the queue */
 232   return TRUE;
 233 }
 234 --><!-- example-end decodebin.c b -->
 235 <!-- example-begin decodebin.c c -->
 236 GstElement *pipeline, *audio;
 237
 238 static void
 239 cb_newpad (GstElement *decodebin,
 240            GstPad     *pad,
 241            gboolean    last,
 242            gpointer    data)
 243 {
 244   GstCaps *caps;
 245   GstStructure *str;
 246   GstPad *audiopad;
 247
 248   /* only link once */
 249   audiopad = gst_element_get_static_pad (audio, "sink");
 250   if (GST_PAD_IS_LINKED (audiopad)) {
 251     g_object_unref (audiopad);
 252     return;
 253   }
 254
 255   /* check media type */
 256   caps = gst_pad_get_caps (pad);
 257   str = gst_caps_get_structure (caps, 0);
 258   if (!g_strrstr (gst_structure_get_name (str), "audio")) {
 259     gst_caps_unref (caps);
 260     gst_object_unref (audiopad);
 261     return;
 262   }
 263   gst_caps_unref (caps);
 264
 265   /* link'n'play */
 266   gst_pad_link (pad, audiopad);
 267
 268   g_object_unref (audiopad);
 269 }
 270
 271 gint
 272 main (gint   argc,
 273       gchar *argv[])
 274 {
 275   GMainLoop *loop;
 276   GstElement *src, *dec, *conv, *sink;
 277   GstPad *audiopad;
 278   GstBus *bus;
 279
 280   /* init GStreamer */
 281   gst_init (&amp;argc, &amp;argv);
 282   loop = g_main_loop_new (NULL, FALSE);
 283
 284   /* make sure we have input */
 285   if (argc != 2) {
 286     g_print ("Usage: %s &lt;filename&gt;\n", argv[0]);
 287     return -1;
 288   }
 289
 290   /* setup */
 291   pipeline = gst_pipeline_new ("pipeline");
 292
 293   bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
 294   gst_bus_add_watch (bus, my_bus_callback, loop);
 295   gst_object_unref (bus);
 296
 297   src = gst_element_factory_make ("filesrc", "source");
 298   g_object_set (G_OBJECT (src), "location", argv[1], NULL);
 299   dec = gst_element_factory_make ("decodebin", "decoder");
 300   g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL);
 301   gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL);
 302   gst_element_link (src, dec);
 303
 304   /* create audio output */
 305   audio = gst_bin_new ("audiobin");
 306   conv = gst_element_factory_make ("audioconvert", "aconv");
 307   audiopad = gst_element_get_static_pad (conv, "sink");
 308   sink = gst_element_factory_make ("alsasink", "sink");
 309   gst_bin_add_many (GST_BIN (audio), conv, sink, NULL);
 310   gst_element_link (conv, sink);
 311   gst_element_add_pad (audio,
 312       gst_ghost_pad_new ("sink", audiopad));
 313   gst_object_unref (audiopad);
 314   gst_bin_add (GST_BIN (pipeline), audio);
 315
 316   /* run */
 317   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 318   g_main_loop_run (loop);
 319
 320   /* cleanup */
 321   gst_element_set_state (pipeline, GST_STATE_NULL);
 322   gst_object_unref (GST_OBJECT (pipeline));
 323
 324   return 0;
 325 }
 326     <!-- example-end decodebin.c c --></programlisting>
 327
 328     <para>
 329       Decodebin, similar to playbin, supports the following features:
 330     </para>
 331     <itemizedlist>
 332       <listitem>
 333         <para>
 334           Can decode an unlimited number of contained streams to decoded
 335           output pads.
 336         </para>
 337       </listitem>
 338       <listitem>
 339         <para>
 340           Is handled as a <classname>GstElement</classname> in all ways,
 341           including tag or error forwarding and state handling.
 342         </para>
 343       </listitem>
 344     </itemizedlist>
 345     <para>
 346       Although decodebin is a good autoplugger, there's a whole lot of
 347       things that it does not do and is not intended to do:
 348     </para>
 349     <itemizedlist>
 350       <listitem>
 351         <para>
 352           Taking care of input streams with a known media type (e.g. a DVD,
 353           an audio-CD or such).
 354         </para>
 355       </listitem>
 356       <listitem>
 357         <para>
 358           Selection of streams (e.g. which audio track to play in case of
 359           multi-language media streams).
 360         </para>
 361       </listitem>
 362       <listitem>
 363         <para>
 364           Overlaying subtitles over a decoded video stream.
 365         </para>
 366       </listitem>
 367     </itemizedlist>
 368     <para>
 369       Decodebin can be easily tested on the commandline, e.g. by using the
 370       command <command>gst-launch-0.10 filesrc location=file.ogg ! decodebin
 371       ! audioconvert ! audioresample ! autoaudiosink</command>.
 372     </para>
 373     <para>
 374       New applications should use decodebin2 instead of the old decodebin.
 375     </para>
 376     <para>
 377       The uridecodebin element is very similar to decodebin2, only that it
 378       automatically plugs a source plugin based on the protocol of the URI
 379       given.
 380     </para>
 381   </sect1>
 382
 383 </chapter>