manual-autoplugging.md

   1 ---
   2 title: Autoplugging
   3 ...
   4
   5 # Autoplugging
   6
   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.
  24
  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.
  31
  32 ## Media types as a way to identify streams
  33
  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
  43 Writer's
  44 Guide](http://gstreamer.freedesktop.org/data/doc/gstreamer/head/pwg/html/section-types-definitions.html).
  45
  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.
  51
  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.
  57
  58 ![The Hello world pipeline with media types](images/mime-world.png
  59 "fig:")
  60
  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.
  64
  65 ## Media stream type detection
  66
  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.
  77
  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.
  81
  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.
  94
  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.
  99
 100 ```  c
 101 #include <gst/gst.h>
 102
 103 [.. my_bus_callback goes here ..]
 104
 105 static gboolean
 106 idle_exit_loop (gpointer data)
 107 {
 108   g_main_loop_quit ((GMainLoop *) data);
 109
 110   /* once */
 111   return FALSE;
 112 }
 113
 114 static void
 115 cb_typefound (GstElement *typefind,
 116           guint       probability,
 117           GstCaps    *caps,
 118           gpointer    data)
 119 {
 120   GMainLoop *loop = data;
 121   gchar *type;
 122
 123   type = gst_caps_to_string (caps);
 124   g_print ("Media type %s found, probability %d%%\n", type, probability);
 125   g_free (type);
 126
 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);
 131 }
 132
 133 gint
 134 main (gint   argc,
 135       gchar *argv[])
 136 {
 137   GMainLoop *loop;
 138   GstElement *pipeline, *filesrc, *typefind, *fakesink;
 139   GstBus *bus;
 140
 141   /* init GStreamer */
 142   gst_init (&argc, &argv);
 143   loop = g_main_loop_new (NULL, FALSE);
 144
 145   /* check args */
 146   if (argc != 2) {
 147     g_print ("Usage: %s <filename>\n", argv[0]);
 148     return -1;
 149   }
 150
 151   /* create a new pipeline to hold the elements */
 152   pipeline = gst_pipeline_new ("pipe");
 153
 154   bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
 155   gst_bus_add_watch (bus, my_bus_callback, NULL);
 156   gst_object_unref (bus);
 157
 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");
 164
 165   /* setup */
 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);
 170
 171   /* unset */
 172   gst_element_set_state (GST_ELEMENT (pipeline), GST_STATE_NULL);
 173   gst_object_unref (GST_OBJECT (pipeline));
 174
 175   return 0;
 176 }
 177
 178 ```
 179
 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.
 183
 184 ## Dynamically autoplugging a pipeline
 185
 186 See [Playback Components](manual-playback-components.md) for using the
 187 high level object that you can use to dynamically construct pipelines.
 188