GI.Gst.Objects.Plugin

GStreamer is extensible, so Element instances can be loaded at runtime. A plugin system can provide one or more of the basic <application>GStreamer</application> PluginFeature subclasses.

A plugin should export a symbol <symbol>gst_plugin_desc</symbol> that is a struct of type PluginDesc. the plugin loader will check the version of the core library the plugin was linked against and will create a new Plugin. It will then call the PluginInitFunc function that was provided in the <symbol>gst_plugin_desc</symbol>.

Once you have a handle to a Plugin (e.g. from the Registry), you can add any object that subclasses PluginFeature.

Usually plugins are always automatically loaded so you don't need to call pluginLoad explicitly to bring it into memory. There are options to statically link plugins to an app or even use GStreamer without a plugin repository in which case pluginLoad can be needed to bring the plugin into memory.

Exported types

newtype Plugin

Memory-managed wrapper type.

Constructors

Plugin (ManagedPtr Plugin)

Instances

GObject Plugin

Defined in GI.Gst.Objects.Plugin

Methods

gobjectType :: IO GType

HasParentTypes Plugin

Defined in GI.Gst.Objects.Plugin

type ParentTypes Plugin

Defined in GI.Gst.Objects.Plugin

type ParentTypes Plugin = Object ': (Object ': ([] :: [Type]))

class (GObject o, IsDescendantOf Plugin o) => IsPlugin o

Type class for types which can be safely cast to Plugin, for instance with toPlugin.

Instances

(GObject o, IsDescendantOf Plugin o) => IsPlugin o

Defined in GI.Gst.Objects.Plugin

toPlugin :: (MonadIO m, IsPlugin o) => o -> m Plugin

Cast to Plugin, for types for which this is known to be safe. For general casts, use castTo.

noPlugin :: Maybe Plugin

A convenience alias for Nothing :: Maybe Plugin.

Methods

addDependency

pluginAddDependency

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: a Plugin

-> Maybe [Text]

envVars: Nothing-terminated array of environment variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or Nothing. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins".

-> Maybe [Text]

paths: Nothing-terminated array of directories/paths where dependent files may be, or Nothing.

-> Maybe [Text]

names: Nothing-terminated array of file names (or file name suffixes, depending on flags) to be used in combination with the paths from paths and/or the paths extracted from the environment variables in envVars, or Nothing.

-> [PluginDependencyFlags]

flags: optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

-> m ()

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

addDependencySimple

pluginAddDependencySimple

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: the Plugin

-> Maybe Text

envVars: one or more environment variables (separated by ':', ';' or ','), or Nothing. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"

-> Maybe Text

paths: one ore more directory paths (separated by ':' or ';' or ','), or Nothing. Example: "/usr/lib/mystuff/plugins"

-> Maybe Text

names: one or more file names or file name suffixes (separated by commas), or Nothing

-> [PluginDependencyFlags]

flags: optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

-> m ()

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

Convenience wrapper function for pluginAddDependency which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above).

getCacheData

pluginGetCacheData

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: a plugin

-> m (Maybe Structure)

Returns: The cached data as a Structure or Nothing.

Gets the plugin specific data cache. If it is Nothing there is no cached data stored. This is the case when the registry is getting rebuilt.

getDescription

pluginGetDescription

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get long name of

-> m Text

Returns: the long name of the plugin

Get the long descriptive name of the plugin

getFilename

pluginGetFilename

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the filename of

-> m [Char]

Returns: the filename of the plugin

get the filename of the plugin

getLicense

pluginGetLicense

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the license of

-> m Text

Returns: the license of the plugin

get the license of the plugin

getName

pluginGetName

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the name of

-> m Text

Returns: the name of the plugin

Get the short name of the plugin

getOrigin

pluginGetOrigin

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the origin of

-> m Text

Returns: the origin of the plugin

get the URL where the plugin comes from

getPackage

pluginGetPackage

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the package of

