changeset 9:44113b1e296b

* Add valueNames to parameter descriptor
* Change valueCount and valueNames to binCount and binNames in output
  descriptor, to avoid confusion with other uses of value
* Some explanatory notes about FFT alignment

--- a/examples/SpectralCentroid.cpp	Mon Apr 03 14:19:02 2006 +0000
+++ b/examples/SpectralCentroid.cpp	Wed Apr 05 16:50:07 2006 +0000
@@ -118,8 +118,8 @@
     d.name = "logcentroid";
     d.unit = "Hz";
     d.description = "Log Frequency Centroid";
-    d.hasFixedValueCount = true;
-    d.valueCount = 1;
+    d.hasFixedBinCount = true;
+    d.binCount = 1;
     d.hasKnownExtents = false;
     d.isQuantized = false;
     d.sampleType = OutputDescriptor::OneSamplePerStep;

--- a/examples/ZeroCrossing.cpp	Mon Apr 03 14:19:02 2006 +0000
+++ b/examples/ZeroCrossing.cpp	Wed Apr 05 16:50:07 2006 +0000
@@ -109,8 +109,8 @@
     zc.name = "counts";
     zc.unit = "crossings";
     zc.description = "Zero Crossing Counts";
-    zc.hasFixedValueCount = true;
-    zc.valueCount = 1;
+    zc.hasFixedBinCount = true;
+    zc.binCount = 1;
     zc.hasKnownExtents = false;
     zc.isQuantized = true;
     zc.quantizeStep = 1.0;
@@ -120,8 +120,8 @@
     zc.name = "zerocrossings";
     zc.unit = "";
     zc.description = "Zero Crossings";
-    zc.hasFixedValueCount = true;
-    zc.valueCount = 0;
+    zc.hasFixedBinCount = true;
+    zc.binCount = 0;
     zc.sampleType = OutputDescriptor::VariableSampleRate;
     zc.sampleRate = m_inputSampleRate;
     list.push_back(zc);

--- a/vamp-sdk/Plugin.h	Mon Apr 03 14:19:02 2006 +0000
+++ b/vamp-sdk/Plugin.h	Wed Apr 05 16:50:07 2006 +0000
@@ -205,59 +205,55 @@
 	std::string unit;
 
 	/**
-	 * True if the output has the same number of values per result
-	 * for every output result.  Outputs for which this is false
+	 * True if the output has the same number of values per sample
+	 * for every output sample.  Outputs for which this is false
 	 * are unlikely to be very useful in a general-purpose host.
 	 */
-	bool hasFixedValueCount;
+	bool hasFixedBinCount;
 
 	/**
 	 * The number of values per result of the output.  Undefined
-	 * if hasFixedValueCount is false.  If this is zero, the output
+	 * if hasFixedBinCount is false.  If this is zero, the output
 	 * is point data (i.e. only the time of each output is of
 	 * interest, the value list will be empty).
-	 *
-	 * Note that this gives the number of values of a single
-	 * output result, not of the output stream (which has one more
-	 * dimension: time).
 	 */
-	size_t valueCount;
+	size_t binCount;
 
 	/**
-	 * The names of each of the values, if appropriate.  This is
+	 * The names of each of the bins, if appropriate.  This is
 	 * always optional.
 	 */
-	std::vector<std::string> valueNames;
+	std::vector<std::string> binNames;
 
 	/**
-	 * True if the results in the output have a fixed numeric
-	 * range (minimum and maximum values).  Undefined if
-	 * valueCount is zero.
+	 * True if the results in each output bin fall within a fixed
+	 * numeric range (minimum and maximum values).  Undefined if
+	 * binCount is zero.
 	 */
 	bool hasKnownExtents;
 
 	/**
 	 * Minimum value of the results in the output.  Undefined if
-	 * hasKnownExtents is false or valueCount is zero.
+	 * hasKnownExtents is false or binCount is zero.
 	 */
 	float minValue;
 
 	/**
 	 * Maximum value of the results in the output.  Undefined if
-	 * hasKnownExtents is false or valueCount is zero.
+	 * hasKnownExtents is false or binCount is zero.
 	 */
 	float maxValue;
 
 	/**
 	 * True if the output values are quantized to a particular
-	 * resolution.  Undefined if valueCount is zero.
+	 * resolution.  Undefined if binCount is zero.
 	 */
 	bool isQuantized;
 
 	/**
 	 * Quantization resolution of the output values (e.g. 1.0 if
 	 * they are all integers).  Undefined if isQuantized is false
-	 * or valueCount is zero.
+	 * or binCount is zero.
 	 */
 	float quantizeStep;
 
