LibXtract  0.7.1
/usr/src/RPM/BUILD/libxtract-0.7.1/xtract/libxtract.h
Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2012 Jamie Bullock
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to
00006  * deal in the Software without restriction, including without limitation the
00007  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
00008  * sell copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
00019  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
00020  * IN THE SOFTWARE.
00021  *
00022  */
00023 
00049 #ifndef XTRACT_H
00050 #define XTRACT_H
00051 
00052 #ifdef __cplusplus
00053 extern "C" {
00054 #endif
00055 
00061 #include "xtract_scalar.h"
00062 #include "xtract_vector.h"
00063 #include "xtract_delta.h"
00064 #include "xtract_types.h"
00065 #include "xtract_macros.h"
00066 #include "xtract_helper.h"
00067 
00074 #define XTRACT_FEATURES 62
00075     
00077 enum xtract_features_ {
00078     XTRACT_MEAN,
00079     XTRACT_VARIANCE,
00080     XTRACT_STANDARD_DEVIATION,
00081     XTRACT_AVERAGE_DEVIATION,
00082     XTRACT_SKEWNESS,
00083     XTRACT_KURTOSIS,
00084     XTRACT_SPECTRAL_MEAN,
00085     XTRACT_SPECTRAL_VARIANCE,
00086     XTRACT_SPECTRAL_STANDARD_DEVIATION,
00087     /*XTRACT_SPECTRAL_AVERAGE_DEVIATION, */
00088     XTRACT_SPECTRAL_SKEWNESS,
00089     XTRACT_SPECTRAL_KURTOSIS,
00090     XTRACT_SPECTRAL_CENTROID,
00091     XTRACT_IRREGULARITY_K,
00092     XTRACT_IRREGULARITY_J,
00093     XTRACT_TRISTIMULUS_1,
00094     XTRACT_TRISTIMULUS_2,
00095     XTRACT_TRISTIMULUS_3,
00096     XTRACT_SMOOTHNESS,
00097     XTRACT_SPREAD,
00098     XTRACT_ZCR,
00099     XTRACT_ROLLOFF,
00100     XTRACT_LOUDNESS,
00101     XTRACT_FLATNESS,
00102     XTRACT_FLATNESS_DB,
00103     XTRACT_TONALITY,
00104     XTRACT_CREST,
00105     XTRACT_NOISINESS,
00106     XTRACT_RMS_AMPLITUDE,
00107     XTRACT_SPECTRAL_INHARMONICITY,
00108     XTRACT_POWER,
00109     XTRACT_ODD_EVEN_RATIO,
00110     XTRACT_SHARPNESS,
00111     XTRACT_SPECTRAL_SLOPE,
00112     XTRACT_LOWEST_VALUE,
00113     XTRACT_HIGHEST_VALUE,
00114     XTRACT_SUM,
00115     XTRACT_NONZERO_COUNT,
00116     XTRACT_HPS,
00117     XTRACT_F0,
00118     XTRACT_FAILSAFE_F0,
00119     XTRACT_WAVELET_F0,
00120     XTRACT_MIDICENT,
00121     XTRACT_LNORM,
00122     XTRACT_FLUX,
00123     XTRACT_ATTACK_TIME,
00124     XTRACT_DECAY_TIME,
00125     XTRACT_DIFFERENCE_VECTOR,
00126     XTRACT_AUTOCORRELATION,
00127     XTRACT_AMDF,
00128     XTRACT_ASDF,
00129     XTRACT_BARK_COEFFICIENTS,
00130     XTRACT_PEAK_SPECTRUM,
00131     XTRACT_SPECTRUM,
00132     XTRACT_AUTOCORRELATION_FFT,
00133     XTRACT_MFCC,
00134     XTRACT_DCT,
00135     XTRACT_HARMONIC_SPECTRUM,
00136     XTRACT_LPC,
00137     XTRACT_LPCC,
00138     XTRACT_SUBBANDS,
00139     /* Helper functions */
00140     XTRACT_WINDOWED,
00141     XTRACT_SMOOTHED
00142 };
00143 
00145 enum xtract_feature_init_ {
00146     XTRACT_INIT_MFCC = 100,
00147     XTRACT_INIT_BARK,
00148     XTRACT_INIT_WINDOWED
00149 };
00150 
00152 enum xtract_feature_types_ {
00153     XTRACT_SCALAR,
00154     XTRACT_VECTOR,
00155     XTRACT_DELTA
00156 };
00157 
00159 enum xtract_mfcc_types_ {
00160     XTRACT_EQUAL_GAIN,
00161     XTRACT_EQUAL_AREA
00162 };
00163 
00164 enum xtract_lnorm_filter_types_ {
00165     XTRACT_NO_LNORM_FILTER,
00166     XTRACT_POSITIVE_SLOPE,
00167     XTRACT_NEGATIVE_SLOPE
00168 };
00169 
00171 enum xtract_return_codes_ {
00172     XTRACT_SUCCESS,
00173     XTRACT_MALLOC_FAILED,
00174     XTRACT_BAD_ARGV,
00175     XTRACT_BAD_VECTOR_SIZE,
00176     XTRACT_BAD_STATE,
00177     XTRACT_DENORMAL_FOUND,
00178     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 */
00179     XTRACT_FEATURE_NOT_IMPLEMENTED,
00180     XTRACT_ARGUMENT_ERROR
00181 };
00182 
00184 enum xtract_spectrum_ {
00185     XTRACT_MAGNITUDE_SPECTRUM,
00186     XTRACT_LOG_MAGNITUDE_SPECTRUM,
00187     XTRACT_POWER_SPECTRUM,
00188     XTRACT_LOG_POWER_SPECTRUM
00189 };
00190 
00192 enum xtract_subband_scales_ {
00193     XTRACT_OCTAVE_SUBBANDS,
00194     XTRACT_LINEAR_SUBBANDS
00195 };
00196 
00198 typedef enum type_ {
00199     XTRACT_FLOAT,
00200     XTRACT_FLOATARRAY,
00201     XTRACT_INT,
00202     XTRACT_MEL_FILTER
00203 } xtract_type_t;
00204 
00206 typedef enum unit_ {
00207     /* NONE, ANY */
00208     XTRACT_HERTZ = 2,
00209     XTRACT_ANY_AMPLITUDE_HERTZ,
00210     XTRACT_DBFS,
00211     XTRACT_DBFS_HERTZ,
00212     XTRACT_PERCENT,
00213     XTRACT_BINS,
00214     XTRACT_SONE,
00215     XTRACT_MIDI_CENT
00216 } xtract_unit_t;
00217 
00219 typedef enum {
00220     XTRACT_FALSE,
00221     XTRACT_TRUE
00222 } xtract_bool_t;
00223 
00225 enum xtract_window_types_ {
00226     XTRACT_GAUSS,
00227     XTRACT_HAMMING,
00228     XTRACT_HANN,
00229     XTRACT_BARTLETT,
00230     XTRACT_TRIANGULAR,
00231     XTRACT_BARTLETT_HANN,
00232     XTRACT_BLACKMAN,
00233     XTRACT_KAISER,
00234     XTRACT_BLACKMAN_HARRIS
00235 };
00236 
00238 typedef enum xtract_vector_ {
00239     /* N/2 magnitude/log-magnitude/power/log-power coeffs and N/2 frequencies */
00240     XTRACT_SPECTRAL,     
00241     /* N spectral amplitudes */
00242     XTRACT_SPECTRAL_MAGNITUDES, 
00243     /* N/2 magnitude/log-magnitude/power/log-power peak coeffs and N/2 
00244      * frequencies */
00245     XTRACT_SPECTRAL_PEAKS,
00246     /* N spectral peak amplitudes */
00247     XTRACT_SPECTRAL_PEAKS_MAGNITUDES,
00248     /* N spectral peak frequencies */
00249     XTRACT_SPECTRAL_PEAKS_FREQUENCIES,
00250     /* N/2 magnitude/log-magnitude/power/log-power harmonic peak coeffs and N/2 
00251      * frequencies */
00252     XTRACT_SPECTRAL_HARMONICS,
00253     /* N spectral harmonic amplitudes */
00254     XTRACT_SPECTRAL_HARMONICS_MAGNITUDES,
00255     /* N spectral harmonic frequencies */
00256     XTRACT_SPECTRAL_HARMONICS_FREQUENCIES,
00257     XTRACT_AUTOCORRELATION_COEFFS,
00258     XTRACT_ARBITRARY_SERIES,
00259     XTRACT_AUDIO_SAMPLES,
00260     XTRACT_MEL_COEFFS, 
00261     XTRACT_LPC_COEFFS, 
00262     XTRACT_LPCC_COEFFS, 
00263     XTRACT_BARK_COEFFS,
00264     XTRACT_SUBFRAMES,
00265     XTRACT_NO_DATA
00266 } xtract_vector_t;
00267 
00269 typedef struct _xtract_function_descriptor {
00270 
00271     int id;
00272 
00273     struct {
00274         char name[XTRACT_MAX_NAME_LENGTH];
00275         char p_name[XTRACT_MAX_NAME_LENGTH]; /* pretty name */
00276         char desc[XTRACT_MAX_DESC_LENGTH];
00277         char p_desc[XTRACT_MAX_DESC_LENGTH]; /* pretty description */
00278         char author[XTRACT_MAX_AUTHOR_LENGTH];
00279         int year;
00280     } algo;
00281 
00282     struct {
00283         xtract_vector_t format;
00284         xtract_unit_t unit;
00285     } data;
00286 
00287     int argc;
00288 
00289     struct {
00290         xtract_type_t type; /* type of the array/value pointed to by argv */
00291         double min[XTRACT_MAXARGS];
00292         double max[XTRACT_MAXARGS];
00293         double def[XTRACT_MAXARGS]; /* defaults */
00294         xtract_unit_t unit[XTRACT_MAXARGS];
00295         int donor[XTRACT_MAXARGS]; /* suggested donor functions for argv */
00296     } argv;
00297 
00298     xtract_bool_t is_scalar;
00299     xtract_bool_t is_delta; /* features in xtract_delta.h can be scalar or vector */ 
00300 
00301     /* The result.<> entries in descritors.c need to be checked */
00302     union {
00303 
00304         struct {
00305             double min;
00306             double max;    
00307             xtract_unit_t unit;
00308         } scalar;
00309 
00310         struct {
00311             xtract_vector_t format;
00312             xtract_unit_t unit;
00313         } vector;
00314 
00315     } result;
00316 
00317 } xtract_function_descriptor_t;
00318 
00365 #ifdef XTRACT_H
00366 extern int(*xtract[XTRACT_FEATURES])(const double *data, const int N, const void *argv, double *result);
00367 
00368 #endif
00369 
00371 int xtract_init_wavelet_f0_state(void);
00372 
00374 typedef struct xtract_mel_filter_ {
00375     int n_filters;
00376     double **filters;
00377 } xtract_mel_filter;
00378 
00383 int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables);
00384 
00393 int xtract_init_bark(int N, double sr, int *band_limits);
00394 
00404 int xtract_init_fft(int N, int feature_name);
00405 
00410 void xtract_free_fft(void);
00411 
00418 double *xtract_init_window(const int N, const int type);
00419 
00425 void xtract_free_window(double *window);
00426 
00427 /* \brief A function to build an array of function descriptors */
00428 xtract_function_descriptor_t *xtract_make_descriptors();
00429 
00430 /* \brief A function to free an array of function descriptors */
00431 int xtract_free_descriptors(xtract_function_descriptor_t *fd);
00432 /* Free functions */
00433 
00436 #ifdef __cplusplus
00437 }
00438 #endif
00439 
00440 #endif