# HG changeset patch # User cannam # Date 1180710051 0 # Node ID fe5486ee1c704e2dca32d13145324c6f314b74ef # Parent 97c5ac99d725406897334ce12cd0faa1e429f2ef * Documentation diff -r 97c5ac99d725 -r fe5486ee1c70 README --- a/README Fri Jun 01 13:53:42 2007 +0000 +++ b/README Fri Jun 01 15:00:51 2007 +0000 @@ -77,6 +77,28 @@ plugin's C API back into a Vamp::Plugin object. Hosts should link with -lvamp-hostsdk. + * vamp-sdk/hostext + +Additional C++ classes to make a host's life easier. + +Vamp::HostExt::PluginLoader provides a very simple interface for a +host to discover, load, and find out category information about the +available plugins. Most "casual" Vamp hosts will probably want to use +this class. + +Vamp::HostExt::PluginInputDomainAdapter provides a simple means for +hosts to handle plugins that expect frequency-domain input, without +having to convert the input themselves. + +Vamp::HostExt::PluginChannelAdapter provides a simple means for hosts +to use plugins that do not necessarily support the same number of +audio channels as they have available, without having to apply a +channel management / mixdown policy themselves. + +The PluginLoader can use the input domain and channel adapters +automatically to make the entire conversion process transparent to the +host if required. + * examples Example plugins implemented using the C++ classes. ZeroCrossing diff -r 97c5ac99d725 -r fe5486ee1c70 vamp-sdk/hostext/PluginChannelAdapter.h --- a/vamp-sdk/hostext/PluginChannelAdapter.h Fri Jun 01 13:53:42 2007 +0000 +++ b/vamp-sdk/hostext/PluginChannelAdapter.h Fri Jun 01 15:00:51 2007 +0000 @@ -78,6 +78,22 @@ * * Hosts requiring a different channel policy from the above will need * to implement it themselves, instead of using PluginChannelAdapter. + * + * Note that PluginChannelAdapter does not override the minimum and + * maximum channel counts returned by the wrapped plugin. The host + * will need to be aware that it is using a PluginChannelAdapter, and + * be prepared to ignore these counts as necessary. (This contrasts + * with the approach used in PluginInputDomainAdapter, which aims to + * make the host completely unaware of which underlying input domain + * is in fact in use.) + * + * The rationale for this is that a host may wish to use the + * PluginChannelAdapter but still discriminate in some way on the + * basis of the number of channels actually supported. For example, a + * simple stereo audio host may prefer to reject plugins that require + * more than two channels on the grounds that doesn't actually + * understand what they are for, rather than allow the channel adapter + * to make a potentially meaningless channel conversion for them. */ class PluginChannelAdapter : public PluginWrapper diff -r 97c5ac99d725 -r fe5486ee1c70 vamp-sdk/hostext/PluginInputDomainAdapter.h --- a/vamp-sdk/hostext/PluginInputDomainAdapter.h Fri Jun 01 13:53:42 2007 +0000 +++ b/vamp-sdk/hostext/PluginInputDomainAdapter.h Fri Jun 01 15:00:51 2007 +0000 @@ -44,27 +44,34 @@ namespace HostExt { /** - * An adapter that converts time-domain input into frequency-domain - * input for plugins that need it. In every other respect this - * adapter behaves like the plugin it wraps. The wrapped plugin may - * be a time-domain plugin, in which case this wrapper does nothing. + * PluginInputDomainAdapter is a Vamp plugin adapter that converts + * time-domain input into frequency-domain input for plugins that need + * it. This permits a host to use time- and frequency-domain plugins + * interchangeably without needing to handle the conversion itself. * - * Uses a Hanning windowed FFT. The FFT implementation is not the - * fastest, so a host can do much better if it cares enough, but it is - * simple and self-contained. + * This adapter uses a basic Hanning windowed FFT that supports + * power-of-two block sizes only. If a frequency domain plugin + * requests a non-power-of-two blocksize, the adapter will adjust it + * to a nearby power of two instead. Thus, getPreferredBlockSize() + * will always return a power of two if the wrapped plugin is a + * frequency domain one. If the plugin doesn't accept the adjusted + * power of two block size, initialise() will fail. * - * Note that this adapter does not support non-power-of-two block - * sizes. + * The adapter provides no way for the host to discover whether the + * underlying plugin is actually a time or frequency domain plugin + * (except that if the preferred block size is not a power of two, it + * must be a time domain plugin). + * + * The FFT implementation is simple and self-contained, but unlikely + * to be the fastest available: a host can usually do better if it + * cares enough. + * + * In every respect other than its input domain handling, the + * PluginInputDomainAdapter behaves identically to the plugin that it + * wraps. The wrapped plugin will be deleted when the wrapper is + * deleted. */ -//!!! It would also be nice to have a channel wrapper, which deals -//with mixing down channels if the plugin needs a different number -//from the input source. It would have some sort of mixdown/channel -//input policy selection. Probably this class and that one should -//both inherit a PluginAdapter class which contains a plugin and -//delegates all calls through to it; the subclass can then override -//only the ones it needs to handle. - class PluginInputDomainAdapter : public PluginWrapper { public: diff -r 97c5ac99d725 -r fe5486ee1c70 vamp-sdk/hostext/PluginLoader.h --- a/vamp-sdk/hostext/PluginLoader.h Fri Jun 01 13:53:42 2007 +0000 +++ b/vamp-sdk/hostext/PluginLoader.h Fri Jun 01 15:00:51 2007 +0000 @@ -49,31 +49,134 @@ namespace HostExt { +/** + * 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 it's recommended, for sound practical reasons. + */ + class PluginLoader { public: + /** + * PluginLoader is a singleton class. This function returns a + * pointer to the single instance of it. Use this to obtain your + * loader object. + */ static PluginLoader *getInstance(); + /** + * PluginKey is a string type that is used to identify a plugin + * uniquely within the scope of "the current system". It consists + * of the 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. + */ typedef std::string PluginKey; + + /** + * PluginKeyList is a sequence of plugin keys, such as returned by + * a plugin lookup function. + */ typedef std::vector PluginKeyList; + + /** + * 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. + */ typedef std::vector PluginCategoryHierarchy; - PluginKeyList listPlugins(); //!!! pass in version number? + /** + * Search for all available Vamp plugins, and return a list of + * them in the order in which they were found. + */ + PluginKeyList listPlugins(); - PluginKey composePluginKey(std::string libraryName, std::string identifier); - + /** + * 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. + * + * See PluginInputDomainAdapter and PluginChannelAdapter for more + * details of the classes that the loader may use if these flags + * are set. + */ enum AdapterFlags { ADAPT_INPUT_DOMAIN = 0x01, ADAPT_CHANNEL_COUNT = 0x02, ADAPT_ALL = 0xff }; - Plugin *loadPlugin(PluginKey plugin, + /** + * Load a Vamp plugin, given its identifying key. If the plugin + * could not be loaded, returns 0. + * + * adapterFlags is a bitwise OR of the values in the AdapterFlags + * enum, indicating under which circumstances an adapter should be + * used to wrap the original plugin. See AdapterFlags for more + * details. If adapterFlags is 0, no optional adapters will be + * used. + * + * The returned plugin should be deleted (using the standard C++ + * delete) after use. + */ + Plugin *loadPlugin(PluginKey key, float inputSampleRate, int adapterFlags = 0); + /** + * Given a Vamp plugin library name and plugin identifier, return + * the corresponding plugin key in a form suitable for passing in to + * loadPlugin. + */ + PluginKey composePluginKey(std::string libraryName, + std::string identifier); + + /** + * Return the category hierarchy for a Vamp plugin, given its + * identifying key. See PluginCategoryHierarchy documentation for + * more details. + * + * If the plugin has no category information, return an empty + * hierarchy. + */ PluginCategoryHierarchy getPluginCategory(PluginKey plugin); + /** + * Return the file path of the dynamic library from which the + * given plugin will be loaded (if available). + */ std::string getLibraryPathForPlugin(PluginKey plugin); protected: diff -r 97c5ac99d725 -r fe5486ee1c70 vamp-sdk/hostext/PluginWrapper.h --- a/vamp-sdk/hostext/PluginWrapper.h Fri Jun 01 13:53:42 2007 +0000 +++ b/vamp-sdk/hostext/PluginWrapper.h Fri Jun 01 15:00:51 2007 +0000 @@ -43,6 +43,15 @@ namespace HostExt { +/** + * PluginWrapper is a simple base class for adapter plugins. It takes + * a pointer to a "to be wrapped" Vamp plugin on construction, and + * provides implementations of all the Vamp plugin methods that simply + * delegate through to the wrapped plugin. A subclass can therefore + * override only the methods that are meaningful for the particular + * adapter. + */ + class PluginWrapper : public Plugin { public: