changeset 129:b8fe675f9c3f

Doc update, & make the plugin key args be called plugin_key rather than just key

--- a/README.rst	Wed Jun 24 15:11:58 2015 +0100
+++ b/README.rst	Wed Jun 24 16:14:32 2015 +0100
@@ -63,33 +63,43 @@
 
 This module contains three sorts of function:
 
- * Lookup functions: ``list_plugins``, ``get_outputs_of``, ``get_category_of``
+ 1. Basic info and lookup functions:
 
-   These retrieve the installed plugin identifiers and get basic
-   information about each plugin. For more detailed information, load
-   a plugin and inspect it using the low-level interface described
-   below.
+   * ``vamp.list_plugins``
+   * ``vamp.get_outputs_of``
+   * ``vamp.get_category_of``
 
- * Process functions: ``process_audio``, ``process_frames``,
-   ``process_audio_multiple_outputs``, ``process_frames_multiple_outputs``
+   These retrieve the installed plugin keys and get basic information
+   about each plugin. (For more detailed information, load a plugin
+   and inspect it using the low-level interface described below.)
+
+ 2. Process functions:
+
+   * ``vamp.process_audio``
+   * ``vamp.process_frames``
+   * ``vamp.process_audio_multiple_outputs``
+   * ``vamp.process_frames_multiple_outputs``
 
    These accept audio input, and produce output in the form of a list
    of feature sets structured similarly to those in the C++ Vamp
-   plugin SDK. The plugin to be used is specified by its identifier. A
-   dictionary of plugin parameter settings may optionally be supplied.
+   plugin SDK. The plugin to be used is specified by its key (the
+   identifier as returned by ``vamp.list_plugins``). A dictionary of
+   plugin parameter settings may optionally be supplied.
 
    The ``_audio`` versions take a single (presumably long) array of
    audio samples as input, and chop it into frames according to the
    plugin's preferred step and block sizes. The ``_frames`` versions
    instead accept an enumerable sequence of audio frame arrays.
 
- * The process-and-collect function: ``collect``
+ 3. The process-and-collect function:
+
+   * ``vamp.collect``
 
    This accepts a single array of audio samples as input, and returns
    an output structure that reflects the underlying structure of the
    feature output (depending on whether it is a curve, grid, etc). The
-   plugin to be used is specified by its identifier. A dictionary of
-   plugin parameter settings may optionally be supplied.
+   plugin to be used is specified by its key. A dictionary of plugin
+   parameter settings may optionally be supplied.
 
    The ``collect`` function processes the whole input before returning
    anything; if you need to supply a streamed input, or retrieve

--- a/vamp/__init__.py	Wed Jun 24 15:11:58 2015 +0100
+++ b/vamp/__init__.py	Wed Jun 24 16:14:32 2015 +0100
@@ -27,11 +27,135 @@
 #   used in advertising or otherwise to promote the sale, use or other
 #   dealings in this Software without prior written authorization.
 
