comparison src/vamp-plugin-sdk-2.5/README @ 23:619f715526df sv_v2.1

Update Vamp plugin SDK to 2.5

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