mirror of
https://github.com/cookiengineer/audacity
synced 2026-01-12 07:35:51 +01:00
Move library tree where it belongs
This commit is contained in:
ra
241
lib-src/libvamp/README
Normal file
241
lib-src/libvamp/README
Normal file
@@ -0,0 +1,241 @@
|
||||
|
||||
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.0 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.
|
||||
|
||||
|
||||
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-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).
|
||||
|
||||
Reference in New Issue
Block a user