-'''Load and use Vamp plugins for audio feature analysis. This module
-is a high-level interface wrapper around a native-code extension, for
-quickly and easily running Vamp analysis plugins on buffers of audio
-data. For low-level plugin loading and manipulation, refer to the
-vamp.vampyhost namespace which contains the native-code extension.
+'''
+Python Vamp plugin host
+=======================
+
+This module allows Python code to load and use native-code Vamp
+plugins (http://vamp-plugins.org) for audio feature analysis.
+
+The module consists of a native-code extension ("vampyhost") that
+provides a low-level wrapper for the Vamp plugin SDK, along with a
+Python wrapper ("vamp") that provides a higher-level abstraction.
+
+No code for loading audio files is included; you'll need to use some
+other module for that. This code expects to receive decoded audio data
+of one or more channels, either as a series of frames or as a single
+whole buffer.
+
+Written by Chris Cannam and George Fazekas at the Centre for Digital
+Music, Queen Mary University of London. Copyright 2008-2015 Queen
+Mary, University of London. Refer to COPYING.rst for licence details.
+
+See home page at https://code.soundsoftware.ac.uk/projects/vampy-host
+for more details.
+
+
+A simple example
+----------------
+
+Using librosa (http://bmcfee.github.io/librosa/) to read an audio
+file, and the NNLS Chroma Vamp plugin
+(https://code.soundsoftware.ac.uk/projects/nnls-chroma/) for
+analysis::
+
+    $ python
+    >>> import vamp
+    >>> import librosa
+    >>> data, rate = librosa.load("example.wav")
+    >>> chroma = vamp.collect(data, rate, "nnls-chroma:nnls-chroma")
+    >>> chroma
+    {'matrix': ( 0.092879819, array([[  61.0532608 ,   60.27478409,   59.3938446 , ...,  182.13394165,
+              42.40084457,  116.55457306],
+           [  68.8901825 ,   63.98115921,   60.77633667, ...,  245.88218689,
+              68.51251984,  164.70120239],
+           [  58.59794617,   50.3429184 ,   45.44804764, ...,  258.02362061,
+              83.95749664,  179.91200256],
+           ..., 
+           [   0.        ,    0.        ,    0.        , ...,    0.        ,
+               0.        ,    0.        ],
+           [   0.        ,    0.        ,    0.        , ...,    0.        ,
+               0.        ,    0.        ],
+           [   0.        ,    0.        ,    0.        , ...,    0.        ,
+               0.        ,    0.        ]], dtype=float32))}
+    >>> stepsize, chromadata = chroma["matrix"]
+    >>> import matplotlib.pyplot as plt
+    >>> plt.imshow(chromadata)
+    <matplotlib.image.AxesImage object at 0x7fe9e0043fd0>
+    >>> plt.show()
+
+And a pitch-chroma plot appears.
+
+
+High-level interface (vamp)
+---------------------------
+
+This module contains three sorts of function:
+
+ 1. Basic info and lookup functions:
+
+   * ``vamp.list_plugins``
+   * ``vamp.get_outputs_of``
+   * ``vamp.get_category_of``
+
+   These retrieve the installed plugin keys and get basic information
+   about each plugin. (For more detailed information, load a plugin
+   and inspect it using the low-level interface described below.)
+
+ 2. Process functions:
+
+   * ``vamp.process_audio``
+   * ``vamp.process_frames``
+   * ``vamp.process_audio_multiple_outputs``
+   * ``vamp.process_frames_multiple_outputs``
+
+   These accept audio input, and produce output in the form of a list
+   of feature sets structured similarly to those in the C++ Vamp
+   plugin SDK. The plugin to be used is specified by its key (the
+   identifier as returned by ``vamp.list_plugins``). A dictionary of
+   plugin parameter settings may optionally be supplied.
+
+   The ``_audio`` versions take a single (presumably long) array of
+   audio samples as input, and chop it into frames according to the
+   plugin's preferred step and block sizes. The ``_frames`` versions
+   instead accept an enumerable sequence of audio frame arrays.
+
+ 3. The process-and-collect function:
+
+   * ``vamp.collect``
+
+   This accepts a single array of audio samples as input, and returns
+   an output structure that reflects the underlying structure of the
+   feature output (depending on whether it is a curve, grid, etc). The
+   plugin to be used is specified by its key. A dictionary of plugin
+   parameter settings may optionally be supplied.
+
+   The ``collect`` function processes the whole input before returning
+   anything; if you need to supply a streamed input, or retrieve
+   results as they are calculated, then you must use one of the
+   ``process`` functions (above) or else the low-level interface
+   (below).
+
+
+Low-level interface (vampyhost)
+-------------------------------
+
+This extension contains facilities that operate on Vamp plugins in a
+way analogous to the existing C++ Vamp Host SDK: ``list_plugins``,
+``get_plugin_path``, ``get_category_of``, ``get_library_for``,
+``get_outputs_of``, ``load_plugin``, and a utility function
+``frame_to_realtime``.
+
+Calling ``load_plugin`` gets you a ``vampyhost.Plugin`` object, which
+then exposes all of the methods found in the Vamp SDK Plugin class.
+
+(Note that methods wrapped directly from the Vamp SDK are named using
+camelCase, so as to match the names found in the C++ SDK. Elsewhere
+this module follows Python PEP8 naming.)
+
+See the individual module and function documentation for further
+details.
+
 '''
 
 import vampyhost

--- a/vamp/collect.py	Wed Jun 24 15:11:58 2015 +0100
+++ b/vamp/collect.py	Wed Jun 24 16:14:32 2015 +0100
@@ -108,7 +108,7 @@
     return rv
 
         
-def collect(data, sample_rate, key, output = "", parameters = {}):
+def collect(data, sample_rate, plugin_key, output = "", parameters = {}):
     """Process audio data with a Vamp plugin, and make the results from a
     single plugin output available as a single structure.
 
@@ -158,7 +158,7 @@
 
     """
 
-    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, key, parameters)
+    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, plugin_key, parameters)
 
     if output == "":
         output_desc = plugin.get_output(0)

--- a/vamp/load.py	Wed Jun 24 15:11:58 2015 +0100
+++ b/vamp/load.py	Wed Jun 24 16:14:32 2015 +0100
@@ -50,29 +50,29 @@
     """
     return vampyhost.list_plugins()
 
-def get_outputs_of(key):
+def get_outputs_of(plugin_key):
     """Obtain a list of the output identifiers for the given plugin key.
     """
-    return vampyhost.get_outputs_of(key)
+    return vampyhost.get_outputs_of(plugin_key)
 
-def get_category_of(key):
+def get_category_of(plugin_key):
     """Obtain the category descriptor, if any, for the given plugin key.
 
     The returned value is a list of descriptor terms, from least
     specific to most specific. The list may be empty if no category
     information is found for the plugin.
     """
-    return vampyhost.get_category_of(key)
+    return vampyhost.get_category_of(plugin_key)
 
-def load_and_configure(data, sample_rate, key, parameters):
-    """Load the plugin with the given key at a given sample rate,
+def load_and_configure(data, sample_rate, plugin_key, parameters):
+    """Load the plugin with the given plugin key, at a given sample rate,
     configure it with the parameter keys and values in the given
     parameter dictionary, and initialise it with its preferred step
     and block size. The channel count is taken from the shape of the
     data array provided.
     """
 
-    plug = vampyhost.load_plugin(key, sample_rate,
+    plug = vampyhost.load_plugin(plugin_key, sample_rate,
                                  vampyhost.ADAPT_INPUT_DOMAIN +
                                  vampyhost.ADAPT_CHANNEL_COUNT)
 

--- a/vamp/process.py	Wed Jun 24 15:11:58 2015 +0100
+++ b/vamp/process.py	Wed Jun 24 16:14:32 2015 +0100
@@ -59,7 +59,7 @@
                 yield { o: r }
 
 
-def process_audio(data, sample_rate, key, output = "", parameters = {}):
+def process_audio(data, sample_rate, plugin_key, output = "", parameters = {}):
     """Process audio data with a Vamp plugin, and make the results from a
     single plugin output available as a generator.
 
@@ -86,7 +86,7 @@
     structure, consider using vamp.collect() instead.
     """
 
-    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, key, parameters)
+    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, plugin_key, parameters)
 
     if output == "":
         output = plugin.get_output(0)["identifier"]
@@ -99,7 +99,7 @@
     plugin.unload()
 
 
-def process_frames(ff, sample_rate, step_size, key, output = "", parameters = {}):
+def process_frames(ff, sample_rate, step_size, plugin_key, output = "", parameters = {}):
     """Process audio data with a Vamp plugin, and make the results from a
     single plugin output available as a generator.
 
@@ -128,7 +128,7 @@
     If you would prefer to obtain all features in a single output
     structure, consider using vamp.collect() instead.
     """
-    plugin = vampyhost.load_plugin(key, sample_rate,
+    plugin = vampyhost.load_plugin(plugin_key, sample_rate,
                                    vampyhost.ADAPT_INPUT_DOMAIN +
                                    vampyhost.ADAPT_BUFFER_SIZE +
                                    vampyhost.ADAPT_CHANNEL_COUNT)
@@ -169,7 +169,7 @@
     plugin.unload()
     
 
-def process_audio_multiple_outputs(data, sample_rate, key, outputs, parameters = {}):
+def process_audio_multiple_outputs(data, sample_rate, plugin_key, outputs, parameters = {}):
     """Process audio data with a Vamp plugin, and make the results from a
     set of plugin outputs available as a generator.
 
@@ -193,7 +193,7 @@
     array of float values.
     """
 
-    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, key, parameters)
+    plugin, step_size, block_size = vamp.load.load_and_configure(data, sample_rate, plugin_key, parameters)
 
     ff = vamp.frames.frames_from_array(data, step_size, block_size)
 
@@ -203,7 +203,7 @@
     plugin.unload()
 
 
-def process_frames_multiple_outputs(ff, sample_rate, step_size, key, outputs, parameters = {}):
+def process_frames_multiple_outputs(ff, sample_rate, step_size, plugin_key, outputs, parameters = {}):
     """Process audio data with a Vamp plugin, and make the results from a
     set of plugin outputs available as a generator.
 
@@ -229,7 +229,7 @@
     duration (RealTime objects), label (string), and a 1-dimensional
     array of float values.
     """
-    plugin = vampyhost.load_plugin(key, sample_rate,
+    plugin = vampyhost.load_plugin(plugin_key, sample_rate,
                                    vampyhost.ADAPT_INPUT_DOMAIN +
                                    vampyhost.ADAPT_BUFFER_SIZE +
                                    vampyhost.ADAPT_CHANNEL_COUNT)