Chris@12: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@12: Chris@12: /* Chris@12: Vamp Chris@12: Chris@12: An API for audio analysis and feature extraction plugins. Chris@12: Chris@12: Centre for Digital Music, Queen Mary, University of London. Chris@12: Copyright 2006-2009 Chris Cannam and QMUL. Chris@12: Chris@12: Permission is hereby granted, free of charge, to any person Chris@12: obtaining a copy of this software and associated documentation Chris@12: files (the "Software"), to deal in the Software without Chris@12: restriction, including without limitation the rights to use, copy, Chris@12: modify, merge, publish, distribute, sublicense, and/or sell copies Chris@12: of the Software, and to permit persons to whom the Software is Chris@12: furnished to do so, subject to the following conditions: Chris@12: Chris@12: The above copyright notice and this permission notice shall be Chris@12: included in all copies or substantial portions of the Software. Chris@12: Chris@12: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@12: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@12: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@12: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR Chris@12: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@12: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@12: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@12: Chris@12: Except as contained in this notice, the names of the Centre for Chris@12: Digital Music; Queen Mary, University of London; and Chris Cannam Chris@12: shall not be used in advertising or otherwise to promote the sale, Chris@12: use or other dealings in this Software without prior written Chris@12: authorization. Chris@12: */ Chris@12: Chris@12: #ifndef _VAMP_PLUGIN_LOADER_H_ Chris@12: #define _VAMP_PLUGIN_LOADER_H_ Chris@12: Chris@12: #include Chris@12: #include Chris@12: #include Chris@12: Chris@12: #include "hostguard.h" Chris@12: #include "PluginWrapper.h" Chris@12: Chris@12: _VAMP_SDK_HOSTSPACE_BEGIN(PluginLoader.h) Chris@12: Chris@12: namespace Vamp { Chris@12: Chris@12: class Plugin; Chris@12: Chris@12: namespace HostExt { Chris@12: Chris@12: /** Chris@12: * \class PluginLoader PluginLoader.h Chris@12: * Chris@12: * Vamp::HostExt::PluginLoader is a convenience class for discovering Chris@12: * and loading Vamp plugins using the typical plugin-path, library Chris@12: * naming, and categorisation conventions described in the Vamp SDK Chris@12: * documentation. This class is intended to greatly simplify the task Chris@12: * of becoming a Vamp plugin host for any C++ application. Chris@12: * Chris@12: * Hosts are not required by the Vamp specification to use the same Chris@12: * plugin search path and naming conventions as implemented by this Chris@12: * class, and are certainly not required to use this actual class. Chris@12: * But we do strongly recommend it. Chris@12: * Chris@12: * \note This class was introduced in version 1.1 of the Vamp plugin SDK. Chris@12: */ Chris@12: Chris@12: class PluginLoader Chris@12: { Chris@12: public: Chris@12: /** Chris@12: * Obtain a pointer to the singleton instance of PluginLoader. Chris@12: * Use this to obtain your loader object. Chris@12: */ Chris@12: static PluginLoader *getInstance(); Chris@12: Chris@12: /** Chris@12: * PluginKey is a string type that is used to identify a plugin Chris@12: * uniquely within the scope of "the current system". It consists Chris@12: * of the lower-cased base name of the plugin library, a colon Chris@12: * separator, and the identifier string for the plugin. It is Chris@12: * only meaningful in the context of a given plugin path (the one Chris@12: * returned by PluginHostAdapter::getPluginPath()). Chris@12: * Chris@12: * Use composePluginKey() to construct a plugin key from a known Chris@12: * plugin library name and identifier. Chris@12: * Chris@12: * Note: the fact that the library component of the key is Chris@12: * lower-cased implies that library names are matched Chris@12: * case-insensitively by the PluginLoader class, regardless of the Chris@12: * case sensitivity of the underlying filesystem. (Plugin Chris@12: * identifiers _are_ case sensitive, however.) Also, it is not Chris@12: * possible to portably extract a working library name from a Chris@12: * plugin key, as the result may fail on case-sensitive Chris@12: * filesystems. Use getLibraryPathForPlugin() instead. Chris@12: */ Chris@12: typedef std::string PluginKey; Chris@12: Chris@12: /** Chris@12: * PluginKeyList is a sequence of plugin keys, such as returned by Chris@12: * listPlugins(). Chris@12: */ Chris@12: typedef std::vector PluginKeyList; Chris@12: Chris@12: /** Chris@12: * PluginCategoryHierarchy is a sequence of general->specific Chris@12: * category names, as may be associated with a single plugin. Chris@12: * This sequence describes the location of a plugin within a Chris@12: * category forest, containing the human-readable names of the Chris@12: * plugin's category tree root, followed by each of the nodes down Chris@12: * to the leaf containing the plugin. Chris@12: * Chris@12: * \see getPluginCategory() Chris@12: */ Chris@12: typedef std::vector PluginCategoryHierarchy; Chris@12: Chris@12: /** Chris@12: * Search for all available Vamp plugins, and return a list of Chris@12: * them in the order in which they were found. Chris@12: */ Chris@12: PluginKeyList listPlugins(); Chris@12: Chris@12: /** Chris@12: * AdapterFlags contains a set of values that may be OR'd together Chris@12: * to indicate in which circumstances PluginLoader should use a Chris@12: * plugin adapter to make a plugin easier to use for a host that Chris@12: * does not want to cater for complex features. Chris@12: * Chris@12: * The available flags are: Chris@12: * Chris@12: * ADAPT_INPUT_DOMAIN - If the plugin expects frequency domain Chris@12: * input, wrap it in a PluginInputDomainAdapter that automatically Chris@12: * converts the plugin to one that expects time-domain input. Chris@12: * This enables a host to accommodate time- and frequency-domain Chris@12: * plugins without needing to do any conversion itself. Chris@12: * Chris@12: * ADAPT_CHANNEL_COUNT - Wrap the plugin in a PluginChannelAdapter Chris@12: * to handle any mismatch between the number of channels of audio Chris@12: * the plugin can handle and the number available in the host. Chris@12: * This enables a host to use plugins that may require the input Chris@12: * to be mixed down to mono, etc., without having to worry about Chris@12: * doing that itself. Chris@12: * Chris@12: * ADAPT_BUFFER_SIZE - Wrap the plugin in a PluginBufferingAdapter Chris@12: * permitting the host to provide audio input using any block Chris@12: * size, with no overlap, regardless of the plugin's preferred Chris@12: * block size (suitable for hosts that read from non-seekable Chris@12: * streaming media, for example). This adapter introduces some Chris@12: * run-time overhead and also changes the semantics of the plugin Chris@12: * slightly (see the PluginBufferingAdapter header documentation Chris@12: * for details). Chris@12: * Chris@12: * ADAPT_ALL_SAFE - Perform all available adaptations that are Chris@12: * meaningful for the plugin and "safe". Currently this means to Chris@12: * ADAPT_INPUT_DOMAIN if the plugin wants FrequencyDomain input; Chris@12: * ADAPT_CHANNEL_COUNT always; and ADAPT_BUFFER_SIZE never. Chris@12: * Chris@12: * ADAPT_ALL - Perform all available adaptations that are Chris@12: * meaningful for the plugin. Chris@12: * Chris@12: * See PluginInputDomainAdapter, PluginChannelAdapter and Chris@12: * PluginBufferingAdapter for more details of the classes that the Chris@12: * loader may use if these flags are set. Chris@12: */ Chris@12: enum AdapterFlags { Chris@12: Chris@12: ADAPT_INPUT_DOMAIN = 0x01, Chris@12: ADAPT_CHANNEL_COUNT = 0x02, Chris@12: ADAPT_BUFFER_SIZE = 0x04, Chris@12: Chris@12: ADAPT_ALL_SAFE = 0x03, Chris@12: Chris@12: ADAPT_ALL = 0xff Chris@12: }; Chris@12: Chris@12: /** Chris@12: * Load a Vamp plugin, given its identifying key. If the plugin Chris@12: * could not be loaded, returns 0. Chris@12: * Chris@12: * The returned plugin should be deleted (using the standard C++ Chris@12: * delete keyword) after use. Chris@12: * Chris@12: * \param adapterFlags a bitwise OR of the values in the AdapterFlags Chris@12: * enumeration, indicating under which circumstances an adapter should be Chris@12: * used to wrap the original plugin. If adapterFlags is 0, no Chris@12: * optional adapters will be used. Otherwise, the returned plugin Chris@12: * may be of an adapter class type which will behave identically Chris@12: * to the original plugin, apart from any particular features Chris@12: * implemented by the adapter itself. Chris@12: * Chris@12: * \see AdapterFlags, PluginInputDomainAdapter, PluginChannelAdapter Chris@12: */ Chris@12: Plugin *loadPlugin(PluginKey key, Chris@12: float inputSampleRate, Chris@12: int adapterFlags = 0); Chris@12: Chris@12: /** Chris@12: * Given a Vamp plugin library name and plugin identifier, return Chris@12: * the corresponding plugin key in a form suitable for passing in to Chris@12: * loadPlugin(). Chris@12: */ Chris@12: PluginKey composePluginKey(std::string libraryName, Chris@12: std::string identifier); Chris@12: Chris@12: /** Chris@12: * Return the category hierarchy for a Vamp plugin, given its Chris@12: * identifying key. Chris@12: * Chris@12: * If the plugin has no category information, return an empty Chris@12: * hierarchy. Chris@12: * Chris@12: * \see PluginCategoryHierarchy Chris@12: */ Chris@12: PluginCategoryHierarchy getPluginCategory(PluginKey plugin); Chris@12: Chris@12: /** Chris@12: * Return the file path of the dynamic library from which the Chris@12: * given plugin will be loaded (if available). Chris@12: */ Chris@12: std::string getLibraryPathForPlugin(PluginKey plugin); Chris@12: Chris@12: protected: Chris@12: PluginLoader(); Chris@12: virtual ~PluginLoader(); Chris@12: Chris@12: class Impl; Chris@12: Impl *m_impl; Chris@12: Chris@12: static PluginLoader *m_instance; Chris@12: }; Chris@12: Chris@12: } Chris@12: Chris@12: } Chris@12: Chris@12: _VAMP_SDK_HOSTSPACE_END(PluginLoader.h) Chris@12: Chris@12: #endif Chris@12: