LibXtract  0.7.1
libxtract.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2012 Jamie Bullock
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *
22  */
23 
49 #ifndef XTRACT_H
50 #define XTRACT_H
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
61 #include "xtract_scalar.h"
62 #include "xtract_vector.h"
63 #include "xtract_delta.h"
64 #include "xtract_types.h"
65 #include "xtract_macros.h"
66 #include "xtract_helper.h"
67 
74 #define XTRACT_FEATURES 62
75 
78  XTRACT_MEAN,
79  XTRACT_VARIANCE,
80  XTRACT_STANDARD_DEVIATION,
81  XTRACT_AVERAGE_DEVIATION,
82  XTRACT_SKEWNESS,
83  XTRACT_KURTOSIS,
84  XTRACT_SPECTRAL_MEAN,
85  XTRACT_SPECTRAL_VARIANCE,
86  XTRACT_SPECTRAL_STANDARD_DEVIATION,
87  /*XTRACT_SPECTRAL_AVERAGE_DEVIATION, */
88  XTRACT_SPECTRAL_SKEWNESS,
89  XTRACT_SPECTRAL_KURTOSIS,
90  XTRACT_SPECTRAL_CENTROID,
91  XTRACT_IRREGULARITY_K,
92  XTRACT_IRREGULARITY_J,
93  XTRACT_TRISTIMULUS_1,
94  XTRACT_TRISTIMULUS_2,
95  XTRACT_TRISTIMULUS_3,
96  XTRACT_SMOOTHNESS,
97  XTRACT_SPREAD,
98  XTRACT_ZCR,
99  XTRACT_ROLLOFF,
100  XTRACT_LOUDNESS,
101  XTRACT_FLATNESS,
102  XTRACT_FLATNESS_DB,
103  XTRACT_TONALITY,
104  XTRACT_CREST,
105  XTRACT_NOISINESS,
106  XTRACT_RMS_AMPLITUDE,
107  XTRACT_SPECTRAL_INHARMONICITY,
108  XTRACT_POWER,
109  XTRACT_ODD_EVEN_RATIO,
110  XTRACT_SHARPNESS,
111  XTRACT_SPECTRAL_SLOPE,
112  XTRACT_LOWEST_VALUE,
113  XTRACT_HIGHEST_VALUE,
114  XTRACT_SUM,
115  XTRACT_NONZERO_COUNT,
116  XTRACT_HPS,
117  XTRACT_F0,
118  XTRACT_FAILSAFE_F0,
119  XTRACT_WAVELET_F0,
120  XTRACT_MIDICENT,
121  XTRACT_LNORM,
122  XTRACT_FLUX,
123  XTRACT_ATTACK_TIME,
124  XTRACT_DECAY_TIME,
125  XTRACT_DIFFERENCE_VECTOR,
126  XTRACT_AUTOCORRELATION,
127  XTRACT_AMDF,
128  XTRACT_ASDF,
129  XTRACT_BARK_COEFFICIENTS,
130  XTRACT_PEAK_SPECTRUM,
131  XTRACT_SPECTRUM,
132  XTRACT_AUTOCORRELATION_FFT,
133  XTRACT_MFCC,
134  XTRACT_DCT,
135  XTRACT_HARMONIC_SPECTRUM,
136  XTRACT_LPC,
137  XTRACT_LPCC,
138  XTRACT_SUBBANDS,
139  /* Helper functions */
140  XTRACT_WINDOWED,
141  XTRACT_SMOOTHED
142 };
143 
146  XTRACT_INIT_MFCC = 100,
147  XTRACT_INIT_BARK,
148  XTRACT_INIT_WINDOWED
149 };
150 
153  XTRACT_SCALAR,
154  XTRACT_VECTOR,
155  XTRACT_DELTA
156 };
157 
160  XTRACT_EQUAL_GAIN,
161  XTRACT_EQUAL_AREA
162 };
163 
164 enum xtract_lnorm_filter_types_ {
165  XTRACT_NO_LNORM_FILTER,
166  XTRACT_POSITIVE_SLOPE,
167  XTRACT_NEGATIVE_SLOPE
168 };
169 
172  XTRACT_SUCCESS,
173  XTRACT_MALLOC_FAILED,
174  XTRACT_BAD_ARGV,
175  XTRACT_BAD_VECTOR_SIZE,
176  XTRACT_BAD_STATE,
177  XTRACT_DENORMAL_FOUND,
178  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 */
179  XTRACT_FEATURE_NOT_IMPLEMENTED,
180  XTRACT_ARGUMENT_ERROR
181 };
182 
185  XTRACT_MAGNITUDE_SPECTRUM,
186  XTRACT_LOG_MAGNITUDE_SPECTRUM,
187  XTRACT_POWER_SPECTRUM,
188  XTRACT_LOG_POWER_SPECTRUM
189 };
190 
193  XTRACT_OCTAVE_SUBBANDS,
194  XTRACT_LINEAR_SUBBANDS
195 };
196 
198 typedef enum type_ {
199  XTRACT_FLOAT,
200  XTRACT_FLOATARRAY,
201  XTRACT_INT,
202  XTRACT_MEL_FILTER
203 } xtract_type_t;
204 
206 typedef enum unit_ {
207  /* NONE, ANY */
208  XTRACT_HERTZ = 2,
209  XTRACT_ANY_AMPLITUDE_HERTZ,
210  XTRACT_DBFS,
211  XTRACT_DBFS_HERTZ,
212  XTRACT_PERCENT,
213  XTRACT_BINS,
214  XTRACT_SONE,
215  XTRACT_MIDI_CENT
216 } xtract_unit_t;
217 
219 typedef enum {
220  XTRACT_FALSE,
221  XTRACT_TRUE
222 } xtract_bool_t;
223 
226  XTRACT_GAUSS,
227  XTRACT_HAMMING,
228  XTRACT_HANN,
229  XTRACT_BARTLETT,
230  XTRACT_TRIANGULAR,
231  XTRACT_BARTLETT_HANN,
232  XTRACT_BLACKMAN,
233  XTRACT_KAISER,
234  XTRACT_BLACKMAN_HARRIS
235 };
236 
238 typedef enum xtract_vector_ {
239  /* N/2 magnitude/log-magnitude/power/log-power coeffs and N/2 frequencies */
240  XTRACT_SPECTRAL,
241  /* N spectral amplitudes */
242  XTRACT_SPECTRAL_MAGNITUDES,
243  /* N/2 magnitude/log-magnitude/power/log-power peak coeffs and N/2
244  * frequencies */
245  XTRACT_SPECTRAL_PEAKS,
246  /* N spectral peak amplitudes */
247  XTRACT_SPECTRAL_PEAKS_MAGNITUDES,
248  /* N spectral peak frequencies */
249  XTRACT_SPECTRAL_PEAKS_FREQUENCIES,
250  /* N/2 magnitude/log-magnitude/power/log-power harmonic peak coeffs and N/2
251  * frequencies */
252  XTRACT_SPECTRAL_HARMONICS,
253  /* N spectral harmonic amplitudes */
254  XTRACT_SPECTRAL_HARMONICS_MAGNITUDES,
255  /* N spectral harmonic frequencies */
256  XTRACT_SPECTRAL_HARMONICS_FREQUENCIES,
257  XTRACT_AUTOCORRELATION_COEFFS,
258  XTRACT_ARBITRARY_SERIES,
259  XTRACT_AUDIO_SAMPLES,
260  XTRACT_MEL_COEFFS,
261  XTRACT_LPC_COEFFS,
262  XTRACT_LPCC_COEFFS,
263  XTRACT_BARK_COEFFS,
264  XTRACT_SUBFRAMES,
265  XTRACT_NO_DATA
267 
270 
271  int id;
272 
273  struct {
274  char name[XTRACT_MAX_NAME_LENGTH];
275  char p_name[XTRACT_MAX_NAME_LENGTH]; /* pretty name */
276  char desc[XTRACT_MAX_DESC_LENGTH];
277  char p_desc[XTRACT_MAX_DESC_LENGTH]; /* pretty description */
278  char author[XTRACT_MAX_AUTHOR_LENGTH];
279  int year;
280  } algo;
281 
282  struct {
283  xtract_vector_t format;
284  xtract_unit_t unit;
285  } data;
286 
287  int argc;
288 
289  struct {
290  xtract_type_t type; /* type of the array/value pointed to by argv */
291  double min[XTRACT_MAXARGS];
292  double max[XTRACT_MAXARGS];
293  double def[XTRACT_MAXARGS]; /* defaults */
294  xtract_unit_t unit[XTRACT_MAXARGS];
295  int donor[XTRACT_MAXARGS]; /* suggested donor functions for argv */
296  } argv;
297 
298  xtract_bool_t is_scalar;
299  xtract_bool_t is_delta; /* features in xtract_delta.h can be scalar or vector */
300 
301  /* The result.<> entries in descritors.c need to be checked */
302  union {
303 
304  struct {
305  double min;
306  double max;
307  xtract_unit_t unit;
308  } scalar;
309 
310  struct {
311  xtract_vector_t format;
312  xtract_unit_t unit;
313  } vector;
314 
315  } result;
316 
318 
365 #ifdef XTRACT_H
366 extern int(*xtract[XTRACT_FEATURES])(const double *data, const int N, const void *argv, double *result);
367 
368 #endif
369 
372 
374 typedef struct xtract_mel_filter_ {
375  int n_filters;
376  double **filters;
378 
383 int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables);
384 
393 int xtract_init_bark(int N, double sr, int *band_limits);
394 
404 int xtract_init_fft(int N, int feature_name);
405 
410 void xtract_free_fft(void);
411 
418 double *xtract_init_window(const int N, const int type);
419 
425 void xtract_free_window(double *window);
426 
427 /* \brief A function to build an array of function descriptors */
428 xtract_function_descriptor_t *xtract_make_descriptors();
429 
430 /* \brief A function to free an array of function descriptors */
431 int xtract_free_descriptors(xtract_function_descriptor_t *fd);
432 /* Free functions */
433 
436 #ifdef __cplusplus
437 }
438 #endif
439 
440 #endif
struct _xtract_function_descriptor xtract_function_descriptor_t
Data structure containing useful information about functions provided by LibXtract.
enum xtract_vector_ xtract_vector_t
Enumeration of vector format types.
xtract_return_codes_
Enumeration of return codes.
Definition: libxtract.h:171
xtract_features_
Enumeration of features, elements are used as indixes to an array of pointers to feature extracton fu...
Definition: libxtract.h:77
int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables)
A function to initialise a mel filter bank.
int xtract_init_bark(int N, double sr, int *band_limits)
A function to initialise bark filter bounds.
void xtract_free_window(double *window)
Free a window as allocated by xtract_make_window()
xtract_spectrum_
Enumeration of spectrum types.
Definition: libxtract.h:184
type_
Enumeration of data types.
Definition: libxtract.h:198
int xtract_init_fft(int N, int feature_name)
An initialisation function for functions using FFT.
struct xtract_mel_filter_ xtract_mel_filter
A structure to store a set of n_filters Mel filters.
xtract_bool_t
Boolean.
Definition: libxtract.h:219
A structure to store a set of n_filters Mel filters.
Definition: libxtract.h:374
enum type_ xtract_type_t
Enumeration of data types.
int xtract_init_wavelet_f0_state(void)
An array of pointers to functions that perform the extraction.
xtract_feature_types_
Enumeration of feature types.
Definition: libxtract.h:152
unit_
Enumeration of units.
Definition: libxtract.h:206
double * xtract_init_window(const int N, const int type)
Make a window of a given type and return a pointer to it.
xtract_feature_init_
Enumeration of feature initialisation functions.
Definition: libxtract.h:145
Data structure containing useful information about functions provided by LibXtract.
Definition: libxtract.h:269
void xtract_free_fft(void)
Free memory used for fft plans.
xtract_subband_scales_
Subband scales.
Definition: libxtract.h:192
xtract_mfcc_types_
Enumeration of mfcc types.
Definition: libxtract.h:159
enum unit_ xtract_unit_t
Enumeration of units.
xtract_vector_
Enumeration of vector format types.
Definition: libxtract.h:238
xtract_window_types_
Window types.
Definition: libxtract.h:225