Mercurial > hg > vamp-plugin-sdk

changeset 239:cc467e52da4c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* Add platform README files
author cannam
date Mon, 10 Nov 2008 12:39:19 +0000
parents 4b5a3031cd08
children 7b90fe049d04
files README build/README.linux build/README.msvc build/README.osx src/doc-overview
diffstat 5 files changed, 358 insertions(+), 219 deletions(-) [+]
line wrap: on
line diff
--- a/README	Sun Nov 09 17:42:37 2008 +0000
+++ b/README	Mon Nov 10 12:39:19 2008 +0000
@@ -9,57 +9,35 @@
 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 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.
+built using version 1.0 of the SDK.  See 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
+
+vamp/vamp.h
+-----------
 
 The formal C language plugin API for Vamp plugins.
 
@@ -68,81 +46,110 @@
 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.
+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
+
+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, and
-refer to the example plugin code in the examples directory.  Plugins
-should link with -lvamp-sdk.
+read vamp-sdk/PluginBase.h and Plugin.h for code documentation.
 
- * vamp-hostsdk
+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 can 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.
+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
-make a host's life easier:
+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 "casual" Vamp hosts will probably want to use
-this class.
+ - 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 means for hosts to
-handle plugins that expect frequency-domain input, without having to
-convert the input themselves.
+ - 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 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.
+ - 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::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.
 
-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.
+ - 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.
 
- * examples
+The PluginLoader class can also use the input domain, channel, and
+buffering adapters automatically to make these conversions transparent
+to the host if required.
 
-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 authors should also refer to the example host code in the host
+directory of the SDK.
 
- * host
+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.
+
+ - 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.
-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
@@ -183,88 +190,6 @@
 provides support for plugin category lookup using this scheme.
 
 
