cannam@229: cannam@229: /** \mainpage Vamp Plugin SDK cannam@229: cannam@229: \section about About Vamp cannam@229: cannam@229: Vamp is an API for C and C++ plugins that process sampled audio data cannam@229: to produce descriptive output (measurements or semantic observations). cannam@229: Find more information at http://www.vamp-plugins.org/ . cannam@229: cannam@229: Although the official API for Vamp plugins is defined in C for maximum cannam@229: binary compatibility, we strongly recommend using the provided C++ cannam@229: classes in the SDK to implement your own plugins and hosts. cannam@229: cannam@229: \section plugins For Plugins cannam@229: cannam@229: Plugins should subclass Vamp::Plugin, and then use a cannam@229: Vamp::PluginAdapter to expose the correct C API for the plugin. Read cannam@229: the documentation for Vamp::PluginBase and Vamp::Plugin before cannam@229: starting. cannam@229: cannam@229: Plugins should be compiled and linked into dynamic libraries using the cannam@229: usual convention for your platform, and should link (preferably cannam@229: statically) with -lvamp-sdk. Any number of plugins can reside in a cannam@229: single dynamic library. See plugins.cpp in the example plugins cannam@229: directory for the sort of code that will need to accompany your plugin cannam@229: class or classes, to make it possible for a host to look up your cannam@229: plugins properly. cannam@229: cannam@239: Please read the relevant README file for your platform found in the cannam@239: Vamp SDK build/ directory, for details about how to ensure the cannam@239: resulting dynamic library exports the correct linker symbols. cannam@229: cannam@229: The following example plugins are provided. You may legally reuse any cannam@229: amount of the code from these examples in any plugins you write, cannam@229: whether proprietary or open-source. cannam@229: cannam@229: - ZeroCrossing calculates the positions and density of zero-crossing cannam@229: points in an audio waveform. cannam@229: cannam@229: - SpectralCentroid calculates the centre of gravity of the frequency cannam@229: domain representation of each block of audio. cannam@229: cannam@242: - PowerSpectrum calculates a power spectrum from the input audio. cannam@242: Actually, it doesn't do any work except converting from the cartesian cannam@242: complex representation. The work of converting to frequency domain cannam@242: is all done for it by the host or host SDK; the plugin just needs to cannam@242: declare that it wants frequency domain input. This is the simplest cannam@242: of the example plugins. cannam@242: cannam@229: - AmplitudeFollower is a simple implementation of SuperCollider's cannam@229: amplitude-follower algorithm. cannam@229: cannam@229: - PercussionOnsetDetector estimates the locations of percussive cannam@229: onsets using a simple method described in "Drum Source Separation cannam@229: using Percussive Feature Detection and Spectral Modulation" by Dan cannam@229: Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005. cannam@229: cannam@239: - FixedTempoEstimator calculates a single beats-per-minute value cannam@239: which is an estimate of the tempo of a piece of music that is assumed cannam@239: to be of fixed tempo, using autocorrelation of a frequency domain cannam@239: energy rise metric. It has several outputs that return intermediate cannam@239: results used in the calculation, and may be a useful example of a cannam@239: plugin having several outputs with varying feature structures. cannam@229: cannam@229: \section hosts For Hosts cannam@229: cannam@229: Hosts will normally use a Vamp::PluginHostAdapter to convert each cannam@229: plugin's exposed C API back into a useful Vamp::Plugin C++ object. cannam@229: cannam@239: The Vamp::HostExt namespace contains several additional C++ classes to cannam@239: do this work for them, and make the host's life easier: cannam@229: cannam@239: - Vamp::HostExt::PluginLoader provides a very easy interface for a cannam@229: host to discover, load, and find out category information about the cannam@239: available plugins. Most Vamp hosts will probably want to use this cannam@239: class. cannam@229: cannam@229: - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for cannam@239: hosts to handle plugins that want frequency-domain input, without cannam@229: having to convert the input themselves. cannam@229: cannam@229: - Vamp::HostExt::PluginChannelAdapter provides a simple means for cannam@229: hosts to use plugins that do not necessarily support the same number cannam@229: of audio channels as they have available, without having to apply a cannam@229: channel management / mixdown policy themselves. cannam@229: cannam@239: - Vamp::HostExt::PluginBufferingAdapter provides a means for hosts to cannam@239: avoid having to negotiate the input step and block size, instead cannam@239: permitting the host to use any block size they desire (and a step cannam@239: size equal to it). This is particularly useful for "streaming" hosts cannam@239: that cannot seek backwards in the input audio stream and so would cannam@239: otherwise need to implement an additional buffer to support step cannam@239: sizes smaller than the block size. cannam@229: cannam@239: - Vamp::HostExt::PluginSummarisingAdapter provides summarisation cannam@239: methods such as mean and median averages of output features, for use cannam@239: in any context where an available plugin produces individual values cannam@239: but the result that is actually needed is some sort of aggregate. cannam@229: cannam@229: The PluginLoader class can also use the input domain, channel, and cannam@229: buffering adapters automatically to make these conversions transparent cannam@229: to the host if required. cannam@229: cannam@239: Host authors should also refer to the example host code in the host cannam@239: directory of the SDK. cannam@239: cannam@229: Hosts should link with -lvamp-hostsdk. cannam@229: cannam@229: (The following notes in this section are mostly relevant for cannam@229: developers that are not using the HostExt classes, or that wish to cannam@229: know more about the policy they implement.) cannam@229: cannam@229: The Vamp API does not officially specify how to load plugin libraries cannam@229: or where to find them. However, the SDK does include a function cannam@229: (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended cannam@239: directory search path that hosts may use for plugin libraries, and a cannam@239: class (Vamp::HostExt::PluginLoader) that implements a sensible cannam@239: cross-platform lookup policy using this path. We recommend using this cannam@239: class in your host unless you have a good reason not to want to. This cannam@239: implementation also permits the user to set the environment variable cannam@239: VAMP_PATH to override the default path if desired. cannam@229: cannam@239: The policy used by Vamp::HostExt::PluginLoader -- and our cannam@239: recommendation for any host -- is to search each directory in this cannam@239: path for .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib cannam@239: (on OS/X) files, then to load each one and perform a dynamic name cannam@239: lookup on the vampGetPluginDescriptor function to enumerate the cannam@239: plugins in the library. The example host has some code that may help, cannam@239: but this operation will necessarily be system-dependent. cannam@229: cannam@229: Vamp also has an informal convention for sorting plugins into cannam@229: functional categories. In addition to the library file itself, a cannam@229: plugin library may install a category file with the same name as the cannam@229: library but .cat extension. The existence and format of this file are cannam@229: not specified by the Vamp API, but by convention the file may contain cannam@229: lines of the format cannam@229: cannam@229: \code cannam@229: vamp:pluginlibrary:pluginname::General Category > Specific Category cannam@229: \endcode cannam@229: cannam@229: which a host may read and use to assign plugins a location within a cannam@229: category tree for display to the user. The expectation is that cannam@229: advanced users may also choose to set up their own preferred category cannam@229: trees, which is why this information is not queried as part of the cannam@239: Vamp plugin's API itself. The Vamp::HostExt::PluginLoader class also cannam@239: provides support for plugin category lookup using this scheme. cannam@229: cannam@229: \section license License cannam@229: cannam@229: This plugin SDK is freely redistributable under a "new-style BSD" cannam@229: licence. See the file COPYING for more details. In short, you may cannam@229: modify and redistribute the SDK and example plugins within any cannam@229: commercial or non-commercial, proprietary or open-source plugin or cannam@229: application under almost any conditions, with no obligation to provide cannam@229: source code, provided you retain the original copyright note. cannam@229: cannam@229: cannam@229: */