# HG changeset patch
# User Jamie Bullock <jamie@postlude.co.uk>
# Date 1166700711 0
# Node ID c20e91e86f088fb576e8fedbae274331c62f3e49
# Parent  4725bee447c2b0189713f40861955d18e16fcbe2
xtract_magnitude_spectrum() and xtract_peaks() share format of N/2 frequency values and N/2 magnitude coefficients. 'Fixed' xtract_loudness() so that N=1 can be used for specific loudness.

diff -r 4725bee447c2 -r c20e91e86f08 src/scalar.c
--- a/src/scalar.c	Wed Dec 20 16:47:52 2006 +0000
+++ b/src/scalar.c	Thu Dec 21 11:31:51 2006 +0000
@@ -291,14 +291,17 @@
 
 int xtract_loudness(const float *data, const int N, const void *argv, float *result){
 
-    int n = BARK_BANDS;
+    int n = N, rv;
 
-    /*if(n != N) return BAD_VECTOR_SIZE; */
+    if(n > BARK_BANDS) 
+	rv = BAD_VECTOR_SIZE; 
+    else
+	rv = SUCCESS;
 
     while(n--)
 	*result += pow(data[n], 0.23);
 
-    return SUCCESS;
+    return rv;
 }
 
 int xtract_flatness(const float *data, const int N, const void *argv, float *result){
diff -r 4725bee447c2 -r c20e91e86f08 src/vector.c
--- a/src/vector.c	Wed Dec 20 16:47:52 2006 +0000
+++ b/src/vector.c	Thu Dec 21 11:31:51 2006 +0000
@@ -51,12 +51,12 @@
     fftwf_execute(plan);
     
     for(n = 1; n < M; n++){
-        result[n] = sqrt(SQ(temp[n]) + SQ(temp[N - n])) / N;
-        result[M + n] = n * q;
+        result[M + n] = sqrt(SQ(temp[n]) + SQ(temp[N - n])) / N;
+        result[n] = n * q;
     }
     
-    result[0] = fabs(temp[0]) / N;
-    result[M] = q * .5;
+    result[M] = fabs(temp[0]) / N;
+    result[0] = q * .5;
     
     fftwf_destroy_plan(plan);
     fftwf_free(temp);
diff -r 4725bee447c2 -r c20e91e86f08 xtract/xtract_scalar.h
--- a/xtract/xtract_scalar.h	Wed Dec 20 16:47:52 2006 +0000
+++ b/xtract/xtract_scalar.h	Thu Dec 21 11:31:51 2006 +0000
@@ -90,16 +90,19 @@
 
 /** \brief Extract the centroid of an input vector
  * 
- * \param *data: a pointer to the first element in an array of floats represeting a frequency spectrum of size N/2 and a magnitude peak spectrum of size N/2 (This is the output format of xtract_peaks)
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the centroid of the values pointed to by *data
+ *
+ * Note: for a more 'accurate' result *result from xtract_peaks() can be passed in. This gives the interpolated peak frequency locations.
+ *
  */
 int xtract_centroid(const float *data, const int N, const void *argv,  float *result);
 
 /** \brief Calculate the Irregularity of an input vector using a method described by Krimphoff (1994)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the irregularity of N values from the array pointed to by *data
@@ -108,7 +111,7 @@
 
 /** \brief Calculate the Irregularity of an input vector using a method described by Jensen (1999)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the irregularity of N values from the array pointed to by *data
@@ -117,7 +120,7 @@
 
 /** \brief Calculate the Tristimulus of an input vector using a method described by Pollard and Jansson (1982)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the amplitudes of the harmonic spectrum of an audio vector e.g. a pointer to the second half of the array pointed to by *result from xtract_harmonics(). The amplitudes of the peak spectrum (e.g. *result from xtract_peaks()) can be used if one wishes to consider all partials not just harmonics.
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients of the harmonic spectrum of an audio vector e.g. a pointer to the second half of the array pointed to by *result from xtract_harmonics(). The amplitudes of the peak spectrum (e.g. *result from xtract_peaks()) can be used if one wishes to consider all partials not just harmonics.
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the tristimulus of N values from the array pointed to by *data
@@ -131,7 +134,7 @@
 
 /** \brief Extract the smoothness of an input vector using a method described by McAdams (1999)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to the first element of an array of integers containing the lower bound, upper bound, and pre-scaling factor, whereby array data in the range lower < n < upper will be pre-scaled by p before processing. 
  * \param *result: the smoothness of N values from the array pointed to by *data
@@ -140,7 +143,7 @@
 
 /** \brief Extract the spectral spread of an input vector using a method described by Casagrande(2005)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the spectral spread of N values from the array pointed to by *data
@@ -160,7 +163,7 @@
 
 /** \brief Extract the spectral rolloff of an input vector using a method described by Bee Suan Ong (2005)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to an array containing a floating point value representing the threshold for rolloff, i.e. the percentile at which the rolloff is determined, expressed in the range 0-1.0, and a float representing the sample rate in Hz
  * \param *result: the spectral rolloff in Hz of N values from the array pointed to by *data. This is the point in the spectrum below which argv[0] of the energy is distributed.
@@ -170,18 +173,21 @@
 /* Loudness */
 /* A set of BARK_BANDS bark coefficients must be passed in, the loudness is calculated approximately according to Moore, Glasberg et al, 1997 */
 
-/** \brief Extract the loudness of an input vector using a method described by Moore, Glasberg et al (2005)
+/** \brief Extract the 'total loudness' of an input vector using a method described by Moore, Glasberg et al (2005)
  * 
  * \param *data: a pointer to the first element in an array of floats representing a set of BARK_BANDS bark coefficients
  * \param N: the number of coefficients to be considered
  * \param *argv: a pointer to NULL
- * \param *result: the loudness of N values from the array pointed to by *data
+ * \param *result: the total loudness of N values from the array pointed to by *data
+ *
+ * Note: if N = 1, the 'specific loudness' of the bark band pointed to by *data will be given by *result
+ *
  */
 int xtract_loudness(const float *data, const int N, const void *argv, float *result);
 
 /** \brief Extract the spectral flatness measure of an input vector using a method described by Tristan Jehan (2005)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the spectral flatness of N values from the array pointed to by *data
@@ -200,7 +206,7 @@
 
 /** \brief Extract the noisiness of an input vector using a method described by Tae Hong Park (2000)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the noisiness of N values from the array pointed to by *data
@@ -227,7 +233,7 @@
 
 /** \brief Extract the spectral crest of an input vector using a method described by Peeters (2003)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the spectral crest of N values from the array pointed to by *data
@@ -236,7 +242,7 @@
     
 /** \brief Extract the Spectral Power of an input vector using a method described by Bee Suan Ong (2005)
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the spectral power of N values from the array pointed to by *data
@@ -256,6 +262,7 @@
 /** \brief Extract the Sharpness of an input vector 
  * 
  * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the Sharpness of N values from the array pointed to by *data
@@ -265,6 +272,7 @@
 /** \brief Extract the Slope of an input vector 
  * 
  * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the Slope of N values from the array pointed to by *data
@@ -305,7 +313,7 @@
  * 
  * \warning {This function doesn't work properly}
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of elements to be considered
  * \param *argv: a pointer to NULL
  * \param *result: the pitch of N values from the array pointed to by *data
diff -r 4725bee447c2 -r c20e91e86f08 xtract/xtract_vector.h
--- a/xtract/xtract_vector.h	Wed Dec 20 16:47:52 2006 +0000
+++ b/xtract/xtract_vector.h	Thu Dec 21 11:31:51 2006 +0000
@@ -38,8 +38,9 @@
  * 
  * \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 NULL 
- * \param *result: the magnitude spectrum of N values from the array pointed to by *data 
+ * \param *argv: a pointer to a float representing the sample rate of the audio 
+ * \param *result: a pointer to an array containing N/2 bin frequencies, and N/2
+ * magnitude coefficients.
  */
 int xtract_magnitude_spectrum(const float *data, const int N, const void *argv, float *result);
 
@@ -54,7 +55,7 @@
 
 /** \brief Extract Mel Frequency Cepstral Coefficients based on a method described by Rabiner
  * 
- * \param *data: a pointer to the first element in an array of floats
+ * \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 a data structure of type xtract_mel_filter, containing n_filters coefficient tables to make up a mel-spaced filterbank
  * \param *result: a pointer to an array containing the resultant MFCC
@@ -82,7 +83,7 @@
 
 /** \brief Extract Average Magnitude Difference Function from time domain signal 
  * 
- * \param *data: a pointer to the first element in an array of floats
+ * \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 NULL 
  * \param *result: the AMDF of N values from the array pointed to by *data 
@@ -99,7 +100,7 @@
 int xtract_asdf(const float *data, const int N, const void *argv, float *result);
     
 /** \brief Extract Bark band coefficients based on a method   
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of array elements to be considered
  * \param *argv: a pointer to an array of ints representing the limits of each bark band. This can be obtained  by calling xtract_init_bark.
  * \param *result: a pointer to an array containing resultant bark coefficients
@@ -110,7 +111,7 @@
 int xtract_bark_coefficients(const float *data, const int N, const void *argv, float *result);
 
 /** \brief Extract the frequency and amplitude of spectral peaks from a magnitude spectrum
- * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the second half of the array pointed to by *result from xtract_magnitude_spectrum().
  * \param N: the number of array elements to be considered
  * \param *argv: a pointer to an array containing the peak threshold as percentage of the magnitude of the maximum peak found, and the sample rate in Hz.  
  * \param *result: a pointer to an array of size N, containing N/2 freqs and N/2 amplitudes