rollback to 3428, before the mysterious removal of libs/* at 3431/3432

git-svn-id: svn://localhost/ardour2/branches/3.0@3435 d708f5d6-7413-0410-9779-e7cbd77b26cf

1 files changed, 240 insertions, 0 deletions

diff --git a/libs/vamp-sdk/README b/libs/vamp-sdk/README
new file mode 100644
index 0000000000..9454038260
--- /dev/null
+++ b/libs/vamp-sdk/README
@@ -0,0 +1,240 @@
+
+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).
+