From b99629643cd0ab45ac698ee5e9e8a5de041c5235 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Sun, 18 Feb 2007 21:02:36 +0000 Subject: [PATCH] gst-libs/gst/utils/: Some more docs (and descriptions for two subtitle formats). Original commit message from CVS: * gst-libs/gst/utils/base-utils.c: * gst-libs/gst/utils/descriptions.c: * gst-libs/gst/utils/install-plugins.c: * gst-libs/gst/utils/missing-plugins.c: Some more docs (and descriptions for two subtitle formats). --- ChangeLog | 8 + gst-libs/gst/pbutils/descriptions.c | 24 ++ gst-libs/gst/pbutils/install-plugins.c | 296 +++++++++++++++++++++++++ gst-libs/gst/pbutils/missing-plugins.c | 33 +++ gst-libs/gst/pbutils/pbutils.c | 56 +++++ gst-libs/gst/utils/base-utils.c | 56 +++++ gst-libs/gst/utils/descriptions.c | 24 ++ gst-libs/gst/utils/install-plugins.c | 296 +++++++++++++++++++++++++ gst-libs/gst/utils/missing-plugins.c | 33 +++ 9 files changed, 826 insertions(+) diff --git a/ChangeLog b/ChangeLog index ec24d1df80..b2588ab127 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2007-02-16 Tim-Philipp Müller + + * gst-libs/gst/utils/base-utils.c: + * gst-libs/gst/utils/descriptions.c: + * gst-libs/gst/utils/install-plugins.c: + * gst-libs/gst/utils/missing-plugins.c: + Some more docs (and descriptions for two subtitle formats). + 2007-02-16 Tim-Philipp Müller * gst-libs/gst/audio/audio.c: diff --git a/gst-libs/gst/pbutils/descriptions.c b/gst-libs/gst/pbutils/descriptions.c index 6bcb9a52bf..34f2ea1989 100644 --- a/gst-libs/gst/pbutils/descriptions.c +++ b/gst-libs/gst/pbutils/descriptions.c @@ -17,6 +17,25 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsdescriptions + * @short_description: Provides human-readable descriptions for caps/codecs + * and encoder, decoder, URI source and URI sink elements + * + * + * + * The above functions provide human-readable strings for media formats + * and decoder/demuxer/depayloader/encoder/muxer/payloader elements for use + * in error dialogs or other messages shown to users. + * + * + * gst_base_utils_add_codec_description_to_tag_list() is a utility function + * for demuxer and decoder elements to add audio/video codec tags from a + * given (fixed) #GstCaps. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -181,6 +200,11 @@ static const FormatInfo formats[] = { {"image/x-sun-raster", "Sun Raster Format (RAS)", 0}, {"image/x-tga", "TGA", 0}, + /* subtitle formats with static descriptions */ + {"application/x-subtitle-sami", N_("Sami subtitle format"), 0}, + {"application/x-subtitle-tmplayer", N_("TMPlayer subtitle format"), 0}, + /* add variant field to typefinder? { "application/x-subtitle", N_("subtitle"), 0}, */ + /* formats with dynamic descriptions */ {"audio/mpeg", NULL, 0}, {"audio/x-mace", NULL, 0}, diff --git a/gst-libs/gst/pbutils/install-plugins.c b/gst-libs/gst/pbutils/install-plugins.c index 805ad36531..2da9e8ac44 100644 --- a/gst-libs/gst/pbutils/install-plugins.c +++ b/gst-libs/gst/pbutils/install-plugins.c @@ -18,6 +18,302 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsinstallplugins + * @short_description: Missing plugin installation support for applications + * + * + * Overview + * + * Using this API, applications can request the installation of missing + * GStreamer plugins. These may be missing decoders/demuxers or encoders/muxers + * for a certain format, sources or sinks for a certain URI protocol + * (e.g. 'http'), or certain elements known by their element factory name + * ('audioresample'). + * + * + * Whether plugin installation is supported or not depends on the operating + * system and/or distribution in question. The vendor of the operating system + * needs to make sure the necessary hooks and mechanisms are in place for + * plugin installation to work. See below for more detailed information. + * + * + * From the application perspective, plugin installation is usually triggered + * either + * + * + * when the application itself has found that it wants or needs to install a + * certain element + * + * + * when the application has been notified by an element (such as playbin or + * decodebin) that one or more plugins are missing and + * the application has decided that it wants to install one or more of those + * missing plugins + * + * + * + * Detail Strings + * + * The install functions in this section all take one or more 'detail strings'. + * These detail strings contain information about the type of plugin that + * needs to be installed (decoder, encoder, source, sink, or named element), + * and some additional information such GStreamer version used and a + * human-readable description of the component to install for user dialogs. + * + * + * Applications should not concern themselves with the composition of the + * string itself. They should regard the string as if it was a shared secret + * between GStreamer and the plugin installer application. + * + * + * Detail strings can be obtained using the function + * gst_missing_plugin_message_get_installer_detail() on a missing-plugin + * message. Such a message will either have been found by the application on + * a pipeline's #GstBus, or the application will have created it itself using + * gst_missing_element_message_new(), gst_missing_decoder_message_new(), + * gst_missing_encoder_message_new(), gst_missing_uri_sink_message_new(), or + * gst_missing_uri_source_message_new(). + * + * Plugin Installation from the Application Perspective + * + * For each GStreamer element/plugin/component that should be installed, the + * application needs one of those 'installer detail' string mentioned in the + * previous section. This string can be obtained, as already mentioned above, + * from a missing-plugin message using the function + * gst_missing_plugin_message_get_installer_detail(). The missing-plugin + * message is either posted by another element and then found on the bus + * by the application, or the application has created it itself as described + * above. + * + * + * The application will then call gst_install_plugins_async(), passing a + * #NULL-terminated array of installer detail strings, and a function that + * should be called when the installation of the plugins has finished + * (successfully or not). Optionally, a #GstInstallPluginsContext created + * with gst_install_plugins_context_new() may be passed as well. This way + * additional optional arguments like the application window's XID can be + * passed to the external installer application. + * + * + * gst_install_plugins_async() will return almost immediately, with the + * return code indicating whether plugin installation was started or not. + * If the necessary hooks for plugin installation are in place and an + * external installer application has in fact been called, the passed in + * function will be called with a result code as soon as the external installer + * has finished. If the result code indicates that new plugins have been + * installed, the application will want to call gst_update_registry() so the + * run-time plugin registry is updated and the new plugins are made available + * to the application. + * + * A Gtk/GLib main loop must be running in order for the result function to + * be called when the external installer has finished. If this is not the case, + * make sure to regularly call + * + * g_main_context_iteration (NULL,FALSE); + * + * from your code. + * + * + * Plugin Installation from the Vendor/Distribution Perspective + * + * 1. Installer hook + * + * + * When GStreamer applications initiate plugin installation via + * gst_install_plugins_async() or gst_install_plugins_sync(), a pre-defined + * helper application will be called. + * + * + * The exact path of the helper application to be called is set at compile + * time, usually by the ./configure script based on the + * install prefix. For a normal package build into the /usr + * prefix, this will usually default to + * /usr/libexec/gst-install-plugins-helper or + * /usr/lib/gst-install-plugins-helper. + * + * + * Vendors/distros who want to support GStreamer plugin installation should + * either provide such a helper script/application or use the + * ./configure option + * --with-install-plugins-helper=/path/to/installer to + * make GStreamer call an installer of their own directly. + * + * + * It is strongly recommended that vendors provide a small helper application + * as interlocutor to the real installer though, even more so if command line + * argument munging is required to transform the command line arguments + * passed by GStreamer to the helper application into arguments that are + * understood by the reeal installer. + * + * + * The helper application path defined at compile time can be overriden at + * runtime by setting the GST_INSTALL_PLUGINS_HELPER + * environment variable. This can be useful for testing/debugging purposes. + * + * + * 2. Arguments passed to the install helper + * + * + * GStreamer will pass the following arguments to the install helper (this is + * in addition to the path of the executable itself, which is by convention + * argv[0]): + * + * + * none to many optional arguments in the form of + * --foo-bar=val. Example: + * --transient-for=XID where XID is the X Window ID of + * the main window of the calling application (so the installer can make + * itself transient to that window). Unknown optional arguments should + * be ignored by the installer. + * + * + * one 'installer detail string' argument for each plugin to be installed; + * these strings will have a gstreamer.net prefix; the + * exact format of the detail string is explained below + * + * + * + * + * 3. Detail string describing the missing plugin + * + * + * The string is in UTF-8 encoding and is made up of several fields, separated + * by '|' characters (but neither the first nor the last character is a '|'). + * The fields are: + * + * + * plugin system identifier, ie. "gstreamer.net" + * + * This identifier determines the format of the rest of the detail string. + * Automatic plugin installers should not process detail strings with + * unknown identifiers. This allows other plugin-based libraries to use + * the same mechanism for their automatic plugin installation needs, or + * for the format to be changed should it turn out to be insufficient. + * + * + * plugin system version, e.g. "0.10" + * + * This is required so that when there is a GStreamer-0.12 or GStreamer-1.0 + * at some point in future, the different major versions can still co-exist + * and use the same plugin install mechanism in the same way. + * + * + * application identifier, e.g. "totem" + * + * This may also be in the form of "pid/12345" if the program name can't + * be obtained for some reason. + * + * + * human-readable localised description of the required component, + * e.g. "Vorbis audio decoder" + * + * + * identifier string for the required component (see below for details about + * how to map this to the package/plugin that needs installing), 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 + * + * + * + * + * optional further fields not yet specified + * + * + * + * + * An entire ID string might then look like this, for example: + * + * gstreamer.net|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis + * + * + * + * Plugin installers parsing this ID string should expect further fields also + * separated by '|' symbols and either ignore them, warn the user, or error + * out when encountering them. + * + * + * 4. Exit codes the installer should return + * + * + * The installer should return one of the following exit codes when it exits: + * + * + * 0 if all of the requested plugins could be installed + * (#GST_INSTALL_PLUGINS_SUCCESS) + * + * + * 1 if no appropriate installation candidate for any of the requested + * plugins could be found. Only return this if nothing has been installed + * (#GST_INSTALL_PLUGINS_NOT_FOUND) + * + * + * 2 if an error occured during the installation. The application will + * assume that the user will already have seen an error message by the + * installer in this case and will usually not show another one + * (#GST_INSTALL_PLUGINS_ERROR) + * + * + * 3 if some of the requested plugins could be installed, but not all + * (#GST_INSTALL_PLUGINS_PARTIAL_SUCCESS) + * + * + * 4 if the user aborted the installation (#GST_INSTALL_PLUGINS_USER_ABORT) + * + * + * + * + * 5. How to map the required detail string to packages + * + * + * It is up to the vendor to find mechanism to map required components from + * the detail string to the actual packages/plugins to install. This could + * be a hardcoded list of mappings, for example, or be part of the packaging + * system metadata. + * + * + * GStreamer plugin files can be introspected for this information. The + * gst-inspect utility has a special command line option + * that will output information similar to what is required. For example + * + * $ gst-inspect-0.10 --print-plugin-auto-install-info /path/to/libgstvorbis.so + * + * should output something along the lines of + * + * decoder-audio/x-vorbis + * element-vorbisdec + * element-vorbisenc + * element-vorbisparse + * element-vorbistag + * encoder-audio/x-vorbis + * + * Note that in the encoder and decoder case the introspected caps can be more + * complex with additional fields, e.g. + * audio/mpeg,mpegversion=(int){2,4}, so they will not + * always exactly match the caps wanted by the application. It is up to the + * installer to deal with this (either by doing proper caps intersection using + * the GStreamer #GstCaps API, or by only taking into account the media type). + * + * + * Another potential source of problems are plugins such as ladspa or + * libvisual where the list of elements depends on the installed + * ladspa/libvisual plugins at the time. This is also up to the distribution + * to handle (but usually not relevant for playback applications). + * + * + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/gst-libs/gst/pbutils/missing-plugins.c b/gst-libs/gst/pbutils/missing-plugins.c index bada28e9e3..ac06aa06e4 100644 --- a/gst-libs/gst/pbutils/missing-plugins.c +++ b/gst-libs/gst/pbutils/missing-plugins.c @@ -17,6 +17,39 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsmissingplugins + * @short_description: Create, recognise and parse missing-plugins messages + * + * + * + * Functions to create, recognise and parse missing-plugins messages for + * applications and elements. + * + * + * Missing-plugin messages are posted on the bus by elements like decodebin + * or playbin if they can't find an appropriate source element or decoder + * element. The application can use these messages for two things: + * + * + * concise error/problem reporting to the user mentioning what exactly + * is missing, see gst_missing_plugin_message_get_description() + * + * + * initiate installation of missing plugins, see + * gst_missing_plugin_message_get_installer_detail() and + * gst_install_plugins_async() + * + * + * + * + * Applications may also create missing-plugin messages themselves to install + * required elements that are missing, using the install mechanism mentioned + * above. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif diff --git a/gst-libs/gst/pbutils/pbutils.c b/gst-libs/gst/pbutils/pbutils.c index e3248af5a7..1f5142448e 100644 --- a/gst-libs/gst/pbutils/pbutils.c +++ b/gst-libs/gst/pbutils/pbutils.c @@ -17,6 +17,57 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutils + * @short_description: General Application and Plugin Utility Library + * + * + * + * libgstbaseutils is a general utility library for plugins and applications, + * available since gst-plugins-base 0.10.12. It currently provides the + * following: + * + * + * + * + * human-readable description strings of codecs, elements, sources, decoders, + * encoders, or sinks from decoder/encoder caps, element names, or protocol + * names. + * + * + * + * + * support for applications to initiate installation of missing plugins (if + * this is supported by the distribution or operating system used) + * + * + * + * + * API for GStreamer elements to create missing-plugin messages in order to + * communicate to the application that a certain type of plugin is missing + * (decoder, encoder, URI protocol source, URI protocol sink, named element) + * + * + * + * + * API for applications to recognise and handle missing-plugin messages + * + * + * + * Linking to this library + * + * You should obtain the required CFLAGS and LIBS using pkg-config on the + * gstreamer-plugins-base-0.10 module. You will then also need to add + * '-lgstbaseutils-0.10' manually to your LIBS line. + * + * Library initialisation + * + * Before using any of its functions, applications and plugins must call + * gst_base_utils_init() to initialise the library. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -31,6 +82,11 @@ * Initialises the base utils support library. This function is not * thread-safe. Applications should call it after calling gst_init(), * plugins should call it from their plugin_init function. + * + * This function may be called multiple times. It will do nothing if the + * library has already been initialised. + * + * Since: 0.10.12 */ void gst_base_utils_init (void) diff --git a/gst-libs/gst/utils/base-utils.c b/gst-libs/gst/utils/base-utils.c index e3248af5a7..1f5142448e 100644 --- a/gst-libs/gst/utils/base-utils.c +++ b/gst-libs/gst/utils/base-utils.c @@ -17,6 +17,57 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutils + * @short_description: General Application and Plugin Utility Library + * + * + * + * libgstbaseutils is a general utility library for plugins and applications, + * available since gst-plugins-base 0.10.12. It currently provides the + * following: + * + * + * + * + * human-readable description strings of codecs, elements, sources, decoders, + * encoders, or sinks from decoder/encoder caps, element names, or protocol + * names. + * + * + * + * + * support for applications to initiate installation of missing plugins (if + * this is supported by the distribution or operating system used) + * + * + * + * + * API for GStreamer elements to create missing-plugin messages in order to + * communicate to the application that a certain type of plugin is missing + * (decoder, encoder, URI protocol source, URI protocol sink, named element) + * + * + * + * + * API for applications to recognise and handle missing-plugin messages + * + * + * + * Linking to this library + * + * You should obtain the required CFLAGS and LIBS using pkg-config on the + * gstreamer-plugins-base-0.10 module. You will then also need to add + * '-lgstbaseutils-0.10' manually to your LIBS line. + * + * Library initialisation + * + * Before using any of its functions, applications and plugins must call + * gst_base_utils_init() to initialise the library. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -31,6 +82,11 @@ * Initialises the base utils support library. This function is not * thread-safe. Applications should call it after calling gst_init(), * plugins should call it from their plugin_init function. + * + * This function may be called multiple times. It will do nothing if the + * library has already been initialised. + * + * Since: 0.10.12 */ void gst_base_utils_init (void) diff --git a/gst-libs/gst/utils/descriptions.c b/gst-libs/gst/utils/descriptions.c index 6bcb9a52bf..34f2ea1989 100644 --- a/gst-libs/gst/utils/descriptions.c +++ b/gst-libs/gst/utils/descriptions.c @@ -17,6 +17,25 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsdescriptions + * @short_description: Provides human-readable descriptions for caps/codecs + * and encoder, decoder, URI source and URI sink elements + * + * + * + * The above functions provide human-readable strings for media formats + * and decoder/demuxer/depayloader/encoder/muxer/payloader elements for use + * in error dialogs or other messages shown to users. + * + * + * gst_base_utils_add_codec_description_to_tag_list() is a utility function + * for demuxer and decoder elements to add audio/video codec tags from a + * given (fixed) #GstCaps. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif @@ -181,6 +200,11 @@ static const FormatInfo formats[] = { {"image/x-sun-raster", "Sun Raster Format (RAS)", 0}, {"image/x-tga", "TGA", 0}, + /* subtitle formats with static descriptions */ + {"application/x-subtitle-sami", N_("Sami subtitle format"), 0}, + {"application/x-subtitle-tmplayer", N_("TMPlayer subtitle format"), 0}, + /* add variant field to typefinder? { "application/x-subtitle", N_("subtitle"), 0}, */ + /* formats with dynamic descriptions */ {"audio/mpeg", NULL, 0}, {"audio/x-mace", NULL, 0}, diff --git a/gst-libs/gst/utils/install-plugins.c b/gst-libs/gst/utils/install-plugins.c index 805ad36531..2da9e8ac44 100644 --- a/gst-libs/gst/utils/install-plugins.c +++ b/gst-libs/gst/utils/install-plugins.c @@ -18,6 +18,302 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsinstallplugins + * @short_description: Missing plugin installation support for applications + * + * + * Overview + * + * Using this API, applications can request the installation of missing + * GStreamer plugins. These may be missing decoders/demuxers or encoders/muxers + * for a certain format, sources or sinks for a certain URI protocol + * (e.g. 'http'), or certain elements known by their element factory name + * ('audioresample'). + * + * + * Whether plugin installation is supported or not depends on the operating + * system and/or distribution in question. The vendor of the operating system + * needs to make sure the necessary hooks and mechanisms are in place for + * plugin installation to work. See below for more detailed information. + * + * + * From the application perspective, plugin installation is usually triggered + * either + * + * + * when the application itself has found that it wants or needs to install a + * certain element + * + * + * when the application has been notified by an element (such as playbin or + * decodebin) that one or more plugins are missing and + * the application has decided that it wants to install one or more of those + * missing plugins + * + * + * + * Detail Strings + * + * The install functions in this section all take one or more 'detail strings'. + * These detail strings contain information about the type of plugin that + * needs to be installed (decoder, encoder, source, sink, or named element), + * and some additional information such GStreamer version used and a + * human-readable description of the component to install for user dialogs. + * + * + * Applications should not concern themselves with the composition of the + * string itself. They should regard the string as if it was a shared secret + * between GStreamer and the plugin installer application. + * + * + * Detail strings can be obtained using the function + * gst_missing_plugin_message_get_installer_detail() on a missing-plugin + * message. Such a message will either have been found by the application on + * a pipeline's #GstBus, or the application will have created it itself using + * gst_missing_element_message_new(), gst_missing_decoder_message_new(), + * gst_missing_encoder_message_new(), gst_missing_uri_sink_message_new(), or + * gst_missing_uri_source_message_new(). + * + * Plugin Installation from the Application Perspective + * + * For each GStreamer element/plugin/component that should be installed, the + * application needs one of those 'installer detail' string mentioned in the + * previous section. This string can be obtained, as already mentioned above, + * from a missing-plugin message using the function + * gst_missing_plugin_message_get_installer_detail(). The missing-plugin + * message is either posted by another element and then found on the bus + * by the application, or the application has created it itself as described + * above. + * + * + * The application will then call gst_install_plugins_async(), passing a + * #NULL-terminated array of installer detail strings, and a function that + * should be called when the installation of the plugins has finished + * (successfully or not). Optionally, a #GstInstallPluginsContext created + * with gst_install_plugins_context_new() may be passed as well. This way + * additional optional arguments like the application window's XID can be + * passed to the external installer application. + * + * + * gst_install_plugins_async() will return almost immediately, with the + * return code indicating whether plugin installation was started or not. + * If the necessary hooks for plugin installation are in place and an + * external installer application has in fact been called, the passed in + * function will be called with a result code as soon as the external installer + * has finished. If the result code indicates that new plugins have been + * installed, the application will want to call gst_update_registry() so the + * run-time plugin registry is updated and the new plugins are made available + * to the application. + * + * A Gtk/GLib main loop must be running in order for the result function to + * be called when the external installer has finished. If this is not the case, + * make sure to regularly call + * + * g_main_context_iteration (NULL,FALSE); + * + * from your code. + * + * + * Plugin Installation from the Vendor/Distribution Perspective + * + * 1. Installer hook + * + * + * When GStreamer applications initiate plugin installation via + * gst_install_plugins_async() or gst_install_plugins_sync(), a pre-defined + * helper application will be called. + * + * + * The exact path of the helper application to be called is set at compile + * time, usually by the ./configure script based on the + * install prefix. For a normal package build into the /usr + * prefix, this will usually default to + * /usr/libexec/gst-install-plugins-helper or + * /usr/lib/gst-install-plugins-helper. + * + * + * Vendors/distros who want to support GStreamer plugin installation should + * either provide such a helper script/application or use the + * ./configure option + * --with-install-plugins-helper=/path/to/installer to + * make GStreamer call an installer of their own directly. + * + * + * It is strongly recommended that vendors provide a small helper application + * as interlocutor to the real installer though, even more so if command line + * argument munging is required to transform the command line arguments + * passed by GStreamer to the helper application into arguments that are + * understood by the reeal installer. + * + * + * The helper application path defined at compile time can be overriden at + * runtime by setting the GST_INSTALL_PLUGINS_HELPER + * environment variable. This can be useful for testing/debugging purposes. + * + * + * 2. Arguments passed to the install helper + * + * + * GStreamer will pass the following arguments to the install helper (this is + * in addition to the path of the executable itself, which is by convention + * argv[0]): + * + * + * none to many optional arguments in the form of + * --foo-bar=val. Example: + * --transient-for=XID where XID is the X Window ID of + * the main window of the calling application (so the installer can make + * itself transient to that window). Unknown optional arguments should + * be ignored by the installer. + * + * + * one 'installer detail string' argument for each plugin to be installed; + * these strings will have a gstreamer.net prefix; the + * exact format of the detail string is explained below + * + * + * + * + * 3. Detail string describing the missing plugin + * + * + * The string is in UTF-8 encoding and is made up of several fields, separated + * by '|' characters (but neither the first nor the last character is a '|'). + * The fields are: + * + * + * plugin system identifier, ie. "gstreamer.net" + * + * This identifier determines the format of the rest of the detail string. + * Automatic plugin installers should not process detail strings with + * unknown identifiers. This allows other plugin-based libraries to use + * the same mechanism for their automatic plugin installation needs, or + * for the format to be changed should it turn out to be insufficient. + * + * + * plugin system version, e.g. "0.10" + * + * This is required so that when there is a GStreamer-0.12 or GStreamer-1.0 + * at some point in future, the different major versions can still co-exist + * and use the same plugin install mechanism in the same way. + * + * + * application identifier, e.g. "totem" + * + * This may also be in the form of "pid/12345" if the program name can't + * be obtained for some reason. + * + * + * human-readable localised description of the required component, + * e.g. "Vorbis audio decoder" + * + * + * identifier string for the required component (see below for details about + * how to map this to the package/plugin that needs installing), 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 + * + * + * + * + * optional further fields not yet specified + * + * + * + * + * An entire ID string might then look like this, for example: + * + * gstreamer.net|0.10|totem|Vorbis audio decoder|decoder-audio/x-vorbis + * + * + * + * Plugin installers parsing this ID string should expect further fields also + * separated by '|' symbols and either ignore them, warn the user, or error + * out when encountering them. + * + * + * 4. Exit codes the installer should return + * + * + * The installer should return one of the following exit codes when it exits: + * + * + * 0 if all of the requested plugins could be installed + * (#GST_INSTALL_PLUGINS_SUCCESS) + * + * + * 1 if no appropriate installation candidate for any of the requested + * plugins could be found. Only return this if nothing has been installed + * (#GST_INSTALL_PLUGINS_NOT_FOUND) + * + * + * 2 if an error occured during the installation. The application will + * assume that the user will already have seen an error message by the + * installer in this case and will usually not show another one + * (#GST_INSTALL_PLUGINS_ERROR) + * + * + * 3 if some of the requested plugins could be installed, but not all + * (#GST_INSTALL_PLUGINS_PARTIAL_SUCCESS) + * + * + * 4 if the user aborted the installation (#GST_INSTALL_PLUGINS_USER_ABORT) + * + * + * + * + * 5. How to map the required detail string to packages + * + * + * It is up to the vendor to find mechanism to map required components from + * the detail string to the actual packages/plugins to install. This could + * be a hardcoded list of mappings, for example, or be part of the packaging + * system metadata. + * + * + * GStreamer plugin files can be introspected for this information. The + * gst-inspect utility has a special command line option + * that will output information similar to what is required. For example + * + * $ gst-inspect-0.10 --print-plugin-auto-install-info /path/to/libgstvorbis.so + * + * should output something along the lines of + * + * decoder-audio/x-vorbis + * element-vorbisdec + * element-vorbisenc + * element-vorbisparse + * element-vorbistag + * encoder-audio/x-vorbis + * + * Note that in the encoder and decoder case the introspected caps can be more + * complex with additional fields, e.g. + * audio/mpeg,mpegversion=(int){2,4}, so they will not + * always exactly match the caps wanted by the application. It is up to the + * installer to deal with this (either by doing proper caps intersection using + * the GStreamer #GstCaps API, or by only taking into account the media type). + * + * + * Another potential source of problems are plugins such as ladspa or + * libvisual where the list of elements depends on the installed + * ladspa/libvisual plugins at the time. This is also up to the distribution + * to handle (but usually not relevant for playback applications). + * + * + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif diff --git a/gst-libs/gst/utils/missing-plugins.c b/gst-libs/gst/utils/missing-plugins.c index bada28e9e3..ac06aa06e4 100644 --- a/gst-libs/gst/utils/missing-plugins.c +++ b/gst-libs/gst/utils/missing-plugins.c @@ -17,6 +17,39 @@ * Boston, MA 02111-1307, USA. */ +/** + * SECTION:gstbaseutilsmissingplugins + * @short_description: Create, recognise and parse missing-plugins messages + * + * + * + * Functions to create, recognise and parse missing-plugins messages for + * applications and elements. + * + * + * Missing-plugin messages are posted on the bus by elements like decodebin + * or playbin if they can't find an appropriate source element or decoder + * element. The application can use these messages for two things: + * + * + * concise error/problem reporting to the user mentioning what exactly + * is missing, see gst_missing_plugin_message_get_description() + * + * + * initiate installation of missing plugins, see + * gst_missing_plugin_message_get_installer_detail() and + * gst_install_plugins_async() + * + * + * + * + * Applications may also create missing-plugin messages themselves to install + * required elements that are missing, using the install mechanism mentioned + * above. + * + * + */ + #ifdef HAVE_CONFIG_H # include "config.h" #endif