cannam@0: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */ cannam@0: cannam@0: /* cannam@2: Vamp cannam@2: cannam@2: An API for audio analysis and feature extraction plugins. cannam@2: cannam@0: Centre for Digital Music, Queen Mary, University of London. cannam@2: Copyright 2006 Chris Cannam. cannam@2: cannam@2: Permission is hereby granted, free of charge, to any person cannam@2: obtaining a copy of this software and associated documentation cannam@2: files (the "Software"), to deal in the Software without cannam@2: restriction, including without limitation the rights to use, copy, cannam@2: modify, merge, publish, distribute, sublicense, and/or sell copies cannam@2: of the Software, and to permit persons to whom the Software is cannam@2: furnished to do so, subject to the following conditions: cannam@2: cannam@2: The above copyright notice and this permission notice shall be cannam@2: included in all copies or substantial portions of the Software. cannam@2: cannam@2: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, cannam@2: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF cannam@2: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND cannam@6: NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR cannam@2: ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF cannam@2: CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION cannam@2: WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. cannam@2: cannam@2: Except as contained in this notice, the names of the Centre for cannam@2: Digital Music; Queen Mary, University of London; and Chris Cannam cannam@2: shall not be used in advertising or otherwise to promote the sale, cannam@2: use or other dealings in this Software without prior written cannam@2: authorization. cannam@0: */ cannam@0: cannam@0: #ifndef _VAMP_PLUGIN_BASE_H_ cannam@0: #define _VAMP_PLUGIN_BASE_H_ cannam@0: cannam@0: #include cannam@0: #include cannam@0: cannam@24: #define VAMP_SDK_VERSION "0.2" cannam@24: cannam@0: namespace Vamp { cannam@0: cannam@0: /** cannam@0: * A base class for plugins with optional configurable parameters, cannam@0: * programs, etc. cannam@0: * cannam@0: * This does not provide the necessary interfaces to instantiate or cannam@0: * run a plugin -- that depends on the plugin subclass, as different cannam@0: * plugin types may have quite different operating structures. This cannam@0: * class just specifies the necessary interface to show editable cannam@0: * controls for the plugin to the user. cannam@0: */ cannam@0: cannam@0: class PluginBase cannam@0: { cannam@0: public: cannam@20: virtual ~PluginBase() { } cannam@20: cannam@0: /** cannam@0: * Get the computer-usable name of the plugin. This should be cannam@0: * reasonably short and contain no whitespace or punctuation cannam@0: * characters. It may be shown to the user, but it won't be the cannam@0: * main method for a user to identify a plugin (that will be the cannam@24: * description, below). This may only contain the characters cannam@24: * [a-zA-Z0-9_]. cannam@0: */ cannam@0: virtual std::string getName() const = 0; cannam@0: cannam@0: /** cannam@0: * Get a human-readable description of the plugin. This should be cannam@0: * self-contained, as it may be shown to the user in isolation cannam@0: * without also showing the plugin's "name". cannam@0: */ cannam@0: virtual std::string getDescription() const = 0; cannam@0: cannam@0: /** cannam@0: * Get the name of the author or vendor of the plugin in cannam@0: * human-readable form. cannam@0: */ cannam@0: virtual std::string getMaker() const = 0; cannam@0: cannam@0: /** cannam@0: * Get the version number of the plugin. cannam@0: */ cannam@0: virtual int getPluginVersion() const = 0; cannam@0: cannam@0: /** cannam@0: * Get the copyright statement or licensing summary of the plugin. cannam@0: */ cannam@0: virtual std::string getCopyright() const = 0; cannam@0: cannam@0: /** cannam@0: * Get the type of plugin (e.g. DSSI, etc). This is likely to be cannam@0: * implemented by the immediate subclass, not by actual plugins. cannam@0: */ cannam@0: virtual std::string getType() const = 0; cannam@0: cannam@0: cannam@0: struct ParameterDescriptor cannam@0: { cannam@0: /** cannam@0: * The name of the parameter, in computer-usable form. Should cannam@0: * be reasonably short, and may only contain the characters cannam@0: * [a-zA-Z0-9_]. cannam@0: */ cannam@0: std::string name; cannam@0: cannam@0: /** cannam@0: * The human-readable name of the parameter. cannam@0: */ cannam@0: std::string description; cannam@0: cannam@0: /** cannam@0: * The unit of the parameter, in human-readable form. cannam@0: */ cannam@0: std::string unit; cannam@0: cannam@0: /** cannam@0: * The minimum value of the parameter. cannam@0: */ cannam@0: float minValue; cannam@0: cannam@0: /** cannam@0: * The maximum value of the parameter. cannam@0: */ cannam@0: float maxValue; cannam@0: cannam@0: /** cannam@24: * The default value of the parameter. The plugin should cannam@24: * ensure that parameters have this value on initialisation cannam@24: * (i.e. the host is not required to explicitly set parameters cannam@24: * if it wants to use their default values). cannam@0: */ cannam@0: float defaultValue; cannam@0: cannam@0: /** cannam@0: * True if the parameter values are quantized to a particular cannam@0: * resolution. cannam@0: */ cannam@0: bool isQuantized; cannam@0: cannam@0: /** cannam@0: * Quantization resolution of the parameter values (e.g. 1.0 cannam@0: * if they are all integers). Undefined if isQuantized is cannam@0: * false. cannam@0: */ cannam@0: float quantizeStep; cannam@9: cannam@9: /** cannam@9: * Names for the quantized values. If isQuantized is true, cannam@9: * this may either be empty or contain one string for each of cannam@9: * the quantize steps from minValue up to maxValue inclusive. cannam@9: * Undefined if isQuantized is false. cannam@9: * cannam@9: * If these names are provided, they should be shown to the cannam@9: * user in preference to the values themselves. The user may cannam@9: * never see the actual numeric values unless they are also cannam@9: * encoded in the names. cannam@9: */ cannam@9: std::vector valueNames; cannam@0: }; cannam@0: cannam@0: typedef std::vector ParameterList; cannam@0: cannam@0: /** cannam@0: * Get the controllable parameters of this plugin. cannam@0: */ cannam@0: virtual ParameterList getParameterDescriptors() const { cannam@0: return ParameterList(); cannam@0: } cannam@0: cannam@0: /** cannam@0: * Get the value of a named parameter. The argument is the name cannam@0: * field from that parameter's descriptor. cannam@0: */ cannam@0: virtual float getParameter(std::string) const { return 0.0; } cannam@0: cannam@0: /** cannam@0: * Set a named parameter. The first argument is the name field cannam@0: * from that parameter's descriptor. cannam@0: */ cannam@0: virtual void setParameter(std::string, float) { } cannam@0: cannam@0: cannam@0: typedef std::vector ProgramList; cannam@0: cannam@0: /** cannam@0: * Get the program settings available in this plugin. cannam@0: * The programs must have unique names. cannam@0: */ cannam@0: virtual ProgramList getPrograms() const { return ProgramList(); } cannam@0: cannam@0: /** cannam@0: * Get the current program. cannam@0: */ cannam@0: virtual std::string getCurrentProgram() const { return ""; } cannam@0: cannam@0: /** cannam@0: * Select a program. (If the given program name is not one of the cannam@0: * available programs, do nothing.) cannam@0: */ cannam@0: virtual void selectProgram(std::string) { } cannam@0: }; cannam@0: cannam@0: } cannam@0: cannam@0: #endif