4 files changed, 30 insertions, 10 deletions
diff --git a/xtract/libxtract.h b/xtract/libxtract.h
index 32d3c31..2fad148 100644
--- a/xtract/libxtract.h
+++ b/xtract/libxtract.h
@@ -96,6 +96,7 @@ enum xtract_features_ {
     XTRACT_ROLLOFF,
     XTRACT_LOUDNESS,
     XTRACT_FLATNESS,
+    XTRACT_FLATNESS_DB,
     XTRACT_TONALITY,
     XTRACT_CREST,
     XTRACT_NOISINESS,
@@ -165,7 +166,8 @@ enum xtract_return_codes_ {
     XTRACT_MALLOC_FAILED,
     XTRACT_BAD_ARGV,
     XTRACT_BAD_VECTOR_SIZE,
-    XTRACT_NO_RESULT,
+    XTRACT_DENORMAL_FOUND,
+    XTRACT_NO_RESULT, /* This usually occurs when the correct calculation cannot take place because required data is missing or would result in a NaN or infinity/-infinity. Under these curcumstances 0.f is usually given by *result */
     XTRACT_FEATURE_NOT_IMPLEMENTED
 };
 
diff --git a/xtract/xtract_helper.h b/xtract/xtract_helper.h
index 645f1cd..ce0ae54 100644
--- a/xtract/xtract_helper.h
+++ b/xtract/xtract_helper.h
@@ -63,6 +63,9 @@ int xtract_windowed(const float *data, const int N, const void *argv, float *res
  */
 int xtract_features_from_subframes(const float *data, const int N, const int feature, const void *argv, float *result);
 
+/** \brief Test whether a number is denormal */
+inline int xtract_is_denormal(double const d);
+
 /** @} */
 
 #ifdef __cplusplus
diff --git a/xtract/xtract_scalar.h b/xtract/xtract_scalar.h
index ff844f0..bfac9a9 100644
--- a/xtract/xtract_scalar.h
+++ b/xtract/xtract_scalar.h
@@ -239,21 +239,34 @@ int xtract_rolloff(const float *data, const int N, const void *argv, float *resu
  */
 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)
+/** \brief Extract the spectral flatness measure of an input vector, where the flatness measure (SFM) is defined as the ratio of the geometric mean to the arithmetic mean of a magnitude spectrum.
+ *
+ * \note The computation method used here is the most efficient by a significant margin, but suffers from precision problems due to the multiplication operationin the geometric mean calculation. This is particularly accute for larger values of N (>=256). However, as noted by Peeters (2003), the SFM should generally be computed on a small number of 'bands' rather than on the complete magnitude spectrum. It is therefore highly recommended that xtract_bands() is used prior to calling xtract_flatness().
  * 
- * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum().
- * \param N: the number of elements to be considered
+ * \param *data: a pointer to the first element in an array of floats representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). Alternatively the magnitudes from a number of 'subbands' can be used by using *result from xtract_bands().
+ * \param N: the number of *data array 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
+ * \param *result: the flatness of N values from the array pointed to by *data
  */
 int xtract_flatness(const float *data, const int N, const void *argv, float *result);
 
+/** \brief Extract the LOG spectral flatness measure of an input vector
+ *
+ * \param *data: a pointer to NULL.
+ * \param N: not used - can safely be set to 0.
+ * \param *argv: a pointer to a float represnting spectral flatness.
+ * \param *result: the LOG spectral flatness of N values from the array pointed to by *data
+ *
+ *  flatness_db = 10 * log10(flatness)
+ *
+ */
+int xtract_flatness_db(const float *data, const int N, const void *argv, float *result);
 
-/** \brief Extract the tonality factor of an input vector using a method described by Tristan Jehan (2005)
+/** \brief Extract the tonality factor of an input vector using a method described by Peeters 2003
  * 
- * \param *data: not used.
- * \param N: not used
- * \param *argv: a pointer to the spectral flatness measure of an audio vector (e.g. the output from xtract_flatness)
+ * \param *data: a pointer to NULL.
+ * \param N: not used - can safely be set to 0.
+ * \param *argv: a pointer to the LOG spectral flatness measure of an audio vector (e.g. the output from xtract_flatness_db)
  * \param *result: the tonality factor of N values from the array pointed to by *data
  */
 int xtract_tonality(const float *data, const int N, const void *argv, float *result);
@@ -309,7 +322,7 @@ int xtract_power(const float *data, const int N, const void *argv, float *result
  * \param *data: a pointer to the first element in an array of floats representing the amplitudes of the harmonic spectrum of an audio vector. It is sufficient to pass in a pointer to the first half of the array pointed to by *result from xtract_harmonic_spectrum().
  * \param N: the number of elements to be considered. If using the array pointed to by *result from xtract_harmonics, N should equal half the total array size i.e., just the amplitudes of the peaks.
  * \param *argv: a pointer to NULL
- * \param *result: the odd/even harmonic ratio of N values from the array pointed to by *data
+ * \param *result: the even/odd harmonic ratio of N values from the array pointed to by *data
  */
 int xtract_odd_even_ratio(const float *data, const int N, const void *argv, float *result);
 
diff --git a/xtract/xtract_vector.h b/xtract/xtract_vector.h
index e758f10..07bf176 100644
--- a/xtract/xtract_vector.h
+++ b/xtract/xtract_vector.h
@@ -43,6 +43,8 @@ extern "C" {
  *
  * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1
  *
+ * \note Before calling xtract_spectrum(), the FFT must be initialised by calling xtract_init_fft(N, XTRACT_SPECTRUM)
+ *
  */
 int xtract_spectrum(const float *data, const int N, const void *argv, float *result);