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@54: The following example plugins are provided:
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@54:  - AmplitudeFollower is an implementation of SuperCollider's
cannam@54:  amplitude-follower algorithm as a simple Vamp plugin.
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@54: \section hosts For Hosts
cannam@54: 
cannam@54: Hosts will usually want to use a Vamp::PluginHostAdapter to convert
cannam@54: each plugin's exposed C API back into a useful Vamp::Plugin object.
cannam@54: 
cannam@54: Hosts should link with -lvamp-hostsdk.
cannam@54: 
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@54: There is an example host in the "host" directory from
cannam@54: which code may 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: */