@@ -284,7 +280,7 @@
 	 *
 	 * If sampleType is VariableSampleRate and this value is
 	 * non-zero, then it may be used to calculate a resolution for
-	 * the output (i.e. the "duration" of each value, in time).
+	 * the output (i.e. the "duration" of each sample, in time).
 	 * It's recommended to set this to zero if that behaviour is
 	 * not desired.
 	 */
@@ -318,8 +314,8 @@
 	
 	/**
 	 * Results for a single sample of this feature.  If the output
-	 * hasFixedValueCount, there must be the same number of values
-	 * as the output's valueCount count.
+	 * hasFixedBinCount, there must be the same number of values
+	 * as the output's binCount count.
 	 */
 	std::vector<float> values;
 
@@ -338,16 +334,19 @@
      * If the plugin's inputDomain is TimeDomain, inputBuffers will
      * point to one array of floats per input channel, and each of
      * these arrays will contain blockSize consecutive audio samples
-     * (the host will zero-pad as necessary).
+     * (the host will zero-pad as necessary).  The timestamp will be
+     * the real time in seconds of the start of the supplied block of
+     * samples.
      *
      * If the plugin's inputDomain is FrequencyDomain, inputBuffers
      * will point to one array of floats per input channel, and each
      * of these arrays will contain blockSize/2 consecutive pairs of
      * real and imaginary component floats corresponding to bins
-     * 0..(blockSize/2-1) of the FFT output.
-     *
-     * The timestamp is the real time in seconds of the start of the
-     * supplied block of samples.
+     * 0..(blockSize/2-1) of the FFT output.  The timestamp will be
+     * the real time in seconds of the centre of the FFT input window
+     * (i.e. the very first block passed to process might contain the
+     * FFT of half a block of zero samples and the first half-block of
+     * the actual data, with a timestamp of zero).
      *
      * Return any features that have become available after this
      * process call.  (These do not necessarily have to fall within

--- a/vamp-sdk/PluginAdapter.cpp	Mon Apr 03 14:19:02 2006 +0000
+++ b/vamp-sdk/PluginAdapter.cpp	Wed Apr 05 16:50:07 2006 +0000
@@ -76,6 +76,15 @@
         desc->defaultValue = m_parameters[i].defaultValue;
         desc->isQuantized = m_parameters[i].isQuantized;
         desc->quantizeStep = m_parameters[i].quantizeStep;
+        desc->valueNames = 0;
+        if (desc->isQuantized && !m_parameters[i].valueNames.empty()) {
+            desc->valueNames = (const char **)
+                malloc((m_parameters[i].valueNames.size()+1) * sizeof(char *));
+            for (unsigned int j = 0; j < m_parameters[i].valueNames.size(); ++j) {
+                desc->valueNames[j] = strdup(m_parameters[i].valueNames[j].c_str());
+            }
+            desc->valueNames[m_parameters[i].valueNames.size()] = 0;
+        }
         m_descriptor.parameters[i] = desc;
     }
     
@@ -134,6 +143,12 @@
         free((void *)desc->name);
         free((void *)desc->description);
         free((void *)desc->unit);
+        if (desc->valueNames) {
+            for (unsigned int j = 0; desc->valueNames[j]; ++j) {
+                free((void *)desc->valueNames[j]);
+            }
+            free((void *)desc->valueNames);
+        }
     }
     free((void *)m_descriptor.parameters);
 
@@ -287,10 +302,10 @@
     if (desc->name) free((void *)desc->name);
     if (desc->description) free((void *)desc->description);
     if (desc->unit) free((void *)desc->unit);
-    for (unsigned int i = 0; i < desc->valueCount; ++i) {
-        free((void *)desc->valueNames[i]);
+    for (unsigned int i = 0; i < desc->binCount; ++i) {
+        free((void *)desc->binNames[i]);
     }
-    if (desc->valueNames) free((void *)desc->valueNames);
+    if (desc->binNames) free((void *)desc->binNames);
     free((void *)desc);
 }
 
@@ -375,22 +390,22 @@
     desc->name = strdup(od.name.c_str());
     desc->description = strdup(od.description.c_str());
     desc->unit = strdup(od.unit.c_str());
