comparison README @ 40:ae3e47e76d2d

* Add plugin path traversal and plugin listing option to vamp-simple-host
* Add more notes on plugin lookup and categorisation

 
 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.
 
-The Vamp API doesn't officially specify how to load plugin libraries
-or where to find them.  However, good practice for a host is to use
-the Vamp path returned by Vamp::PluginHostAdapter::getPluginPath() and
-search each directory in this path for .so, .dll or .dylib files
-(depending on platform), loading each one and testing for the
-vampGetPluginDescriptor function to enumerate the plugins in this
-object.  The example host has some code that may help.
+
+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.
+
+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.
+
+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 API itself.
 
 
 Building the SDK
 ================