7 In [Your first application](manual-helloworld.md), you've learned to
8 build a simple media player for Ogg/Vorbis files. By using alternative
9 elements, you are able to build media players for other media types,
10 such as Ogg/Speex, MP3 or even video formats. However, you would rather
11 want to build an application that can automatically detect the media
12 type of a stream and automatically generate the best possible pipeline
13 by looking at all available elements in a system. This process is called
14 autoplugging, and GStreamer contains high-quality autopluggers. If
15 you're looking for an autoplugger, don't read any further and go to
16 [Playback Components](manual-playback-components.md). This chapter will
17 explain the *concept* of autoplugging and typefinding. It will explain
18 what systems GStreamer includes to dynamically detect the type of a
19 media stream, and how to generate a pipeline of decoder elements to
20 playback this media. The same principles can also be used for
21 transcoding. Because of the full dynamicity of this concept, GStreamer
22 can be automatically extended to support new media types without needing
23 any adaptations to its autopluggers.
25 We will first introduce the concept of Media types as a dynamic and
26 extendible way of identifying media streams. After that, we will
27 introduce the concept of typefinding to find the type of a media stream.
28 Lastly, we will explain how autoplugging and the GStreamer registry can
29 be used to setup a pipeline that will convert media from one mediatype
30 to another, for example for media decoding.
32 ## Media types as a way to identify streams
34 We have previously introduced the concept of capabilities as a way for
35 elements (or, rather, pads) to agree on a media type when streaming data
36 from one element to the next (see [Capabilities of a
37 pad](manual-pads.md#capabilities-of-a-pad)). We have explained that a
38 capability is a combination of a media type and a set of properties. For
39 most container formats (those are the files that you will find on your
40 hard disk; Ogg, for example, is a container format), no properties are
41 needed to describe the stream. Only a media type is needed. A full list
42 of media types and accompanying properties can be found in [the Plugin
44 Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/section-types-definitions.html).
46 An element must associate a media type to its source and sink pads when
47 it is loaded into the system. GStreamer knows about the different
48 elements and what type of data they expect and emit through the
49 GStreamer registry. This allows for very dynamic and extensible element
50 creation as we will see.
52 In [Your first application](manual-helloworld.md), we've learned to
53 build a music player for Ogg/Vorbis files. Let's look at the media types
54 associated with each pad in this pipeline. [The Hello world pipeline
55 with media types](#the-hello-world-pipeline-with-media-types) shows what
56 media type belongs to each pad in this pipeline.
58 ![The Hello world pipeline with media types](images/mime-world.png
61 Now that we have an idea how GStreamer identifies known media streams,
62 we can look at methods GStreamer uses to setup pipelines for media
63 handling and for media type detection.
65 ## Media stream type detection
67 Usually, when loading a media stream, the type of the stream is not
68 known. This means that before we can choose a pipeline to decode the
69 stream, we first need to detect the stream type. GStreamer uses the
70 concept of typefinding for this. Typefinding is a normal part of a
71 pipeline, it will read data for as long as the type of a stream is
72 unknown. During this period, it will provide data to all plugins that
73 implement a typefinder. When one of the typefinders recognizes the
74 stream, the typefind element will emit a signal and act as a passthrough
75 module from that point on. If no type was found, it will emit an error
76 and further media processing will stop.
78 Once the typefind element has found a type, the application can use this
79 to plug together a pipeline to decode the media stream. This will be
80 discussed in the next section.
82 Plugins in GStreamer can, as mentioned before, implement typefinder
83 functionality. A plugin implementing this functionality will submit a
84 media type, optionally a set of file extensions commonly used for this
85 media type, and a typefind function. Once this typefind function inside
86 the plugin is called, the plugin will see if the data in this media
87 stream matches a specific pattern that marks the media type identified
88 by that media type. If it does, it will notify the typefind element of
89 this fact, telling which mediatype was recognized and how certain we are
90 that this stream is indeed that mediatype. Once this run has been
91 completed for all plugins implementing a typefind functionality, the
92 typefind element will tell the application what kind of media stream it
93 thinks to have recognized.
95 The following code should explain how to use the typefind element. It
96 will print the detected media type, or tell that the media type was not
97 found. The next section will introduce more useful behaviours, such as
98 plugging together a decoding pipeline.
103 [.. my_bus_callback goes here ..]
106 idle_exit_loop (gpointer data)
108 g_main_loop_quit ((GMainLoop *) data);
115 cb_typefound (GstElement *typefind,
120 GMainLoop *loop = data;
123 type = gst_caps_to_string (caps);
124 g_print ("Media type %s found, probability %d%%\n", type, probability);
127 /* since we connect to a signal in the pipeline thread context, we need
128 * to set an idle handler to exit the main loop in the mainloop context.
129 * Normally, your app should not need to worry about such things. */
130 g_idle_add (idle_exit_loop, loop);
138 GstElement *pipeline, *filesrc, *typefind, *fakesink;
142 gst_init (&argc, &argv);
143 loop = g_main_loop_new (NULL, FALSE);
147 g_print ("Usage: %s <filename>\n", argv[0]);
151 /* create a new pipeline to hold the elements */
152 pipeline = gst_pipeline_new ("pipe");
154 bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
155 gst_bus_add_watch (bus, my_bus_callback, NULL);
156 gst_object_unref (bus);
158 /* create file source and typefind element */
159 filesrc = gst_element_factory_make ("filesrc", "source");
160 g_object_set (G_OBJECT (filesrc), "location", argv[1], NULL);
161 typefind = gst_element_factory_make ("typefind", "typefinder");
162 g_signal_connect (typefind, "have-type", G_CALLBACK (cb_typefound), loop);
163 fakesink = gst_element_factory_make ("fakesink", "sink");
166 gst_bin_add_many (GST_BIN (pipeline), filesrc, typefind, fakesink, NULL);
167 gst_element_link_many (filesrc, typefind, fakesink, NULL);
168 gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_PLAYING);
169 g_main_loop_run (loop);
172 gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_NULL);
173 gst_object_unref (GST_OBJECT (pipeline));
180 Once a media type has been detected, you can plug an element (e.g. a
181 demuxer or decoder) to the source pad of the typefind element, and
182 decoding of the media stream will start right after.
184 ## Dynamically autoplugging a pipeline
186 See [Playback Components](manual-playback-components.md) for using the
187 high level object that you can use to dynamically construct pipelines.