Vamp::HostExt::PluginLoader Class Reference

Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp plugins using the typical plugin-path, library naming, and categorisation conventions described in the Vamp SDK documentation. More...

`#include <vamp-hostsdk/PluginLoader.h>`

## Public Types

enum | AdapterFlags { ADAPT_INPUT_DOMAIN = 0x01, ADAPT_CHANNEL_COUNT = 0x02, ADAPT_BUFFER_SIZE = 0x04, ADAPT_ALL_SAFE = 0x03, ADAPT_ALL = 0xff }
| AdapterFlags contains a set of values that may be OR'd together to indicate in which circumstances PluginLoader should use a plugin adapter to make a plugin easier to use for a host that does not want to cater for complex features. More...
typedef std::string | PluginKey
| PluginKey is a string type that is used to identify a plugin uniquely within the scope of "the current system". More...
typedef std::vector< PluginKey > | PluginKeyList
| PluginKeyList is a sequence of plugin keys, such as returned by listPlugins(). More...
typedef std::vector< std::string > | PluginCategoryHierarchy
| PluginCategoryHierarchy is a sequence of general->specific category names, as may be associated with a single plugin. More...

## Public Member Functions

PluginKeyList | listPlugins ()
| Search for all available Vamp plugins, and return a list of them in the order in which they were found. More...
PluginKeyList | listPluginsIn (std::vector< std::string > libraryNames)
| Search for available Vamp plugins in libraries with the given library names, and return a list of them in the order in which they were found. More...
PluginKeyList | listPluginsNotIn (std::vector< std::string > libraryNames)
| Search for available Vamp plugins in libraries other than those with the given library names, and return a list of them in the order in which they were found. More...
Plugin * | loadPlugin (PluginKey key, float inputSampleRate, int adapterFlags=0)
| Load a Vamp plugin, given its identifying key. More...
PluginKey | composePluginKey (std::string libraryName, std::string identifier)
| Given a Vamp plugin library name and plugin identifier, return the corresponding plugin key in a form suitable for passing in to loadPlugin(). More...
PluginCategoryHierarchy | getPluginCategory (PluginKey plugin)
| Return the category hierarchy for a Vamp plugin, given its identifying key. More...
std::string | getLibraryPathForPlugin (PluginKey plugin)
| Return the file path of the dynamic library from which the given plugin will be loaded (if available). More...

## Static Public Member Functions

static PluginLoader * | getInstance ()
| Obtain a pointer to the singleton instance of PluginLoader. More...

## Protected Member Functions

| PluginLoader ()
virtual | ~PluginLoader ()

## Protected Attributes

Impl * | m_impl

## Static Protected Attributes

static PluginLoader * | m_instance

## Detailed Description

Vamp::HostExt::PluginLoader is a convenience class for discovering and loading Vamp plugins using the typical plugin-path, library naming, and categorisation conventions described in the Vamp SDK documentation.

This class is intended to greatly simplify the task of becoming a Vamp plugin host for any C++ application.

Hosts are not required by the Vamp specification to use the same plugin search path and naming conventions as implemented by this class, and are certainly not required to use this actual class. But we do strongly recommend it.

This class is not thread-safe; use it from a single application thread, or guard access to it with a mutex.

Note
  This class was introduced in version 1.1 of the Vamp plugin SDK.

Definition at line 75 of file PluginLoader.h.

## Member Typedef Documentation

## PluginKey

typedef std::string Vamp::HostExt::PluginLoader::PluginKey

PluginKey is a string type that is used to identify a plugin uniquely within the scope of "the current system".

It consists of the lower-cased base name of the plugin library, a colon separator, and the identifier string for the plugin. It is only meaningful in the context of a given plugin path (the one returned by PluginHostAdapter::getPluginPath()).

Use composePluginKey() to construct a plugin key from a known plugin library name and identifier.

Note: the fact that the library component of the key is lower-cased implies that library names are matched case-insensitively by the PluginLoader class, regardless of the case sensitivity of the underlying filesystem. (Plugin identifiers are case sensitive, however.) Also, it is not possible to portably extract a working library name from a plugin key, as the result may fail on case-sensitive filesystems. Use getLibraryPathForPlugin() instead.

Definition at line 104 of file PluginLoader.h.

## PluginKeyList

typedef std::vector<PluginKey> Vamp::HostExt::PluginLoader::PluginKeyList

PluginKeyList is a sequence of plugin keys, such as returned by listPlugins().

Definition at line 110 of file PluginLoader.h.

## PluginCategoryHierarchy

typedef std::vector<std::string> Vamp::HostExt::PluginLoader::PluginCategoryHierarchy

PluginCategoryHierarchy is a sequence of general->specific category names, as may be associated with a single plugin.

This sequence describes the location of a plugin within a category forest, containing the human-readable names of the plugin's category tree root, followed by each of the nodes down to the leaf containing the plugin.

See also
  getPluginCategory()

Definition at line 122 of file PluginLoader.h.

## Member Enumeration Documentation

## AdapterFlags

enum Vamp::HostExt::PluginLoader::AdapterFlags

AdapterFlags contains a set of values that may be OR'd together to indicate in which circumstances PluginLoader should use a plugin adapter to make a plugin easier to use for a host that does not want to cater for complex features.

The available flags are:

ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain input, wrap it in a PluginInputDomainAdapter that automatically converts the plugin to one that expects time-domain input. This enables a host to accommodate time- and frequency-domain plugins without needing to do any conversion itself.

ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter to handle any mismatch between the number of channels of audio the plugin can handle and the number available in the host. This enables a host to use plugins that may require the input to be mixed down to mono, etc., without having to worry about doing that itself.