-> m Text

Returns: the package of the plugin

get the package the plugin belongs to.

getReleaseDateString

pluginGetReleaseDateString

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the release date of

-> m (Maybe Text)

Returns: the date string of the plugin, or Nothing if not available.

Get the release date (and possibly time) in form of a string, if available.

For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain a time component after the date as well, in which case the string will be formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").

There may be plugins that do not have a valid release date set on them.

getSource

pluginGetSource

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the source of

-> m Text

Returns: the source of the plugin

get the source module the plugin belongs to.

getVersion

pluginGetVersion

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to get the version of

-> m Text

Returns: the version of the plugin

get the version of the plugin

isLoaded

pluginIsLoaded

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to query

-> m Bool

Returns: True is loaded, False otherwise

queries if the plugin is loaded into memory

listFree

pluginListFree

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> [a]

list: list of Plugin

-> m ()

Unrefs each member of list, then frees the list.

load

pluginLoad

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: plugin to load

-> m (Maybe Plugin)

Returns: a reference to a loaded plugin, or Nothing on error.

Loads plugin. Note that the *return value* is the loaded plugin; plugin is untouched. The normal use pattern of this function goes like this:

GstPlugin *loaded_plugin;
loaded_plugin = gst_plugin_load (plugin);
// presumably, we're no longer interested in the potentially-unloaded plugin
gst_object_unref (plugin);
plugin = loaded_plugin;

loadByName

pluginLoadByName

Arguments

:: (HasCallStack, MonadIO m)

=> Text

name: name of plugin to load

-> m (Maybe Plugin)

Returns: a reference to a loaded plugin, or Nothing on error.

Load the named plugin. Refs the plugin.

loadFile

pluginLoadFile

Arguments

:: (HasCallStack, MonadIO m)

=> [Char]

filename: the plugin filename to load

-> m Plugin

Returns: a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or Nothing if an error occurred. (Can throw GError)

Loads the given plugin and refs it. Caller needs to unref after use.

registerStatic

pluginRegisterStatic

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

majorVersion: the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here

-> Int32

minorVersion: the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here

-> Text

name: a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)

-> Text

description: description of the plugin

-> PluginInitFunc

initFunc: pointer to the init function of this plugin.

-> Text

version: version string of the plugin

-> Text

license: effective license of plugin. Must be one of the approved licenses (see PluginDesc above) or the plugin will not be registered.

-> Text

source: source module plugin belongs to

-> Text

package: shipped package plugin belongs to

-> Text

origin: URL to provider of plugin

-> m Bool

Returns: True if the plugin was registered correctly, otherwise False.

Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file).

You must make sure that GStreamer has been initialised (with init or via gst_init_get_option_group()) before calling this function.

registerStaticFull

pluginRegisterStaticFull

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

majorVersion: the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here

-> Int32

minorVersion: the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here

-> Text

name: a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)

-> Text

description: description of the plugin

-> PluginInitFullFunc

initFullFunc: pointer to the init function with user data of this plugin.

-> Text

version: version string of the plugin

-> Text

license: effective license of plugin. Must be one of the approved licenses (see PluginDesc above) or the plugin will not be registered.

-> Text

source: source module plugin belongs to

-> Text

package: shipped package plugin belongs to

-> Text

origin: URL to provider of plugin

-> m Bool

Returns: True if the plugin was registered correctly, otherwise False.

Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file) with a PluginInitFullFunc which allows user data to be passed to the callback function (useful for bindings).

You must make sure that GStreamer has been initialised (with init or via gst_init_get_option_group()) before calling this function.

setCacheData

pluginSetCacheData

Arguments

:: (HasCallStack, MonadIO m, IsPlugin a)

=> a

plugin: a plugin

-> Structure

cacheData: a structure containing the data to cache

-> m ()

Adds plugin specific data to cache. Passes the ownership of the structure to the plugin.

The cache is flushed every time the registry is rebuilt.