cannam@14: 
cannam@14: Vamp
cannam@14: ====
cannam@14: 
cannam@14: An API for audio analysis and feature extraction plugins.
cannam@14: 
cannam@44:    http://www.vamp-plugins.org/
cannam@44: 
cannam@14: Vamp is an API for C and C++ plugins that process sampled audio data
cannam@18: to produce descriptive output (measurements or semantic observations).
cannam@14: 
Chris@424: This is version 2.7 of the Vamp plugin Software Development Kit.
cannam@256: 
cannam@78: Plugins and hosts built with this SDK are binary compatible with those
Chris@423: built using any version 2.0 or newer of the SDK.
Chris@423: 
Chris@423: Plugins and hosts built with this SDK are binary compatible with those
cannam@256: built using version 1.0 of the SDK, with certain restrictions.  See
cannam@256: the file README.compat for more details.
cannam@256: 
cannam@256: See the file CHANGELOG for a list of the changes in this release.
cannam@78: 
cannam@215: A documentation guide to writing plugins using the Vamp SDK can be
cannam@215: found at http://www.vamp-plugins.org/guide.pdf .
cannam@215: 
cannam@239: 
cannam@239: Compiling and Installing the SDK and Examples
cannam@239: =============================================
cannam@239: 
cannam@239: This SDK is intended for use on Windows, OS/X, Linux, and other POSIX
cannam@239: and GNU platforms.
cannam@239: 
cannam@239: Please see the platform-specific README file (README.msvc, README.osx,
cannam@239: README.linux) in the build/ directory for details about how to compile
cannam@239: and install the SDK, how to build plugin libraries using it, and how
cannam@239: to install the example plugins so you can use them in a host.
cannam@239: 
cannam@239: 
cannam@239: What's In This SDK
cannam@239: ==================
cannam@239: 
cannam@78: This SDK contains the following:
cannam@14: 
cannam@239: 
cannam@239: vamp/vamp.h
cannam@239: -----------
cannam@14: 
cannam@14: The formal C language plugin API for Vamp plugins.
cannam@14: 
cannam@14: A Vamp plugin is a dynamic library (.so, .dll or .dylib depending on
cannam@14: platform) exposing one C-linkage entry point (vampGetPluginDescriptor)
cannam@14: which returns data defined in the rest of this C header.
cannam@14: 
cannam@78: Although the C API is the official API for Vamp, we don't recommend
cannam@239: that you program directly to it.  The C++ abstractions found in the
cannam@239: vamp-sdk and vamp-hostsdk directories (below) are preferable for most
cannam@239: purposes and are more thoroughly documented.
cannam@14: 
cannam@239: 
cannam@239: vamp-sdk
cannam@239: --------
cannam@14: 
cannam@237: C++ classes for implementing Vamp plugins.
cannam@18: 
cannam@78: Plugins should subclass Vamp::Plugin and then use Vamp::PluginAdapter
cannam@78: to expose the correct C API for the plugin.  Plugin authors should
cannam@239: read vamp-sdk/PluginBase.h and Plugin.h for code documentation.
cannam@18: 
cannam@239: See "examples" below for details of the example plugins in the SDK,
cannam@239: from which you are welcome to take code and inspiration.
cannam@239: 
cannam@239: Plugins should link with -lvamp-sdk.
cannam@239: 
cannam@239: 
cannam@239: vamp-hostsdk
cannam@239: ------------
cannam@14: 
cannam@237: C++ classes for implementing Vamp hosts.
cannam@64: 
cannam@239: Hosts will normally use a Vamp::PluginHostAdapter to convert each
cannam@239: plugin's exposed C API back into a useful Vamp::Plugin C++ object.
cannam@237: 
cannam@237: 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@64: 
cannam@239:  - Vamp::HostExt::PluginLoader provides a very easy interface for a
cannam@239:  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@64: 
cannam@239:  - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
cannam@239:  hosts to handle plugins that want frequency-domain input, without
cannam@239:  having to convert the input themselves.
cannam@64: 
cannam@239:  - Vamp::HostExt::PluginChannelAdapter provides a simple means for
cannam@239:  hosts to use plugins that do not necessarily support the same number
cannam@239:  of audio channels as they have available, without having to apply a
cannam@239:  channel management / mixdown policy themselves.
cannam@64: 
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@125: 
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@64: 
cannam@239: The PluginLoader class can also use the input domain, channel, and
cannam@239: buffering adapters automatically to make these conversions transparent
cannam@239: to the host if required.
cannam@14: 
cannam@239: Host authors should also refer to the example host code in the host
cannam@239: directory of the SDK.
cannam@14: 
cannam@239: Hosts should link with -lvamp-hostsdk.
cannam@239: 
cannam@239: 
Chris@397: vamp-hostsdk/host-c.h
Chris@397: ---------------------
Chris@397: 
Chris@397: A C-linkage header wrapping the part of the C++ SDK code that handles
Chris@397: plugin discovery and library loading. Host programs written in C or in
Chris@397: a language with a C-linkage foreign function interface may choose to
Chris@397: use this header to discover and load plugin libraries, together with
Chris@397: the vamp/vamp.h formal API to interact with plugins themselves. See
Chris@397: the header for more documentation.
Chris@397: 
Chris@397: 
cannam@239: examples
cannam@239: --------
cannam@239: 
cannam@239: Example plugins implemented using the C++ classes.
cannam@239: 
cannam@239: These plugins are intended to be useful examples you can draw code
cannam@239: from in order to provide the basic shape and structure of a Vamp
cannam@239: plugin.  They are also intended to be correct and useful, if simple.
cannam@239: 
cannam@239:  - ZeroCrossing calculates the positions and density of zero-crossing
cannam@239:  points in an audio waveform.
cannam@239: 
cannam@239:  - SpectralCentroid calculates the centre of gravity of the frequency
cannam@239:  domain representation of each block of audio.
cannam@239: 
cannam@242:  - PowerSpectrum calculates a power spectrum from the input audio.
cannam@244:  Actually, it doesn't do any work except calculating power from a
cannam@244:  cartesian complex FFT output.  The work of calculating this frequency
cannam@244:  domain output is done for it by the host or host SDK; the plugin just
cannam@244:  needs to declare that it wants frequency domain input.  This is the
cannam@244:  simplest of the example plugins.
cannam@242: 
cannam@239:  - AmplitudeFollower is a simple implementation of SuperCollider's
cannam@239:  amplitude-follower algorithm.
cannam@239: 
cannam@239:  - PercussionOnsetDetector estimates the locations of percussive
cannam@239:  onsets using a simple method described in "Drum Source Separation
cannam@239:  using Percussive Feature Detection and Spectral Modulation" by Dan
cannam@239:  Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@239: 
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@239: 
cannam@239: 
cannam@290: skeleton
cannam@290: --------
cannam@290: 
cannam@290: Skeleton code that could be used as a template for your new plugin
cannam@290: implementation.
cannam@290: 
cannam@290: 
cannam@239: host
cannam@239: ----
cannam@14: 
cannam@16: A simple command-line Vamp host, capable of loading a plugin and using
cannam@16: it to process a complete audio file, with its default parameters.
cannam@14: 
cannam@250: This host also contains a number of options for listing the installed
cannam@250: plugins and their properties in various formats.  For that reason, it
cannam@250: isn't really as simple as one might hope.  The core of the code is
cannam@250: still reasonably straightforward, however.
cannam@250: 
cannam@40: 
cannam@40: Plugin Lookup and Categorisation
cannam@40: ================================
cannam@40: 
cannam@40: The Vamp API does not officially specify how to load plugin libraries
cannam@40: or where to find them.  However, the SDK does include a function
cannam@40: (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@75: directory search path that hosts may use for plugin libraries, and a
cannam@75: class (Vamp::HostExt::PluginLoader) that implements a sensible
cannam@75: cross-platform lookup policy using this path.  We recommend using this
cannam@75: class in your host unless you have a good reason not to want to.  This
cannam@75: implementation also permits the user to set the environment variable
cannam@75: VAMP_PATH to override the default path if desired.
cannam@40: 
cannam@75: The policy used by Vamp::HostExt::PluginLoader -- and our
cannam@75: recommendation for any host -- is to search each directory in the path
cannam@75: returned by getPluginPath for .DLL (on Windows), .so (on Linux,
cannam@75: Solaris, BSD etc) or .dylib (on OS/X) files, then to load each one and
cannam@75: perform a dynamic name lookup on the vampGetPluginDescriptor function
cannam@75: to enumerate the plugins in the library.  This operation will
cannam@75: necessarily be system-dependent.
cannam@40: 
cannam@40: Vamp also has an informal convention for sorting plugins into
cannam@40: functional categories.  In addition to the library file itself, a
cannam@40: plugin library may install a category file with the same name as the
cannam@40: library but .cat extension.  The existence and format of this file are
cannam@40: not specified by the Vamp API, but by convention the file may contain
cannam@40: lines of the format
cannam@40: 
cannam@40: vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@40: 
cannam@40: which a host may read and use to assign plugins a location within a
cannam@40: category tree for display to the user.  The expectation is that
cannam@40: advanced users may also choose to set up their own preferred category
cannam@40: trees, which is why this information is not queried as part of the
cannam@75: Vamp plugin's API itself.  The Vamp::HostExt::PluginLoader class also
cannam@75: provides support for plugin category lookup using this scheme.
cannam@32: 
cannam@14: 
cannam@14: Licensing
cannam@14: =========
cannam@14: 
cannam@18: This plugin SDK is freely redistributable under a "new-style BSD"
cannam@42: licence.  See the file COPYING for more details.  In short, you may
cannam@42: modify and redistribute the SDK and example plugins within any
cannam@42: commercial or non-commercial, proprietary or open-source plugin or
cannam@42: application under almost any conditions, with no obligation to provide
cannam@42: source code, provided you retain the original copyright note.
cannam@14: 
cannam@14: 
cannam@14: See Also
cannam@14: ========
cannam@14: 
cannam@14: Sonic Visualiser, an interactive open-source graphical audio
cannam@14: inspection, analysis and visualisation tool supporting Vamp plugins.
cannam@35: http://www.sonicvisualiser.org/
cannam@14: 
cannam@14: 
cannam@44: Authors
cannam@44: =======
cannam@44: 
cannam@44: Vamp and the Vamp SDK were designed and made at the Centre for Digital
cannam@64: Music at Queen Mary, University of London.
cannam@44: 
Chris@423: The SDK was written by Chris Cannam, copyright (c) 2005-2016
cannam@64: Chris Cannam and QMUL.
cannam@64: 
cannam@64: Mark Sandler and Christian Landone provided ideas and direction, and
cannam@64: Mark Levy, Dan Stowell, Martin Gasser and Craig Sapp provided testing
cannam@64: and other input for the 1.0 API and SDK.  The API also uses some ideas
cannam@64: from prior plugin systems, notably DSSI (http://dssi.sourceforge.net)
cannam@64: and FEAPI (http://feapi.sourceforge.net).
cannam@64: