mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-10-22 02:13:46 +00:00
d0bcc34dad
Original commit message from CVS: * docs/manual/advanced-autoplugging.xml: * docs/manual/advanced-clocks.xml: * docs/manual/advanced-interfaces.xml: * docs/manual/advanced-metadata.xml: * docs/manual/advanced-position.xml: * docs/manual/advanced-schedulers.xml: * docs/manual/advanced-threads.xml: * docs/manual/appendix-gnome.xml: * docs/manual/appendix-programs.xml: * docs/manual/appendix-quotes.xml: * docs/manual/autoplugging.xml: * docs/manual/basics-bins.xml: * docs/manual/basics-data.xml: * docs/manual/basics-elements.xml: * docs/manual/basics-helloworld.xml: * docs/manual/basics-init.xml: * docs/manual/basics-pads.xml: * docs/manual/basics-plugins.xml: * docs/manual/bins-api.xml: * docs/manual/bins.xml: * docs/manual/buffers-api.xml: * docs/manual/buffers.xml: * docs/manual/clocks.xml: * docs/manual/components.xml: * docs/manual/cothreads.xml: * docs/manual/debugging.xml: * docs/manual/dparams-app.xml: * docs/manual/dynamic.xml: * docs/manual/elements-api.xml: * docs/manual/elements.xml: * docs/manual/factories.xml: * docs/manual/gnome.xml: * docs/manual/goals.xml: * docs/manual/helloworld.xml: * docs/manual/helloworld2.xml: * docs/manual/highlevel-components.xml: * docs/manual/highlevel-xml.xml: * docs/manual/init-api.xml: * docs/manual/intro-basics.xml: * docs/manual/intro-motivation.xml: * docs/manual/intro-preface.xml: * docs/manual/intro.xml: * docs/manual/links-api.xml: * docs/manual/links.xml: * docs/manual/manual.xml: * docs/manual/motivation.xml: * docs/manual/pads-api.xml: * docs/manual/pads.xml: * docs/manual/plugins-api.xml: * docs/manual/plugins.xml: * docs/manual/programs.xml: * docs/manual/queues.xml: * docs/manual/quotes.xml: * docs/manual/schedulers.xml: * docs/manual/states-api.xml: * docs/manual/states.xml: * docs/manual/threads.xml: * docs/manual/typedetection.xml: * docs/manual/win32.xml: * docs/manual/xml.xml: Try 2. This time, include a short preface as a "general introduction", also add code blocks around all code samples so they get compiled. We still need a way to tell readers the filename of the code sample. In some cases, don't show all code in the documentation, but do include it in the generated code. This allows for focussing on specific bits in the docs, while still having a full test application available. * examples/manual/Makefile.am: Fix up examples for new ADM. Add several of the new examples that were either added or were missing from the build system. * examples/manual/extract.pl: Allow nameless blocks.
282 lines
8.5 KiB
XML
282 lines
8.5 KiB
XML
<chapter id="chapter-components">
|
|
<title>Components</title>
|
|
|
|
<para>
|
|
&GStreamer; includes several higher-level components to simplify your
|
|
applications life. All of the components discussed here (for now) are
|
|
targetted at media playback. The idea of each of these components is
|
|
to integrate as closely as possible with a &GStreamer; pipeline, but
|
|
to hide the complexity of media type detection and several other
|
|
rather complex topics that have been discussed in <xref
|
|
linkend="part-advanced"/>.
|
|
</para>
|
|
|
|
<para>
|
|
We currently recommend people to use either playbin (see <xref
|
|
linkend="section-components-playbin"/>) or decodebin (see <xref
|
|
linkend="section-components-decodebin"/>), depending on their needs. The
|
|
other components discussed here are either outdated or deprecated. The
|
|
documentation is provided for legacy purposes. Use of those other
|
|
components is not recommended.
|
|
</para>
|
|
|
|
<sect1 id="section-components-playbin">
|
|
<title>Playbin</title>
|
|
|
|
<para>
|
|
Playbin is an element that can be created using the standard &GStreamer;
|
|
API (e.g. <function>gst_element_factory_make ()</function>). The factory
|
|
is conveniently called <quote>playbin</quote>. By being a
|
|
<classname>GstElement</classname>, playbin automatically supports all
|
|
of the features of this class, including error handling, tag support,
|
|
state handling, getting stream positions, seeking, and so on.
|
|
</para>
|
|
|
|
<para>
|
|
Setting up a playbin pipeline is as simple as creating an instance of
|
|
the playbin element, setting a file location (this has to be a valid
|
|
URI, so <quote><protocol>://<location></quote>, e.g.
|
|
file:///tmp/my.ogg or http://www.example.org/stream.ogg) using the
|
|
<quote>uri</quote> property on playbin, and then setting the element
|
|
to the <classname>GST_STATE_PLAYING</classname> state. Internally,
|
|
playbin uses threads, so there's no need to iterate the element or
|
|
anything. However, one thing to keep in mind is that signals fired
|
|
by playbin might come from another than the main thread, so be sure
|
|
to keep this in mind in your signal handles. Most application
|
|
programmers will want to use a function such as <function>g_idle_add
|
|
()</function> to make sure that the signal is handled in the main
|
|
thread.
|
|
</para>
|
|
|
|
<programlisting><!-- example-begin playbin.c -->
|
|
#include <gst/gst.h>
|
|
|
|
static void
|
|
cb_eos (GstElement *play,
|
|
gpointer data)
|
|
{
|
|
gst_main_quit ();
|
|
}
|
|
|
|
static void
|
|
cb_error (GstElement *play,
|
|
GstElement *src,
|
|
GError *err,
|
|
gchar *debug,
|
|
gpointer data)
|
|
{
|
|
g_print ("Error: %s\n", err->message);
|
|
}
|
|
|
|
gint
|
|
main (gint argc,
|
|
gchar *argv[])
|
|
{
|
|
GstElement *play;
|
|
|
|
/* init GStreamer */
|
|
gst_init (&argc, &argv);
|
|
|
|
/* make sure we have a URI */
|
|
if (argc != 2) {
|
|
g_print ("Usage: %s <URI>\n", argv[0]);
|
|
return -1;
|
|
}
|
|
|
|
/* set up */
|
|
play = gst_element_factory_make ("playbin", "play");
|
|
g_object_set (G_OBJECT (play), "uri", argv[1], NULL);
|
|
g_signal_connect (play, "eos", G_CALLBACK (cb_eos), NULL);
|
|
g_signal_connect (play, "error", G_CALLBACK (cb_error), NULL);
|
|
if (gst_element_set_state (play, GST_STATE_PLAYING) != GST_STATE_SUCCESS) {
|
|
g_print ("Failed to play\n");
|
|
return -1;
|
|
}
|
|
|
|
/* now run */
|
|
gst_main ();
|
|
|
|
/* also clean up */
|
|
gst_element_set_state (play, GST_STATE_NULL);
|
|
gst_object_unref (GST_OBJECT (play));
|
|
|
|
return 0;
|
|
}
|
|
<!-- example-end playbin.c --></programlisting>
|
|
|
|
<para>
|
|
Playbin has several features that have been discussed previously:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Settable video and audio output (using the <quote>video-sink</quote>
|
|
and <quote>audio-sink</quote> properties).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Mostly controllable and trackable as a
|
|
<classname>GstElement</classname>, including error handling, eos
|
|
handling, tag handling, state handling, media position handling and
|
|
seeking.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Buffers network-sources.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Supports visualizations for audio-only media.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="section-components-decodebin">
|
|
<title>Decodebin</title>
|
|
|
|
<para>
|
|
Decodebin is the actual autoplugger backend of playbin, which was
|
|
discussed in the previous section. Decodebin will, in short, accept
|
|
input from a source that is linked to its sinkpad and will try to
|
|
detect the media type contained in the stream, and set up decoder
|
|
routines for each of those. It will automatically select decoders.
|
|
For each decoded stream, it will emit the <quote>new-decoded-pad</quote>
|
|
signal, to let the client know about the newly found decoded stream.
|
|
For unknown streams (which might be the whole stream), it will emit
|
|
the <quote>unknown-type</quote> signal. The application is then
|
|
responsible for reporting the error to the user.
|
|
</para>
|
|
|
|
<para>
|
|
The example code below will play back an audio stream of an input
|
|
file. For readability, it does not include any error handling of
|
|
any sort.
|
|
</para>
|
|
|
|
<programlisting><!-- example-begin decodebin.c -->
|
|
#include <gst/gst.h>
|
|
|
|
GstElement *pipeline, *audio;
|
|
GstPad *audiopad;
|
|
|
|
static void
|
|
cb_newpad (GstElement *decodebin,
|
|
GstPad *pad,
|
|
gboolean last,
|
|
gpointer data)
|
|
{
|
|
GstCaps *caps;
|
|
GstStructure *str;
|
|
|
|
/* only link audio; only link once */
|
|
if (GST_PAD_IS_LINKED (audiopad))
|
|
return;
|
|
caps = gst_pad_get_caps (pad);
|
|
str = gst_caps_get_structure (caps, 0);
|
|
if (!g_strrstr (gst_structure_get_name (str), "audio"))
|
|
return;
|
|
|
|
/* link'n'play */
|
|
gst_pad_link (pad, audiopad);
|
|
gst_bin_add (GST_BIN (pipeline), audio);
|
|
gst_bin_sync_children_state (GST_BIN (pipeline));
|
|
}
|
|
|
|
gint
|
|
main (gint argc,
|
|
gchar *argv[])
|
|
{
|
|
GstElement *src, *dec, *conv, *scale, *sink;
|
|
|
|
/* init GStreamer */
|
|
gst_init (&argc, &argv);
|
|
|
|
/* make sure we have input */
|
|
if (argc != 2) {
|
|
g_print ("Usage: %s <filename>\n", argv[0]);
|
|
return -1;
|
|
}
|
|
|
|
/* setup */
|
|
pipeline = gst_pipeline_new ("pipeline");
|
|
src = gst_element_factory_make ("filesrc", "source");
|
|
g_object_set (G_OBJECT (src), "location", argv[1], NULL);
|
|
dec = gst_element_factory_make ("decodebin", "decoder");
|
|
g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL);
|
|
audio = gst_bin_new ("audiobin");
|
|
conv = gst_element_factory_make ("audioconvert", "aconv");
|
|
audiopad = gst_element_get_pad (conv, "sink");
|
|
scale = gst_element_factory_make ("audioscale", "scale");
|
|
sink = gst_element_factory_make ("alsasink", "sink");
|
|
gst_bin_add_many (GST_BIN (audio), conv, scale, sink, NULL);
|
|
gst_element_link_many (conv, scale, sink, NULL);
|
|
gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL);
|
|
gst_element_link (src, dec);
|
|
|
|
/* run */
|
|
gst_element_set_state (audio, GST_STATE_PAUSED);
|
|
gst_element_set_state (pipeline, GST_STATE_PLAYING);
|
|
while (gst_bin_iterate (GST_BIN (pipeline))) ;
|
|
|
|
/* cleanup */
|
|
gst_element_set_state (pipeline, GST_STATE_NULL);
|
|
gst_object_unref (GST_OBJECT (pipeline));
|
|
|
|
return 0;
|
|
}
|
|
<!-- example-end decodebin.c --></programlisting>
|
|
|
|
<para>
|
|
Although decodebin is a good autoplugger, there's a whole lot of
|
|
things that it does not do and is not intended to do:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Taking care of input streams with a known media type (e.g. a DVD,
|
|
an audio-CD or such).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Selection of streams (e.g. which audio track to play in case of
|
|
multi-language media streams).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Overlaying subtitles over a decoded video stream.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
|
|
<sect1 id="section-components-spider">
|
|
<title>Spider</title>
|
|
|
|
<para>
|
|
Bla
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="section-components-gst-play">
|
|
<title>GstPlay</title>
|
|
<para>
|
|
GstPlay is a GtkWidget with a simple API to play, pause and stop a media file.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="section-components-gst-editor">
|
|
<title>GstEditor</title>
|
|
<para>
|
|
GstEditor is a set of widgets to display a graphical representation of a
|
|
pipeline.
|
|
</para>
|
|
</sect1>
|
|
|
|
</chapter>
|