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@1: /* xtract_scalar.h: declares functions that extract a feature as a vector from an input vector */
jamie@1: 
jamie@56: #ifndef XTRACT_VECTOR_H
jamie@56: #define XTRACT_VECTOR_H
jamie@1: 
jamie@1: #ifdef __cplusplus
jamie@1: extern "C" {
jamie@1: #endif
jamie@20: 	
jamie@20: /**
jamie@83:   * \defgroup vector vector extraction functions
jamie@20:   *
jamie@83:   * Defines vector extraction functions, and their parameters.
jamie@20:   * @{
jamie@20:   */
jamie@1: 
jamie@105: /** \brief Extract frequency domain spectrum from time domain signal
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
jamie@2:  * \param N: the number of array elements to be considered
jamie@105:  * \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.
jamie@105:  * \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. 
jamie@105:  *
jamie@105:  * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1
jamie@105:  *
jamie@113:  * \note Before calling xtract_spectrum(), the FFT must be initialised by calling xtract_init_fft(N, XTRACT_SPECTRUM)
jamie@113:  *
jamie@2:  */
jamie@54: int xtract_spectrum(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@30: /** \brief Extract autocorrelation from time domain signal using FFT based method
jamie@30:  * 
jamie@30:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
jamie@30:  * \param N: the number of array elements to be considered
jamie@30:  * \param *argv: a pointer to NULL 
jamie@30:  * \param *result: the autocorrelation of N values from the array pointed to by *data 
jamie@30:  */
jamie@43: int xtract_autocorrelation_fft(const float *data, const int N, const void *argv, float *result);
jamie@30: 
jamie@30: /** \brief Extract Mel Frequency Cepstral Coefficients based on a method described by Rabiner
jamie@30:  * 
jamie@72:  * \param *data: a pointer to the first element in an array of spectral magnitudes, e.g. the first half of the array pointed to by *resul from xtract_spectrum()
jamie@30:  * \param N: the number of array elements to be considered
jamie@30:  * \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
jamie@30:  * \param *result: a pointer to an array containing the resultant MFCC
jamie@30:  * 
jamie@30:  * The data structure pointed to by *argv must be obtained by first calling xtract_init_mfcc
jamie@30:  */
jamie@43: int xtract_mfcc(const float *data, const int N, const void *argv, float *result);
jamie@30: 
jamie@30: /** \brief Extract the Discrete Cosine transform of a time domain signal
jamie@30:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
jamie@30:  * \param N: the number of array elements to be considered
jamie@30:  * \param *argv: a pointer to NULL 
jamie@30:  * \param *result: a pointer to an array containing resultant dct coefficients
jamie@30:  */
jamie@43: int xtract_dct(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract autocorrelation from time domain signal using time-domain autocorrelation technique 
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
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 autocorrelation of N values from the array pointed to by *data 
jamie@2:  */
jamie@43: int xtract_autocorrelation(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@2: /** \brief Extract Average Magnitude Difference Function from time domain signal 
jamie@2:  * 
jamie@47:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
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 AMDF of N values from the array pointed to by *data 
jamie@2:  */
jamie@43: int xtract_amdf(const float *data, const int N, const void *argv, float *result);
jamie@1:     
jamie@2: /** \brief Extract Average Squared Difference Function from time domain signal 
jamie@2:  * 
jamie@2:  * \param *data: a pointer to the first element in an array of floats representing an audio vector
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 ASDF of N values from the array pointed to by *data 
jamie@2:  */
jamie@43: int xtract_asdf(const float *data, const int N, const void *argv, float *result);
jamie@1:     
jamie@2: /** \brief Extract Bark band coefficients based on a method   
jamie@54:  * \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 first half of the array pointed to by *result from xtract_spectrum().
jamie@2:  * \param N: the number of array elements to be considered
jamie@42:  * \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.
jamie@2:  * \param *result: a pointer to an array containing resultant bark coefficients
jamie@2:  *
jamie@2:  * The limits array pointed to by *argv must be obtained by first calling xtract_init_bark
jamie@2:  * 
jamie@2:  */
jamie@43: int xtract_bark_coefficients(const float *data, const int N, const void *argv, float *result);
jamie@1: 
jamie@52: /** \brief Extract the amplitude and frequency of spectral peaks from a magnitude spectrum
jamie@59:  * \param *data: a pointer to an array of size N containing N magnitude/power/log magnitude/log power coefficients. (e.g. the first half of the array pointed to by *result from xtract_spectrum().
jamie@59:  * \param N: the size of the input array (note: it is assumed that enough memory has been allocated for an output array twice the size)
jamie@55:  * \param *argv: a pointer to an array of floats, the first representing (samplerate / N), the second representing the peak threshold as percentage of the magnitude of the maximum peak found
jamie@59:  * \param *result: a pointer to an array of size N * 2 containing N magnitude/power/log magnitude/log power coefficients and N bin frequencies.
jamie@45:  *
jamie@2:  */
jamie@52: int xtract_peak_spectrum(const float *data, const int N, const void *argv, float *result);
jamie@20: 
jamie@38: /** \brief Extract the harmonic spectrum of from a of a peak spectrum 
jamie@52:  * \param *data: a pointer to the first element in an array of floats representing the peak spectrum of an audio vector (e.g. *result from  xtract_peaks). It is expected that the first half of the array pointed to by *data will contain amplitudes for each peak considered, and the the second half will contain the respective frequencies
jamie@38:  * \param N: the size of the array pointed to by *data
jamie@38:  * \param *argv: a pointer to an array containing the fundamental (f0) of the spectrum, and a threshold (t) where 0<=t<=1.0, and t determines the distance from the nearest harmonic number within which a partial can be considered harmonic.
jamie@52:  * \param *result: a pointer to an array of size N containing N/2 magnitude coefficients and N/2 bin frequencies.
jamie@38:  */
jamie@52: int xtract_harmonic_spectrum(const float *data, const int N, const void *argv, float *result);
jamie@38: 
jamie@104: /** \brief Extract Linear Predictive Coding Coefficients
jamie@104:  * 
jamie@104:  * Based on algorithm in Rabiner and Juang as implemented by Jutta Degener in Dr. Dobb's Journal December, 1994.
jamie@104:  *
jamie@104:  * Returns N-1 reflection (PARCOR) coefficients and N-1 LPC coefficients via *result
jamie@104:  *
jamie@104:  * \param *data: N autocorrelation values e.g the data pointed to by *result from xtract_autocorrelation() 
jamie@104:  * \param N: the number of autocorrelation values to be considered
jamie@104:  * \param *argv: a pointer to NULL
jamie@104:  * \param *result: a pointer to an array containing N-1 reflection coefficients and N-1 LPC coefficients. 
jamie@104:  * 
jamie@104:  * An array of size 2 * (N - 1) must be allocated, and *result must point to its first element.
jamie@104:  */
jamie@104: int xtract_lpc(const float *data, const int N, const void *argv, float *result);
jamie@104: 
jamie@104: /** \brief Extract Linear Predictive Coding Cepstral Coefficients
jamie@104:  * 
jamie@104:  * \param *data: a pointer to the first element in an array of LPC coeffiecients e.g. a pointer to the second half of the array pointed to by *result from xtract_lpc()
jamie@104:  * \param N: the number of LPC coefficients to be considered
jamie@104:  * \param *argv: a pointer to a float representing the order of the result vector. This must be a whole number. According to Rabiner and Juang the ratio between the number (p) of LPC coefficients and the order (Q) of the LPC cepstrum is given by Q ~ (3/2)p where Q > p.
jamie@104:  * \param *result: a pointer to an array containing the resultant LPCC.
jamie@104:  * 
jamie@104:  * An array of size Q, where Q is given by argv[0] must be allocated, and *result must point to its first element.
jamie@104:  *
jamie@104:  */
jamie@104: int xtract_lpcc(const float *data, const int N, const void *argv, float *result);
jamie@104: 
jamie@104: 
jamie@104: 
jamie@20: /** @} */
jamie@20: 
jamie@1: #ifdef __cplusplus
jamie@1: }
jamie@1: #endif
jamie@1: 
jamie@1: #endif