annotate vamp-sdk/PluginBase.h @ 88:d17b9ca3b8c9

* add -o <file> option to vamp-simple-host
author cannam
date Fri, 12 Oct 2007 09:52:10 +0000
parents 9d3272c7db60
children 24859c958732
rev   line source
cannam@0 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
cannam@0 2
cannam@0 3 /*
cannam@2 4 Vamp
cannam@2 5
cannam@2 6 An API for audio analysis and feature extraction plugins.
cannam@2 7
cannam@0 8 Centre for Digital Music, Queen Mary, University of London.
cannam@2 9 Copyright 2006 Chris Cannam.
cannam@2 10
cannam@2 11 Permission is hereby granted, free of charge, to any person
cannam@2 12 obtaining a copy of this software and associated documentation
cannam@2 13 files (the "Software"), to deal in the Software without
cannam@2 14 restriction, including without limitation the rights to use, copy,
cannam@2 15 modify, merge, publish, distribute, sublicense, and/or sell copies
cannam@2 16 of the Software, and to permit persons to whom the Software is
cannam@2 17 furnished to do so, subject to the following conditions:
cannam@2 18
cannam@2 19 The above copyright notice and this permission notice shall be
cannam@2 20 included in all copies or substantial portions of the Software.
cannam@2 21
cannam@2 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
cannam@2 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
cannam@2 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
cannam@6 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
cannam@2 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
cannam@2 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
cannam@2 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
cannam@2 29
cannam@2 30 Except as contained in this notice, the names of the Centre for
cannam@2 31 Digital Music; Queen Mary, University of London; and Chris Cannam
cannam@2 32 shall not be used in advertising or otherwise to promote the sale,
cannam@2 33 use or other dealings in this Software without prior written
cannam@2 34 authorization.
cannam@0 35 */
cannam@0 36
cannam@0 37 #ifndef _VAMP_PLUGIN_BASE_H_
cannam@0 38 #define _VAMP_PLUGIN_BASE_H_
cannam@0 39
cannam@0 40 #include <string>
cannam@0 41 #include <vector>
cannam@0 42
cannam@64 43 #define VAMP_SDK_VERSION "1.1"
cannam@24 44
cannam@0 45 namespace Vamp {
cannam@0 46
cannam@0 47 /**
cannam@0 48 * A base class for plugins with optional configurable parameters,
cannam@53 49 * programs, etc. The Vamp::Plugin is derived from this, and
cannam@53 50 * individual Vamp plugins should derive from that.
cannam@0 51 *
cannam@53 52 * This class does not provide the necessary interfaces to instantiate
cannam@53 53 * or run a plugin. It only specifies an interface for retrieving
cannam@53 54 * those controls that the host may wish to show to the user for
cannam@53 55 * editing. It could meaningfully be subclassed by real-time plugins
cannam@53 56 * or other sorts of plugin as well as Vamp plugins.
cannam@0 57 */
cannam@0 58
cannam@0 59 class PluginBase
cannam@0 60 {
cannam@0 61 public:
cannam@20 62 virtual ~PluginBase() { }
cannam@20 63
cannam@0 64 /**
cannam@50 65 * Get the Vamp API compatibility level of the plugin.
cannam@50 66 */
cannam@50 67 virtual unsigned int getVampApiVersion() const { return 1; }
cannam@50 68
cannam@50 69 /**
cannam@0 70 * Get the computer-usable name of the plugin. This should be
cannam@0 71 * reasonably short and contain no whitespace or punctuation
cannam@47 72 * characters. It may only contain the characters [a-zA-Z0-9_].
cannam@47 73 * This is the authoritative way for a program to identify a
cannam@47 74 * plugin within a given library.
cannam@47 75 *
cannam@47 76 * This text may be visible to the user, but it should not be the
cannam@47 77 * main text used to identify a plugin to the user (that will be
cannam@49 78 * the name, below).
cannam@49 79 *
cannam@49 80 * Example: "zero_crossings"
cannam@49 81 */
cannam@49 82 virtual std::string getIdentifier() const = 0;
cannam@49 83
cannam@49 84 /**
cannam@49 85 * Get a human-readable name or title of the plugin. This
cannam@49 86 * should be brief and self-contained, as it may be used to
cannam@49 87 * identify the plugin to the user in isolation (i.e. without also
cannam@49 88 * showing the plugin's "identifier").
cannam@49 89 *
cannam@49 90 * Example: "Zero Crossings"
cannam@0 91 */
cannam@0 92 virtual std::string getName() const = 0;
cannam@0 93
cannam@0 94 /**
cannam@49 95 * Get a human-readable description for the plugin, typically
cannam@49 96 * a line of text that may optionally be displayed in addition
cannam@49 97 * to the plugin's "name". May be empty if the name has said
cannam@49 98 * it all already.
cannam@49 99 *
cannam@49 100 * Example: "Detect and count zero crossing points"
cannam@0 101 */
cannam@0 102 virtual std::string getDescription() const = 0;
cannam@0 103
cannam@0 104 /**
cannam@0 105 * Get the name of the author or vendor of the plugin in
cannam@47 106 * human-readable form. This should be a short identifying text,
cannam@47 107 * as it may be used to label plugins from the same source in a
cannam@47 108 * menu or similar.
cannam@0 109 */
cannam@0 110 virtual std::string getMaker() const = 0;
cannam@0 111
cannam@0 112 /**
cannam@47 113 * Get the copyright statement or licensing summary for the
cannam@47 114 * plugin. This can be an informative text, without the same
cannam@47 115 * presentation constraints as mentioned for getMaker above.
cannam@47 116 */
cannam@47 117 virtual std::string getCopyright() const = 0;
cannam@47 118
cannam@47 119 /**
cannam@0 120 * Get the version number of the plugin.
cannam@0 121 */
cannam@0 122 virtual int getPluginVersion() const = 0;
cannam@0 123
cannam@0 124
cannam@0 125 struct ParameterDescriptor
cannam@0 126 {
cannam@0 127 /**
cannam@0 128 * The name of the parameter, in computer-usable form. Should
cannam@0 129 * be reasonably short, and may only contain the characters
cannam@0 130 * [a-zA-Z0-9_].
cannam@0 131 */
cannam@49 132 std::string identifier;
cannam@49 133
cannam@49 134 /**
cannam@49 135 * The human-readable name of the parameter.
cannam@49 136 */
cannam@0 137 std::string name;
cannam@0 138
cannam@0 139 /**
cannam@49 140 * A human-readable short text describing the parameter. May be
cannam@49 141 * empty if the name has said it all already.
cannam@0 142 */
cannam@0 143 std::string description;
cannam@0 144
cannam@0 145 /**
cannam@0 146 * The unit of the parameter, in human-readable form.
cannam@0 147 */
cannam@0 148 std::string unit;
cannam@0 149
cannam@0 150 /**
cannam@0 151 * The minimum value of the parameter.
cannam@0 152 */
cannam@0 153 float minValue;
cannam@0 154
cannam@0 155 /**
cannam@0 156 * The maximum value of the parameter.
cannam@0 157 */
cannam@0 158 float maxValue;
cannam@0 159
cannam@0 160 /**
cannam@24 161 * The default value of the parameter. The plugin should
cannam@24 162 * ensure that parameters have this value on initialisation
cannam@24 163 * (i.e. the host is not required to explicitly set parameters
cannam@24 164 * if it wants to use their default values).
cannam@0 165 */
cannam@0 166 float defaultValue;
cannam@0 167
cannam@0 168 /**
cannam@0 169 * True if the parameter values are quantized to a particular
cannam@0 170 * resolution.
cannam@0 171 */
cannam@0 172 bool isQuantized;
cannam@0 173
cannam@0 174 /**
cannam@0 175 * Quantization resolution of the parameter values (e.g. 1.0
cannam@0 176 * if they are all integers). Undefined if isQuantized is
cannam@0 177 * false.
cannam@0 178 */
cannam@0 179 float quantizeStep;
cannam@9 180
cannam@9 181 /**
cannam@9 182 * Names for the quantized values. If isQuantized is true,
cannam@9 183 * this may either be empty or contain one string for each of
cannam@9 184 * the quantize steps from minValue up to maxValue inclusive.
cannam@9 185 * Undefined if isQuantized is false.
cannam@9 186 *
cannam@9 187 * If these names are provided, they should be shown to the
cannam@9 188 * user in preference to the values themselves. The user may
cannam@9 189 * never see the actual numeric values unless they are also
cannam@9 190 * encoded in the names.
cannam@9 191 */
cannam@9 192 std::vector<std::string> valueNames;
cannam@0 193 };
cannam@0 194
cannam@0 195 typedef std::vector<ParameterDescriptor> ParameterList;
cannam@0 196
cannam@0 197 /**
cannam@0 198 * Get the controllable parameters of this plugin.
cannam@0 199 */
cannam@0 200 virtual ParameterList getParameterDescriptors() const {
cannam@0 201 return ParameterList();
cannam@0 202 }
cannam@0 203
cannam@0 204 /**
cannam@49 205 * Get the value of a named parameter. The argument is the identifier
cannam@0 206 * field from that parameter's descriptor.
cannam@0 207 */
cannam@0 208 virtual float getParameter(std::string) const { return 0.0; }
cannam@0 209
cannam@0 210 /**
cannam@49 211 * Set a named parameter. The first argument is the identifier field
cannam@0 212 * from that parameter's descriptor.
cannam@0 213 */
cannam@0 214 virtual void setParameter(std::string, float) { }
cannam@0 215
cannam@0 216
cannam@0 217 typedef std::vector<std::string> ProgramList;
cannam@0 218
cannam@0 219 /**
cannam@64 220 * Get the program settings available in this plugin. A program
cannam@64 221 * is a named shorthand for a set of parameter values; changing
cannam@64 222 * the program may cause the plugin to alter the values of its
cannam@64 223 * published parameters (and/or non-public internal processing
cannam@64 224 * parameters). The host should re-read the plugin's parameter
cannam@64 225 * values after setting a new program.
cannam@64 226 *
cannam@0 227 * The programs must have unique names.
cannam@0 228 */
cannam@0 229 virtual ProgramList getPrograms() const { return ProgramList(); }
cannam@0 230
cannam@0 231 /**
cannam@0 232 * Get the current program.
cannam@0 233 */
cannam@0 234 virtual std::string getCurrentProgram() const { return ""; }
cannam@0 235
cannam@0 236 /**
cannam@0 237 * Select a program. (If the given program name is not one of the
cannam@0 238 * available programs, do nothing.)
cannam@0 239 */
cannam@0 240 virtual void selectProgram(std::string) { }
cannam@47 241
cannam@47 242 /**
cannam@47 243 * Get the type of plugin. This is to be implemented by the
cannam@47 244 * immediate subclass, not by actual plugins. Do not attempt to
cannam@47 245 * implement this in plugin code.
cannam@47 246 */
cannam@47 247 virtual std::string getType() const = 0;
cannam@0 248 };
cannam@0 249
cannam@0 250 }
cannam@0 251
cannam@0 252 #endif