Chris@23: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ Chris@23: Chris@23: /* Chris@23: Vamp Chris@23: Chris@23: An API for audio analysis and feature extraction plugins. Chris@23: Chris@23: Centre for Digital Music, Queen Mary, University of London. Chris@23: Copyright 2006 Chris Cannam. Chris@23: Chris@23: Permission is hereby granted, free of charge, to any person Chris@23: obtaining a copy of this software and associated documentation Chris@23: files (the "Software"), to deal in the Software without Chris@23: restriction, including without limitation the rights to use, copy, Chris@23: modify, merge, publish, distribute, sublicense, and/or sell copies Chris@23: of the Software, and to permit persons to whom the Software is Chris@23: furnished to do so, subject to the following conditions: Chris@23: Chris@23: The above copyright notice and this permission notice shall be Chris@23: included in all copies or substantial portions of the Software. Chris@23: Chris@23: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, Chris@23: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF Chris@23: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND Chris@23: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR Chris@23: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF Chris@23: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION Chris@23: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Chris@23: Chris@23: Except as contained in this notice, the names of the Centre for Chris@23: Digital Music; Queen Mary, University of London; and Chris Cannam Chris@23: shall not be used in advertising or otherwise to promote the sale, Chris@23: use or other dealings in this Software without prior written Chris@23: authorization. Chris@23: */ Chris@23: Chris@23: #ifndef _VAMP_SDK_PLUGIN_BASE_H_ Chris@23: #define _VAMP_SDK_PLUGIN_BASE_H_ Chris@23: Chris@23: #include Chris@23: #include Chris@23: Chris@23: #include "plugguard.h" Chris@23: _VAMP_SDK_PLUGSPACE_BEGIN(PluginBase.h) Chris@23: Chris@23: namespace Vamp { Chris@23: Chris@23: /** Chris@23: * A base class for plugins with optional configurable parameters, Chris@23: * programs, etc. The Vamp::Plugin is derived from this, and Chris@23: * individual Vamp plugins should derive from that. Chris@23: * Chris@23: * This class does not provide the necessary interfaces to instantiate Chris@23: * or run a plugin. It only specifies an interface for retrieving Chris@23: * those controls that the host may wish to show to the user for Chris@23: * editing. It could meaningfully be subclassed by real-time plugins Chris@23: * or other sorts of plugin as well as Vamp plugins. Chris@23: */ Chris@23: Chris@23: class PluginBase Chris@23: { Chris@23: public: Chris@23: virtual ~PluginBase() { } Chris@23: Chris@23: /** Chris@23: * Get the Vamp API compatibility level of the plugin. Chris@23: */ Chris@23: virtual unsigned int getVampApiVersion() const { return 2; } Chris@23: Chris@23: /** Chris@23: * Get the computer-usable name of the plugin. This should be Chris@23: * reasonably short and contain no whitespace or punctuation Chris@23: * characters. It may only contain the characters [a-zA-Z0-9_-]. Chris@23: * This is the authoritative way for a program to identify a Chris@23: * plugin within a given library. Chris@23: * Chris@23: * This text may be visible to the user, but it should not be the Chris@23: * main text used to identify a plugin to the user (that will be Chris@23: * the name, below). Chris@23: * Chris@23: * Example: "zero_crossings" Chris@23: */ Chris@23: virtual std::string getIdentifier() const = 0; Chris@23: Chris@23: /** Chris@23: * Get a human-readable name or title of the plugin. This Chris@23: * should be brief and self-contained, as it may be used to Chris@23: * identify the plugin to the user in isolation (i.e. without also Chris@23: * showing the plugin's "identifier"). Chris@23: * Chris@23: * Example: "Zero Crossings" Chris@23: */ Chris@23: virtual std::string getName() const = 0; Chris@23: Chris@23: /** Chris@23: * Get a human-readable description for the plugin, typically Chris@23: * a line of text that may optionally be displayed in addition Chris@23: * to the plugin's "name". May be empty if the name has said Chris@23: * it all already. Chris@23: * Chris@23: * Example: "Detect and count zero crossing points" Chris@23: */ Chris@23: virtual std::string getDescription() const = 0; Chris@23: Chris@23: /** Chris@23: * Get the name of the author or vendor of the plugin in Chris@23: * human-readable form. This should be a short identifying text, Chris@23: * as it may be used to label plugins from the same source in a Chris@23: * menu or similar. Chris@23: */ Chris@23: virtual std::string getMaker() const = 0; Chris@23: Chris@23: /** Chris@23: * Get the copyright statement or licensing summary for the Chris@23: * plugin. This can be an informative text, without the same Chris@23: * presentation constraints as mentioned for getMaker above. Chris@23: */ Chris@23: virtual std::string getCopyright() const = 0; Chris@23: Chris@23: /** Chris@23: * Get the version number of the plugin. Chris@23: */ Chris@23: virtual int getPluginVersion() const = 0; Chris@23: Chris@23: Chris@23: struct ParameterDescriptor Chris@23: { Chris@23: /** Chris@23: * The name of the parameter, in computer-usable form. Should Chris@23: * be reasonably short, and may only contain the characters Chris@23: * [a-zA-Z0-9_-]. Chris@23: */ Chris@23: std::string identifier; Chris@23: Chris@23: /** Chris@23: * The human-readable name of the parameter. Chris@23: */ Chris@23: std::string name; Chris@23: Chris@23: /** Chris@23: * A human-readable short text describing the parameter. May be Chris@23: * empty if the name has said it all already. Chris@23: */ Chris@23: std::string description; Chris@23: Chris@23: /** Chris@23: * The unit of the parameter, in human-readable form. Chris@23: */ Chris@23: std::string unit; Chris@23: Chris@23: /** Chris@23: * The minimum value of the parameter. Chris@23: */ Chris@23: float minValue; Chris@23: Chris@23: /** Chris@23: * The maximum value of the parameter. Chris@23: */ Chris@23: float maxValue; Chris@23: Chris@23: /** Chris@23: * The default value of the parameter. The plugin should Chris@23: * ensure that parameters have this value on initialisation Chris@23: * (i.e. the host is not required to explicitly set parameters Chris@23: * if it wants to use their default values). Chris@23: */ Chris@23: float defaultValue; Chris@23: Chris@23: /** Chris@23: * True if the parameter values are quantized to a particular Chris@23: * resolution. Chris@23: */ Chris@23: bool isQuantized; Chris@23: Chris@23: /** Chris@23: * Quantization resolution of the parameter values (e.g. 1.0 Chris@23: * if they are all integers). Undefined if isQuantized is Chris@23: * false. Chris@23: */ Chris@23: float quantizeStep; Chris@23: Chris@23: /** Chris@23: * Names for the quantized values. If isQuantized is true, Chris@23: * this may either be empty or contain one string for each of Chris@23: * the quantize steps from minValue up to maxValue inclusive. Chris@23: * Undefined if isQuantized is false. Chris@23: * Chris@23: * If these names are provided, they should be shown to the Chris@23: * user in preference to the values themselves. The user may Chris@23: * never see the actual numeric values unless they are also Chris@23: * encoded in the names. Chris@23: */ Chris@23: std::vector valueNames; Chris@23: Chris@23: ParameterDescriptor() : // the defaults are invalid: you must set them Chris@23: minValue(0), maxValue(0), defaultValue(0), isQuantized(false) { } Chris@23: }; Chris@23: Chris@23: typedef std::vector ParameterList; Chris@23: Chris@23: /** Chris@23: * Get the controllable parameters of this plugin. Chris@23: */ Chris@23: virtual ParameterList getParameterDescriptors() const { Chris@23: return ParameterList(); Chris@23: } Chris@23: Chris@23: /** Chris@23: * Get the value of a named parameter. The argument is the identifier Chris@23: * field from that parameter's descriptor. Chris@23: */ Chris@23: virtual float getParameter(std::string) const { return 0.0; } Chris@23: Chris@23: /** Chris@23: * Set a named parameter. The first argument is the identifier field Chris@23: * from that parameter's descriptor. Chris@23: */ Chris@23: virtual void setParameter(std::string, float) { } Chris@23: Chris@23: Chris@23: typedef std::vector ProgramList; Chris@23: Chris@23: /** Chris@23: * Get the program settings available in this plugin. A program Chris@23: * is a named shorthand for a set of parameter values; changing Chris@23: * the program may cause the plugin to alter the values of its Chris@23: * published parameters (and/or non-public internal processing Chris@23: * parameters). The host should re-read the plugin's parameter Chris@23: * values after setting a new program. Chris@23: * Chris@23: * The programs must have unique names. Chris@23: */ Chris@23: virtual ProgramList getPrograms() const { return ProgramList(); } Chris@23: Chris@23: /** Chris@23: * Get the current program. Chris@23: */ Chris@23: virtual std::string getCurrentProgram() const { return ""; } Chris@23: Chris@23: /** Chris@23: * Select a program. (If the given program name is not one of the Chris@23: * available programs, do nothing.) Chris@23: */ Chris@23: virtual void selectProgram(std::string) { } Chris@23: Chris@23: /** Chris@23: * Get the type of plugin. This is to be implemented by the Chris@23: * immediate subclass, not by actual plugins. Do not attempt to Chris@23: * implement this in plugin code. Chris@23: */ Chris@23: virtual std::string getType() const = 0; Chris@23: }; Chris@23: Chris@23: } Chris@23: Chris@23: _VAMP_SDK_PLUGSPACE_END(PluginBase.h) Chris@23: Chris@23: #endif