docs/design/part-missing-plugins.txt

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