-Compiling the SDK and Examples
-==============================
-
-This SDK is intended for use on Windows, OS/X, Linux, and other POSIX
-platforms.
-
- * Windows
-
-Two Visual C++ project files are included:
-
-   VampPluginSDK.vcproj -- builds the SDK into a single static
-   library, but does not build the example plugins or host
-
-   VampExamplePlugins.vcproj -- builds the example plugins DLL, but
-   does not build the library or host
-
-Alternatively, when using Visual Studio or another IDE to build a
-plugin or host using the SDK, you may prefer to simply add the .h and
-.cpp files in the vamp-sdk and vamp-sdk/hostext directories to your
-existing project.
-
-As the command-line host has additional library dependencies (namely
-libsndfile), no pre-packaged project is included to build it.
-
-When using Visual C++ to build plugins, you will need to ensure that
-the plugin entry point (vampGetPluginDescriptor) is exported from the
-DLL so that the plugins can be loaded.  One way to achieve this is to
-add the linker option /EXPORT:vampGetPluginDescriptor to your project.
-The included VampExamplePlugins.vcproj does this.
-
-If you are using a Cygwin or MinGW GNU toolchain, use the included
-Makefile (see Linux and other POSIX platforms below).
-
- * OS/X
-
-Run "make -f Makefile.osx" to build the SDK, example plugins, and
-command-line host.
-
-Note that the host requires that you have libsndfile
-(http://www.mega-nerd.com/libsndfile/) installed.  To build only the
-SDK and examples, "make -f Makefile.osx sdk examples".
-
-If you are using an IDE, you may prefer to simply add the .h and .cpp
-files in the vamp-sdk and vamp-sdk/hostext directories to your
-existing project.
-
- * Linux and other Unixesque platforms
-
-To build the SDK, example plugins, and command-line host, edit the
-Makefile to suit your platform according to the comments in it, then
-run "make".
-
-Note that the host requires that you have libsndfile
-(http://www.mega-nerd.com/libsndfile/) installed.  To build only the
-SDK and examples, edit the Makefile then run "make sdk examples".
-
-
-Installing the Example Plugins
-==============================
-
-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
 =========
 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/build/README.linux	Mon Nov 10 12:39:19 2008 +0000
@@ -0,0 +1,65 @@
+
+The Vamp Plugin SDK -- Platform Notes for Linux and other GNU platforms
+=======================================================================
+
+Building at the command line
+----------------------------
+
+To build the SDK, example plugins, and command-line host, first edit
+the Makefile to suit your platform according to the comments in it,
+then run "make".
+
+Note that you must have libsndfile
+(http://www.mega-nerd.com/libsndfile/) installed in order to build the
+command-line host successfully.  To build only the SDK and examples,
+run "make sdk examples" instead of just "make".
+
+
+Installing the Example Plugins
+------------------------------
+
+To install the example plugins so you can load them in Vamp hosts,
+copy the files
+
+   examples/vamp-example-plugins.so
+and
+   examples/vamp-example-plugins.cat
+
+to
+   /usr/local/lib/vamp/
+or 
+   $HOME/vamp/
+
+
+Plugin Linkage
+--------------
+
+Vamp plugins are distributed as dynamic libraries (.so files).  A
+properly packaged Vamp plugin library should export exactly one public
+symbol, namely the Vamp API entry point vampGetPluginDescriptor.
+
+The default for the GNU linker is to export all of the symbols in the
+library.  This will work (the host will be able to load the plugin),
+but it unnecessarily pollutes the host's symbol namespace, it may
+cause symbol collisions in some esoteric circumstances, and it
+increases the amount of time the plugin takes to load.
+
+To improve this behaviour, you can instruct the linker to export only
+the one required symbol using a linker script.  To do this, place the
+text
+
+{
+	global: vampGetPluginDescriptor;
+	local: *;
+};
+
+into a text file, and then use the --version-script option to the
+linker to tell it to refer to this file.  All other symbols will then
+be properly hidden.
+
+The Makefile included in this SDK uses this method to manage symbol
+visibility for the included example plugins, using the file
+build/vamp-plugin.map.  There are other methods that will work too,
+but this one is simple and has the advantage of requiring no changes
+to the code.
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/build/README.msvc	Mon Nov 10 12:39:19 2008 +0000
@@ -0,0 +1,80 @@
+
+The Vamp Plugin SDK -- Platform Notes for Visual C++ on Windows
+===============================================================
+
+Visual C++ Project Files
+------------------------
+
+Three Visual C++ project files are included with the SDK:
+
+ - build/VampPluginSDK.vcproj
+
+   This builds the plugin SDK into a single static library, but does
+   not build the example plugins, the host SDK, or the host.  (We
+   recommend using static linkage for the SDK rather than distributing
+   it as a DLL, particularly when building plugins.)
+
+ - build/VampHostSDK.vcproj
+
+   This builds the host SDK into a single static library, but does not
+   build the plugin SDK, example plugins, or host.
+
+ - build/VampExamplePlugins.vcproj
+
+   This builds the example plugins DLL, but does not build the plugin
+   or host SDKs or the host.  You don't need to build the plugin SDK
+   before this, because this project simply includes the plugin SDK
+   files rather than using the library.
+
+Of course, when using Visual Studio or another IDE to build a plugin
+or host using the SDK, you may simply add the .h and .cpp files in the
+vamp-sdk or vamp-hostsdk directories to your existing project.  This
+is the approach taken in the VampExamplePlugins project.
+
+As the command-line host has additional library dependencies (namely
+libsndfile), no pre-packaged project is included to build it.
+
+
+Installing the Example Plugins
+------------------------------
+
+To install the example plugins so you can load them in Vamp hosts,
+copy the files
+
+   build\release\vamp-example-plugins.dll
+and
+   examples\vamp-example-plugins.cat
+
+to
+
+   C:\Program Files\Vamp Plugins
+
+
+Plugin Linkage
+--------------
+
+Vamp plugins are distributed as dynamic libraries (DLLs).  A properly
+packaged Vamp plugin DLL should export exactly one public symbol,
+namely the Vamp API entry point vampGetPluginDescriptor.
+
+One nice tidy way to achieve this with Visual Studio is to add the
+linker option /EXPORT:vampGetPluginDescriptor to your project.  (All
+of the other symbols will be properly hidden, because that is the
+default for the Visual Studio linker.)  The included example plugins
+project in build/VampExamplePlugins.vcproj does this.
+
+Alternatively, you may modify vamp/vamp.h to add the
+__declspec(dllexport) attribute to the vampGetPluginDescriptor
+declaration.  This is not present by default, because it isn't
+portable and, as we only want one symbol exported, the above linker
+option works equally well without code changes.
+
+(If you don't take at least one of these actions, your plugin library
+simply will not load in any host.)
+
+
+Using MinGW/Cygwin
+------------------
+
+Refer to README.linux for build instructions using the GNU toolchain.
+
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/build/README.osx	Mon Nov 10 12:39:19 2008 +0000
@@ -0,0 +1,67 @@
+
+The Vamp Plugin SDK -- Platform Notes for OS/X
+==============================================
+
+Building at the command line
+----------------------------
+
+To build the SDK, example plugins, and command-line host:
+
+ $ make -f Makefile.osx
+
+Note that you must have libsndfile
+(http://www.mega-nerd.com/libsndfile/) installed in order to build the
+command-line host successfully.  To build only the SDK and examples:
+
+ $ make -f Makefile.osx sdk examples
+
+If you are using an IDE, you may prefer to simply add the .h and .cpp
+files in the vamp-sdk and/or vamp-hostsdk directories to your existing
+project.
+
+
+Installing the Example Plugins
+------------------------------
+
+To install the example plugins so you can load them in Vamp hosts,
+copy the files
+
+   examples/vamp-example-plugins.dylib
+and
+   examples/vamp-example-plugins.cat
+
+to
+   /Library/Audio/Plug-Ins/Vamp/
+or 
+   $HOME/Library/Audio/Plug-Ins/Vamp/
+
+
+Plugin Linkage
+--------------
+
+Vamp plugins are distributed as dynamic libraries (.dylib).  A
+well-packaged Vamp plugin library should export exactly one public
+symbol, namely the Vamp API entry point vampGetPluginDescriptor.
+
+The default for the OS/X linker is to export all of the symbols in the
+library.  This will work (the host will be able to load the plugin),
+but it unnecessarily pollutes the host's symbol namespace, it may
+cause symbol collisions in some esoteric circumstances, and it
+increases the amount of time the plugin takes to load.
+
+To improve this behaviour, you can instruct the linker to export only
+the one required symbol using a symbols list file.  To do this, place
+the single line
+
+_vampGetPluginDescriptor
+
+(with leading underscore) into a text file, and then use the
+-exported_symbols_list option to the linker to tell it to refer to
+this file.  All other symbols will then be properly hidden.
+
+The Makefile.osx included in this SDK uses this method to manage
+symbol visibility for the included example plugins, using the file
+build/vamp-plugin.list.  There are other methods that will work too,
+but this one is simple and has the advantage of requiring no changes
+to the code.
+
--- a/src/doc-overview	Sun Nov 09 17:42:37 2008 +0000
+++ b/src/doc-overview	Mon Nov 10 12:39:19 2008 +0000
@@ -26,12 +26,9 @@
 class or classes, to make it possible for a host to look up your
 plugins properly.
 
-You will also need to ensure that the entry point
-vampGetPluginDescriptor is properly exported (made public) from your
-shared library.  The method to do this depends on your linker; for
-example, when using the Windows Visual Studio linker, use the linker
-flag "/EXPORT:vampGetPluginDescriptor".  Exported symbols are the
-default with most other current platforms' linkers.
+Please read the relevant README file for your platform found in the
+Vamp SDK build/ directory, for details about how to ensure the
+resulting dynamic library exports the correct linker symbols.
 
 The following example plugins are provided.  You may legally reuse any
 amount of the code from these examples in any plugins you write,
@@ -51,29 +48,28 @@
  using Percussive Feature Detection and Spectral Modulation" by Dan
  Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005.
 
- - FixedTempoEstimator calculates a single bpm 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.
+ - 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.
 
 \section hosts For Hosts
 
 Hosts will normally use a Vamp::PluginHostAdapter to convert each
 plugin's exposed C API back into a useful Vamp::Plugin C++ object.
 
-Starting with version 1.1 of the Vamp SDK, there are several classes
-in the Vamp::HostExt namespace that aim to make the host's life as
-easy as possible:
+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 simple interface for a
+ - 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.
+ 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 expect frequency-domain input, without
+ hosts to handle plugins that want frequency-domain input, without
  having to convert the input themselves.
 
  - Vamp::HostExt::PluginChannelAdapter provides a simple means for
@@ -81,24 +77,26 @@
  of audio channels as they have available, without having to apply a
  channel management / mixdown policy themselves.
 
- - Vamp::HostExt::PluginBufferingAdapter (new in version 1.2) 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::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 (new in version 2.0)
- 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.
+ - 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.
 
 (The following notes in this section are mostly relevant for
@@ -108,14 +106,20 @@
 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.
+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.
 
-Our suggestion for a host is to search each directory in this path 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.  The example host has some code that may help, but this
-operation will necessarily be system-dependent.
+The policy used by Vamp::HostExt::PluginLoader -- and our
+recommendation for any host -- is to search each directory in this
+path 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.  The example host has some code that may help,
+but 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
@@ -132,10 +136,8 @@
 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 API itself.
-
-There is an example host in the "host" directory from which code may
-be drawn.
+Vamp plugin's API itself.  The Vamp::HostExt::PluginLoader class also
+provides support for plugin category lookup using this scheme.
 
 \section license License