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