subprojects/gst-docs/markdown/additional/design/missing-plugins.md

   1 # What to do when a plugin is missing
   2
   3 The mechanism and API described in this document requires GStreamer core
   4 and gst-plugins-base versions \>= 0.10.12. Further information on some
   5 aspects of this document can be found in the libgstbaseutils API
   6 reference.
   7
   8 We only discuss playback pipelines for now.
   9
  10 A three step process:
  11
  12 # GStreamer level
  13
  14 Elements will use a "missing-plugin" element message to report
  15 missing plugins, with the following fields set:
  16
  17 * **`type`**: (string) { "urisource", "urisink", "decoder", "encoder",
  18 "element" } (we do not distinguish between demuxer/decoders/parsers etc.)
  19
  20 * **`detail`**: (string) or (caps) depending on the type { ANY } ex: "mms,
  21 "mmsh", "audio/x-mp3,rate=48000,…"
  22
  23 * **`name`**: (string) { ANY } ex: "MMS protocol handler",..
  24
  25 ### missing uri handler
  26
  27 ex. mms://foo.bar/file.asf
  28
  29 When no protocol handler is installed for mms://, the application will not be
  30 able to instantiate an element for that uri (`gst_element_make_from_uri()`
  31 returns NULL).
  32
  33 Playbin will post a `missing-plugin` element message with the type set to
  34 "urisource", detail set to "mms". Optionally the friendly name can be filled
  35 in as well.
  36
  37 ### missing typefind function
  38
  39 We don't recognize the type of the file, this should normally not happen
  40 because all the typefinders are in the basic GStreamer installation.
  41 There is not much useful information we can give about how to resolve this
  42 issue. It is possible to use the first N bytes of the data to determine the
  43 type (and needed plugin) on the server. We don't explore this option in this
  44 document yet, but the proposal is flexible enough to accommodate this in the
  45 future should the need arise.
  46
  47 ### missing demuxer
  48
  49 Typically after running typefind on the data we determine the type of the
  50 file. If there is no plugin found for the type, a `missing-plugin` element
  51 message is posted by decodebin with the following fields: Type set to
  52 "decoder", detail set to the caps for witch no plugin was found. Optionally
  53 the friendly name can be filled in as well.
  54
  55 ### missing decoder
  56
  57 The demuxer will dynamically create new pads with specific caps while it
  58 figures out the contents of the container format. Decodebin tries to find the
  59 decoders for these formats in the registry. If there is no decoder found, a
  60 `missing-plugin` element message is posted by decodebin with the following
  61 fields: Type set to "decoder", detail set to the caps for which no plugin
  62 was found. Optionally the friendly name can be filled in as well. There is
  63 no distinction made between the missing demuxer and decoder at the
  64 application level.
  65
  66 ### missing element
  67
  68 Decodebin and playbin will create a set of helper elements when they set up
  69 their decoding pipeline. These elements are typically colorspace, sample rate,
  70 audio sinks,... Their presence on the system is required for the functionality
  71 of decodebin. It is typically a package dependency error if they are not
  72 present but in case of a corrupted system the following `missing-plugin`
  73 element message will be emitted: type set to "element", detail set to the
  74 element factory name and the friendly name optionally set to a description
  75 of the element's functionality in the decoding pipeline.
  76
  77 Except for reporting the missing plugins, no further policy is enforced at the
  78 GStreamer level. It is up to the application to decide whether a missing
  79 plugin constitutes a problem or not.
  80
  81 ## Application level
  82
  83 The application's job is to listen for the `missing-plugin` element messages
  84 and to decide on a policy to handle them. Following cases exist:
  85
  86 ### partially missing plugins
  87
  88 The application will be able to complete a state change to PAUSED but there
  89 will be a `missing-plugin` element message on the `GstBus`.
  90
  91 This means that it will be possible to play back part of the media file but not
  92 all of it.
  93
  94 For example: suppose we have an .avi file with mp3 audio and divx video. If we
  95 have the mp3 audio decoder but not the divx video decoder, it will be possible
  96 to play only the audio part but not the video part. For an audio playback
  97 application, this is not a problem but a video player might want to decide on:
  98
  99   - require the use to install the additionally required plugins.
 100   - inform the user that only the audio will be played back
 101   - ask the user if it should download the additional codec or only play
 102     the audio part.
 103   - …
 104
 105 ### completely unplayable stream
 106
 107 The application will receive an ERROR message from GStreamer informing it that
 108 playback stopped (before it could reach PAUSED). This happens because none of
 109 the streams is connected to a decoder. The error code and domain should be one
 110 of the following in this case:
 111
 112    - `GST_CORE_ERROR_MISSING_PLUGIN` (domain: `GST_CORE_ERROR`)
 113    - `GST_STREAM_ERROR_CODEC_NOT_FOUND` (domain: `GST_STREAM_ERROR`)
 114
 115 The application can then see that there are a set of `missing-plugin` element
 116 messages on the `GstBus` and can decide to trigger the download procedure. It
 117 does that as described in the following section.
 118
 119 `missing-plugin` element messages can be identified using the function
 120 `gst_is_missing_plugin_message()`.
 121
 122 ## Plugin download stage
 123
 124 At this point the application has
 125   - collected one or more `missing-plugin` element messages
 126   - made a decision that additional plugins should be installed
 127
 128 It will call a GStreamer utility function to convert each `missing-plugin`
 129 message into an identifier string describing the missing capability. This is
 130 done using the function `gst_missing_plugin_message_get_installer_detail()`.
 131
 132 The application will then pass these strings to `gst_install_plugins_async()`
 133 or `gst_install_plugins_sync()` to initiate the download. See the API
 134 documentation there (`libgstbaseutils`, part of `gst-plugins-base`) for more
 135 details.
 136
 137 When new plugins have been installed, the application will have to initiate
 138 a re-scan of the GStreamer plugin registry using `gst_update_registry()`.
 139
 140 ### Format of the (UTF-8) string ID passed to the external installer system
 141
 142 The string is made up of several fields, separated by '|' characters.
 143 The fields are:
 144
 145 - plugin system identifier, ie. "gstreamer" This identifier determines
 146 the format of the rest of the detail string. Automatic plugin
 147 installers should not process detail strings with unknown
 148 identifiers. This allows other plugin-based libraries to use the
 149 same mechanism for their automatic plugin installation needs, or for
 150 the format to be changed should it turn out to be insufficient.
 151
 152 - plugin system version, e.g. "1.0" This is required so that when
 153 there is a GStreamer-2.0 or GStreamer-3.0 at some point in future,
 154 the different major versions can still co-exist and use the same
 155 plugin install mechanism in the same way.
 156
 157 - application identifier, e.g. "totem" This may also be in the form of
 158 "pid/12345" if the program name can’t be obtained for some reason.
 159
 160 - human-readable localised description of the required component, e.g.
 161 "Vorbis audio decoder"
 162
 163 - identifier string for the required component, e.g.
 164
 165 - urisource-(`PROTOCOL_REQUIRED`) e.g. `urisource-http` or `urisource-mms`
 166
 167 - element-(`ELEMENT_REQUIRED`), e.g. `element-videoconvert`
 168
 169 - decoder-(`CAPS_REQUIRED`) e.g. `decoder-audio/x-vorbis` or
 170 `decoder-application/ogg` or `decoder-audio/mpeg, mpegversion=(int)4` or
 171 `decoder-video/mpeg, systemstream=(boolean)true, mpegversion=(int)2`
 172
 173 - encoder-(`CAPS_REQUIRED`) e.g. `encoder-audio/x-vorbis`
 174
 175 - optional further fields not yet specified
 176
 177 * An entire ID string might then look like this, for example:
 178 `gstreamer|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis`
 179
 180 * Plugin installers parsing this ID string should expect further fields also
 181 separated by '|' symbols and either ignore them, warn the user, or error
 182 out when encountering them.
 183
 184 * The human-readable description string is provided by the libgstbaseutils
 185 library that can be found in gst-plugins-base versions >= 0.10.12 and can
 186 also be used by demuxers to find out the codec names for taglists from given
 187 caps in a unified and consistent way.
 188
 189 * Applications can create these detail strings using the function
 190 `gst_missing_plugin_message_get_installer_detail()` on a given missing-plugin
 191 message.
 192
 193 ### Using missing-plugin messages for error reporting:
 194
 195 Missing-plugin messages are also useful for error reporting purposes, either in
 196 the case where the application does not support libgimme-codec, or the external
 197 installer is not available or not able to install the required plugins.
 198
 199 When creating error messages, applications may use the function
 200 `gst_missing_plugin_message_get_description()` to obtain a possibly translated
 201 description from each missing-plugin message (e.g. "Matroska demuxer" or
 202 "Theora video depayloader"). This can be used to report to the user exactly
 203 what it is that is missing.
 204
 205 ## Notes for packagers
 206
 207 An easy way to introspect plugin .so files is:
 208
 209 ```
 210 $ gst-inspect --print-plugin-auto-install-info /path/to/libgstfoo.so
 211 ```
 212
 213 The output will be something like:
 214
 215 ```
 216 decoder-audio/x-vorbis
 217 element-vorbisdec
 218 element-vorbisenc
 219 element-vorbisparse
 220 element-vorbistag
 221 encoder-audio/x-vorbis
 222 ```
 223
 224 BUT could also be like this (from the faad element in this case):
 225
 226 ```
 227 decoder-audio/mpeg, mpegversion=(int){ 2, 4 }
 228 ```
 229
 230 NOTE that this does not exactly match the caps string that the installer
 231 will get from the application. The application will always ever ask for
 232 one of
 233
 234 ```
 235 decoder-audio/mpeg, mpegversion=(int)2
 236 decoder-audio/mpeg, mpegversion=(int)4
 237 ```
 238
 239 When introspecting, keep in mind that there are GStreamer plugins
 240 that in turn load external plugins. Examples of these are pitfdll,
 241 ladspa, or the GStreamer libvisual plugin. Those plugins will only
 242 announce elements for the currently installed external plugins at
 243 the time of introspection\! With the exception of pitfdll, this is
 244 not really relevant to the playback case, but may become an issue in
 245 future when applications like buzztard, jokosher or pitivi start
 246 requestion elements by name, for example ladspa effect elements or
 247 so.
 248
 249 This case could be handled if those wrapper plugins would also provide a
 250 `gst-install-xxx-plugins-helper`, where xxx={ladspa|visual|...}. Thus if the
 251 distro specific `gst-install-plugins-helper` can't resolve a request for e.g.
 252 `element-bml-sonicverb` it can forward the request to
 253 `gst-install-bml-plugins-helper` (bml is the buzz machine loader).
 254
 255 ## Further references:
 256
 257 <http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-libs/html/gstreamer-base-utils.html>