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 your
   6     applications 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. The
  18     other components discussed here are either outdated or deprecated. The
  19     documentation is provided for legacy purposes. Use of those other
  20     components is not recommended.
  21   </para>
  22
  23   <sect1 id="section-components-playbin">
  24     <title>Playbin</title>
  25
  26     <para>
  27       Playbin is an element that can be created using the standard &GStreamer;
  28       API (e.g. <function>gst_element_factory_make ()</function>). The factory
  29       is conveniently called <quote>playbin</quote>. By being a
  30       <classname>GstElement</classname>, playbin automatically supports all
  31       of the features of this class, including error handling, tag support,
  32       state handling, getting stream positions, seeking, and so on.
  33     </para>
  34
  35     <para>
  36       Setting up a playbin pipeline is as simple as creating an instance of
  37       the playbin element, setting a file location (this has to be a valid
  38       URI, so <quote>&lt;protocol&gt;://&lt;location&gt;</quote>, e.g.
  39       file:///tmp/my.ogg or http://www.example.org/stream.ogg) using the
  40       <quote>uri</quote> property on playbin, and then setting the element
  41       to the <classname>GST_STATE_PLAYING</classname> state. Internally,
  42       playbin uses threads, so there's no need to iterate the element or
  43       anything. However, one thing to keep in mind is that signals fired
  44       by playbin might come from another than the main thread, so be sure
  45       to keep this in mind in your signal handles. Most application
  46       programmers will want to use a function such as <function>g_idle_add
  47       ()</function> to make sure that the signal is handled in the main
  48       thread.
  49     </para>
  50
  51     <programlisting>
  52 #include &lt;gst/gst.h&gt;
  53
  54 static void
  55 cb_eos (GstElement *play,
  56         gpointer    data)
  57 {
  58   gst_main_quit ();
  59 }
  60
  61 static void
  62 cb_error (GstElement *play,
  63           GstElement *src,
  64           GError     *err,
  65           gchar      *debug,
  66           gpointer    data)
  67 {
  68   g_print ("Error: %s\n", err->message);
  69 }
  70
  71 gint
  72 main (gint   argc,
  73       gchar *argv[])
  74 {
  75   GstElement *play;
  76
  77   /* init GStreamer */
  78   gst_init (&amp;argc, &amp;argv);
  79
  80   /* make sure we have a URI */
  81   if (argc != 2) {
  82     g_print ("Usage: %s &lt;URI&gt;\n", argv[0]);
  83    return -1;
  84   }
  85
  86   /* set up */
  87   play = gst_element_factory_make ("playbin", "play);
  88   g_object_set (G_OBJECT (play), "uri", argv[1], NULL);
  89   g_signal_connect (play, "eos", G_CALLBACK (cb_eos), NULL);
  90   g_signal_connect (play, "error", G_CALLBACK (cb_error), NULL);
  91   if (gst_element_set_state (play, GST_STATE_PLAYING) != GST_STATE_SUCCESS) {
  92     g_print ("Failed to play\n");
  93     return -1;
  94   }
  95
  96   /* now run */
  97   gst_main ();
  98
  99   /* also clean up */
 100   gst_element_set_state (play, GST_STATE_NULL);
 101   gst_object_unref (GST_OBJECT (play));
 102
 103   return 0;
 104 }
 105     </programlisting>
 106
 107     <para>
 108       Playbin has several features that have been discussed previously:
 109     </para>
 110     <itemizedlist>
 111       <listitem>
 112         <para>
 113           Settable video and audio output (using the <quote>video-sink</quote>
 114           and <quote>audio-sink</quote> properties).
 115         </para>
 116       </listitem>
 117       <listitem>
 118         <para>
 119           Mostly controllable and trackable as a
 120           <classname>GstElement</classname>, including error handling, eos
 121           handling, tag handling, state handling, media position handling and
 122           seeking.
 123         </para>
 124       </listitem>
 125       <listitem>
 126         <para>
 127           Buffers network-sources.
 128         </para>
 129       </listitem>
 130       <listitem>
 131         <para>
 132           Supports visualizations for audio-only media.
 133         </para>
 134       </listitem>
 135     </itemizedlist>
 136   </sect1>
 137
 138   <sect1 id="section-components-decodebin">
 139     <title>Decodebin</title>
 140
 141     <para>
 142       Decodebin is the actual autoplugger backend of playbin, which was
 143       discussed in the previous section. Decodebin will, in short, accept
 144       input from a source that is linked to its sinkpad and will try to
 145       detect the media type contained in the stream, and set up decoder
 146       routines for each of those. It will automatically select decoders.
 147       For each decoded stream, it will emit the <quote>new-decoded-pad</quote>
 148       signal, to let the client know about the newly found decoded stream.
 149       For unknown streams (which might be the whole stream), it will emit
 150       the <quote>unknown-type</quote> signal. The application is then
 151       responsible for reporting the error to the user.
 152     </para>
 153
 154     <para>
 155       The example code below will play back an audio stream of an input
 156       file. For readability, it does not include any error handling of
 157       any sort.
 158     </para>
 159
 160     <programlisting>
 161 #include &lt;gst/gst.h&gt;
 162
 163 GstElement *pipeline, *audio;
 164 GstPad *audiopad;
 165
 166 static void
 167 cb_newpad (GstElement *decodebin,
 168            GstPad     *pad,
 169            gboolean    last,
 170            gpointer    data)
 171 {
 172   GstCaps *caps;
 173   GstStructure *str;
 174
 175   /* only link audio; only link once */
 176   if (GST_PAD_IS_LINKED (audiopad))
 177     return;
 178   caps = gst_pad_get_caps (pad);
 179   str = gst_caps_get_structure (caps, 0);
 180   if (!strstr (gst_structure_get_name (str), "audio"))
 181     return;
 182
 183   /* link'n'play */
 184   gst_pad_link (pad, audiopad);
 185   gst_bin_add (GST_BIN (pipeline), audio);
 186   gst_bin_sync_children_state (GST_BIN (pipeline));
 187 }
 188
 189 gint
 190 main (gint   argc,
 191       gchar *argv[])
 192 {
 193   GstElement *src, *dec, *conv, *scale, *sink;
 194
 195   /* init GStreamer */
 196   gst_init (&amp;argc, &amp;argv);
 197
 198   /* make sure we have input */
 199   if (argc != 2) {
 200     g_print ("Usage: %s &lt;filename&gt;\n", argv[0]);
 201     return -1;
 202   }
 203
 204   /* setup */
 205   pipeline = gst_pipeline_new ("pipeline");
 206   src = gst_element_factory_make ("filesrc", "source");
 207   g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
 208   dec = gst_element_factory_make ("decodebin", "decoder");
 209   g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL);
 210   audio = gst_bin_new ("audiobin");
 211   conv = gst_element_factory_make ("audioconvert", "aconv");
 212   audiopad = gst_element_get_pad (conv, "sink");
 213   scale = gst_element_factory_make ("audioscale", "scale");
 214   sink = gst_element_factory_make ("alsasink", "sink");
 215   gst_bin_add_many (GST_BIN (audio), conv, scale, sink, NULL);
 216   gst_element_link_many (conv, scale, sink);
 217   gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL);
 218   gst_element_link (src, dec);
 219
 220   /* run */
 221   gst_element_set_state (audio, GST_STATE_PAUSED);
 222   gst_element_set_state (pipeline, GST_STATE_PLAYING);
 223   while (gst_bin_iterate (GST_BIN (pipeline))) ;
 224
 225   /* cleanup */
 226   gst_element_set_state (pipeline, GST_STATE_NULL);
 227   gst_object_unref (GST_OBJECT (pipeline));
 228
 229   return 0;
 230 }
 231     </programlisting>
 232
 233     <para>
 234       Although decodebin is a good autoplugger, there's a whole lot of
 235       things that it does not do and is not intended to do:
 236     </para>
 237     <itemizedlist>
 238       <listitem>
 239         <para>
 240           Taking care of input streams with a known media type (e.g. a DVD,
 241           an audio-CD or such).
 242         </para>
 243       </listitem>
 244       <listitem>
 245         <para>
 246           Selection of streams (e.g. which audio track to play in case of
 247           multi-language media streams).
 248         </para>
 249       </listitem>
 250       <listitem>
 251         <para>
 252           Overlaying subtitles over a decoded video stream.
 253         </para>
 254       </listitem>
 255     </itemizedlist>
 256   </sect1>
 257
 258   <sect1 id="section-components-spider">
 259     <title>Spider</title>
 260
 261     <para>
 262       Bla
 263     </para>
 264   </sect1>
 265
 266   <sect1 id="section-components-gst-play">
 267     <title>GstPlay</title>
 268     <para>
 269       GstPlay is a GtkWidget with a simple API to play, pause and stop a media file.
 270     </para>
 271
 272   </sect1>
 273
 274   <sect1 id="section-components-gst-editor">
 275     <title>GstEditor</title>
 276     <para>
 277       GstEditor is a set of widgets to display a graphical representation of a
 278       pipeline.
 279     </para>
 280   </sect1>
 281
 282 </chapter>