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