diff options
Diffstat (limited to 'xtract')
| -rw-r--r-- | xtract/libxtract.h | 55 | ||||
| -rw-r--r-- | xtract/xtract_delta.h | 15 | ||||
| -rw-r--r-- | xtract/xtract_macros.h | 2 | ||||
| -rw-r--r-- | xtract/xtract_scalar.h | 245 | ||||
| -rw-r--r-- | xtract/xtract_types.h | 5 | ||||
| -rw-r--r-- | xtract/xtract_vector.h | 77 |
6 files changed, 286 insertions, 113 deletions
diff --git a/xtract/libxtract.h b/xtract/libxtract.h index 960aa66..0e4f254 100644 --- a/xtract/libxtract.h +++ b/xtract/libxtract.h @@ -44,7 +44,6 @@ extern "C" { #define BARK_BANDS 26 /** \brief Enumeration of features, elements are used as indixes to an array of pointers to feature extracton functions */ - enum features_ { MEAN, VARIANCE, @@ -90,7 +89,6 @@ enum features_ { }; /** \brief Enumeration of feature types */ - enum feature_types_ { SCALAR, VECTOR, @@ -98,14 +96,12 @@ enum feature_types_ { }; /** \brief Enumeration of mfcc types */ - enum mfcc_types_ { EQUAL_GAIN, EQUAL_AREA }; /** \brief Enumeration of return codes */ - enum return_codes_ { SUCCESS, MALLOC_FAILED, @@ -115,30 +111,18 @@ enum return_codes_ { /** * - * \brief Perform feature extraction - * - * \param - * - * In general functions in this library conform to the following prototpe: + * \brief An array of pointers to functions that perform the extraction * - * int xtract_featurename(float *data, int N, void *argv, float *result) + * \param *data: a pointer to the start of the input data (usually the first element in an array) * + * \param N: the number of elements to be processed * - * float *data: a pointer to an array element - * - * int N: the number of elements to be processed by the function - * - * void *argv: an abitrary number of additional arguments - * - * float *result: a pointer to the result + * \param *argv: an abitrary number of additional arguments, used to pass additional parameters to the function being called * + * \param *result: a pointer to the first element in the result * * Each function will iterate over N array elements, the first of which is - * pointed to by *data. It is therefore up to the caller to ensure that an - * approriate range of data is provided. For example, if the function expects - * an array containing an harmonic spectrum, then they array pointed to by - * *data must contain the amplitudes of harmonic frequencies in adjacent - * elemets + * pointed to by *data. It is up to the calling function to ensure that the array is in the format expected by the function being called. * * For scalar and delta features, *result will point to a single value. * @@ -149,27 +133,28 @@ enum return_codes_ { * * All functions return an integer error code as descibed in the enumeration * return_codes_ - * - * */ - - -int(*xtract[XTRACT_FEATURES])(float *, int, void *, float *); - -/* Data structures */ + * + * example:<br> + * xtract[PEAKS](amplitude_spectrum, 512, threshold, peaks) + */ +int(*xtract[XTRACT_FEATURES])(float *data, int N, void *argv, float *result); +/** \brief A structure to store a set of n_filters Mel filters */ typedef struct xtract_mel_filter_ { int n_filters; float **filters; } xtract_mel_filter; - -/* Initialisation functions */ -/* xtract_init_mfcc */ -/* It is up to the caller to pass in a pointer to memory allocated for freq_bands arrays of length N. This function populates these arrays with magnitude coefficients representing the mel filterbank on a linear scale */ +/** \brief A function to initialise a mel filter bank + * + * It is up to the caller to pass in a pointer to memory allocated for freq_bands arrays of length N. This function populates these arrays with magnitude coefficients representing the mel filterbank on a linear scale + */ int xtract_init_mfcc(int N, float nyquist, int style, float freq_max, float freq_min, int freq_bands, float **fft_tables); -/* xtract_init_bark */ -/* A pointer to an array of BARK_BANDS ints most be passed in, and is populated with BARK_BANDS fft bin numbers representing the limits of each band */ +/** \brief A function to initialise bark filter bounds + * + * A pointer to an array of BARK_BANDS ints most be passed in, and is populated with BARK_BANDS fft bin numbers representing the limits of each band + */ int xtract_init_bark(int N, float nyquist, int *band_limits); diff --git a/xtract/xtract_delta.h b/xtract/xtract_delta.h index 68f18a4..bf6fa15 100644 --- a/xtract/xtract_delta.h +++ b/xtract/xtract_delta.h @@ -18,7 +18,7 @@ * USA. */ -/* xtract_delta.h: declares functions that extract a feature as a single value from more than one input vector */ +/** \file xtract_delta.h: declares functions that extract a feature as a single value or vector from more than one input vector */ #ifndef XTRACT_DELTA #define XTRACT_DELTA @@ -28,26 +28,21 @@ extern "C" { #endif #include "xtract_types.h" -/* Flux/temporal variation */ -/* Gaël Richard (2006)*/ +/* \brief Extract spectral flux as defined by Gaël Richard (2006)*/ int xtract_flux(float *data, int N, void *argv , float *result); /*xtract_frame_tracker *xf */ -/* Attack Time */ - +/** \brief Extract attack Time */ int xtract_attack_time(float *data, int N, void *argv , float *result); /* xtract_amp_tracker *xa */ -/* Temporal decrease */ - +/** Extract temporal decrease */ int xtract_decay_time(float *data, int N, void *argv, float *result); /* xtract_amp_tracker *xa */ -/* Delta vector */ -/* Generic function to calculate the delta of a feature over a given period (in frames */ - +/** \brief A generic function to calculate the delta of a feature over a given period (in frames) */ int xtract_delta_feature(float *data, int N, void *argv, float *result); /*xtract_frame_tracker *xf */ /*float frames*/ diff --git a/xtract/xtract_macros.h b/xtract/xtract_macros.h index d225db2..4aebf59 100644 --- a/xtract/xtract_macros.h +++ b/xtract/xtract_macros.h @@ -20,7 +20,7 @@ -/* xtract_delta.h: defines useful macros */ +/** \file xtract_delta.h: defines useful macros */ #ifndef XTRACT_MACROS #define XTRACT_MACROS diff --git a/xtract/xtract_scalar.h b/xtract/xtract_scalar.h index d0d780b..46b4549 100644 --- a/xtract/xtract_scalar.h +++ b/xtract/xtract_scalar.h @@ -18,7 +18,7 @@ * USA. */ -/* xtract_scalar.h: declares functions that extract a feature as a single value from an input vector */ +/** \file xtract_scalar.h: declares functions that extract a feature as a single value from an input vector */ #ifndef XTRACT_SCALAR #define XTRACT_SCALAR @@ -28,110 +28,251 @@ extern "C" { #endif -/* Statistical features */ - +/** \brief Extract the mean of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the mean of N values from the array pointed to by *data + */ int xtract_mean(float *data, int N, void *argv, float *result); -/* mean is passed in as arg */ + +/** \brief Extract the variance of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to a value representing the mean of the input vector + * \param *result: the variance of N values from the array pointed to by *data + */ int xtract_variance(float *data, int N, void *argv, float *result); -/* variance is passed in as arg */ + +/** \brief Extract the deviation of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to a value representing the variance of the input vector + * \param *result: the deviation of N values from the array pointed to by *data + */ int xtract_standard_deviation(float *data, int N, void *argv, float *result); -/* mean is passed in as arg */ + +/** \brief Extract the average deviation of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to a value representing the mean of the input vector + * \param *result: the average deviation of N values from the array pointed to by *data + */ int xtract_average_deviation(float *data, int N, void *argv, float *result); -/* mean and standard deviation are passed in as arg */ + +/** \brief Extract the skewness of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to an array of values representing the mean and standard deviation of the input vector + * \param *result: the skewness of N values from the array pointed to by *data + */ int xtract_skewness(float *data, int N, void *argv, float *result); -/* mean and standard deviation are passed in as arg */ -int xtract_kurtosis(float *data, int N, void *argv, float *result); -/* Irregularity */ +/** \brief Extract the kurtosis of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to an array of values representing the mean and standard deviation of the input vector + * \param *result: the kurtosis of N values from the array pointed to by *data + */ +int xtract_kurtosis(float *data, int N, void *argv, float *result); -/* Krimphoff (1994) */ +/** \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 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 + */ int xtract_irregularity_k(float *data, int N, void *argv, float *result); -/* Jensen (1999) */ -int xtract_irregularity_j(float *data, int N, void *argv, float *result); -/* Tristimulus */ +/** \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 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 + */ +int xtract_irregularity_j(float *data, int N, void *argv, float *result); -/* Pollard and Jansson (1982) */ +/** \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 + * \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 + * + * These three functions provide the first, second and third order tristimulus formulae + * + */ int xtract_tristimulus_1(float *data, int N, void *argv, float *result); int xtract_tristimulus_2(float *data, int N, void *argv, float *result); int xtract_tristimulus_3(float *data, int N, void *argv, float *result); -/* Smoothness */ - -/*McAdams (1999)*/ +/** \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 N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the smoothness of N values from the array pointed to by *data + */ int xtract_smoothness(float *data, int N, void *argv, float *result); -/* Spectral Spread */ - -/* Casagrande 2005 */ - +/** \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 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 + */ int xtract_spread(float *data, int N, void *argv, float *result); /* Zero crossing rate */ +/** \brief Extract the zero crossing rate of an input vector + * + * \param *data: a pointer to the first element in an array of floats + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the zero crossing rate of N values from the array pointed to by *data + */ int xtract_zcr(float *data, int N, void *argv, float *result); -/* Rolloff */ - -/* Bee Suan Ong (2005) */ -/* Threshold is the percentile at which the rolloff is determined */ - +/** \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 N: the number of elements to be considered + * \param *argv: a pointer to a floating point value representing the threshold for rolloff, i.e. the percentile at which the rolloff is determined + * \param *result: the spectral rolloff of N values from the array pointed to by *data + */ int xtract_rolloff(float *data, int N, void *argv, float *result); /* 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) + * + * \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 + */ int xtract_loudness(float *data, int N, void *argv, float *result); -/* Spectral Flatness Measure */ -/* Tristan Jehan (2005) */ - +/** \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 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 + */ int xtract_flatness(float *data, int N, void *argv, float *result); -/* Tonality Factor */ -/* Tristan Jehan (2005) */ +/** \brief Extract the tonality factor 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 spectral peaks of an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the tonality factor of N values from the array pointed to by *data + */ int xtract_tonality(float *data, int N, void *argv, float *result); -/* Noisiness */ -/* Tae Hong Park (2000) */ - +/** \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 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 + */ int xtract_noisiness(float *data, int N, void *argv, float *result); -/* RMS amplitude */ -/* Tae Hong Park (2000) */ - +/** \brief Extract the RMS amplitude 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 + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the RMS amplitude of N values from the array pointed to by *data + */ int xtract_rms_amplitude(float *data, int N, void *argv, float *result); -/* Inharmonicity */ - +/** \brief Extract the Inharmonicity of an input vector + * + * \param *data: a pointer to the first element in an array of floats representing the amplitudes of the spectral peaks in an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to a multidimensional array containing the fundamental frequency of the input vector in the first element of the first dimension, and the frequencies of the spectral peaks in the second dimension + * \param *result: the inharmonicity of N values from the array pointed to by *data + */ int xtract_inharmonicity(float *data, int N, void *argv, float *result); -/* Spectral Crest */ -/* Peeters (2003) */ +/** \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 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 + */ int xtract_crest(float *data, int N, void *argv, float *result); -/* Spectral Power */ -/* Bee Suan Ong (2005) */ +/** \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 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 + */ int xtract_power(float *data, int N, void *argv, float *result); /* Odd to even harmonic ratio */ - +/** \brief Extract the Odd to even harmonic ratio of an input vector + * + * \param *data: a pointer to the first element in an array of floats representing the harmonic spectrum of an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the odd/even harmonic ratio of N values from the array pointed to by *data + */ int xtract_odd_even_ratio(float *data, int N, void *argv, float *result); -/* Sharpness */ - +/** \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 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 + */ int xtract_sharpness(float *data, int N, void *argv, float *result); -/* Slope */ +/** \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 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 + */ int xtract_slope(float *data, int N, void *argv, float *result); -/* F0 */ -/*This method takes a guess which can come from taking the ZCR of an autocorrelation function, and then finds the spectral peak that most closely matches the gess */ +/** \brief Extract the value of the first partial in an input vector + * + * \param *data: a pointer to the first element in an array of floats that represents the frequencies of the spectral peaks of an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to a float value representing the approximate F0 + * \param *result: the F0 of N values from the array pointed to by *data + * + * This method takes a guess which can come from taking the ZCR of an autocorrelation function, and then finds the spectral peak that most closely matches the gess */ int xtract_f0(float *data, int N, void *argv, float *result); -/* Pitch */ -/* Pitch via HPS analysis */ +/** \brief Extract the Pitch of an input vector using Harmonic Product Spectrum (HPS) analysis + * + * \param *data: a pointer to the first element in an array of floats representing the magnitude spectrum of an audio vector + * \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 + */ int xtract_hps(float *data, int N, void *argv, float *result); #ifdef __cplusplus diff --git a/xtract/xtract_types.h b/xtract/xtract_types.h index 39fce64..f679a27 100644 --- a/xtract/xtract_types.h +++ b/xtract/xtract_types.h @@ -18,7 +18,7 @@ * USA. */ -/* xtract_types.h: declares specialised variable types used by libxtract */ +/* \file xtract_types.h: declares specialised variable types used by libxtract */ #ifndef XTRACT_TYPES #define XTRACT_TYPES @@ -27,8 +27,7 @@ extern "C" { #endif -/* Data structure used to store amplitude data between calls to xtract_attack_time and other functions. */ - +/* \brief Data structure used to store amplitude data between calls to xtract_attack_time and other functions. */ typedef struct _xtract_amp_tracker { int count; float previous_amp; diff --git a/xtract/xtract_vector.h b/xtract/xtract_vector.h index 16a6cc3..aa751a3 100644 --- a/xtract/xtract_vector.h +++ b/xtract/xtract_vector.h @@ -27,35 +27,88 @@ extern "C" { #endif -/* Extracts normalized (0-1) frequency domain magnitude spectrum from time domain signal */ +/** \brief Extract normalized (0-1) frequency domain magnitude 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 NULL + * \param *result: the magnitude spectrum of N values from the array pointed to by *data + */ int xtract_magnitude_spectrum(float *data, int N, void *argv, float *result); -/* Autocorrelation */ +/** \brief Extract autocorrelation from time domain signal using time-domain autocorrelation technique + * + * \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 autocorrelation of N values from the array pointed to by *data + */ int xtract_autocorrelation(float *data, int N, void *argv, float *result); - +/** \brief Extract autocorrelation from time domain signal using FFT based method + * + * \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 autocorrelation of N values from the array pointed to by *data + */ int xtract_autocorrelation_fft(float *data, int N, void *argv, float *result); -/* Average Magnitude Difference Function */ +/** \brief Extract Average Magnitude Difference Function from time domain signal + * + * \param *data: a pointer to the first element in an array of floats + * \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 + */ int xtract_amdf(float *data, int N, void *argv, float *result); -/* Average Squared Difference Function */ +/** \brief Extract Average Squared Difference Function 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 NULL + * \param *result: the ASDF of N values from the array pointed to by *data + */ int xtract_asdf(float *data, int N, void *argv, float *result); -/* MFCC */ -/* Rabiner */ +/** \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 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 + * + * The data structure pointed to by *argv must be obtained by first calling xtract_init_mfcc + */ int xtract_mfcc(float *data, int N, void *argv, float *result); -/* Bark band */ - +/** \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 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 + * \param *result: a pointer to an array containing resultant bark coefficients + * + * The limits array pointed to by *argv must be obtained by first calling xtract_init_bark + * + */ int xtract_bark_coefficients(float *data, int N, void *argv, float *result); -/* Discrete cosine transform */ +/** \brief Extract the Discrete Cosine transform of a 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 NULL + * \param *result: a pointer to an array containing resultant dct coefficients + */ int xtract_dct(float *data, int N, void *argv, float *result); -/* Frequency and amplitude of spectral peaks */ -/* Takes peak threshold as percentage below max peak, and sr as argv, returns a pointer to an array of size N, containing N/2 freqs and N/2 amplitudes, amplitudes are on a decibel scale with dbFS = 0 */ +/** \brief Extract the frequency and amplitude of spectral peaks from a of 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 N: the number of array elements to be considered + * \param *argv: a pointer to an array containing peak threshold as percentage below max peak, and sample rate + * \param *result: a pointer to an array of size N, containing N/2 freqs and N/2 amplitudes, amplitudes are on a decibel scale with dbFS = 0 + */ int xtract_peaks(float *data, int N, void *argv, float *result); #ifdef __cplusplus |