libxtract.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 Jamie Bullock
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 */

#ifndef XTRACT_H
#define XTRACT_H

#ifdef __cplusplus
extern "C" {
#endif

#include "xtract_scalar.h"
#include "xtract_vector.h"
#include "xtract_delta.h"
#include "xtract_types.h"
#include "xtract_macros.h"
#include "xtract_helper.h"

#define XTRACT_FEATURES 62
    
enum xtract_features_ {
    XTRACT_MEAN,
    XTRACT_VARIANCE,
    XTRACT_STANDARD_DEVIATION,
    XTRACT_AVERAGE_DEVIATION,
    XTRACT_SKEWNESS,
    XTRACT_KURTOSIS,
    XTRACT_SPECTRAL_MEAN,
    XTRACT_SPECTRAL_VARIANCE,
    XTRACT_SPECTRAL_STANDARD_DEVIATION,
    /*XTRACT_SPECTRAL_AVERAGE_DEVIATION, */
    XTRACT_SPECTRAL_SKEWNESS,
    XTRACT_SPECTRAL_KURTOSIS,
    XTRACT_SPECTRAL_CENTROID,
    XTRACT_IRREGULARITY_K,
    XTRACT_IRREGULARITY_J,
    XTRACT_TRISTIMULUS_1,
    XTRACT_TRISTIMULUS_2,
    XTRACT_TRISTIMULUS_3,
    XTRACT_SMOOTHNESS,
    XTRACT_SPREAD,
    XTRACT_ZCR,
    XTRACT_ROLLOFF,
    XTRACT_LOUDNESS,
    XTRACT_FLATNESS,
    XTRACT_FLATNESS_DB,
    XTRACT_TONALITY,
    XTRACT_CREST,
    XTRACT_NOISINESS,
    XTRACT_RMS_AMPLITUDE,
    XTRACT_SPECTRAL_INHARMONICITY,
    XTRACT_POWER,
    XTRACT_ODD_EVEN_RATIO,
    XTRACT_SHARPNESS,
    XTRACT_SPECTRAL_SLOPE,
    XTRACT_LOWEST_VALUE,
    XTRACT_HIGHEST_VALUE,
    XTRACT_SUM,
    XTRACT_NONZERO_COUNT,
    XTRACT_HPS,
    XTRACT_F0,
    XTRACT_FAILSAFE_F0,
    XTRACT_WAVELET_F0,
    XTRACT_MIDICENT,
    XTRACT_LNORM,
    XTRACT_FLUX,
    XTRACT_ATTACK_TIME,
    XTRACT_DECAY_TIME,
    XTRACT_DIFFERENCE_VECTOR,
    XTRACT_AUTOCORRELATION,
    XTRACT_AMDF,
    XTRACT_ASDF,
    XTRACT_BARK_COEFFICIENTS,
    XTRACT_PEAK_SPECTRUM,
    XTRACT_SPECTRUM,
    XTRACT_AUTOCORRELATION_FFT,
    XTRACT_MFCC,
    XTRACT_DCT,
    XTRACT_HARMONIC_SPECTRUM,
    XTRACT_LPC,
    XTRACT_LPCC,
    XTRACT_SUBBANDS,
    /* Helper functions */
    XTRACT_WINDOWED,
    XTRACT_SMOOTHED
};

enum xtract_feature_init_ {
    XTRACT_INIT_MFCC = 100,
    XTRACT_INIT_BARK,
    XTRACT_INIT_WINDOWED
};

enum xtract_feature_types_ {
    XTRACT_SCALAR,
    XTRACT_VECTOR,
    XTRACT_DELTA
};

enum xtract_mfcc_types_ {
    XTRACT_EQUAL_GAIN,
    XTRACT_EQUAL_AREA
};

enum xtract_lnorm_filter_types_ {
    XTRACT_NO_LNORM_FILTER,
    XTRACT_POSITIVE_SLOPE,
    XTRACT_NEGATIVE_SLOPE
};

enum xtract_return_codes_ {
    XTRACT_SUCCESS,
    XTRACT_MALLOC_FAILED,
    XTRACT_BAD_ARGV,
    XTRACT_BAD_VECTOR_SIZE,
    XTRACT_BAD_STATE,
    XTRACT_DENORMAL_FOUND,
    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 */
    XTRACT_FEATURE_NOT_IMPLEMENTED,
    XTRACT_ARGUMENT_ERROR
};

enum xtract_spectrum_ {
    XTRACT_MAGNITUDE_SPECTRUM,
    XTRACT_LOG_MAGNITUDE_SPECTRUM,
    XTRACT_POWER_SPECTRUM,
    XTRACT_LOG_POWER_SPECTRUM
};

enum xtract_subband_scales_ {
    XTRACT_OCTAVE_SUBBANDS,
    XTRACT_LINEAR_SUBBANDS
};

typedef enum type_ {
    XTRACT_FLOAT,
    XTRACT_FLOATARRAY,
    XTRACT_INT,
    XTRACT_MEL_FILTER
} xtract_type_t;

typedef enum unit_ {
    /* NONE, ANY */
    XTRACT_HERTZ = 2,
    XTRACT_ANY_AMPLITUDE_HERTZ,
    XTRACT_DBFS,
    XTRACT_DBFS_HERTZ,
    XTRACT_PERCENT,
    XTRACT_BINS,
    XTRACT_SONE,
    XTRACT_MIDI_CENT
} xtract_unit_t;

typedef enum {
    XTRACT_FALSE,
    XTRACT_TRUE
} xtract_bool_t;

enum xtract_window_types_ {
    XTRACT_GAUSS,
    XTRACT_HAMMING,
    XTRACT_HANN,
    XTRACT_BARTLETT,
    XTRACT_TRIANGULAR,
    XTRACT_BARTLETT_HANN,
    XTRACT_BLACKMAN,
    XTRACT_KAISER,
    XTRACT_BLACKMAN_HARRIS
};

typedef enum xtract_vector_ {
    /* N/2 magnitude/log-magnitude/power/log-power coeffs and N/2 frequencies */
    XTRACT_SPECTRAL,     
    /* N spectral amplitudes */
    XTRACT_SPECTRAL_MAGNITUDES, 
    /* N/2 magnitude/log-magnitude/power/log-power peak coeffs and N/2 
     * frequencies */
    XTRACT_SPECTRAL_PEAKS,
    /* N spectral peak amplitudes */
    XTRACT_SPECTRAL_PEAKS_MAGNITUDES,
    /* N spectral peak frequencies */
    XTRACT_SPECTRAL_PEAKS_FREQUENCIES,
    /* N/2 magnitude/log-magnitude/power/log-power harmonic peak coeffs and N/2 
     * frequencies */
    XTRACT_SPECTRAL_HARMONICS,
    /* N spectral harmonic amplitudes */
    XTRACT_SPECTRAL_HARMONICS_MAGNITUDES,
    /* N spectral harmonic frequencies */
    XTRACT_SPECTRAL_HARMONICS_FREQUENCIES,
    XTRACT_AUTOCORRELATION_COEFFS,
    XTRACT_ARBITRARY_SERIES,
    XTRACT_AUDIO_SAMPLES,
    XTRACT_MEL_COEFFS, 
    XTRACT_LPC_COEFFS, 
    XTRACT_LPCC_COEFFS, 
    XTRACT_BARK_COEFFS,
    XTRACT_SUBFRAMES,
    XTRACT_NO_DATA
} xtract_vector_t;

typedef struct _xtract_function_descriptor {

    int id;

    struct {
        char name[XTRACT_MAX_NAME_LENGTH];
        char p_name[XTRACT_MAX_NAME_LENGTH]; /* pretty name */
        char desc[XTRACT_MAX_DESC_LENGTH];
        char p_desc[XTRACT_MAX_DESC_LENGTH]; /* pretty description */
        char author[XTRACT_MAX_AUTHOR_LENGTH];
        int year;
    } algo;

    struct {
        xtract_vector_t format;
        xtract_unit_t unit;
    } data;

    int argc;

    struct {
        xtract_type_t type; /* type of the array/value pointed to by argv */
        double min[XTRACT_MAXARGS];
        double max[XTRACT_MAXARGS];
        double def[XTRACT_MAXARGS]; /* defaults */
        xtract_unit_t unit[XTRACT_MAXARGS];
        int donor[XTRACT_MAXARGS]; /* suggested donor functions for argv */
    } argv;

    xtract_bool_t is_scalar;
    xtract_bool_t is_delta; /* features in xtract_delta.h can be scalar or vector */ 

    /* The result.<> entries in descritors.c need to be checked */
    union {

        struct {
            double min;
            double max;    
            xtract_unit_t unit;
        } scalar;

        struct {
            xtract_vector_t format;
            xtract_unit_t unit;
        } vector;

    } result;

} xtract_function_descriptor_t;

#ifdef XTRACT_H
extern int(*xtract[XTRACT_FEATURES])(const double *data, const int N, const void *argv, double *result);

#endif

int xtract_init_wavelet_f0_state(void);

typedef struct xtract_mel_filter_ {
    int n_filters;
    double **filters;
} xtract_mel_filter;

int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables);

int xtract_init_bark(int N, double sr, int *band_limits);

int xtract_init_fft(int N, int feature_name);

void xtract_free_fft(void);

double *xtract_init_window(const int N, const int type);

void xtract_free_window(double *window);

/* \brief A function to build an array of function descriptors */
xtract_function_descriptor_t *xtract_make_descriptors();

/* \brief A function to free an array of function descriptors */
int xtract_free_descriptors(xtract_function_descriptor_t *fd);
/* Free functions */

#ifdef __cplusplus
}
#endif

#endif