-    desc->hasFixedValueCount = od.hasFixedValueCount;
-    desc->valueCount = od.valueCount;
+    desc->hasFixedBinCount = od.hasFixedBinCount;
+    desc->binCount = od.binCount;
 
-    if (od.valueCount > 0) {
-        desc->valueNames = (const char **)
-            malloc(od.valueCount * sizeof(const char *));
+    if (od.hasFixedBinCount && od.binCount > 0) {
+        desc->binNames = (const char **)
+            malloc(od.binCount * sizeof(const char *));
         
-        for (unsigned int i = 0; i < od.valueCount; ++i) {
-            if (i < od.valueNames.size()) {
-                desc->valueNames[i] = strdup(od.valueNames[i].c_str());
+        for (unsigned int i = 0; i < od.binCount; ++i) {
+            if (i < od.binNames.size()) {
+                desc->binNames[i] = strdup(od.binNames[i].c_str());
             } else {
-                desc->valueNames[i] = 0;
+                desc->binNames[i] = 0;
             }
         }
     } else {
-        desc->valueNames = 0;
+        desc->binNames = 0;
     }
 
     desc->hasKnownExtents = od.hasKnownExtents;

--- a/vamp-sdk/PluginBase.h	Mon Apr 03 14:19:02 2006 +0000
+++ b/vamp-sdk/PluginBase.h	Wed Apr 05 16:50:07 2006 +0000
@@ -141,6 +141,19 @@
 	 * false.
 	 */
 	float quantizeStep;
+
+        /**
+         * Names for the quantized values.  If isQuantized is true,
+         * this may either be empty or contain one string for each of
+         * the quantize steps from minValue up to maxValue inclusive.
+         * Undefined if isQuantized is false.
+         *
+         * If these names are provided, they should be shown to the
+         * user in preference to the values themselves.  The user may
+         * never see the actual numeric values unless they are also
+         * encoded in the names.
+         */
+        std::vector<std::string> valueNames;
     };
 
     typedef std::vector<ParameterDescriptor> ParameterList;

--- a/vamp-sdk/PluginHostAdapter.cpp	Mon Apr 03 14:19:02 2006 +0000
+++ b/vamp-sdk/PluginHostAdapter.cpp	Wed Apr 05 16:50:07 2006 +0000
@@ -125,6 +125,11 @@
         pd.defaultValue = spd->defaultValue;
         pd.isQuantized = spd->isQuantized;
         pd.quantizeStep = spd->quantizeStep;
+        if (pd.isQuantized && spd->valueNames) {
+            for (unsigned int j = 0; spd->valueNames[j]; ++j) {
+                pd.valueNames.push_back(spd->valueNames[j]);
+            }
+        }
         list.push_back(pd);
     }
     return list;
@@ -220,10 +225,12 @@
         d.name = sd->name;
         d.description = sd->description;
         d.unit = sd->unit;
-        d.hasFixedValueCount = sd->hasFixedValueCount;
-        d.valueCount = sd->valueCount;
-        for (unsigned int j = 0; j < sd->valueCount; ++j) {
-            d.valueNames.push_back(sd->valueNames[j] ? sd->valueNames[j] : "");
+        d.hasFixedBinCount = sd->hasFixedBinCount;
+        d.binCount = sd->binCount;
+        if (d.hasFixedBinCount) {
+            for (unsigned int j = 0; j < sd->binCount; ++j) {
+                d.binNames.push_back(sd->binNames[j] ? sd->binNames[j] : "");
+            }
         }
         d.hasKnownExtents = sd->hasKnownExtents;
         d.minValue = sd->minValue;

--- a/vamp/vamp.h	Mon Apr 03 14:19:02 2006 +0000
+++ b/vamp/vamp.h	Wed Apr 05 16:50:07 2006 +0000
@@ -61,6 +61,7 @@
     float defaultValue;
     int isQuantized;
     float quantizeStep;
+    const char **valueNames;
 
 } VampParameterDescriptor;
 
@@ -77,9 +78,9 @@
     const char *name;
     const char *description;
     const char *unit;
-    int hasFixedValueCount;
-    unsigned int valueCount;
-    const char **valueNames;
+    int hasFixedBinCount;
+    unsigned int binCount;
+    const char **binNames;
     int hasKnownExtents;
     float minValue;
     float maxValue;