LibXtract  0.6.2
libxtract.h
Go to the documentation of this file.
1 /* libxtract feature extraction library
2  *
3  * Copyright (C) 2006 Jamie Bullock
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
18  * USA.
19  */
20 
46 #ifndef XTRACT_H
47 #define XTRACT_H
48 
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
52 
58 #include "xtract_scalar.h"
59 #include "xtract_vector.h"
60 #include "xtract_delta.h"
61 #include "xtract_types.h"
62 #include "xtract_macros.h"
63 #include "xtract_helper.h"
64 
71 #define XTRACT_FEATURES 60
72 
75  XTRACT_MEAN,
76  XTRACT_VARIANCE,
77  XTRACT_STANDARD_DEVIATION,
78  XTRACT_AVERAGE_DEVIATION,
79  XTRACT_SKEWNESS,
80  XTRACT_KURTOSIS,
81  XTRACT_SPECTRAL_MEAN,
82  XTRACT_SPECTRAL_VARIANCE,
83  XTRACT_SPECTRAL_STANDARD_DEVIATION,
84  XTRACT_SPECTRAL_AVERAGE_DEVIATION,
85  XTRACT_SPECTRAL_SKEWNESS,
86  XTRACT_SPECTRAL_KURTOSIS,
87  XTRACT_SPECTRAL_CENTROID,
88  XTRACT_IRREGULARITY_K,
89  XTRACT_IRREGULARITY_J,
90  XTRACT_TRISTIMULUS_1,
91  XTRACT_TRISTIMULUS_2,
92  XTRACT_TRISTIMULUS_3,
93  XTRACT_SMOOTHNESS,
94  XTRACT_SPREAD,
95  XTRACT_ZCR,
96  XTRACT_ROLLOFF,
97  XTRACT_LOUDNESS,
98  XTRACT_FLATNESS,
99  XTRACT_FLATNESS_DB,
100  XTRACT_TONALITY,
101  XTRACT_CREST,
102  XTRACT_NOISINESS,
103  XTRACT_RMS_AMPLITUDE,
104  XTRACT_SPECTRAL_INHARMONICITY,
105  XTRACT_POWER,
106  XTRACT_ODD_EVEN_RATIO,
107  XTRACT_SHARPNESS,
108  XTRACT_SPECTRAL_SLOPE,
109  XTRACT_LOWEST_VALUE,
110  XTRACT_HIGHEST_VALUE,
111  XTRACT_SUM,
112  XTRACT_NONZERO_COUNT,
113  XTRACT_HPS,
114  XTRACT_F0,
115  XTRACT_FAILSAFE_F0,
116  XTRACT_LNORM,
117  XTRACT_FLUX,
118  XTRACT_ATTACK_TIME,
119  XTRACT_DECAY_TIME,
120  XTRACT_DIFFERENCE_VECTOR,
121  XTRACT_AUTOCORRELATION,
122  XTRACT_AMDF,
123  XTRACT_ASDF,
124  XTRACT_BARK_COEFFICIENTS,
125  XTRACT_PEAK_SPECTRUM,
126  XTRACT_SPECTRUM,
127  XTRACT_AUTOCORRELATION_FFT,
128  XTRACT_MFCC,
129  XTRACT_DCT,
130  XTRACT_HARMONIC_SPECTRUM,
131  XTRACT_LPC,
132  XTRACT_LPCC,
133  XTRACT_SUBBANDS,
134  /* Helper functions */
135  XTRACT_WINDOWED
136 };
137 
140  XTRACT_INIT_MFCC = 100,
141  XTRACT_INIT_BARK,
142  XTRACT_INIT_WINDOWED
143 };
144 
147  XTRACT_SCALAR,
148  XTRACT_VECTOR,
149  XTRACT_DELTA
150 };
151 
154  XTRACT_EQUAL_GAIN,
155  XTRACT_EQUAL_AREA
156 };
157 
158 enum xtract_lnorm_filter_types_ {
159  XTRACT_NO_LNORM_FILTER,
160  XTRACT_POSITIVE_SLOPE,
161  XTRACT_NEGATIVE_SLOPE
162 };
163 
166  XTRACT_SUCCESS,
167  XTRACT_MALLOC_FAILED,
168  XTRACT_BAD_ARGV,
169  XTRACT_BAD_VECTOR_SIZE,
170  XTRACT_DENORMAL_FOUND,
171  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 */
172  XTRACT_FEATURE_NOT_IMPLEMENTED
173 };
174 
177  XTRACT_MAGNITUDE_SPECTRUM,
178  XTRACT_LOG_MAGNITUDE_SPECTRUM,
179  XTRACT_POWER_SPECTRUM,
180  XTRACT_LOG_POWER_SPECTRUM
181 };
182 
185  XTRACT_OCTAVE_SUBBANDS,
186  XTRACT_LINEAR_SUBBANDS
187 };
188 
190 typedef enum type_ {
191  XTRACT_FLOAT,
192  XTRACT_FLOATARRAY,
193  XTRACT_INT,
194  XTRACT_MEL_FILTER
196 
198 typedef enum unit_ {
199  /* NONE, ANY */
200  XTRACT_HERTZ = 2,
201  XTRACT_ANY_AMPLITUDE_HERTZ,
202  XTRACT_DBFS,
203  XTRACT_DBFS_HERTZ,
204  XTRACT_PERCENT,
205  XTRACT_BINS,
206  XTRACT_SONE
208 
210 typedef enum {
211  XTRACT_FALSE,
212  XTRACT_TRUE
213 } xtract_bool_t;
214 
217  XTRACT_GAUSS,
218  XTRACT_HAMMING,
219  XTRACT_HANN,
220  XTRACT_BARTLETT,
221  XTRACT_TRIANGULAR,
222  XTRACT_BARTLETT_HANN,
223  XTRACT_BLACKMAN,
224  XTRACT_KAISER,
225  XTRACT_BLACKMAN_HARRIS
226 };
227 
229 typedef enum xtract_vector_ {
230  /* N/2 magnitude/log-magnitude/power/log-power coeffs and N/2 frequencies */
231  XTRACT_SPECTRAL,
232  /* N spectral amplitudes */
233  XTRACT_SPECTRAL_MAGNITUDES,
234  /* N/2 magnitude/log-magnitude/power/log-power peak coeffs and N/2
235  * frequencies */
236  XTRACT_SPECTRAL_PEAKS,
237  /* N spectral peak amplitudes */
238  XTRACT_SPECTRAL_PEAKS_MAGNITUDES,
239  /* N spectral peak frequencies */
240  XTRACT_SPECTRAL_PEAKS_FREQUENCIES,
241  /* N/2 magnitude/log-magnitude/power/log-power harmonic peak coeffs and N/2
242  * frequencies */
243  XTRACT_SPECTRAL_HARMONICS,
244  /* N spectral harmonic amplitudes */
245  XTRACT_SPECTRAL_HARMONICS_MAGNITUDES,
246  /* N spectral harmonic frequencies */
247  XTRACT_SPECTRAL_HARMONICS_FREQUENCIES,
248  XTRACT_AUTOCORRELATION_COEFFS,
249  XTRACT_ARBITRARY_SERIES,
250  XTRACT_AUDIO_SAMPLES,
251  XTRACT_MEL_COEFFS,
252  XTRACT_LPC_COEFFS,
253  XTRACT_LPCC_COEFFS,
254  XTRACT_BARK_COEFFS,
255  XTRACT_SUBFRAMES,
256  XTRACT_NO_DATA
258 
261 
262  int id;
263 
264  struct {
265  char name[XTRACT_MAX_NAME_LENGTH];
266  char p_name[XTRACT_MAX_NAME_LENGTH]; /* pretty name */
267  char desc[XTRACT_MAX_DESC_LENGTH];
268  char p_desc[XTRACT_MAX_DESC_LENGTH]; /* pretty description */
269  char author[XTRACT_MAX_AUTHOR_LENGTH];
270  int year;
271  } algo;
272 
273  struct {
274  xtract_vector_t format;
275  xtract_unit_t unit;
276  } data;
277 
278  int argc;
279 
280  struct {
281  xtract_type_t type; /* type of the array/value pointed to by argv */
282  float min[XTRACT_MAXARGS];
283  float max[XTRACT_MAXARGS];
284  float def[XTRACT_MAXARGS]; /* defaults */
285  xtract_unit_t unit[XTRACT_MAXARGS];
286  int donor[XTRACT_MAXARGS]; /* suggested donor functions for argv */
287  } argv;
288 
289  xtract_bool_t is_scalar;
290  xtract_bool_t is_delta; /* features in xtract_delta.h can be scalar or vector */
291 
292  /* The result.<> entries in descritors.c need to be checked */
293  union {
294 
295  struct {
296  float min;
297  float max;
298  xtract_unit_t unit;
299  } scalar;
300 
301  struct {
302  xtract_vector_t format;
303  xtract_unit_t unit;
304  } vector;
305 
306  } result;
307 
309 
356 #ifdef XTRACT_H
357 extern int(*xtract[XTRACT_FEATURES])(const float *data, const int N, const void *argv, float *result);
358 
359 #endif
360 
362 typedef struct xtract_mel_filter_ {
363  int n_filters;
364  float **filters;
366 
371 int xtract_init_mfcc(int N, float nyquist, int style, float freq_min, float freq_max, int freq_bands, float **fft_tables);
372 
381 int xtract_init_bark(int N, float sr, int *band_limits);
382 
392 int xtract_init_fft(int N, int feature_name);
393 
398 void xtract_free_fft(void);
399 
406 float *xtract_init_window(const int N, const int type);
407 
413 void xtract_free_window(float *window);
414 
415 /* \brief A function to build an array of function descriptors */
416 xtract_function_descriptor_t *xtract_make_descriptors();
417 
418 /* \brief A function to free an array of function descriptors */
419 int xtract_free_descriptors(xtract_function_descriptor_t *fd);
420 /* Free functions */
421 
424 #ifdef __cplusplus
425 }
426 #endif
427 
428 #endif
int xtract_init_mfcc(int N, float nyquist, int style, float freq_min, float freq_max, int freq_bands, float **fft_tables)
A function to initialise a mel filter bank.
int xtract_init_fft(int N, int feature_name)
An initialisation function for functions using FFT.
xtract_return_codes_
Enumeration of return codes.
Definition: libxtract.h:165
type_
Enumeration of data types.
Definition: libxtract.h:190
enum unit_ xtract_unit_t
Enumeration of units.
xtract_mfcc_types_
Enumeration of mfcc types.
Definition: libxtract.h:153
float * xtract_init_window(const int N, const int type)
Make a window of a given type and return a pointer to it.
void xtract_free_window(float *window)
Free a window as allocated by xtract_make_window()
xtract_feature_types_
Enumeration of feature types.
Definition: libxtract.h:146
xtract_vector_
Enumeration of vector format types.
Definition: libxtract.h:229
struct _xtract_function_descriptor xtract_function_descriptor_t
Data structure containing useful information about functions provided by LibXtract.
xtract_bool_t
Boolean.
Definition: libxtract.h:210
xtract_spectrum_
Enumeration of spectrum types.
Definition: libxtract.h:176
xtract_subband_scales_
Subband scales.
Definition: libxtract.h:184
unit_
Enumeration of units.
Definition: libxtract.h:198
struct xtract_mel_filter_ xtract_mel_filter
An array of pointers to functions that perform the extraction.
void xtract_free_fft(void)
Free memory used for fft plans.
xtract_feature_init_
Enumeration of feature initialisation functions.
Definition: libxtract.h:139
xtract_window_types_
Window types.
Definition: libxtract.h:216
xtract_features_
Enumeration of features, elements are used as indixes to an array of pointers to feature extracton fu...
Definition: libxtract.h:74
enum type_ xtract_type_t
Enumeration of data types.
enum xtract_vector_ xtract_vector_t
Enumeration of vector format types.
int xtract_init_bark(int N, float sr, int *band_limits)
A function to initialise bark filter bounds.
Data structure containing useful information about functions provided by LibXtract.
Definition: libxtract.h:260
An array of pointers to functions that perform the extraction.
Definition: libxtract.h:362