annotate vamp-sdk/doc-overview @ 211:caa9d07bb9bd

* Update VC project file to handle proper export of plugin lookup function, and use the right dll name to match the other platforms and the .cat file
author cannam
date Sat, 18 Oct 2008 16:51:51 +0000
parents 7a27dbdd663a
children 991d2ae87980
rev   line source
cannam@54 1
cannam@54 2 /** \mainpage Vamp Plugin SDK
cannam@54 3
cannam@54 4 \section about About Vamp
cannam@54 5
cannam@54 6 Vamp is an API for C and C++ plugins that process sampled audio data
cannam@54 7 to produce descriptive output (measurements or semantic observations).
cannam@54 8 Find more information at http://www.vamp-plugins.org/ .
cannam@54 9
cannam@54 10 Although the official API for Vamp plugins is defined in C for maximum
cannam@54 11 binary compatibility, we strongly recommend using the provided C++
cannam@54 12 classes in the SDK to implement your own plugins and hosts.
cannam@54 13
cannam@54 14 \section plugins For Plugins
cannam@54 15
cannam@54 16 Plugins should subclass Vamp::Plugin, and then use a
cannam@54 17 Vamp::PluginAdapter to expose the correct C API for the plugin. Read
cannam@54 18 the documentation for Vamp::PluginBase and Vamp::Plugin before
cannam@54 19 starting.
cannam@54 20
cannam@54 21 Plugins should be compiled and linked into dynamic libraries using the
cannam@54 22 usual convention for your platform, and should link (preferably
cannam@54 23 statically) with -lvamp-sdk. Any number of plugins can reside in a
cannam@54 24 single dynamic library. See plugins.cpp in the example plugins
cannam@54 25 directory for the sort of code that will need to accompany your plugin
cannam@54 26 class or classes, to make it possible for a host to look up your
cannam@54 27 plugins properly.
cannam@54 28
cannam@54 29 The following example plugins are provided:
cannam@54 30
cannam@54 31 - ZeroCrossing calculates the positions and density of zero-crossing
cannam@54 32 points in an audio waveform.
cannam@54 33
cannam@54 34 - SpectralCentroid calculates the centre of gravity of the frequency
cannam@54 35 domain representation of each block of audio.
cannam@54 36
cannam@54 37 - AmplitudeFollower is an implementation of SuperCollider's
cannam@54 38 amplitude-follower algorithm as a simple Vamp plugin.
cannam@54 39
cannam@54 40 - PercussionOnsetDetector estimates the locations of percussive
cannam@54 41 onsets using a simple method described in "Drum Source Separation
cannam@54 42 using Percussive Feature Detection and Spectral Modulation" by Dan
cannam@54 43 Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
cannam@54 44
cannam@54 45 \section hosts For Hosts
cannam@54 46
cannam@75 47 Hosts will normally use a Vamp::PluginHostAdapter to convert each
cannam@75 48 plugin's exposed C API back into a useful Vamp::Plugin C++ object.
cannam@75 49
cannam@75 50 Starting with version 1.1 of the Vamp SDK, there are several classes
cannam@75 51 in the Vamp::HostExt namespace that aim to make the host's life as
cannam@75 52 easy as possible:
cannam@75 53
cannam@75 54 - Vamp::HostExt::PluginLoader provides a very simple interface for a
cannam@75 55 host to discover, load, and find out category information about the
cannam@75 56 available plugins. Most "casual" Vamp hosts will probably want to
cannam@75 57 use this class.
cannam@75 58
cannam@75 59 - Vamp::HostExt::PluginInputDomainAdapter provides a simple means for
cannam@75 60 hosts to handle plugins that expect frequency-domain input, without
cannam@75 61 having to convert the input themselves.
cannam@75 62
cannam@75 63 - Vamp::HostExt::PluginChannelAdapter provides a simple means for
cannam@75 64 hosts to use plugins that do not necessarily support the same number
cannam@75 65 of audio channels as they have available, without having to apply a
cannam@75 66 channel management / mixdown policy themselves.
cannam@75 67
cannam@126 68 - Vamp::HostExt::PluginBufferingAdapter (new in version 1.2) provides
cannam@126 69 a means for hosts to avoid having to negotiate the input step and
cannam@126 70 block size, instead permitting the host to use any block size they
cannam@126 71 desire (and a step size equal to it). This is particularly useful
cannam@126 72 for "streaming" hosts that cannot seek backwards in the input audio
cannam@126 73 stream and so would otherwise need to implement an additional buffer
cannam@126 74 to support step sizes smaller than the block size.
cannam@126 75
cannam@75 76 The PluginLoader class can also use the input domain and channel
cannam@75 77 adapters automatically to make the entire conversion process
cannam@75 78 transparent to the host if required.
cannam@54 79
cannam@54 80 Hosts should link with -lvamp-hostsdk.
cannam@54 81
cannam@75 82 (The following notes in this section are mostly relevant for
cannam@75 83 developers that are not using the HostExt classes, or that wish to
cannam@75 84 know more about the policy they implement.)
cannam@75 85
cannam@54 86 The Vamp API does not officially specify how to load plugin libraries
cannam@54 87 or where to find them. However, the SDK does include a function
cannam@54 88 (Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended
cannam@54 89 directory search path that hosts may use for plugin libraries.
cannam@54 90
cannam@54 91 Our suggestion for a host is to search each directory in this path for
cannam@54 92 .DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on
cannam@54 93 OS/X) files, then to load each one and perform a dynamic name lookup
cannam@54 94 on the vampGetPluginDescriptor function to enumerate the plugins in
cannam@54 95 the library. The example host has some code that may help, but this
cannam@54 96 operation will necessarily be system-dependent.
cannam@54 97
cannam@54 98 Vamp also has an informal convention for sorting plugins into
cannam@54 99 functional categories. In addition to the library file itself, a
cannam@54 100 plugin library may install a category file with the same name as the
cannam@54 101 library but .cat extension. The existence and format of this file are
cannam@54 102 not specified by the Vamp API, but by convention the file may contain
cannam@54 103 lines of the format
cannam@54 104
cannam@54 105 \code
cannam@54 106 vamp:pluginlibrary:pluginname::General Category > Specific Category
cannam@54 107 \endcode
cannam@54 108
cannam@54 109 which a host may read and use to assign plugins a location within a
cannam@54 110 category tree for display to the user. The expectation is that
cannam@54 111 advanced users may also choose to set up their own preferred category
cannam@54 112 trees, which is why this information is not queried as part of the
cannam@54 113 Vamp API itself.
cannam@54 114
cannam@75 115 There is an example host in the "host" directory from which code may
cannam@75 116 be drawn.
cannam@54 117
cannam@54 118 \section license License
cannam@54 119
cannam@54 120 This plugin SDK is freely redistributable under a "new-style BSD"
cannam@54 121 licence. See the file COPYING for more details. In short, you may
cannam@54 122 modify and redistribute the SDK and example plugins within any
cannam@54 123 commercial or non-commercial, proprietary or open-source plugin or
cannam@54 124 application under almost any conditions, with no obligation to provide
cannam@54 125 source code, provided you retain the original copyright note.
cannam@54 126
cannam@54 127
cannam@54 128 */