diff options
Diffstat (limited to 'libs/vamp-sdk/README')
| -rw-r--r-- | libs/vamp-sdk/README | 240 |
1 files changed, 0 insertions, 240 deletions
diff --git a/libs/vamp-sdk/README b/libs/vamp-sdk/README deleted file mode 100644 index 9454038260..0000000000 --- a/libs/vamp-sdk/README +++ /dev/null @@ -1,240 +0,0 @@ - -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.1b 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. - -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 -lvampsdk. [*NOTE: this has changed from vamp-sdk in -previous versions, to avoid conflict with the use of hyphens for -library versioning schemes on some platforms.] - -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 -lvamphostsdk. [*NOTE: this has changed from vamp-hostsdk -in previous versions, to avoid conflict with the use of hyphens for -library versioning schemes on some platforms.] - - * vamp-sdk/hostext - -Additional C++ classes to make a host's life easier (introduced in -version 1.1 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. - -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. - - -Building and Installing the SDK and Examples -============================================ - -To build the SDK, the simple host, and the example plugins, edit the -Makefile to suit your platform according to the comments in it, then -run "make". - -To use an IDE to build a plugin or host using the Vamp SDK, simply add -the .cpp files in the vamp-sdk directory to your project. - -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-2007 -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). - |