mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-24 17:20:36 +00:00
626cbdc8b2
Original commit message from CVS: cleanup of unused and forgoten sections fixed links from the manual and the pwg to the API docs added more notes to README
198 lines
7.4 KiB
XML
198 lines
7.4 KiB
XML
<chapter id="chapter-autoplug">
|
|
<title>Autoplugging</title>
|
|
<para>
|
|
<application>GStreamer</application> provides an API to automatically
|
|
construct complex pipelines based on source and destination capabilities.
|
|
This feature is very useful 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 link 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
|
|
source 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_autoplug_factory_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_autoplug_factory_get_list().
|
|
</para>
|
|
<para>
|
|
If the autoplugger supports the RENDERER API, use the
|
|
gst_autoplug_to_renderers() function to create a bin that links
|
|
the source 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_autoplug_factory_make ("staticrender");
|
|
|
|
/* create an osssink */
|
|
sink = gst_element_factory_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 link the sink pad */
|
|
...
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
If the autoplugger supports the CAPS API, use the gst_autoplug_to_caps()
|
|
function to link the source caps to the destination caps. The created
|
|
bin will have source and sink pads compatible with the provided caps.
|
|
|
|
<programlisting>
|
|
|
|
GstAutoplug *autoplug;
|
|
GstElement *element;
|
|
|
|
/* create a static autoplugger */
|
|
autoplug = gst_autoplug_factory_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 link the src/sink pads */
|
|
...
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="section-autoplug-cache">
|
|
<!-- FIXME: this is outdated, there is no GstAutoplugCache in gst-0.8.X -->
|
|
<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 seen in
|
|
<xref linkend="chapter-typedetection"/>, the typefind function consumes a
|
|
buffer to determine its media type. After we have set up the pipeline
|
|
to play the media stream we should be able to 'replay' the previous buffer(s).
|
|
This is what 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 link the sink pad
|
|
to the source pad of an element with unknown caps.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Link the source pad of the autoplugcache to the sink pad of
|
|
the typefind element.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Iterate 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 source 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
|
|
relink the pads.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<para>
|
|
In the next chapter we will create a new version of our helloworld example using the
|
|
autoplugger, the autoplugcache and the typefind element.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="section-autoplugging-spider">
|
|
<title>Another approach to autoplugging</title>
|
|
<para>
|
|
The autoplug API is interesting, but often impractical. It is static;
|
|
it cannot deal with dynamic pipelines. An element that will
|
|
automatically figure out and decode the type is more useful.
|
|
Enter the spider.
|
|
</para>
|
|
<sect2>
|
|
<title>The spider element</title>
|
|
<para>
|
|
The spider element is a generalized autoplugging element. At this point (April 2002), it's
|
|
the best we've got; it can be inserted anywhere within a pipeline to perform caps
|
|
conversion, if possible. Consider the following gst-launch line:
|
|
<programlisting>
|
|
$ gst-launch filesrc location=my.mp3 ! spider ! osssink
|
|
</programlisting>
|
|
The spider will detect the type of the stream, autoplug it to the osssink's caps, and play
|
|
the pipeline. It's neat.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Spider features</title>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Automatically typefinds the incoming stream.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Has request pads on the source side. This means that it can
|
|
autoplug one source stream into many sink streams. For example,
|
|
an MPEG1 system stream can have audio as well as video; that
|
|
pipeline would be represented in gst-launch syntax as
|
|
|
|
<programlisting>
|
|
$ gst-launch filesrc location=my.mpeg1 ! spider ! { queue ! osssink } spider.src_%d!
|
|
{ queue ! xvideosink }
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|