changeset 151:5a6b8f4be9b9 tracks tip

Docs

--- a/.hgsubstate	Fri Apr 21 14:22:42 2017 +0100
+++ b/.hgsubstate	Fri Apr 21 14:33:57 2017 +0100
@@ -1,2 +1,2 @@
-b35d5b2abf847f9102e58cb23bd37f69b26f8bda test/vamp-test-plugin
+96cb7ef3cc24630e86d1ac1556b8ce48510d9634 test/vamp-test-plugin
 c42aeb56d8288001ff45d6f00594e5f5b1e8f3de vamp-plugin-sdk

--- a/vamp/collect.py	Fri Apr 21 14:22:42 2017 +0100
+++ b/vamp/collect.py	Fri Apr 21 14:33:57 2017 +0100
@@ -159,20 +159,30 @@
     by setting its parameters according to the (string) key and
     (float) value data found in the dict.
 
-    The results are returned in a dictionary which will always contain
-    exactly one element, whose key is one of the strings "vector",
-    "matrix", "list", or "tracks".
+    The results are returned in a dictionary. This will always contain
+    exactly one of the keys "vector", "matrix", or "list". In addition
+    it may optionally contain the key "tracks". Which of these is used
+    depends on the structure of features set out in the output
+    descriptor for the requested plugin output, and sometimes on the
+    features themselves, as follows:
 
-    Which one is used depends on the structure of features set out in
-    the output descriptor for the requested plugin output, and sometimes
-    on the features themselves:
+    * If the plugin output emits single-valued features at a fixed
+    sample-rate, then the "vector" element will be used. It will contain
+    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 single-valued features continuously at
-    a fixed sample-rate starting at the beginning of the input, then the
-    "vector" element will be used. It will contain 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 above is true but it also happens that the plugin output
+    has gaps between some features, so that a single continuous vector
+    can't convey all the relevant information, then the "tracks" element
+    will additionally be used. It will contain a list of dictionaries,
+    one for each set of contiguous points in the output, each containing
+    elements "start" (start time in seconds), "step" (step time in
+    seconds), and "values" (a one-dimensional NumPy array of contiguous
+    feature values). An example of such a feature might be the output of
+    a pitch tracker that emits values only during pitched sections of
+    the input audio.
 
     * If the plugin output emits multiple-valued features, with an
     equal number of bins per feature, at a fixed sample-rate, then
@@ -181,14 +191,6 @@
     values) and a two-dimensional NumPy array of feature values. An
     example of such a feature might be a spectrogram.
 
-    * If the plugin output emits single-valued features at a fixed
-    sample-rate but with gaps between features or a non-zero start time,
-    then the "tracks" element will be used. It will contain a list of
-    dictionaries, each containing a startTime, a stepTime, and a
-    one-dimensional NumPy array of contiguous feature values. An example
-    of such a feature might be a pitch tracker that emits values only
-    during pitched sections of the input audio.
-
     * Otherwise, the "list" element will be used, and will contain a
     list of features, where each feature is represented as a
     dictionary containing a timestamp (always) and a duration