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