1 <chapter id="chapter-components">
2 <title>Components</title>
5 &GStreamer; includes several higher-level components to simplify an
6 application developer's 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"/>.
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.
18 Playbin is the recommended solution for everything related to simple
19 playback of media that should just work. Decodebin is a more flexible
20 autoplugger that could be used to add more advanced features, such
21 as playlist support, crossfading of audio tracks and so on. Its
22 programming interface is more low-level than that of playbin, though.
25 <sect1 id="section-components-playbin">
26 <title>Playbin</title>
29 Playbin is an element that can be created using the standard &GStreamer;
30 API (e.g. <function>gst_element_factory_make ()</function>). The factory
31 is conveniently called <quote>playbin</quote>. By being a
32 <classname>GstPipeline</classname> (and thus a
33 <classname>GstElement</classname>), playbin automatically supports all
34 of the features of this class, including error handling, tag support,
35 state handling, getting stream positions, seeking, and so on.
39 Setting up a playbin pipeline is as simple as creating an instance of
40 the playbin element, setting a file location using the
41 <quote>uri</quote> property on playbin, and then setting the element
42 to the <classname>GST_STATE_PLAYING</classname> state (the location has to be a valid
43 URI, so <quote><protocol>://<location></quote>, e.g.
44 file:///tmp/my.ogg or http://www.example.org/stream.ogg). Internally,
45 playbin will set up a pipeline to playback the media location.
48 <programlisting><!-- example-begin playbin.c a -->
49 #include <gst/gst.h>
50 <!-- example-end playbin.c a -->
51 [.. my_bus_callback goes here ..]<!-- example-begin playbin.c b --><!--
53 my_bus_callback (GstBus *bus,
57 GMainLoop *loop = data;
59 switch (GST_MESSAGE_TYPE (message)) {
60 case GST_MESSAGE_ERROR: {
64 gst_message_parse_error (message, &err, &debug);
65 g_print ("Error: %s\n", err->message);
69 g_main_loop_quit (loop);
74 g_main_loop_quit (loop);
77 /* unhandled message */
81 /* remove message from the queue */
84 --><!-- example-end playbin.c b -->
85 <!-- example-begin playbin.c c -->
95 gst_init (&argc, &argv);
96 loop = g_main_loop_new (NULL, FALSE);
98 /* make sure we have a URI */
100 g_print ("Usage: %s <URI>\n", argv[0]);
105 play = gst_element_factory_make ("playbin", "play");
106 g_object_set (G_OBJECT (play), "uri", argv[1], NULL);
108 bus = gst_pipeline_get_bus (GST_PIPELINE (play));
109 gst_bus_add_watch (bus, my_bus_callback, loop);
110 gst_object_unref (bus);
112 gst_element_set_state (play, GST_STATE_PLAYING);
115 g_main_loop_run (loop);
118 gst_element_set_state (play, GST_STATE_NULL);
119 gst_object_unref (GST_OBJECT (play));
123 <!-- example-end playbin.c c --></programlisting>
126 Playbin has several features that have been discussed previously:
131 Settable video and audio output (using the <quote>video-sink</quote>
132 and <quote>audio-sink</quote> properties).
137 Mostly controllable and trackable as a
138 <classname>GstElement</classname>, including error handling, eos
139 handling, tag handling, state handling (through the
140 <classname>GstBus</classname>), media position handling and
146 Buffers network-sources, with buffer fullness notifications being
147 passed through the <classname>GstBus</classname>.
152 Supports visualizations for audio-only media.
157 Supports subtitles, both in the media as well as from separate
158 files. For separate subtitle files, use the <quote>suburi</quote>
164 Supports stream selection and disabling. If your media has
165 multiple audio or subtitle tracks, you can dynamically choose
166 which one to play back, or decide to turn it off alltogther
167 (which is especially useful to turn off subtitles). For each
168 of those, use the <quote>current-text</quote> and other related
174 For convenience, it is possible to test <quote>playbin</quote> on
175 the commandline, using the command <quote>gst-launch-0.10 playbin
176 uri=file:///path/to/file</quote>.
179 New applications should use playbin2 instead of the old playbin.
183 <sect1 id="section-components-decodebin">
184 <title>Decodebin</title>
187 Decodebin is the actual autoplugger backend of playbin, which was
188 discussed in the previous section. Decodebin will, in short, accept
189 input from a source that is linked to its sinkpad and will try to
190 detect the media type contained in the stream, and set up decoder
191 routines for each of those. It will automatically select decoders.
192 For each decoded stream, it will emit the <quote>new-decoded-pad</quote>
193 signal, to let the client know about the newly found decoded stream.
194 For unknown streams (which might be the whole stream), it will emit
195 the <quote>unknown-type</quote> signal. The application is then
196 responsible for reporting the error to the user.
198 <programlisting><!-- example-begin decodebin.c a -->
199 #include <gst/gst.h>
200 <!-- example-end decodebin.c a -->
201 [.. my_bus_callback goes here ..]<!-- example-begin decodebin.c b --><!--
203 my_bus_callback (GstBus *bus,
207 GMainLoop *loop = data;
209 switch (GST_MESSAGE_TYPE (message)) {
210 case GST_MESSAGE_ERROR: {
214 gst_message_parse_error (message, &err, &debug);
215 g_print ("Error: %s\n", err->message);
219 g_main_loop_quit (loop);
222 case GST_MESSAGE_EOS:
224 g_main_loop_quit (loop);
227 /* unhandled message */
231 /* remove message from the queue */
234 --><!-- example-end decodebin.c b -->
235 <!-- example-begin decodebin.c c -->
236 GstElement *pipeline, *audio;
239 cb_newpad (GstElement *decodebin,
249 audiopad = gst_element_get_static_pad (audio, "sink");
250 if (GST_PAD_IS_LINKED (audiopad)) {
251 g_object_unref (audiopad);
255 /* check media type */
256 caps = gst_pad_get_caps (pad);
257 str = gst_caps_get_structure (caps, 0);
258 if (!g_strrstr (gst_structure_get_name (str), "audio")) {
259 gst_caps_unref (caps);
260 gst_object_unref (audiopad);
263 gst_caps_unref (caps);
266 gst_pad_link (pad, audiopad);
268 g_object_unref (audiopad);
276 GstElement *src, *dec, *conv, *sink;
281 gst_init (&argc, &argv);
282 loop = g_main_loop_new (NULL, FALSE);
284 /* make sure we have input */
286 g_print ("Usage: %s <filename>\n", argv[0]);
291 pipeline = gst_pipeline_new ("pipeline");
293 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
294 gst_bus_add_watch (bus, my_bus_callback, loop);
295 gst_object_unref (bus);
297 src = gst_element_factory_make ("filesrc", "source");
298 g_object_set (G_OBJECT (src), "location", argv[1], NULL);
299 dec = gst_element_factory_make ("decodebin", "decoder");
300 g_signal_connect (dec, "new-decoded-pad", G_CALLBACK (cb_newpad), NULL);
301 gst_bin_add_many (GST_BIN (pipeline), src, dec, NULL);
302 gst_element_link (src, dec);
304 /* create audio output */
305 audio = gst_bin_new ("audiobin");
306 conv = gst_element_factory_make ("audioconvert", "aconv");
307 audiopad = gst_element_get_static_pad (conv, "sink");
308 sink = gst_element_factory_make ("alsasink", "sink");
309 gst_bin_add_many (GST_BIN (audio), conv, sink, NULL);
310 gst_element_link (conv, sink);
311 gst_element_add_pad (audio,
312 gst_ghost_pad_new ("sink", audiopad));
313 gst_object_unref (audiopad);
314 gst_bin_add (GST_BIN (pipeline), audio);
317 gst_element_set_state (pipeline, GST_STATE_PLAYING);
318 g_main_loop_run (loop);
321 gst_element_set_state (pipeline, GST_STATE_NULL);
322 gst_object_unref (GST_OBJECT (pipeline));
326 <!-- example-end decodebin.c c --></programlisting>
329 Decodebin, similar to playbin, supports the following features:
334 Can decode an unlimited number of contained streams to decoded
340 Is handled as a <classname>GstElement</classname> in all ways,
341 including tag or error forwarding and state handling.
346 Although decodebin is a good autoplugger, there's a whole lot of
347 things that it does not do and is not intended to do:
352 Taking care of input streams with a known media type (e.g. a DVD,
353 an audio-CD or such).
358 Selection of streams (e.g. which audio track to play in case of
359 multi-language media streams).
364 Overlaying subtitles over a decoded video stream.
369 Decodebin can be easily tested on the commandline, e.g. by using the
370 command <command>gst-launch-0.10 filesrc location=file.ogg ! decodebin
371 ! audioconvert ! audioresample ! autoaudiosink</command>.
374 New applications should use decodebin2 instead of the old decodebin.
377 The uridecodebin element is very similar to decodebin2, only that it
378 automatically plugs a source plugin based on the protocol of the URI