LibXtract 0.6.2

/usr/src/packages/BUILD/libxtract-0.6.2/xtract/libxtract.h

Go to the documentation of this file.
00001 /* libxtract feature extraction library
00002  *  
00003  * Copyright (C) 2006 Jamie Bullock
00004  *
00005  * This program is free software; you can redistribute it and/or modify
00006  * it under the terms of the GNU General Public License as published by
00007  * the Free Software Foundation; either version 2 of the License, or
00008  * (at your option) any later version.
00009  *
00010  * This program is distributed in the hope that it will be useful,
00011  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00013  * GNU General Public License for more details.
00014  *
00015  * You should have received a copy of the GNU General Public License
00016  * along with this program; if not, write to the Free Software
00017  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
00018  * USA.
00019  */
00020 
00046 #ifndef XTRACT_H
00047 #define XTRACT_H
00048 
00049 #ifdef __cplusplus
00050 extern "C" {
00051 #endif
00052 
00058 #include "xtract_scalar.h"
00059 #include "xtract_vector.h"
00060 #include "xtract_delta.h"
00061 #include "xtract_types.h"
00062 #include "xtract_macros.h"
00063 #include "xtract_helper.h"
00064 
00071 #define XTRACT_FEATURES 60
00072     
00074 enum xtract_features_ {
00075     XTRACT_MEAN,
00076     XTRACT_VARIANCE,
00077     XTRACT_STANDARD_DEVIATION,
00078     XTRACT_AVERAGE_DEVIATION,
00079     XTRACT_SKEWNESS,
00080     XTRACT_KURTOSIS,
00081     XTRACT_SPECTRAL_MEAN,
00082     XTRACT_SPECTRAL_VARIANCE,
00083     XTRACT_SPECTRAL_STANDARD_DEVIATION,
00084     XTRACT_SPECTRAL_AVERAGE_DEVIATION,
00085     XTRACT_SPECTRAL_SKEWNESS,
00086     XTRACT_SPECTRAL_KURTOSIS,
00087     XTRACT_SPECTRAL_CENTROID,
00088     XTRACT_IRREGULARITY_K,
00089     XTRACT_IRREGULARITY_J,
00090     XTRACT_TRISTIMULUS_1,
00091     XTRACT_TRISTIMULUS_2,
00092     XTRACT_TRISTIMULUS_3,
00093     XTRACT_SMOOTHNESS,
00094     XTRACT_SPREAD,
00095     XTRACT_ZCR,
00096     XTRACT_ROLLOFF,
00097     XTRACT_LOUDNESS,
00098     XTRACT_FLATNESS,
00099     XTRACT_FLATNESS_DB,
00100     XTRACT_TONALITY,
00101     XTRACT_CREST,
00102     XTRACT_NOISINESS,
00103     XTRACT_RMS_AMPLITUDE,
00104     XTRACT_SPECTRAL_INHARMONICITY,
00105     XTRACT_POWER,
00106     XTRACT_ODD_EVEN_RATIO,
00107     XTRACT_SHARPNESS,
00108     XTRACT_SPECTRAL_SLOPE,
00109     XTRACT_LOWEST_VALUE,
00110     XTRACT_HIGHEST_VALUE,
00111     XTRACT_SUM,
00112     XTRACT_NONZERO_COUNT,
00113     XTRACT_HPS,
00114     XTRACT_F0,
00115     XTRACT_FAILSAFE_F0,
00116     XTRACT_LNORM,
00117     XTRACT_FLUX,
00118     XTRACT_ATTACK_TIME,
00119     XTRACT_DECAY_TIME,
00120     XTRACT_DIFFERENCE_VECTOR,
00121     XTRACT_AUTOCORRELATION,
00122     XTRACT_AMDF,
00123     XTRACT_ASDF,
00124     XTRACT_BARK_COEFFICIENTS,
00125     XTRACT_PEAK_SPECTRUM,
00126     XTRACT_SPECTRUM,
00127     XTRACT_AUTOCORRELATION_FFT,
00128     XTRACT_MFCC,
00129     XTRACT_DCT,
00130     XTRACT_HARMONIC_SPECTRUM,
00131     XTRACT_LPC,
00132     XTRACT_LPCC,
00133     XTRACT_SUBBANDS,
00134     /* Helper functions */
00135     XTRACT_WINDOWED
00136 };
00137 
00139 enum xtract_feature_init_ {
00140     XTRACT_INIT_MFCC = 100,
00141     XTRACT_INIT_BARK,
00142     XTRACT_INIT_WINDOWED
00143 };
00144 
00146 enum xtract_feature_types_ {
00147     XTRACT_SCALAR,
00148     XTRACT_VECTOR,
00149     XTRACT_DELTA
00150 };
00151 
00153 enum xtract_mfcc_types_ {
00154     XTRACT_EQUAL_GAIN,
00155     XTRACT_EQUAL_AREA
00156 };
00157 
00158 enum xtract_lnorm_filter_types_ {
00159     XTRACT_NO_LNORM_FILTER,
00160     XTRACT_POSITIVE_SLOPE,
00161     XTRACT_NEGATIVE_SLOPE
00162 };
00163 
00165 enum xtract_return_codes_ {
00166     XTRACT_SUCCESS,
00167     XTRACT_MALLOC_FAILED,
00168     XTRACT_BAD_ARGV,
00169     XTRACT_BAD_VECTOR_SIZE,
00170     XTRACT_DENORMAL_FOUND,
00171     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 */
00172     XTRACT_FEATURE_NOT_IMPLEMENTED
00173 };
00174 
00176 enum xtract_spectrum_ {
00177     XTRACT_MAGNITUDE_SPECTRUM,
00178     XTRACT_LOG_MAGNITUDE_SPECTRUM,
00179     XTRACT_POWER_SPECTRUM,
00180     XTRACT_LOG_POWER_SPECTRUM
00181 };
00182 
00184 enum xtract_subband_scales_ {
00185     XTRACT_OCTAVE_SUBBANDS,
00186     XTRACT_LINEAR_SUBBANDS
00187 };
00188 
00190 typedef enum type_ {
00191     XTRACT_FLOAT,
00192     XTRACT_FLOATARRAY,
00193     XTRACT_INT,
00194     XTRACT_MEL_FILTER
00195 } xtract_type_t;
00196 
00198 typedef enum unit_ {
00199     /* NONE, ANY */
00200     XTRACT_HERTZ = 2,
00201     XTRACT_ANY_AMPLITUDE_HERTZ,
00202     XTRACT_DBFS,
00203     XTRACT_DBFS_HERTZ,
00204     XTRACT_PERCENT,
00205     XTRACT_BINS,
00206     XTRACT_SONE
00207 } xtract_unit_t;
00208 
00210 typedef enum {
00211     XTRACT_FALSE,
00212     XTRACT_TRUE
00213 } xtract_bool_t;
00214 
00216 enum xtract_window_types_ {
00217     XTRACT_GAUSS,
00218     XTRACT_HAMMING,
00219     XTRACT_HANN,
00220     XTRACT_BARTLETT,
00221     XTRACT_TRIANGULAR,
00222     XTRACT_BARTLETT_HANN,
00223     XTRACT_BLACKMAN,
00224     XTRACT_KAISER,
00225     XTRACT_BLACKMAN_HARRIS
00226 };
00227 
00229 typedef enum xtract_vector_ {
00230     /* N/2 magnitude/log-magnitude/power/log-power coeffs and N/2 frequencies */
00231     XTRACT_SPECTRAL,     
00232     /* N spectral amplitudes */
00233     XTRACT_SPECTRAL_MAGNITUDES, 
00234     /* N/2 magnitude/log-magnitude/power/log-power peak coeffs and N/2 
00235      * frequencies */
00236     XTRACT_SPECTRAL_PEAKS,
00237     /* N spectral peak amplitudes */
00238     XTRACT_SPECTRAL_PEAKS_MAGNITUDES,
00239     /* N spectral peak frequencies */
00240     XTRACT_SPECTRAL_PEAKS_FREQUENCIES,
00241     /* N/2 magnitude/log-magnitude/power/log-power harmonic peak coeffs and N/2 
00242      * frequencies */
00243     XTRACT_SPECTRAL_HARMONICS,
00244     /* N spectral harmonic amplitudes */
00245     XTRACT_SPECTRAL_HARMONICS_MAGNITUDES,
00246     /* N spectral harmonic frequencies */
00247     XTRACT_SPECTRAL_HARMONICS_FREQUENCIES,
00248     XTRACT_AUTOCORRELATION_COEFFS,
00249     XTRACT_ARBITRARY_SERIES,
00250     XTRACT_AUDIO_SAMPLES,
00251     XTRACT_MEL_COEFFS, 
00252     XTRACT_LPC_COEFFS, 
00253     XTRACT_LPCC_COEFFS, 
00254     XTRACT_BARK_COEFFS,
00255     XTRACT_SUBFRAMES,
00256     XTRACT_NO_DATA
00257 } xtract_vector_t;
00258 
00260 typedef struct _xtract_function_descriptor {
00261 
00262     int id;
00263 
00264     struct {
00265         char name[XTRACT_MAX_NAME_LENGTH];
00266         char p_name[XTRACT_MAX_NAME_LENGTH]; /* pretty name */
00267         char desc[XTRACT_MAX_DESC_LENGTH];
00268         char p_desc[XTRACT_MAX_DESC_LENGTH]; /* pretty description */
00269         char author[XTRACT_MAX_AUTHOR_LENGTH];
00270         int year;
00271     } algo;
00272 
00273     struct {
00274         xtract_vector_t format;
00275         xtract_unit_t unit;
00276     } data;
00277 
00278     int argc;
00279 
00280     struct {
00281         xtract_type_t type; /* type of the array/value pointed to by argv */
00282         float min[XTRACT_MAXARGS];
00283         float max[XTRACT_MAXARGS];
00284         float def[XTRACT_MAXARGS]; /* defaults */
00285         xtract_unit_t unit[XTRACT_MAXARGS];
00286         int donor[XTRACT_MAXARGS]; /* suggested donor functions for argv */
00287     } argv;
00288 
00289     xtract_bool_t is_scalar;
00290     xtract_bool_t is_delta; /* features in xtract_delta.h can be scalar or vector */ 
00291 
00292     /* The result.<> entries in descritors.c need to be checked */
00293     union {
00294 
00295         struct {
00296             float min;
00297             float max;     
00298             xtract_unit_t unit;
00299         } scalar;
00300 
00301         struct {
00302             xtract_vector_t format;
00303             xtract_unit_t unit;
00304         } vector;
00305 
00306     } result;
00307 
00308 } xtract_function_descriptor_t;
00309 
00356 #ifdef XTRACT_H
00357 extern int(*xtract[XTRACT_FEATURES])(const float *data, const int N, const void *argv, float *result);
00358 
00359 #endif
00360 
00362 typedef struct xtract_mel_filter_ {
00363     int n_filters;
00364     float **filters;
00365 } xtract_mel_filter;
00366 
00371 int xtract_init_mfcc(int N, float nyquist, int style, float freq_min, float freq_max, int freq_bands, float **fft_tables);
00372 
00381 int xtract_init_bark(int N, float sr, int *band_limits);
00382 
00392 int xtract_init_fft(int N, int feature_name);
00393 
00398 void xtract_free_fft(void);
00399 
00406 float *xtract_init_window(const int N, const int type);
00407 
00413 void xtract_free_window(float *window);
00414 
00415 /* \brief A function to build an array of function descriptors */
00416 xtract_function_descriptor_t *xtract_make_descriptors();
00417 
00418 /* \brief A function to free an array of function descriptors */
00419 int xtract_free_descriptors(xtract_function_descriptor_t *fd);
00420 /* Free functions */
00421 
00424 #ifdef __cplusplus
00425 }
00426 #endif
00427 
00428 #endif