gstreamer/docs/manual/autoplugging.sgml

<chapter id="cha-autoplug">
  <title>Autoplugging</title>
  <para> 
    <application>GStreamer</application> provides an API to automatically
    construct complex pipelinebased on source and destination capabilities.
    This feature is very usefull if you want to convert type X to type Y but
    don't care about the plugins needed to accomplish this task. The 
    autoplugger will consult the plugin repository, select and connect the
    elements needed for the conversion.
  </para>
  <para> 
    The autoplugger API is implemented in an abstract class. Autoplugger implementations
    reside in plugins and are therefore optional and can be optimized for a specific
    task.  Two types of autopluggers exist: renderer ones and non
    renderer ones. the renderer autopluggers will not have any src pads while the
    non renderer ones do. The renderer autopluggers are mainly used for media
    playback while the non renderer ones are used for arbitrary format conversion.
  </para>

  <sect1>
    <title>Using autoplugging</title>
    <para> 
      You first need to create a suitable autoplugger with gst_autoplugfactory_make().
      The name of the autoplugger must be one of the registered autopluggers..
    </para>
    <para>
      A list of all available autopluggers can be obtained with gst_autoplugfactory_get_list().
    </para>
    <para>
      If the autoplugger supports the RENDERER API, use gst_autoplug_to_renderers() call to
      create a bin that connects the src caps to the specified render elements. You can
      then add the bin to a pipeline and run it.

      <programlisting>

        GstAutoplug *autoplug;
	GstElement  *element;
	GstElement  *sink;

	/* create a static autoplugger */
	autoplug = gst_autoplugfactory_make ("staticrender");

	/* create an osssink */
	sink = gst_elementfactory_make ("osssink", "our_sink");

	/* create an element that can play audio/mp3 through osssink */
	element = gst_autoplug_to_renderers (autoplug,
	                                     gst_caps_new (
	                                       "sink_audio_caps",
	                                       "audio/mp3",
	                                       NULL
	                                     ),
	                                     sink,
	                                     NULL);

	/* add the element to a bin and connect the sink pad */
	...
      </programlisting>
    </para>
    <para>
      If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps() function to
      connect the src caps to the destination caps. The created bin will have src and sink
      pads compatible with the provided caps.

      <programlisting>

        GstAutoplug *autoplug;
	GstElement  *element;

	/* create a static autoplugger */
	autoplug = gst_autoplugfactory_make ("static");

	/* create an element that converts audio/mp3 to audio/raw */
	element = gst_autoplug_to_caps (autoplug,
	                                gst_caps_new (
	                                  "sink_audio_caps",
	                                  "audio/mp3",
	                                  NULL
	                                ),
	                                gst_caps_new (
	                                  "src_audio_caps",
	                                  "audio/raw",
	                                  NULL
	                                ),
	                                NULL);

	/* add the element to a bin and connect the src/sink pads */
	...
      </programlisting>
    </para>
  </sect1>
  <sect1>
    <title>Using the <classname>GstAutoplugCache</classname> element</title>
    <para>
      The <classname>GstAutoplugCache</classname> element is used to cache the 
      media stream when performing typedetection. As we have have seen in the
      previous chapter (typedetection), the type typefind function consumes a 
      buffer to determine the media type of it. After we have set up the pipeline
      to play the media stream we should be able to 'replay' the previous buffer(s).
      This is where the autoplugcache is used for.
    </para>
    <para>
      The basic usage pattern for the autoplugcache in combination with the typefind 
      element is like this:
      <orderedlist>
        <listitem>
          <para>
	    Add the autoplugcache element to a bin and connect the sink pad to the src
	    pad of an element with unkown caps.
          </para>
        </listitem>
        <listitem>
          <para>
	    Connect the src pad of the autoplugcache to the sink pad of the typefind 
	    element.
          </para>
        </listitem>
        <listitem>
          <para>
	    Loop the pipeline until the typefind element has found a type. 
          </para>
        </listitem>
        <listitem>
          <para>
	    Remove the typefind element and add the plugins needed to play back the discovered
	    media type to the autoplugcache src pad.
          </para>
        </listitem>
        <listitem>
          <para>
	    Reset the cache to start playback of the cached data. Connect to the 
	    "cache_empty" signal.
          </para>
        </listitem>
        <listitem>
          <para>
	    In the cache_empty signal callback function, remove the autoplugcache and
	    reconnect the pads.
          </para>
        </listitem>
      </orderedlist>
    </para>
    <para>
      In the next chapter we will create a new version of our helloworld exaple using the
      autoplugger, the autoplugcache and the typefind element.
    </para>
  </sect1>
</chapter>