changeset 99:7764eb74a3c6

Docs

--- a/vamp/collect.py	Tue Feb 03 14:43:50 2015 +0000
+++ b/vamp/collect.py	Tue Feb 03 16:24:37 2015 +0000
@@ -81,7 +81,49 @@
 
         
 def collect(data, sample_rate, key, output = "", parameters = {}):
+    """Process audio data with a Vamp plugin, and make the results from a
+    single plugin output available as a single structure.
 
+    The provided data should be a 1- or 2-dimensional list or NumPy
+    array of floats. If it is 2-dimensional, the first dimension is
+    taken to be the channel count.
+
+    The returned results will be those calculated by the plugin with
+    the given key and returned through its output with the given
+    output identifier. If the requested output is the empty string,
+    the first output provided by the plugin will be used.
+
+    If the parameters dict is non-empty, the plugin will be configured
+    by setting its parameters according to the (string) key and
+    (float) value data found in the dict.
+
+    The structure in which the results are returned depends upon the
+    output descriptor for the requested plugin output, as follows:
+
+    * If the plugin output emits single-valued features at a fixed
+      sample-rate, then this function will return a tuple of step time
+      (the time in seconds between consecutive feature values) and a
+      one-dimensional NumPy array of feature values. An example of
+      such a feature might be a loudness curve against time.
+
+    * If the plugin output emits multiple-valued features, with an
+      equal number of bins per feature, at a fixed sample-rate, then
+      this function will return a tuple of step time (the time in
+      seconds between consecutive feature values) and a
+      two-dimensional NumPy array of feature values. An example of
+      such a feature might be a spectrogram.
+
+    * Otherwise this function will return a list of features, where
+      each feature is represented as a dictionary containing a
+      timestamp (always) and a duration (optionally), a label
+      (string), and a 1-dimensional array of float values.
+
+    If you would prefer to obtain features as they are calculated
+    (where the plugin supports this) and with the format in which the
+    plugin returns them, via an asynchronous generator function, use
+    vamp.process() instead.
+    """
+    
     plugin, step_size, block_size = load.load_and_configure(data, sample_rate, key, parameters)
 
     if output == "":
@@ -99,29 +141,31 @@
     plugin.unload()
     return rv
 
+
+#!!! restore & complete this once process is refactored:
         
-def collect_frames(ff, channels, sample_rate, step_size, key, output = "", parameters = {}):
+# def collect_frames(ff, channels, sample_rate, step_size, key, output = "", parameters = {}):
 
-    plug = vampyhost.load_plugin(key, sample_rate,
-                                 vampyhost.ADAPT_INPUT_DOMAIN +
-                                 vampyhost.ADAPT_BUFFER_SIZE +
-                                 vampyhost.ADAPT_CHANNEL_COUNT)
+#     plug = vampyhost.load_plugin(key, sample_rate,
+#                                  vampyhost.ADAPT_INPUT_DOMAIN +
+#                                  vampyhost.ADAPT_BUFFER_SIZE +
+#                                  vampyhost.ADAPT_CHANNEL_COUNT)
 
-    plug.set_parameter_values(parameters)
+#     plug.set_parameter_values(parameters)
 
-    if not plug.initialise(channels, step_size, block_size):
-        raise "Failed to initialise plugin"
+#     if not plug.initialise(channels, step_size, block_size):
+#         raise "Failed to initialise plugin"
 
-    if output == "":
-        output_desc = plugin.get_output(0)
-        output = output_desc["identifier"]
-    else:
-        output_desc = plugin.get_output(output)
+#     if output == "":
+#         output_desc = plugin.get_output(0)
+#         output = output_desc["identifier"]
+#     else:
+#         output_desc = plugin.get_output(output)
 
-    results = process.process_frames_with_plugin(ff, sample_rate, step_size, plugin, [output])
+#     results = process.process_frames_with_plugin(ff, sample_rate, step_size, plugin, [output])
 
-    rv = reshape(results, sample_rate, step_size, output_desc)
+#     rv = reshape(results, sample_rate, step_size, output_desc)
 
-    plugin.unload()
-    return rv
+#     plugin.unload()
+#     return rv
 

--- a/vamp/process.py	Tue Feb 03 14:43:50 2015 +0000
+++ b/vamp/process.py	Tue Feb 03 16:24:37 2015 +0000
@@ -52,6 +52,9 @@
     dictionary containing, optionally, timestamp and duration
     (RealTime objects), label (string), and a 1-dimensional array of
     float values.
+
+    If you would prefer to obtain all features in a single output
+    structure, consider using vamp.collect() instead.
     """
 
     plugin, step_size, block_size = load.load_and_configure(data, sample_rate, key, parameters)
@@ -92,8 +95,10 @@
     dictionary containing, optionally, timestamp and duration
     (RealTime objects), label (string), and a 1-dimensional array of
     float values.
+
+    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,
                                    vampyhost.ADAPT_INPUT_DOMAIN +
                                    vampyhost.ADAPT_BUFFER_SIZE +
@@ -136,7 +141,28 @@
     
 
 def process_multiple_outputs(data, sample_rate, key, outputs, parameters = {}):
-#!!! docstring
+    """Process audio data with a Vamp plugin, and make the results from a
+    set of plugin outputs available as a generator.
+
+    The provided data should be a 1- or 2-dimensional list or NumPy
+    array of floats. If it is 2-dimensional, the first dimension is
+    taken to be the channel count.
+
+    The returned results will be those calculated by the plugin with
+    the given key and returned through its outputs whose identifiers
+    are given in the outputs argument.
+
+    If the parameters dict is non-empty, the plugin will be configured
+    by setting its parameters according to the (string) key and
+    (float) value data found in the dict.
+
+    This function acts as a generator, yielding a sequence of result
+    feature sets as it obtains them. Each feature set is a dictionary
+    mapping from output identifier to a list of features, each
+    represented as a dictionary containing, optionally, timestamp and
+    duration (RealTime objects), label (string), and a 1-dimensional
+    array of float values.
+    """
 
     plugin, step_size, block_size = load.load_and_configure(data, sample_rate, key, parameters)
 
@@ -146,3 +172,7 @@
         yield r
 
     plugin.unload()
+
+#!!!
+# + process_frames_multiple_outputs
+# + refactor common material