Update of /cvsroot/audacity/lib-src/libvamp
In directory sc8-pr-cvs11.sourceforge.net:/tmp/cvs-serv30437/lib-src/libvamp
Added Files:
COPYING Doxyfile Makefile README
Log Message:
New files for Chris Cannam's vamp plug in
--- NEW FILE: README ---
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.1 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 -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
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".
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
When building a plugin or host of your own using the SDK, you will
need to include the headers from the vamp-sdk directory; then when
linking your plugin or host, we suggest statically linking the SDK
code (in preference to distributing it alongside your program in DLL
form). An easy way to do this, if using a project-based build tool
such as Visual Studio or XCode, is simply to add the .cpp files in the
vamp-sdk directory to your project.
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).
--- NEW FILE: Doxyfile ---
# Doxyfile 1.4.4
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
# TAG = value [value, ...]
# For lists items can also be appended using:
# TAG += value [value, ...]
# Values that contain spaces should be placed between quotes (" ")
#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
[...1196 lines suppressed...]
# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
# generate a legend page explaining the meaning of the various boxes and
# arrows in the dot generated graphs.
GENERATE_LEGEND = YES
# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
# remove the intermediate dot files that are used to generate
# the various graphs.
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
# The SEARCHENGINE tag specifies whether or not a search engine should be
# used. If set to NO the values of all tags below this one will be ignored.
SEARCHENGINE = NO
--- NEW FILE: Makefile ---
# Makefile for the Vamp plugin SDK. This builds the SDK objects,
# libraries, example plugins, and the test host. Please adjust to
# suit your operating system requirements.
APIDIR = vamp
SDKDIR = vamp-sdk
HOSTEXTDIR = vamp-sdk/hostext
EXAMPLEDIR = examples
HOSTDIR = host
###
### Start of user-serviceable parts
###
# Default build target (or use "make <target>" to select one).
# Targets are:
# all -- build everything
# sdk -- build all the Vamp SDK libraries for plugins and hosts
# plugins -- build the example plugins (and the SDK if required)
# host -- build the simple Vamp plugin host (and the SDK if required)
# test -- build the host and example plugins, and run a quick test
# clean -- remove binary targets
# distclean -- remove all targets
#
default: all
# Compile flags
#
CXXFLAGS := $(CXXFLAGS) -O2 -Wall -I.
# Libraries required for the plugins.
# (Note that it is desirable to statically link libstdc++ if possible,
# because our plugin exposes only a C API so there are no boundary
# compatibility problems.)
#
PLUGIN_LIBS = $(SDKDIR)/libvamp-sdk.a
#PLUGIN_LIBS = vamp-sdk/libvamp-sdk.a $(shell g++
-print-file-name=libstdc++.a)
# Flags required to tell the compiler to link to a dynamically loadable object
#
PLUGIN_LDFLAGS = -shared -Wl,-Bsymbolic -static-libgcc
# File extension for a dynamically loadable object
#
PLUGIN_EXT = .so
## For OS/X with g++:
#PLUGIN_LDFLAGS = -dynamiclib
#PLUGIN_EXT = .dylib
# Libraries required for the host.
#
HOST_LIBS = $(SDKDIR)/libvamp-hostsdk.a -lsndfile -ldl
# Locations for "make install". This will need quite a bit of
# editing for non-Linux platforms. Of course you don't necessarily
# have to use "make install".
#
INSTALL_PREFIX := /usr/local
INSTALL_API_HEADERS := $(INSTALL_PREFIX)/include/vamp
INSTALL_SDK_HEADERS := $(INSTALL_PREFIX)/include/vamp-sdk
INSTALL_HOSTEXT_HEADERS := $(INSTALL_PREFIX)/include/vamp-sdk/hostext
INSTALL_SDK_LIBS := $(INSTALL_PREFIX)/lib
INSTALL_SDK_LIBNAME := libvamp-sdk.so.1.0.0
INSTALL_SDK_LINK_ABI := libvamp-sdk.so.1
INSTALL_SDK_LINK_DEV := libvamp-sdk.so
INSTALL_SDK_STATIC := libvamp-sdk.a
INSTALL_SDK_LA := libvamp-sdk.la
INSTALL_HOSTSDK_LIBNAME := libvamp-hostsdk.so.1.0.0
INSTALL_HOSTSDK_LINK_ABI := libvamp-hostsdk.so.1
INSTALL_HOSTSDK_LINK_DEV := libvamp-hostsdk.so
INSTALL_HOSTSDK_STATIC := libvamp-hostsdk.a
INSTALL_HOSTSDK_LA := libvamp-hostsdk.la
INSTALL_PKGCONFIG := $(INSTALL_PREFIX)/lib/pkgconfig
### End of user-serviceable parts
API_HEADERS = \
$(APIDIR)/vamp.h
SDK_HEADERS = \
$(SDKDIR)/Plugin.h \
$(SDKDIR)/PluginAdapter.h \
$(SDKDIR)/PluginBase.h \
$(SDKDIR)/RealTime.h
HOSTSDK_HEADERS = \
$(SDKDIR)/Plugin.h \
$(SDKDIR)/PluginBase.h \
$(SDKDIR)/PluginHostAdapter.h \
$(SDKDIR)/RealTime.h
HOSTEXT_HEADERS = \
$(HOSTEXTDIR)/PluginChannelAdapter.h \
$(HOSTEXTDIR)/PluginInputDomainAdapter.h \
$(HOSTEXTDIR)/PluginLoader.h \
$(HOSTEXTDIR)/PluginWrapper.h
SDK_OBJECTS = \
$(SDKDIR)/PluginAdapter.o \
$(SDKDIR)/RealTime.o
HOSTSDK_OBJECTS = \
$(SDKDIR)/PluginHostAdapter.o \
$(HOSTEXTDIR)/PluginChannelAdapter.o \
$(HOSTEXTDIR)/PluginInputDomainAdapter.o \
$(HOSTEXTDIR)/PluginLoader.o \
$(HOSTEXTDIR)/PluginWrapper.o \
$(SDKDIR)/RealTime.o
SDK_STATIC = \
$(SDKDIR)/libvamp-sdk.a
HOSTSDK_STATIC = \
$(SDKDIR)/libvamp-hostsdk.a
SDK_DYNAMIC = \
$(SDKDIR)/libvamp-sdk.so
HOSTSDK_DYNAMIC = \
$(SDKDIR)/libvamp-hostsdk.so
SDK_LA = \
$(SDKDIR)/libvamp-sdk.la
PLUGIN_HEADERS = \
$(EXAMPLEDIR)/SpectralCentroid.h \
$(EXAMPLEDIR)/PercussionOnsetDetector.h \
$(EXAMPLEDIR)/AmplitudeFollower.h \
$(EXAMPLEDIR)/ZeroCrossing.h
PLUGIN_OBJECTS = \
$(EXAMPLEDIR)/SpectralCentroid.o \
$(EXAMPLEDIR)/PercussionOnsetDetector.o \
$(EXAMPLEDIR)/AmplitudeFollower.o \
$(EXAMPLEDIR)/ZeroCrossing.o \
$(EXAMPLEDIR)/plugins.o
PLUGIN_TARGET = \
$(EXAMPLEDIR)/vamp-example-plugins$(PLUGIN_EXT)
HOST_HEADERS = \
$(HOSTDIR)/system.h
HOST_OBJECTS = \
$(HOSTDIR)/vamp-simple-host.o
HOST_TARGET = \
$(HOSTDIR)/vamp-simple-host
sdk: $(SDK_STATIC) $(SDK_DYNAMIC) $(HOSTSDK_STATIC)
$(HOSTSDK_DYNAMIC)
plugins: $(PLUGIN_TARGET)
host: $(HOST_TARGET)
all: sdk plugins host test
$(SDK_STATIC): $(SDK_OBJECTS) $(API_HEADERS) $(SDK_HEADERS)
$(AR) r $@ $(SDK_OBJECTS)
$(HOSTSDK_STATIC): $(HOSTSDK_OBJECTS) $(API_HEADERS) $(HOSTSDK_HEADERS)
$(HOSTEXT_HEADERS)
$(AR) r $@ $(HOSTSDK_OBJECTS)
$(SDK_DYNAMIC): $(SDK_OBJECTS) $(API_HEADERS) $(SDK_HEADERS)
$(CXX) $(LDFLAGS) $(PLUGIN_LDFLAGS) -o $@ $(SDK_OBJECTS)
$(HOSTSDK_DYNAMIC): $(HOSTSDK_OBJECTS) $(API_HEADERS) $(HOSTSDK_HEADERS)
$(HOSTEXT_HEADERS)
$(CXX) $(LDFLAGS) $(PLUGIN_LDFLAGS) -o $@ $(HOSTSDK_OBJECTS)
$(PLUGIN_TARGET): $(PLUGIN_OBJECTS) $(SDK_STATIC) $(PLUGIN_HEADERS)
$(CXX) $(LDFLAGS) $(PLUGIN_LDFLAGS) -o $@ $(PLUGIN_OBJECTS)
$(PLUGIN_LIBS)
$(HOST_TARGET): $(HOST_OBJECTS) $(HOSTSDK_STATIC) $(HOST_HEADERS)
$(CXX) $(LDFLAGS) $(HOST_LDFLAGS) -o $@ $(HOST_OBJECTS)
$(HOST_LIBS)
test: plugins host
VAMP_PATH=$(EXAMPLEDIR) $(HOST_TARGET) -l
clean:
rm -f $(SDK_OBJECTS) $(HOSTSDK_OBJECTS) $(PLUGIN_OBJECTS)
$(HOST_OBJECTS)
distclean: clean
rm -f $(SDK_STATIC) $(SDK_DYNAMIC) $(HOSTSDK_STATIC)
$(HOSTSDK_DYNAMIC) $(PLUGIN_TARGET) $(HOST_TARGET) *~ */*~
install: $(SDK_STATIC) $(SDK_DYNAMIC) $(HOSTSDK_STATIC)
$(HOSTSDK_DYNAMIC) $(PLUGIN_TARGET) $(HOST_TARGET)
mkdir -p $(INSTALL_API_HEADERS)
mkdir -p $(INSTALL_SDK_HEADERS)
mkdir -p $(INSTALL_HOSTEXT_HEADERS)
mkdir -p $(INSTALL_SDK_LIBS)
mkdir -p $(INSTALL_PKGCONFIG)
cp $(API_HEADERS) $(INSTALL_API_HEADERS)
cp $(SDK_HEADERS) $(INSTALL_SDK_HEADERS)
cp $(HOSTSDK_HEADERS) $(INSTALL_SDK_HEADERS)
cp $(HOSTEXT_HEADERS) $(INSTALL_HOSTEXT_HEADERS)
cp $(SDK_STATIC) $(INSTALL_SDK_LIBS)
cp $(HOSTSDK_STATIC) $(INSTALL_SDK_LIBS)
cp $(SDK_DYNAMIC) $(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LIBNAME)
cp $(HOSTSDK_DYNAMIC)
$(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LIBNAME)
rm -f $(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LINK_ABI)
ln -s $(INSTALL_SDK_LIBNAME)
$(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LINK_ABI)
rm -f $(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LINK_ABI)
ln -s $(INSTALL_HOSTSDK_LIBNAME)
$(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LINK_ABI)
rm -f $(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LINK_DEV)
ln -s $(INSTALL_SDK_LIBNAME)
$(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LINK_DEV)
rm -f $(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LINK_DEV)
ln -s $(INSTALL_HOSTSDK_LIBNAME)
$(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LINK_DEV)
sed "s,%PREFIX%,$(INSTALL_PREFIX)," $(APIDIR)/vamp.pc.in \
> $(INSTALL_PKGCONFIG)/vamp.pc
sed "s,%PREFIX%,$(INSTALL_PREFIX)," $(SDKDIR)/vamp-sdk.pc.in \
> $(INSTALL_PKGCONFIG)/vamp-sdk.pc
sed "s,%PREFIX%,$(INSTALL_PREFIX),"
$(SDKDIR)/vamp-hostsdk.pc.in \
> $(INSTALL_PKGCONFIG)/vamp-hostsdk.pc
sed -e "s,%LIBNAME%,$(INSTALL_SDK_LIBNAME),g" \
-e "s,%LINK_ABI%,$(INSTALL_SDK_LINK_ABI),g" \
-e "s,%LINK_DEV%,$(INSTALL_SDK_LINK_DEV),g" \
-e "s,%STATIC%,$(INSTALL_SDK_STATIC),g" \
-e "s,%LIBS%,$(INSTALL_SDK_LIBS),g" $(SDK_LA).in \
> $(INSTALL_SDK_LIBS)/$(INSTALL_SDK_LA)
sed -e "s,%LIBNAME%,$(INSTALL_HOSTSDK_LIBNAME),g" \
-e "s,%LINK_ABI%,$(INSTALL_HOSTSDK_LINK_ABI),g" \
-e "s,%LINK_DEV%,$(INSTALL_HOSTSDK_LINK_DEV),g" \
-e "s,%STATIC%,$(INSTALL_HOSTSDK_STATIC),g" \
-e "s,%LIBS%,$(INSTALL_SDK_LIBS),g" $(SDK_LA).in \
> $(INSTALL_SDK_LIBS)/$(INSTALL_HOSTSDK_LA)
--- NEW FILE: COPYING ---
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR
ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Except as contained in this notice, the names of the Centre for
Digital Music; Queen Mary, University of London; and Chris Cannam
shall not be used in advertising or otherwise to promote the sale,
use or other dealings in this Software without prior written
authorization.
-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Audacity-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/audacity-cvs
