Mercurial > hg > vamp-plugin-sdk
view README @ 228:e58242c9ff85 distinct-libraries
* more moving
author | cannam |
---|---|
date | Thu, 06 Nov 2008 14:21:59 +0000 |
parents | a5a54b60e82e |
children | 3ad28b1e2150 |
line wrap: on
line source
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). The principal differences between Vamp and a real-time audio processing plugin system such as VST are: * Vamp plugins may output complex multidimensional data with labels. As a consequence, they are likely to work best when the output data has a much lower sampling rate than the input. (This also means it is usually desirable to implement them in C++ using the high-level base class provided rather than use the raw C API.) * While Vamp plugins receive data block-by-block, they are not required to return output immediately on receiving the input. A Vamp plugin may be non-causal, preferring to store up data based on its input until the end of a processing run and then return all results at once. * Vamp plugins have more control over their inputs than a typical real-time processing plugin. For example, they can indicate to the host their preferred processing block and step sizes, and these may differ. * Vamp plugins may ask to receive data in the frequency domain instead of the time domain. The host takes the responsibility for converting the input data using an FFT of windowed frames. This simplifies plugins that do straightforward frequency-domain processing and permits the host to cache frequency-domain data when possible. * A Vamp plugin is configured once before each processing run, and receives no further parameter changes during use -- unlike real- time plugin APIs in which the input parameters may change at any time. This also means that fundamental properties such as the number of values per output or the preferred processing block size may depend on the input parameters. * Vamp plugins do not have to be able to run in real time. About this SDK ============== This is version 1.3 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. A documentation guide to writing plugins using the Vamp SDK can be found at http://www.vamp-plugins.org/guide.pdf . 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++ abstraction found in the vamp-sdk directory (below) is preferable for most purposes and is more thoroughly documented. * vamp-sdk C++ classes for straightforwardly implementing Vamp plugins and hosts. 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, and refer to the example plugin code in the examples directory. Plugins should link with -lvamp-sdk. Hosts may use the Vamp::PluginHostAdapter to convert the loaded plugin's C API back into a Vamp::Plugin object. Host authors should refer to the example host code in the host directory. Hosts should link with -lvamp-hostsdk. * vamp-sdk/hostext Additional C++ classes to make a host's life easier (introduced in versions 1.1 and 1.2 of the Vamp SDK). Vamp::HostExt::PluginLoader provides a very easy interface for a host to discover, load, and find out category information about the available plugins. Most "casual" Vamp hosts will probably want to use this class. Vamp::HostExt::PluginInputDomainAdapter provides a means for hosts to handle plugins that expect frequency-domain input, without having to convert the input themselves. Vamp::HostExt::PluginChannelAdapter provides a means for hosts to use plugins that do not necessarily support the same number of audio channels as they have available, without having to worry about applying 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. The PluginLoader class can also use the input domain and channel adapters automatically to make the entire conversion process transparent to the host if required. * examples Example plugins implemented using the C++ classes. 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. AmplitudeFollower tracks the amplitude of a signal based on a method from the SuperCollider real-time audio system. 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. * 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. Requires libsndfile (http://www.mega-nerd.com/libsndfile/). If you don't have libsndfile, you may want to edit the Makefile to change the default build target from "all" to "sdk", so as to compile only the SDK and not the host. 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. Compiling the SDK and Examples ============================== This SDK is intended for use on Windows, OS/X, Linux, and other POSIX platforms. * Windows Two Visual C++ project files are included: VampPluginSDK.vcproj -- builds the SDK into a single static library, but does not build the example plugins or host VampExamplePlugins.vcproj -- builds the example plugins DLL, but does not build the library or host Alternatively, when using Visual Studio or another IDE to build a plugin or host using the SDK, you may prefer to simply add the .h and .cpp files in the vamp-sdk and vamp-sdk/hostext directories to your existing project. As the command-line host has additional library dependencies (namely libsndfile), no pre-packaged project is included to build it. When using Visual C++ to build plugins, you will need to ensure that the plugin entry point (vampGetPluginDescriptor) is exported from the DLL so that the plugins can be loaded. One way to achieve this is to add the linker option /EXPORT:vampGetPluginDescriptor to your project. The included VampExamplePlugins.vcproj does this. If you are using a Cygwin or MinGW GNU toolchain, use the included Makefile (see Linux and other POSIX platforms below). * OS/X Run "make -f Makefile.osx" to build the SDK, example plugins, and command-line host. Note that the host requires that you have libsndfile (http://www.mega-nerd.com/libsndfile/) installed. To build only the SDK and examples, "make -f Makefile.osx sdk examples". If you are using an IDE, you may prefer to simply add the .h and .cpp files in the vamp-sdk and vamp-sdk/hostext directories to your existing project. * Linux and other Unixesque platforms To build the SDK, example plugins, and command-line host, edit the Makefile to suit your platform according to the comments in it, then run "make". Note that the host requires that you have libsndfile (http://www.mega-nerd.com/libsndfile/) installed. To build only the SDK and examples, edit the Makefile then run "make sdk examples". Installing the Example Plugins ============================== Installing the example plugins so that they can be found by other Vamp hosts depends on your platform: * Windows: copy the files examples/vamp-example-plugins.dll examples/vamp-example-plugins.cat to C:\Program Files\Vamp Plugins * Linux: copy the files examples/vamp-example-plugins.so examples/vamp-example-plugins.cat to /usr/local/lib/vamp/ * OS/X: copy the files examples/vamp-example-plugins.dylib examples/vamp-example-plugins.cat to /Library/Audio/Plug-Ins/Vamp 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-2008 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).