mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-29 11:40:38 +00:00
5566946241
Original commit message from CVS: * docs/random/draft-missing-plugins.txt: Update: use element message instead of adding a new message type to the core; don't provide GStreamer API to initiate the plugin download, just provide API to compose the strings needed and let an external libgimmestuff handle the rest.
156 lines
6.5 KiB
Text
156 lines
6.5 KiB
Text
What to do when a plugin is missing
|
|
===================================
|
|
|
|
We only discuss playback pipelines for now.
|
|
|
|
A three step process:
|
|
|
|
1) GStreamer level
|
|
|
|
- elements will use a "missing-plugin" element message to report missing
|
|
plugins, with the following fields set:
|
|
|
|
- type: (string) { "urisource", "urisink", "decoder", "encoder", "element" }
|
|
(we do not distinguish between demuxer/decoders/parsers etc.)
|
|
- detail: (string) or (caps) depending on the type { ANY }
|
|
ex: "mms, "mmsh", "audio/x-mp3,rate=48000,..."
|
|
- name: (string) { ANY }
|
|
ex: "MMS protocol handler",..
|
|
|
|
- missing uri handler
|
|
|
|
ex. mms://foo.bar/file.asf
|
|
|
|
When no protocol handler is installed for mms://, the application will not be
|
|
able to instantiate an element for that uri (gst_element_make_from_uri()
|
|
returns NULL).
|
|
|
|
Playbin will post a "missing-plugin" element message with the type set to
|
|
"urisource", detail set to "mms". Optionally the friendly name can be filled
|
|
in as well.
|
|
|
|
- missing typefind function
|
|
|
|
We don't recognize the type of the file, this should normally not happen
|
|
because all the typefinders are in the basic GStreamer installation.
|
|
There is not much useful information we can give about how to resolve this
|
|
issue. It is possible to use the first N bytes of the data to determine the
|
|
type (and needed plugin) on the server. We don't explore this option in this
|
|
document yet, but the proposal is flexible enough to accomodate this in the
|
|
future should the need arise.
|
|
|
|
- missing demuxer
|
|
|
|
Typically after running typefind on the data we determine the type of the
|
|
file. If there is no plugin found for the type, a "missing-plugin" element
|
|
message is posted by decodebin with the following fields: Type set to
|
|
"decoder", detail set to the caps for witch no plugin was found. Optionally
|
|
the friendly name can be filled in as well.
|
|
|
|
- missing decoder
|
|
|
|
The demuxer will dynamically create new pads with specific caps while it
|
|
figures out the contents of the container format. Decodebin tries to find the
|
|
decoders for these formats in the registry. If there is no decoder found, a
|
|
"missing-plugin" element message is posted by decodebin with the following
|
|
fields: Type set to "decoder", detail set to the caps for which no plugin
|
|
was found. Optionally the friendly name can be filled in as well. There is
|
|
no distinction made between the missing demuxer and decoder at the
|
|
application level.
|
|
|
|
- missing element
|
|
|
|
Decodebin and playbin will create a set of helper elements when they set up
|
|
their decoding pipeline. These elements are typically colorspace, sample rate,
|
|
audio sinks,... Their presence on the system is required for the functionality
|
|
of decodebin. It is typically a package dependency error if they are not
|
|
present but in case of a corrupted system the following "missing-plugin"
|
|
element message will be emitted: type set to "element", detail set to the
|
|
element factory name and the friendly name optionally set to a description
|
|
of the element's functionality in the decoding pipeline.
|
|
|
|
Except for reporting the missing plugins, no further policy is enforced at the
|
|
GStreamer level. It is up to the application to decide whether a missing
|
|
plugin constitutes a problem or not.
|
|
|
|
|
|
2) application level
|
|
|
|
The application's job is to listen for the "missing-plugin" element messages
|
|
and to decide on a policy to handle them. Following cases exist:
|
|
|
|
- partially missing plugins
|
|
|
|
The application will be able to complete a state change to PAUSED but there
|
|
will be a "missing-plugin" element message on the GstBus.
|
|
|
|
This means that it will be possible to play back part of the media file but not
|
|
all of it.
|
|
|
|
For example: suppose we have an .avi file with mp3 audio and divx video. If we
|
|
have the mp3 audio decoder but not the divx video decoder, it will be possible
|
|
to play only the audio part but not the video part. For an audio playback
|
|
application, this is not a problem but a video player might want to decide on:
|
|
|
|
- require the use to install the additionally required plugins.
|
|
- inform the user that only the audio will be played back
|
|
- ask the user if it should download the additional codec or only play the
|
|
audio part.
|
|
- ...
|
|
|
|
- completely unplayable stream
|
|
|
|
The application will receive an ERROR message from GStreamer informing it that
|
|
playback stopped (before it could reach PAUSED). This happens because none of
|
|
the streams is connected to a decoder.
|
|
|
|
The application can then see that there are a set of "missing-plugin" element
|
|
messages on the GstBus and can decide to trigger the download procedure. It
|
|
does that as described in the following section.
|
|
|
|
|
|
3) Plugin download stage
|
|
|
|
At this point the application has
|
|
- collected one or more "missing-plugin" element messages
|
|
- made a decision that additional plugins should be installed
|
|
|
|
It will call a GStreamer utility function to convert each "missing-plugin"
|
|
message into an identifier string describing the missing capability.
|
|
|
|
The application will then pass these strings to an external libgimmecodec
|
|
to initiate the download. Error handling and progress reporting etc. will
|
|
all be handled using libgimmecodec's API.
|
|
|
|
When new plugins have been installed, the application will have to initiate
|
|
a re-scan of the GStreamer plugin registry.
|
|
|
|
|
|
4) Format of the (UTF-8) string ID passed to the external installer system
|
|
|
|
The string is made up of several fields, separated by '|' characters.
|
|
The fields are:
|
|
|
|
- plugin system identifier, ie. gstreamer.net
|
|
- plugin system version, e.g. 0.10
|
|
- application identifier, e.g. totem
|
|
- human-readable localised description of the required component,
|
|
e.g. "Vorbis audio decoder"
|
|
- identifier string for the required component, e.g.
|
|
- urisource-$(PROTOCOL_REQUIRED)
|
|
e.g. urisource-http or urisource-mms
|
|
- element-$(ELEMENT_REQUIRED),
|
|
e.g. element-ffmpegcolorspace
|
|
- decoder-$(CAPS_REQUIRED)
|
|
e.g. decoder-audio/x-vorbis or decoder-application/ogg
|
|
- encoder-$(CAPS_REQUIRED)
|
|
e.g. encoder-audio/x-vorbis
|
|
|
|
An entire ID string might then look like this, for example:
|
|
|
|
gstreamer.net|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis
|
|
|
|
The human-readable description string will come from a new utility
|
|
library that yet to be added to gst-plugins-base and which can then also
|
|
be used by demuxers to find out the codec names for taglists from given
|
|
caps in a unified and consistent way.
|