:right-sidebar: True

Registry
===================================================================

.. currentmodule:: gi.repository.Gst





.. class:: Registry(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gst.Object`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`





One registry holds the metadata of a set of plugins.

<emphasis role="bold">Design:</emphasis>

The :obj:`~gi.repository.Gst.Registry` object is a list of plugins and some functions for dealing
with them. Each :obj:`~gi.repository.Gst.Plugin` is matched 1-1 with a file on disk, and may or may
not be loaded at a given time.

The primary source, at all times, of plugin information is each plugin file
itself. Thus, if an application wants information about a particular plugin,
or wants to search for a feature that satisfies given criteria, the primary
means of doing so is to load every plugin and look at the resulting
information that is gathered in the default registry. Clearly, this is a time
consuming process, so we cache information in the registry file. The format
and location of the cache file is internal to gstreamer.

On startup, plugins are searched for in the plugin search path. The following
locations are checked in this order:

- location from --gst-plugin-path commandline option.
- the GST_PLUGIN_PATH environment variable.
- the GST_PLUGIN_SYSTEM_PATH environment variable.
- default locations (if GST_PLUGIN_SYSTEM_PATH is not set).
  Those default locations are:
  ``$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/``
  and ``$prefix/libs/gstreamer-$GST_API_VERSION/``\.
  `$XDG_DATA_HOME <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__ defaults to
  ``$HOME/.local/share``\.


The registry cache file is loaded from
``$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin``
(where $XDG_CACHE_HOME defaults to ``$HOME/.cache``\) or the file listed in the ``GST_REGISTRY``
env var. One reason to change the registry location is for testing.

For each plugin that is found in the plugin search path, there could be 3
possibilities for cached information:

- the cache may not contain information about a given file.
- the cache may have stale information.
- the cache may have current information.


In the first two cases, the plugin is loaded and the cache updated. In
addition to these cases, the cache may have entries for plugins that are not
relevant to the current process. These are marked as not available to the
current process. If the cache is updated for whatever reason, it is marked
dirty.

A dirty cache is written out at the end of initialization. Each entry is
checked to make sure the information is minimally valid. If not, the entry is
simply dropped.

Implementation notes:
--------------------------------------------------------------------------------

The "cache" and "registry" are different concepts and can represent
different sets of plugins. For various reasons, at init time, the cache is
stored in the default registry, and plugins not relevant to the current
process are marked with the :const:`~gi.repository.Gst.PluginFlags.CACHED` bit. These plugins are
removed at the end of initialization.




Methods
-------

.. rst-class:: interim-class

.. class:: Registry
   :no-index:


   .. method:: add_feature(feature: ~gi.repository.Gst.PluginFeature) -> bool

      Add the feature to the registry. The feature-added signal will be emitted.

      ``feature``\'s reference count will be incremented, and any floating
      reference will be removed (see :func:`~gi.repository.Gst.Object.ref_sink`)






      :param feature: the feature to add




   .. method:: add_plugin(plugin: ~gi.repository.Gst.Plugin) -> bool

      Add the plugin to the registry. The plugin-added signal will be emitted.

      ``plugin``\'s reference count will be incremented, and any floating
      reference will be removed (see :func:`~gi.repository.Gst.Object.ref_sink`)






      :param plugin: the plugin to add




   .. method:: check_feature_version(feature_name: str, min_major: int, min_minor: int, min_micro: int) -> bool

      Checks whether a plugin feature by the given name exists in
      ``registry`` and whether its version is at least the
      version required.






      :param feature_name: the name of the feature (e.g. "oggdemux")

      :param min_major: the minimum major version number

      :param min_minor: the minimum minor version number

      :param min_micro: the minimum micro version number




   .. method:: feature_filter(filter: ~typing.Callable[[~gi.repository.Gst.PluginFeature, ~typing.Any], bool], first: bool, user_data: ~typing.Any = None) -> list[~gi.repository.Gst.PluginFeature]

      Runs a filter against all features of the plugins in the registry
      and returns a GList with the results.
      If the first flag is set, only the first match is
      returned (as a list with a single object).






      :param filter: the filter to use

      :param first: only return first match

      :param user_data: user data passed to the filter function




   .. method:: find_feature(name: str, type: ~gobject.GType) -> ~gi.repository.Gst.PluginFeature | None

      Find the pluginfeature with the given name and type in the registry.






      :param name: the pluginfeature name to find

      :param type: the pluginfeature type to find




   .. method:: find_plugin(name: str) -> ~gi.repository.Gst.Plugin | None

      Find the plugin with the given name in the registry.
      The plugin will be reffed; caller is responsible for unreffing.






      :param name: the plugin name to find




   .. classmethod:: fork_is_enabled() -> bool

      By default GStreamer will perform scanning and rebuilding of the
      registry file using a helper child process.

      Applications might want to disable this behaviour with the
      :func:`~gi.repository.Gst.Registry.fork_set_enabled` function, in which case new plugins
      are scanned (and loaded) into the application process.









   .. classmethod:: fork_set_enabled() -> None

      Applications might want to disable/enable spawning of a child helper process
      when rebuilding the registry. See :func:`~gi.repository.Gst.Registry.fork_is_enabled` for more
      information.









   .. classmethod:: get() -> ~gi.repository.Gst.Registry

      Retrieves the singleton plugin registry. The caller does not own a
      reference on the registry, as it is alive as long as GStreamer is
      initialized.









   .. method:: get_feature_list(type: ~gobject.GType) -> list[~gi.repository.Gst.PluginFeature]

      Retrieves a ``GList`` of :obj:`~gi.repository.Gst.PluginFeature` of ``type``\.






      :param type: a :obj:`~gi.repository.GObject.Type`\.




   .. method:: get_feature_list_by_plugin(name: str) -> list[~gi.repository.Gst.PluginFeature]

      Retrieves a ``GList`` of features of the plugin with name ``name``\.






      :param name: a plugin name.




   .. method:: get_feature_list_cookie() -> int

      Returns the registry's feature list cookie. This changes
      every time a feature is added or removed from the registry.









   .. method:: get_plugin_list() -> list[~gi.repository.Gst.Plugin]

      Get a copy of all plugins registered in the given registry. The refcount
      of each element in the list in incremented.









   .. method:: lookup(filename: str) -> ~gi.repository.Gst.Plugin | None

      Look up a plugin in the given registry with the given filename.
      If found, plugin is reffed.






      :param filename: the name of the file to look up




   .. method:: lookup_feature(name: str) -> ~gi.repository.Gst.PluginFeature | None

      Find a :obj:`~gi.repository.Gst.PluginFeature` with ``name`` in ``registry``\.






      :param name: a :obj:`~gi.repository.Gst.PluginFeature` name




   .. method:: plugin_filter(filter: ~typing.Callable[[~gi.repository.Gst.Plugin, ~typing.Any], bool], first: bool, user_data: ~typing.Any = None) -> list[~gi.repository.Gst.Plugin]

      Runs a filter against all plugins in the registry and returns a ``GList`` with
      the results. If the first flag is set, only the first match is
      returned (as a list with a single object).
      Every plugin is reffed; use :func:`~gi.repository.Gst.Plugin.list_free` after use, which
      will unref again.






      :param filter: the filter to use

      :param first: only return first match

      :param user_data: user data passed to the filter function




   .. method:: remove_feature(feature: ~gi.repository.Gst.PluginFeature) -> None

      Remove the feature from the registry.

      MT safe.






      :param feature: the feature to remove




   .. method:: remove_plugin(plugin: ~gi.repository.Gst.Plugin) -> None

      Remove the plugin from the registry.

      MT safe.






      :param plugin: the plugin to remove




   .. method:: scan_path(path: str) -> bool

      Scan the given path for plugins to add to the registry. The syntax of the
      path is specific to the registry.






      :param path: the path to scan










Signals
-------

.. rst-class:: interim-class

.. class:: Registry.signals
   :no-index:
   

   .. method:: feature_added(feature: ~gi.repository.Gst.PluginFeature) -> None

      The type of the None singleton.







      :param feature: the feature that has been added




   .. method:: plugin_added(plugin: ~gi.repository.Gst.Plugin) -> None

      The type of the None singleton.







      :param plugin: the plugin that has been added










Fields
------

.. rst-class:: interim-class

.. class:: Registry
   :no-index:
   

   .. attribute:: object

      






   .. attribute:: priv