docs/manual/autoplugging.xml

   1 <chapter id="cha-autoplug">
   2   <title>Autoplugging</title>
   3   <para>
   4     <application>GStreamer</application> provides an API to automatically
   5     construct complex pipelines based on source and destination capabilities.
   6     This feature is very useful if you want to convert type X to type Y but
   7     don't care about the plugins needed to accomplish this task. The
   8     autoplugger will consult the plugin repository, select and link the
   9     elements needed for the conversion.
  10   </para>
  11   <para>
  12     The autoplugger API is implemented in an abstract class. Autoplugger
  13     implementations reside in plugins and are therefore optional and can be
  14     optimized for a specific task.  Two types of autopluggers exist: renderer
  15     ones and non-renderer ones. The renderer autopluggers will not have any
  16     source pads while the non-renderer ones do. The renderer autopluggers are
  17     mainly used for media playback while the non renderer ones are used for
  18     arbitrary format conversion.
  19   </para>
  20
  21   <sect1>
  22     <title>Using autoplugging</title>
  23     <para>
  24       You first need to create a suitable autoplugger with gst_autoplug_factory_make().
  25       The name of the autoplugger must be one of the registered autopluggers..
  26     </para>
  27     <para>
  28       A list of all available autopluggers can be obtained with gst_autoplug_factory_get_list().
  29     </para>
  30     <para>
  31       If the autoplugger supports the RENDERER API, use the
  32       gst_autoplug_to_renderers() function to create a bin that links
  33       the source caps to the specified render elements. You can then add
  34       the bin to a pipeline and run it.
  35
  36       <programlisting>
  37
  38         GstAutoplug *autoplug;
  39         GstElement  *element;
  40         GstElement  *sink;
  41
  42         /* create a static autoplugger */
  43         autoplug = gst_autoplug_factory_make ("staticrender");
  44
  45         /* create an osssink */
  46         sink = gst_element_factory_make ("osssink", "our_sink");
  47
  48         /* create an element that can play audio/mp3 through osssink */
  49         element = gst_autoplug_to_renderers (autoplug,
  50                                              gst_caps_new (
  51                                                "sink_audio_caps",
  52                                                "audio/mp3",
  53                                                NULL
  54                                              ),
  55                                              sink,
  56                                              NULL);
  57
  58         /* add the element to a bin and link the sink pad */
  59         ...
  60       </programlisting>
  61     </para>
  62     <para>
  63       If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps()
  64       function to link the source caps to the destination caps. The created
  65       bin will have source and sink pads compatible with the provided caps.
  66
  67       <programlisting>
  68
  69         GstAutoplug *autoplug;
  70         GstElement  *element;
  71
  72         /* create a static autoplugger */
  73         autoplug = gst_autoplug_factory_make ("static");
  74
  75         /* create an element that converts audio/mp3 to audio/raw */
  76         element = gst_autoplug_to_caps (autoplug,
  77                                         gst_caps_new (
  78                                           "sink_audio_caps",
  79                                           "audio/mp3",
  80                                           NULL
  81                                         ),
  82                                         gst_caps_new (
  83                                           "src_audio_caps",
  84                                           "audio/raw",
  85                                           NULL
  86                                         ),
  87                                         NULL);
  88
  89         /* add the element to a bin and link the src/sink pads */
  90         ...
  91       </programlisting>
  92     </para>
  93   </sect1>
  94   <sect1>
  95     <title>Using the <classname>GstAutoplugCache</classname> element</title>
  96     <para>
  97       The <classname>GstAutoplugCache</classname> element is used to cache the
  98       media stream when performing typedetection. As we have have seen in the
  99       previous chapter (typedetection), the type typefind function consumes a
 100       buffer to determine the media type of it. After we have set up the pipeline
 101       to play the media stream we should be able to 'replay' the previous buffer(s).
 102       This is where the autoplugcache is used for.
 103     </para>
 104     <para>
 105       The basic usage pattern for the autoplugcache in combination with the typefind
 106       element is like this:
 107       <orderedlist>
 108         <listitem>
 109           <para>
 110             Add the autoplugcache element to a bin and link the sink pad
 111             to the source pad of an element with unknown caps.
 112           </para>
 113         </listitem>
 114         <listitem>
 115           <para>
 116             Link the source pad of the autoplugcache to the sink pad of
 117             the typefind element.
 118           </para>
 119         </listitem>
 120         <listitem>
 121           <para>
 122             Iterate the pipeline until the typefind element has found a type.
 123           </para>
 124         </listitem>
 125         <listitem>
 126           <para>
 127             Remove the typefind element and add the plugins needed to play
 128             back the discovered media type to the autoplugcache source pad.
 129           </para>
 130         </listitem>
 131         <listitem>
 132           <para>
 133             Reset the cache to start playback of the cached data. Connect to the
 134             "cache_empty" signal.
 135           </para>
 136         </listitem>
 137         <listitem>
 138           <para>
 139             In the cache_empty signal callback function, remove the autoplugcache and
 140             relink the pads.
 141           </para>
 142         </listitem>
 143       </orderedlist>
 144     </para>
 145     <para>
 146       In the next chapter we will create a new version of our helloworld example using the
 147       autoplugger, the autoplugcache and the typefind element.
 148     </para>
 149   </sect1>
 150   <sect1>
 151     <title>Another approach to autoplugging</title>
 152     <para>
 153       The autoplug API is interesting, but often impractical. It is static;
 154       it cannot deal with dynamic pipelines (insert ref here). What you
 155       often want is just an element to stick into a pipeline that will DWIM
 156       (Do What I Mean)(ref). Enter the spider.
 157     </para>
 158     <sect2>
 159       <title>The spider element</title>
 160       <para>
 161         The spider element is a generalized autoplugging element. At this point (April 2002), it's
 162         the best we've got; it can be inserted anywhere within a pipeline to perform caps
 163         conversion, if possible. Consider the following gst-launch line:
 164         <programlisting>
 165           $ gst-launch filesrc location=my.mp3 ! spider ! osssink
 166         </programlisting>
 167         The spider will detect the type of the stream, autoplug it to the osssink's caps, and play
 168         the pipeline. It's neat.
 169       </para>
 170     </sect2>
 171     <sect2>
 172       <title>Spider features</title>
 173       <para>
 174         <orderedlist>
 175           <listitem>
 176             <para>
 177               Automatically typefinds the incoming stream.
 178             </para>
 179           </listitem>
 180          <listitem>
 181             <para>
 182               Has request pads on the source side. This means that it can
 183               autoplug one source stream into many sink streams. For example,
 184               an MPEG1 system stream can have audio as well as video; that
 185               pipeline would be represented in gst-launch syntax as
 186
 187               <programlisting>
 188                 $ gst-launch filesrc location=my.mpeg1 ! spider ! { queue ! osssink } spider.src_%d!
 189                              { queue ! xvideosink }
 190               </programlisting>
 191             </para>
 192           </listitem>
 193         </orderedlist>
 194       </para>
 195     </sect2>
 196   </sect1>
 197 </chapter>