ADAPT_BUFFER_SIZE - Wrap the plugin in a PluginBufferingAdapter permitting the host to provide audio input using any block size, with no overlap, regardless of the plugin's preferred block size (suitable for hosts that read from non-seekable streaming media, for example). This adapter introduces some run-time overhead and also changes the semantics of the plugin slightly (see the PluginBufferingAdapter header documentation for details).

ADAPT_ALL_SAFE - Perform all available adaptations that are meaningful for the plugin and "safe". Currently this means to ADAPT_INPUT_DOMAIN if the plugin wants FrequencyDomain input; ADAPT_CHANNEL_COUNT always; and ADAPT_BUFFER_SIZE never.

ADAPT_ALL - Perform all available adaptations that are meaningful for the plugin.

See PluginInputDomainAdapter, PluginChannelAdapter and PluginBufferingAdapter for more details of the classes that the loader may use if these flags are set.

Enumerator
ADAPT_INPUT_DOMAIN |
ADAPT_CHANNEL_COUNT |
ADAPT_BUFFER_SIZE |
ADAPT_ALL_SAFE |
ADAPT_ALL |

Definition at line 200 of file PluginLoader.h.

## Constructor & Destructor Documentation

## PluginLoader()

Vamp::HostExt::PluginLoader::PluginLoader | ( |  | ) |

protected

## ~PluginLoader()

virtual Vamp::HostExt::PluginLoader::~PluginLoader | ( |  | ) |

protected virtual

## Member Function Documentation

## getInstance()

static PluginLoader* Vamp::HostExt::PluginLoader::getInstance | ( |  | ) |

static

Obtain a pointer to the singleton instance of PluginLoader.

Use this to obtain your loader object.

## listPlugins()

PluginKeyList Vamp::HostExt::PluginLoader::listPlugins | ( |  | ) |

Search for all available Vamp plugins, and return a list of them in the order in which they were found.

Referenced by enumeratePlugins(), and printPluginCategoryList().

## listPluginsIn()

PluginKeyList Vamp::HostExt::PluginLoader::listPluginsIn | ( | std::vector< std::string > | libraryNames | ) |

Search for available Vamp plugins in libraries with the given library names, and return a list of them in the order in which they were found.

Do not attempt to load any plugin libraries other than those named.

The library names should be supplied without path or suffix. For example, use "vamp-example-plugins" to find plugins in /install/path/of/vamp-example-plugins.dll (or .so etc). This is the same concept of "library name" as appears in the plugin key:

See also
  composePluginKey().

## listPluginsNotIn()

PluginKeyList Vamp::HostExt::PluginLoader::listPluginsNotIn | ( | std::vector< std::string > | libraryNames | ) |

Search for available Vamp plugins in libraries other than those with the given library names, and return a list of them in the order in which they were found.

Do not attempt to load any of the libraries named.

The library names should be supplied without path or suffix. For example, use "vamp-example-plugins" to find plugins not appearing in /install/path/of/vamp-example-plugins.dll (or .so etc). This is the same concept of "library name" as appears in the plugin key:

See also
  composePluginKey().

## loadPlugin()

Plugin* Vamp::HostExt::PluginLoader::loadPlugin | ( | PluginKey | key,
|  | float | inputSampleRate,
|  | int | adapterFlags = `0`
| ) |  |

Load a Vamp plugin, given its identifying key.

If the plugin could not be loaded, returns 0.

The returned plugin should be deleted (using the standard C++ delete keyword) after use.

Parameters

  adapterFlags

  a bitwise OR of the values in the AdapterFlags enumeration, indicating under which circumstances an adapter should be used to wrap the original plugin. If adapterFlags is 0, no optional adapters will be used. Otherwise, the returned plugin may be of an adapter class type which will behave identically to the original plugin, apart from any particular features implemented by the adapter itself.

See also
  AdapterFlags, PluginInputDomainAdapter, PluginChannelAdapter

Referenced by enumeratePlugins(), printPluginCategoryList(), and runPlugin().

## composePluginKey()

PluginKey Vamp::HostExt::PluginLoader::composePluginKey | ( | std::string | libraryName,
|  | std::string | identifier
| ) |  |

Given a Vamp plugin library name and plugin identifier, return the corresponding plugin key in a form suitable for passing in to loadPlugin().

Referenced by runPlugin().

## getPluginCategory()

PluginCategoryHierarchy Vamp::HostExt::PluginLoader::getPluginCategory | ( | PluginKey | plugin | ) |

Return the category hierarchy for a Vamp plugin, given its identifying key.

If the plugin has no category information, return an empty hierarchy.

See also
  PluginCategoryHierarchy

Referenced by enumeratePlugins(), and printPluginCategoryList().

## getLibraryPathForPlugin()

std::string Vamp::HostExt::PluginLoader::getLibraryPathForPlugin | ( | PluginKey | plugin | ) |

Return the file path of the dynamic library from which the given plugin will be loaded (if available).

Referenced by enumeratePlugins().

## Member Data Documentation

## m_impl

Impl* Vamp::HostExt::PluginLoader::m_impl

protected

Definition at line 261 of file PluginLoader.h.

## m_instance

PluginLoader* Vamp::HostExt::PluginLoader::m_instance

static protected

Definition at line 264 of file PluginLoader.h.

The documentation for this class was generated from the following file:

- PluginLoader.h