jamie@1: /* libxtract feature extraction library
jamie@1:  *  
jamie@1:  * Copyright (C) 2006 Jamie Bullock
jamie@1:  *
jamie@1:  * This program is free software; you can redistribute it and/or modify
jamie@1:  * it under the terms of the GNU General Public License as published by
jamie@1:  * the Free Software Foundation; either version 2 of the License, or
jamie@1:  * (at your option) any later version.
jamie@1:  *
jamie@1:  * This program is distributed in the hope that it will be useful,
jamie@1:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
jamie@1:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
jamie@1:  * GNU General Public License for more details.
jamie@1:  *
jamie@1:  * You should have received a copy of the GNU General Public License
jamie@1:  * along with this program; if not, write to the Free Software
jamie@1:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
jamie@1:  * USA.
jamie@1:  */
jamie@1: 
jamie@2: /** \file xtract_scalar.h: declares functions that extract a feature as a single value from an input vector */
jamie@1: 
jamie@1: #ifndef XTRACT_SCALAR
jamie@1: #define XTRACT_SCALAR
jamie@1: 
jamie@1: #ifdef __cplusplus
jamie@1: extern "C" {
jamie@1: #endif
jamie@1: 
jamie@20: /**
jamie@20:   * \defgroup scalar extraction functions
jamie@20:   *
jamie@20:   * Defines scalar extraction functions, and their parameters.
jamie@20:   * @{
jamie@20:   */
jamie@1: 
jamie@2: /** \brief Extract the mean of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of array elements to be considered
jamie@2:  * \param *argv: a pointer to NULL 
jamie@2:  * \param *result: the mean of N values from the array pointed to by *data 
jamie@2:  */
jamie@43: int xtract_mean(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the variance of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@41:  * \param *argv: a pointer to a float representing the mean of the input vector
jamie@2:  * \param *result: the variance of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_variance(const float *data, const int N, const void *argv, float *result);
jamie@2: 
jamie@2: /** \brief Extract the deviation of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@41:  * \param *argv: a pointer to a float representing the variance of the input vector
jamie@2:  * \param *result: the deviation of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_standard_deviation(const float *data, const int N, const void *argv, float *result);
jamie@2: 
jamie@2: /** \brief Extract the average deviation of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@41:  * \param *argv: a pointer to a float representing the mean of the input vector
jamie@2:  * \param *result: the  average deviation of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_average_deviation(const float *data, const int N, const void *argv, float *result);
jamie@2: 
jamie@2: /** \brief Extract the skewness of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@41:  * \param *argv: a pointer to an array of floats representing the mean and standard deviation of the input vector
jamie@2:  * \param *result: the skewness of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_skewness(const float *data, const int N, const void *argv,  float *result);
jamie@2: 
jamie@2: /** \brief Extract the kurtosis of an input vector
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to an array of values representing the mean and standard deviation of the input vector
jamie@2:  * \param *result: the kurtosis of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_kurtosis(const float *data, const int N, const void *argv,  float *result);
jamie@1: 
jamie@41: /** \brief Extract the centroid of an input vector
jamie@11:  * 
jamie@47:  * \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().
jamie@11:  * \param N: the number of elements to be considered
jamie@11:  * \param *argv: a pointer to NULL
jamie@11:  * \param *result: the centroid of the values pointed to by *data
jamie@47:  *
jamie@47:  * Note: for a more 'accurate' result *result from xtract_peaks() can be passed in. This gives the interpolated peak frequency locations.
jamie@47:  *
jamie@11:  */
jamie@43: int xtract_centroid(const float *data, const int N, const void *argv,  float *result);
jamie@11: 
jamie@2: /** \brief Calculate the Irregularity of an input vector using a method described by Krimphoff (1994)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the irregularity of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_irregularity_k(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Calculate the Irregularity of an input vector using a method described by Jensen (1999)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the irregularity of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_irregularity_j(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Calculate the Tristimulus of an input vector using a method described by Pollard and Jansson (1982)
jamie@2:  * 
jamie@47:  * \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.
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the tristimulus of N values from the array pointed to by *data
jamie@2:  *
jamie@2:  * These three functions provide the first, second and third order tristimulus formulae
jamie@2:  * 
jamie@2:  */
jamie@43: int xtract_tristimulus_1(const float *data, const int N, const void *argv, float *result);
jamie@43: int xtract_tristimulus_2(const float *data, const int N, const void *argv, float *result);
jamie@43: int xtract_tristimulus_3(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the smoothness of an input vector using a method described by McAdams (1999)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@43:  * \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. 
jamie@2:  * \param *result: the smoothness of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_smoothness(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the spectral spread of an input vector using a method described by Casagrande(2005)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the spectral spread of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_spread(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@1: /* Zero crossing rate */
jamie@1: 
jamie@2: /** \brief Extract the zero crossing rate of an input vector 
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats 
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the zero crossing rate of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_zcr(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the spectral rolloff of an input vector using a method described by Bee Suan Ong (2005)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@42:  * \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
jamie@42:  * \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.
jamie@2:  */
jamie@43: int xtract_rolloff(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@47: /** \brief Extract the 'total loudness' of an input vector using a method described by Moore, Glasberg et al (2005)
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats representing a set of BARK_BANDS bark coefficients
jamie@2:  * \param N: the number of coefficients to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@47:  * \param *result: the total loudness of N values from the array pointed to by *data
jamie@47:  *
jamie@47:  * Note: if N = 1, the 'specific loudness' of the bark band pointed to by *data will be given by *result
jamie@47:  *
jamie@2:  */
jamie@43: int xtract_loudness(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the spectral flatness measure of an input vector using a method described by Tristan Jehan (2005)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the spectral flatness of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_flatness(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@1: 
jamie@2: /** \brief Extract the tonality factor of an input vector using a method described by Tristan Jehan (2005)
jamie@2:  * 
jamie@42:  * \param *data: not used.
jamie@42:  * \param N: not used
jamie@42:  * \param *argv: a pointer to the spectral flatness measure of an audio vector (e.g. the output from xtract_flatness)
jamie@2:  * \param *result: the tonality factor of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_tonality(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the noisiness of an input vector using a method described by Tae Hong Park (2000)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the noisiness of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_noisiness(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the RMS amplitude of an input vector using a method described by Tae Hong Park (2000)
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats  
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the RMS amplitude of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_rms_amplitude(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the Inharmonicity of an input vector 
jamie@2:  * 
jamie@41:  * \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)
jamie@2:  * \param N: the number of elements to be considered
jamie@41:  * \param *argv: a pointer to a float representing the fundamental frequency of the input vector.
jamie@2:  * \param *result: the inharmonicity of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_inharmonicity(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the spectral crest of an input vector using a method described by Peeters (2003)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the spectral crest of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_crest(const float *data, const int N, const void *argv, float *result);
jamie@1:     
jamie@2: /** \brief Extract the Spectral Power of an input vector using a method described by Bee Suan Ong (2005)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the spectral power of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_power(const float *data, const int N, const void *argv, float *result);
jamie@1:     
jamie@1: /* Odd to even harmonic ratio */
jamie@2: /** \brief Extract the Odd to even harmonic ratio of an input vector 
jamie@2:  * 
jamie@38:  * \param *data: a pointer to the first element in an array of floats representing the frequencies of the harmonic spectrum of an audio vector. It is sufficient to pass in a pointer to the array pointed to by *result from xtract_harmonics.
jamie@38:  * \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 frequencies of the peaks.
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the odd/even harmonic ratio of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_odd_even_ratio(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the Sharpness of an input vector 
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the Sharpness of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_sharpness(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@48: /** \brief Extract the Slope of an input vector using a method described by Peeters(2003)
jamie@2:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the Slope of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_slope(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@45: /** \brief Extract the value of the lowest value in an input vector
jamie@2:  * 
jamie@43:  * \param *data: a pointer to the first element in an array of floats
jamie@2:  * \param N: the number of elements to be considered
jamie@45:  * \param *argv: a pointer to a float representing the lower limit for the search. i.e. (*result > *argv) returns 1.
jamie@45:  * \param *result: a pointer to a value representing the lowest component in *data that falls above a given threshold. 
jamie@2:  * 
jamie@43:  */
jamie@45: int xtract_lowest_value(const float *data, const int N, const void *argv, float *result);
jamie@45: 
jamie@45: /** \brief Extract the value of the highest value in an input vector
jamie@45:  * 
jamie@45:  * \param *data: a pointer to the first element in an array of floats
jamie@45:  * \param N: the number of elements to be considered
jamie@45:  * \param *argv: a pointer to NULL.
jamie@45:  * \param *result: a pointer to a value representing the highest component in *data. 
jamie@45:  * 
jamie@45:  */
jamie@45: int xtract_highest_value(const float *data, const int N, const void *argv, float *result);
jamie@45: 
jamie@45: /** \brief Extract the sum of the values in an input vector
jamie@45:  * 
jamie@45:  * \param *data: a pointer to the first element in an array of floats
jamie@45:  * \param N: the number of elements to be considered
jamie@45:  * \param *argv: a pointer to NULL.
jamie@45:  * \param *result: a pointer to a value representing the sum of all of the values pointed to by *data. 
jamie@45:  * 
jamie@45:  */
jamie@45: int xtract_sum(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract the Pitch of an input vector using Harmonic Product Spectrum (HPS) analysis
jamie@2:  * 
jamie@22:  * \warning {This function doesn't work properly}
jamie@22:  * 
jamie@47:  * \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().
jamie@2:  * \param N: the number of elements to be considered
jamie@2:  * \param *argv: a pointer to NULL
jamie@2:  * \param *result: the pitch of N values from the array pointed to by *data
jamie@2:  */
jamie@43: int xtract_hps(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@5: /** \brief Extract the fundamental frequency of an input vector 
jamie@5:  * 
jamie@5:  * \param *data: a pointer to the first element in an array of floats representing an audio vector 
jamie@5:  * \param N: the number of elements to be considered
jamie@22:  * \param *argv: a pointer to a float representing the audio sample rate
jamie@5:  * \param *result: the pitch of N values from the array pointed to by *data
jamie@12:  *
jamie@22:  * This algorithm is based on the AMDF, with peak and centre clipping. It would benefit from further improvements to improve noise robustness and overall efficiency
jamie@12:  * 
jamie@5:  */
jamie@43: int xtract_f0(const float *data, const int N, const void *argv, float *result);
jamie@43: 
jamie@43: /** \brief Extract the fundamental frequency of an input vector 
jamie@43:  * 
jamie@43:  * \param *data: a pointer to the first element in an array of floats representing an audio vector 
jamie@43:  * \param N: the number of elements to be considered
jamie@43:  * \param *argv: a pointer to a float representing the audio sample rate
jamie@43:  * \param *result: the pitch of N values from the array pointed to by *data
jamie@43:  *
jamie@43:  * This function wraps xtract_f0, but provides the frequency of the lowest partial in the peak spectrum if f0 can't be found.
jamie@43:  *  
jamie@43:  */
jamie@43: int xtract_failsafe_f0(const float *data, const int N, const void *argv, float *result);
jamie@5: 
jamie@20: /** @} */
jamie@20: 
jamie@1: #ifdef __cplusplus
jamie@1: }
jamie@1: #endif
jamie@1: 
jamie@1: #endif
jamie@1: 
jamie@1: 
jamie@1: