- Added extra argument to xtract_spectrum to give the option of normalising the magnitude/power coeffificients

- Removed duplicate code block (argc assignment) from descriptors.c
- Added some extra documentation to libxtract.h

2 files changed, 18 insertions, 4 deletions

diff --git a/xtract/libxtract.h b/xtract/libxtract.h
index 40512b0..4b948f1 100644
--- a/xtract/libxtract.h
+++ b/xtract/libxtract.h
@@ -25,8 +25,19 @@
   * 
   * This philosophy of 'cascading' features is followed throughout the library, for example with features that operate on the magnitude spectrum of a signal vector (e.g. 'irregularity'), the magnitude spectrum is not calculated 'inside' the respective function, instead, a pointer to the first element in an array containing the magnitude spectrum is passed in as an argument. 
   *
-  * Hopefully this not only makes the library more efficient when computing large numbers of features, but also makes it more flexible because extraction functions can be combined arbitrarily (one can take the irregularility of the Mel Frequency Cepstral Coefficients for example).
+  * Hopefully this not only makes the library more efficient when computing large numbers of features, but also makes it more flexible because extraction functions can be combined arbitrarily (one can take the irregularility of the Mel Frequency Cepstral Coefficients for example). 
   *
+  * All feature extraction functions follow the same prototype:
+  *
+int xtract_function_name(const float *data, const int N, const void *argv, float *result){
+  *
+  * \param const float *data points to an array of floats representing the input data
+  * \param const int N represents the number of elementes from *data to be considered in the calculation
+  * \param const void *argv represents an arbitrary list of arguments. Used to pass in values required by the feature calculation
+  * \param float *result points to an array of floats, or a single float represnting the result of the calculation
+  *
+  *
+  * It is up to the calling function to allocate enough memory for the *data, *argv, and *result, and to free it when required. Some feature extraction functions may also require an _init() function to be called in order to perform some initialisation. The struct xtract_function_descriptor_t is used to give an indication of recommended default values, and argc for the *argv array.
   *
   * LibXtract can be downloaded from http://www.sf.net/projects/libxtract
   *
diff --git a/xtract/xtract_vector.h b/xtract/xtract_vector.h
index 7effac0..e758f10 100644
--- a/xtract/xtract_vector.h
+++ b/xtract/xtract_vector.h
@@ -34,12 +34,15 @@ extern "C" {
   * @{
   */
 
-/** \brief Extract normalized (0-1) frequency domain spectrum from time domain signal 
+/** \brief Extract frequency domain spectrum from time domain signal
  * 
  * \param *data: a pointer to the first element in an array of floats representing an audio vector
  * \param N: the number of array elements to be considered
- * \param *argv: a pointer to an array of floats, the first representing (samplerate / N), the second will be cast to an integer and determines the spectrum type (e.g. XTRACT_MAGNITUDE_SPECTRUM, XTRACT_LOG_POWER_SPECTRUM). The third argument determines whether or not the DC component is included in the output. If argv[2] == 1, then the DC component is included in which case the size of the array pointed to by *result must be N+2. For any further use of the array pointed to by *result, the value of N must reflect the (larger) array size.
- * \param *result: a pointer to an array of size N containing N/2 magnitude/power/log magnitude/log power coefficients and N/2 bin frequencies.
+ * \param *argv: a pointer to an array of floats, the first representing (samplerate / N), the second will be cast to an integer and determines the spectrum type (e.g. XTRACT_MAGNITUDE_SPECTRUM, XTRACT_LOG_POWER_SPECTRUM). The third argument determines whether or not the DC component is included in the output. If argv[2] == 1, then the DC component is included in which case the size of the array pointed to by *result must be N+2. For any further use of the array pointed to by *result, the value of N must reflect the (larger) array size. The fourth argument determines whether the magnitude/power coefficients are to be normalised. If argv[3] == 1, then the coefficients are normalised.
+ * \param *result: a pointer to an array of size N containing N/2 magnitude/power/log magnitude/log power coefficients and N/2 bin frequencies. 
+ *
+ * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1
+ *
  */
 int xtract_spectrum(const float *data, const int N, const void *argv, float *result);