From fc4f132415391c0b5dd52072ce7e25473e06e3a9 Mon Sep 17 00:00:00 2001 From: Jamie Bullock Date: Fri, 7 Nov 2014 12:49:21 +0000 Subject: Move xtract inside "include" directory --- include/xtract/libxtract.h | 440 +++++++++++++++++++++++++++++++++++ include/xtract/xtract_delta.h | 88 +++++++ include/xtract/xtract_helper.h | 109 +++++++++ include/xtract/xtract_macros.h | 47 ++++ include/xtract/xtract_scalar.h | 483 +++++++++++++++++++++++++++++++++++++++ include/xtract/xtract_stateful.h | 66 ++++++ include/xtract/xtract_types.h | 48 ++++ include/xtract/xtract_vector.h | 188 +++++++++++++++ xtract/libxtract.h | 440 ----------------------------------- xtract/xtract_delta.h | 88 ------- xtract/xtract_helper.h | 109 --------- xtract/xtract_macros.h | 47 ---- xtract/xtract_scalar.h | 483 --------------------------------------- xtract/xtract_stateful.h | 66 ------ xtract/xtract_types.h | 48 ---- xtract/xtract_vector.h | 188 --------------- 16 files changed, 1469 insertions(+), 1469 deletions(-) create mode 100644 include/xtract/libxtract.h create mode 100644 include/xtract/xtract_delta.h create mode 100644 include/xtract/xtract_helper.h create mode 100644 include/xtract/xtract_macros.h create mode 100644 include/xtract/xtract_scalar.h create mode 100644 include/xtract/xtract_stateful.h create mode 100644 include/xtract/xtract_types.h create mode 100644 include/xtract/xtract_vector.h delete mode 100644 xtract/libxtract.h delete mode 100644 xtract/xtract_delta.h delete mode 100644 xtract/xtract_helper.h delete mode 100644 xtract/xtract_macros.h delete mode 100644 xtract/xtract_scalar.h delete mode 100644 xtract/xtract_stateful.h delete mode 100644 xtract/xtract_types.h delete mode 100644 xtract/xtract_vector.h diff --git a/include/xtract/libxtract.h b/include/xtract/libxtract.h new file mode 100644 index 0000000..17540c5 --- /dev/null +++ b/include/xtract/libxtract.h @@ -0,0 +1,440 @@ +/* + * 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. + * + */ + +/** \mainpage + * + * LibXtract is a simple, portable, lightweight library of audio feature extraction functions. The purpose of the library is to provide a relatively exhaustive set of feature extraction primatives that are designed to be 'cascaded' to create a extraction hierarchies. + * For example, 'variance', 'average deviation', 'skewness' and 'kurtosis', all require the 'mean' of the input vector to be precomputed. However, rather than compute the 'mean' 'inside' each function, it is expected that the 'mean' will be passed in as an argument. This means that if the user wishes to use all of these features, the mean is calculated only once, and then passed to any functions that require it. + * + * This philosophy of 'cascading' features is followed throughout the library, for example with features that operate on the magnitude spectrum of a signal vector (e.g. 'irregularity'), the magnitude spectrum is not calculated 'inside' the respective function, instead, a pointer to the first element in an array containing the magnitude spectrum is passed in as an argument. + * + * Hopefully this not only makes the library more efficient when computing large numbers of features, but also makes it more flexible because extraction functions can be combined arbitrarily (one can take the irregularility of the Mel Frequency Cepstral Coefficients for example). + * + * All feature extraction functions follow the same prototype: + * + * **int xtract_function_name(const double *data, const int N, const void *argv, double *result);** + * + * \param const double *data points to an array of doubles representing the input data + * \param const int N represents the number of elementes from *data to be considered in the calculation + * \param const void *argv represents an arbitrary list of arguments. Used to pass in values required by the feature calculation + * \param double *result points to an array of doubles, or a single double represnting the result of the calculation + * + * + * It is up to the calling function to allocate enough memory for the *data, *argv, and *result, and to free it when required. Some feature extraction functions may also require an _init() function to be called in order to perform some initialisation. The struct xtract_function_descriptor_t is used to give an indication of recommended default values, and argc for the *argv array. + * + * LibXtract can be downloaded from http://www.sf.net/projects/libxtract + * + */ + +#ifndef XTRACT_H +#define XTRACT_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \file libxtract.h + * \brief main header file and API definition + */ + +#include "xtract_scalar.h" +#include "xtract_vector.h" +#include "xtract_delta.h" +#include "xtract_types.h" +#include "xtract_macros.h" +#include "xtract_helper.h" + +/** \defgroup libxtract API + * + * Defines a very simple API that provides access to the functions in the library + * @{ + */ + +#define XTRACT_FEATURES 62 + +/** \brief Enumeration of features, elements are used as indixes to an array of pointers to feature extracton functions */ +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 +}; + +/** \brief Enumeration of feature initialisation functions */ +enum xtract_feature_init_ { + XTRACT_INIT_MFCC = 100, + XTRACT_INIT_BARK, + XTRACT_INIT_WINDOWED +}; + +/** \brief Enumeration of feature types */ +enum xtract_feature_types_ { + XTRACT_SCALAR, + XTRACT_VECTOR, + XTRACT_DELTA +}; + +/** \brief Enumeration of mfcc types */ +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 +}; + +/** \brief Enumeration of return codes */ +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 +}; + +/** \brief Enumeration of spectrum types */ +enum xtract_spectrum_ { + XTRACT_MAGNITUDE_SPECTRUM, + XTRACT_LOG_MAGNITUDE_SPECTRUM, + XTRACT_POWER_SPECTRUM, + XTRACT_LOG_POWER_SPECTRUM +}; + +/** \brief Subband scales */ +enum xtract_subband_scales_ { + XTRACT_OCTAVE_SUBBANDS, + XTRACT_LINEAR_SUBBANDS +}; + +/** \brief Enumeration of data types*/ +typedef enum type_ { + XTRACT_FLOAT, + XTRACT_FLOATARRAY, + XTRACT_INT, + XTRACT_MEL_FILTER +} xtract_type_t; + +/** \brief Enumeration of units*/ +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; + +/** \brief Boolean */ +typedef enum { + XTRACT_FALSE, + XTRACT_TRUE +} xtract_bool_t; + +/** \brief Window types */ +enum xtract_window_types_ { + XTRACT_GAUSS, + XTRACT_HAMMING, + XTRACT_HANN, + XTRACT_BARTLETT, + XTRACT_TRIANGULAR, + XTRACT_BARTLETT_HANN, + XTRACT_BLACKMAN, + XTRACT_KAISER, + XTRACT_BLACKMAN_HARRIS +}; + +/** \brief Enumeration of vector format types*/ +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; + +/** \brief Data structure containing useful information about functions provided by LibXtract. */ +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; + +/** + * + * \brief An array of pointers to functions that perform the extraction + * + * \param *data: a pointer to the start of the input data (usually the first element in an array) + * + * \param N: the number of elements to be processed + * + * \param *argv: an abitrary number of additional arguments, used to pass additional parameters to the function being called. All arguments are compulsary! + * + * \param *result: a pointer to the first element in the result + * + * Each function will iterate over N array elements, the first of which is + * pointed to by *data. It is up to the calling function to ensure that the array is in the format expected by the function being called. + * + * For scalar and delta features, *result will point to a single value. + * + * For vector features it will point to the first element in an array. + * + * Memory for this array must be allocated and freed by the calling + * function. + * + * All functions return an integer error code as descibed in the enumeration + * return_codes_ + * + * The preprocessor macro: XTRACT must be defined before this can be used + * + * example:
+ * \verbatim +#include +#define XTRACT +#include "libxtract.h" + +main () { +double values[] = {1.0, 2.0, 3.0, 4.0, 5.0}; +int N = 5; +double mean; + +xtract[MEAN]((void *)values, N, NULL, &mean); + +printf("Mean = %.2f\n", mean); +} +\endverbatim + * The calling function may additionally make some tests against the value returned by xtract + * + */ +#ifdef XTRACT_H +extern int(*xtract[XTRACT_FEATURES])(const double *data, const int N, const void *argv, double *result); + +#endif + +/** \brief A function to initialise wavelet f0 detector state */ +int xtract_init_wavelet_f0_state(void); + +/** \brief A structure to store a set of n_filters Mel filters */ +typedef struct xtract_mel_filter_ { + int n_filters; + double **filters; +} xtract_mel_filter; + +/** \brief A function to initialise a mel filter bank + * + * It is up to the caller to pass in a pointer to memory allocated for freq_bands arrays of length N. This function populates these arrays with magnitude coefficients representing the mel filterbank on a linear scale + */ +int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables); + +/** \brief A function to initialise bark filter bounds + * + * A pointer to an array of BARK_BANDS ints most be passed in, and is populated with BARK_BANDS fft bin numbers representing the limits of each band + * + * \param N: the audio block size + * \param sr: The sample audio sample rate + * \param *band_limits: a pointer to an array of BARK_BANDS ints + */ +int xtract_init_bark(int N, double sr, int *band_limits); + +/** \brief An initialisation function for functions using FFT + * + * This function initialises global data structures used by functions requiring FFT functionality. It can be called multiple times with different feature names. Calling it more than once with the same feature name is not a valid operation and will result in a memory leak. + * + * \param N: the size of the FFT + * \param feature_name: the name of the feature the FFT is being used for, + * e.g. XTRACT_DCT + * + */ +int xtract_init_fft(int N, int feature_name); + +/** \brief Free memory used for fft plans + * + * This function should be used to explicitly free memory allocated for ffts by xtract_init_fft(). It is primarily intended for use if a new FFT needs to be taken with a different blocksize. If only one fft size is required then there is no need to call this function since it will be called when the program exits. + * */ +void xtract_free_fft(void); + +/** \brief Make a window of a given type and return a pointer to it + * + * \param N: the size of the window + * \param type: the type of the window as given in the enumeration window_types_ + * + */ +double *xtract_init_window(const int N, const int type); + +/** \brief Free a window as allocated by xtract_make_window() + * + * \param *window: a pointer to an array of doubles as allocated by xtract_make_window() + * + */ +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 diff --git a/include/xtract/xtract_delta.h b/include/xtract/xtract_delta.h new file mode 100644 index 0000000..c7b3ee7 --- /dev/null +++ b/include/xtract/xtract_delta.h @@ -0,0 +1,88 @@ +/* + * 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. + * + */ + +/** \file xtract_delta.h: declares functions that scalar or vector value from 2 or more input vectors */ + +#ifndef XTRACT_DELTA_H +#define XTRACT_DELTA_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup delta `delta' extraction functions + * + * Functions that extract a scalar or vector value from 2 or more input vectors + * + * @{ + */ + +#include "xtract_types.h" + +/** \brief Extract flux + * + * \note FIX: don't be lazy -- take the lnorm of the difference vector! + * An alias for xtract_lnorm() + */ +int xtract_flux(const double *data, const int N, const void *argv , double *result); + +/** \brief Extract the L-norm of a vector + * + * \param *data: a pointer to the first element in an array of doubles representing the difference between two subsequent frames of output from a vector-based feature e.g. the *result from xtract_difference_vector() + * \param N: the length of the array pointed to by *data + * \param *argv: a pointer to an array of doubles, the first representing the "norm order". The second argument represents the filter type determining what values we consider from the difference vector as given in the enumeration xtract_lnorm_filter_types_ (libxtract.h), the third sets whether we want the result to be normalised in the range 0-1 (0 = no normalise, 1 = normalise) + * \param *result: a pointer to a double representing the flux + * + */ +int xtract_lnorm(const double *data, const int N, const void *argv , double *result); +/*xtract_frame_tracker *xf */ + +/** \brief Extract attack Time */ +int xtract_attack_time(const double *data, const int N, const void *argv , double *result); +/* xtract_amp_tracker *xa */ + +/** Extract temporal decrease */ +int xtract_decay_time(const double *data, const int N, const void *argv, double *result); +/* xtract_amp_tracker *xa */ + + +/** \brief Extract the difference between two vectors + * + * \param *data a pointer to an array representing two distinct vectors, e.g. two successive magnitude spectra. + * \param N the size of the array pointed to by *data + * \param *argv a pointer to NULL + * \param *result a pointer to an array of size N / 2 representing the difference between the two input vectors. + * + * */ +int xtract_difference_vector(const double *data, const int N, const void *argv, double *result); +/*xtract_frame_tracker *xf */ +/*double frames*/ + +/** @} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/xtract/xtract_helper.h b/include/xtract/xtract_helper.h new file mode 100644 index 0000000..7296f0e --- /dev/null +++ b/include/xtract/xtract_helper.h @@ -0,0 +1,109 @@ +/* + * 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. + * + */ + +/** \file xtract_helper.h: helper functions for making life with libxtract a bit more bearable */ + +#ifndef XTRACT_HELPER_H +#define XTRACT_HELPER_H + +#ifdef __cplusplus +extern "C" { +#endif + +#ifdef _MSC_VER + #ifndef __cplusplus + typedef int bool; + #define false 0 + #define true 1 + #endif +#else + #include +#endif + + +/** + * \defgroup helper helper functions + * + * Declares helper functions, and their parameters. + * + * \note These functions don't necessarily conform to the prototype used in xtract_scalar.h and xtract_vector.h etc, and as such are intended to be called 'directly' rather than via the xtract[] function pointer array (libxtract.h) + * + * @{ + */ + +/** \brief Apply a window function to an array of length N + * + * \param *data a pointer to an array of doubles + * \param N the number of elements in the array pointed to by *data + * \param *argv a pointer to a window function as returned by xtract_make_window() + * \param *result a pointer to the first element an array containing the windowed data + * + * It is up to the caller to generate and free the array containing the window, and to allocate and free memory of size N to hold the data pointed to by *result + * + */ +int xtract_windowed(const double *data, const int N, const void *argv, double *result); + +/** \brief Divides the array pointed to by *data into two subframes, and applies a given feature to each subframe, returning them in a single array pointed to by result + * + * \param *data an array of doubles + * \param N the number of elements in the array pointed by *data + * \param feature an integer representing the feature to be applied to each subframe in data. This will be a value as given in the enumeration xtract_features_ (libxtract.h) + * \param *argv a pointer to the argument vector to be passed to the feature extraction function as determined by feature + * \param *result a pointer to the 'packed' results of the feature calculation. This may be passed in as *data to xtract_features_from_subframes() to calculate further features on the subframes, or xtract_difference_vector(), to get the difference between the subframes. + * + * + * It is important to ensure that any _init_*() functions that are called in preparation for functions that are called on subframes are given the subframe size as 'N', and not the frame size. i.e. if xtract_features_from_subframes() is called with N=64, and feature=XTRACT_SPECTRUM, then xtract_init_fft() should be called with N=32. + * + */ +int xtract_features_from_subframes(const double *data, const int N, const int feature, const void *argv, double *result); + +/** \brief Test whether a number is denormal */ +int xtract_is_denormal(double const d); + +/** \brief Test whether a number is a power of two */ +bool xtract_is_poweroftwo(unsigned int x); + + +/** \brief Smooth a vector + * + * \param *data a pointer to an array of doubles + * \param N the number of elements in the array pointed to by *data to be smoothed + * \param *argv a pointer to a double giving the smoothing gain + * \param *result a pointer to the first element an array containing the smoothed data + * + * \note if passing in a spectrum e.g. *result from xtract_spectrum(), then N for xtract_smoothed() should be N / 2 with respect to the N for xtract_spectrum() so only amplitude components are smoothed, not frequencies! + * + */ + int xtract_smoothed(const double *data, const int N, const void *argv, double *result); + + +/** @} */ + +#ifdef __cplusplus +} +#endif + +#endif + + + diff --git a/include/xtract/xtract_macros.h b/include/xtract/xtract_macros.h new file mode 100644 index 0000000..3445866 --- /dev/null +++ b/include/xtract/xtract_macros.h @@ -0,0 +1,47 @@ +/* + * 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. + * + */ + +/** \file xtract_macros.h: defines useful public macros */ + +#ifndef XTRACT_MACROS_H +#define XTRACT_MACROS_H + +#ifdef __cplusplus +extern "C" { +#endif + +#define XTRACT_BARK_BANDS 26 +#define XTRACT_WINDOW_SIZE 1024/* dummy macro for descriptors where argc is window size */ +#define XTRACT_NONE 0 +#define XTRACT_ANY -1 +#define XTRACT_UNKNOWN -2 +#define XTRACT_MAXARGS 4 +#define XTRACT_MAX_NAME_LENGTH 64 +#define XTRACT_MAX_AUTHOR_LENGTH 128 +#define XTRACT_MAX_DESC_LENGTH 256 + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/xtract/xtract_scalar.h b/include/xtract/xtract_scalar.h new file mode 100644 index 0000000..8e24284 --- /dev/null +++ b/include/xtract/xtract_scalar.h @@ -0,0 +1,483 @@ +/* + * 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. + * + */ + +/** \file xtract_scalar.h: declares functions that extract a feature as a single value from an input vector */ + +#ifndef XTRACT_SCALAR_H +#define XTRACT_SCALAR_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup scalar scalar extraction functions + * + * Functions that extract a feature as a single value from an input vector + * + * @{ + */ + +/** \brief Extract the mean of an input vector + * + * \param *data: a pointer to the first element + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the mean of N values from the array pointed to by *data + */ +int xtract_mean(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the variance of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the mean of the input vector + * \param *result: the variance of N values from the array pointed to by *data + */ +int xtract_variance(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the deviation of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the variance of the input vector + * \param *result: the deviation of N values from the array pointed to by *data + */ +int xtract_standard_deviation(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the average deviation of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the mean of the input vector + * \param *result: the average deviation of N values from the array pointed to by *data + */ +int xtract_average_deviation(const double *data, const int N, const void *argv, double *result); + + +/** \brief Extract the skewness of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to an array of doubles representing the mean and standard deviation of the input vector + * \param *result: the skewness of N values from the array pointed to by *data + */ +int xtract_skewness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the kurtosis of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to an array of values representing the mean and standard deviation of the input vector + * \param *result: the kurtosis of N values from the array pointed to by *data + */ +int xtract_kurtosis(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the mean of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to NULL + * \param *result: the mean of the spectrum pointed to by *data + */ +int xtract_spectral_mean(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the variance of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the number of elements to be considered + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to a double representing the spectral mean of the input spectrum + * \param *result: the variance of the spectrum pointed to by *data + */ +int xtract_spectral_variance(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the deviation of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to a double representing the spectral variance of the input spectrum + * \param *result: the deviation of the spectrum pointed to by *data + */ +int xtract_spectral_standard_deviation(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the average deviation of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to a double representing the spectral mean of the input spectrum + * \param *result: the average deviation of the spectrum pointed to by *data + */ +/* +int xtract_spectral_average_deviation(const double *data, const int N, const void *argv, double *result); +*/ + +/** \brief Extract the skewness of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to an array of doubles representing the spectral mean and spectral standard deviation of the input spectrum + * \param *result: the skewness of the spectrum pointed to by *data + */ +int xtract_spectral_skewness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the kurtosis of an input spectrum + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to an array of values representing the spectral mean and spectral standard deviation of the input spectrum + * \param *result: the kurtosis of the spectrum pointed to by *data + */ +int xtract_spectral_kurtosis(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the centroid of an input vector + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the centroid of the values pointed to by *data + * + * Note: for a more 'accurate' result *result from xtract_peak_spectrum() can be passed in. This gives the interpolated peak frequency locations. + * + */ +int xtract_spectral_centroid(const double *data, const int N, const void *argv, double *result); + +/** \brief Calculate the Irregularity of an input vector using a method described by Krimphoff (1994) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the irregularity of N values from the array pointed to by *data + */ +int xtract_irregularity_k(const double *data, const int N, const void *argv, double *result); + +/** \brief Calculate the Irregularity of an input vector using a method described by Jensen (1999) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the irregularity of N values from the array pointed to by *data + */ +int xtract_irregularity_j(const double *data, const int N, const void *argv, double *result); + +/** \brief Calculate the Tristimulus of an input vector using a method described by Pollard and Jansson (1982) + * + * \param *data: a pointer to the first element in an array of doubles representing a harmonic spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_harmonic_spectrum()) + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. + * \param *result: the tristimulus of N values from the array pointed to by *data + * + * These three functions provide the first, second and third order tristimulus formulae + * + */ +int xtract_tristimulus_1(const double *data, const int N, const void *argv, double *result); +int xtract_tristimulus_2(const double *data, const int N, const void *argv, double *result); +int xtract_tristimulus_3(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the smoothness of an input vector using a method described by McAdams (1999) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the smoothness of N values from the array pointed to by *data + */ +int xtract_smoothness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the spectral spread of an input vector using a method described by Casagrande(2005) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double corresponding to the spectral centroid + * \param *result: the spectral spread of N values from the array pointed to by *data + */ +int xtract_spread(const double *data, const int N, const void *argv, double *result); + +/* Zero crossing rate */ + +/** \brief Extract the zero crossing rate of an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the zero crossing rate of N values from the array pointed to by *data + */ +int xtract_zcr(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the spectral rolloff of an input vector using a method described by Bee Suan Ong (2005) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to an array containing a double representing (samplerate / N ) and a double representing the threshold for rolloff, i.e. the percentile at which the rolloff is determined, expressed as a percentage, and + * \param *result: the spectral rolloff in Hz of N values from the array pointed to by *data. This is the point in the spectrum below which argv[0] of the energy is distributed. + */ +int xtract_rolloff(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the 'total loudness' of an input vector using a method described by Moore, Glasberg et al (2005) + * + * \param *data: a pointer to the first element in an array of doubles representing a set of BARK_BANDS bark coefficients + * \param N: the number of coefficients to be considered + * \param *argv: a pointer to NULL + * \param *result: the total loudness of N values from the array pointed to by *data + * + * Note: if N = 1, the 'specific loudness' of the bark band pointed to by *data will be given by *result + * + */ +int xtract_loudness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the spectral flatness measure of an input vector, where the flatness measure (SFM) is defined as the ratio of the geometric mean to the arithmetic mean of a magnitude spectrum. + * + * \note The computation method used here is the most efficient by a significant margin, but suffers from precision problems due to the multiplication operationin the geometric mean calculation. This is particularly accute for larger values of N (>=256). However, as noted by Peeters (2003), the SFM should generally be computed on a small number of 'bands' rather than on the complete magnitude spectrum. It is therefore highly recommended that xtract_bands() is used prior to calling xtract_flatness(). + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). Alternatively the magnitudes from a number of 'subbands' can be used by using *result from xtract_bands(). + * \param N: the number of *data array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the flatness of N values from the array pointed to by *data + */ +int xtract_flatness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the LOG spectral flatness measure of an input vector + * + * \param *data: a pointer to NULL. + * \param N: not used - can safely be set to 0. + * \param *argv: a pointer to a double represnting spectral flatness. + * \param *result: the LOG spectral flatness of N values from the array pointed to by *data + * + * flatness_db = 10 * log10(flatness) + * + */ +int xtract_flatness_db(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the tonality factor of an input vector using a method described by Peeters 2003 + * + * \param *data: a pointer to NULL. + * \param N: not used - can safely be set to 0. + * \param *argv: a pointer to the LOG spectral flatness measure of an audio vector (e.g. the output from xtract_flatness_db) + * \param *result: the tonality factor of N values from the array pointed to by *data + */ +int xtract_tonality(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the noisiness of an input vector using a method described by Tae Hong Park (2000) + * + * \param *data: a pointer to NULL + * \param N: + * \param *argv: a pointer to an array containing a double represnting the number of harmonic partials in a spectrum, and a double representing the number of partials in a spectrum + * \param *result: the noisiness coefficient as calculated from argv + */ +int xtract_noisiness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the RMS amplitude of an input vector using a method described by Tae Hong Park (2000) + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the RMS amplitude of N values from the array pointed to by *data + */ +int xtract_rms_amplitude(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Inharmonicity of an input vector + * + * \param *data: a pointer to the first element in an array of doubles represeting a magnitude peak spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_peak_spectrum()) + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. + * \param *result: the inharmonicity of N values from the array pointed to by *data + */ +int xtract_spectral_inharmonicity(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the spectral crest of an input vector using a method described by Peeters (2003) + * + * \param *data: a pointer to NULL + * \param N: not used + * \param *argv: a pointer to an array containing a double representing the maximum value in a spectrum, and a double representing the mean value of a spectrum + * \param *result: the spectral crest of N values from the array pointed to by *data + */ +int xtract_crest(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Spectral Power of an input vector using a method described by Bee Suan Ong (2005) + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the spectral power of N values from the array pointed to by *data + */ +int xtract_power(const double *data, const int N, const void *argv, double *result); + +/* Odd to even harmonic ratio */ +/** \brief Extract the Odd to even harmonic ratio of an input vector + * + * \param *data: a pointer to the first element in an array of doubles representing a harmonic spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_harmonic_spectrum()) + * \param N: the number of elements to be considered. + * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. + * \param *result: the even/odd harmonic ratio of N values from the array pointed to by *data + */ +int xtract_odd_even_ratio(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Sharpness of an input vector + * + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the Sharpness of N values from the array pointed to by *data + */ +int xtract_sharpness(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Slope of an input vector using a method described by Peeters(2003) + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the Slope of N values from the array pointed to by *data + */ +int xtract_spectral_slope(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the value of the lowest value in an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the lower limit for the search. All values in the array pointed to by *data that are below or equal to this threshold will be ignored. + * \param *result: a pointer to a value representing the lowest component in *data that falls above a given threshold. + * + * \return XTRACT_SUCCESS is a lowest value was found or XTRACT_NO_VALUE if all values + * in the array pointed to by *data are below or equal to the threshold set with *argv + * + * \note If XTRACT_NO_VALUE is returned, *result will be set to DBL_MAX + * + */ +int xtract_lowest_value(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the value of the highest value in an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL. + * \param *result: a pointer to a value representing the highest component in *data. + * + */ +int xtract_highest_value(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the sum of the values in an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: a pointer to NULL. + * \param *result: a pointer to a value representing the sum of all of the values pointed to by *data. + * + */ +int xtract_sum(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Pitch of an input vector using Harmonic Product Spectrum (HPS) analysis + * + * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector (e.g. *result from xtract_spectrum). It is expected that the first half of the array pointed to by *data will contain amplitudes for each frequecy bin, and the second half will contain the respective frequencies + * \param N: The length of the vector pointed to by *data. + * \param *argv: a pointer to NULL + * \param *result: the pitch of N values from the array pointed to by *data + */ +int xtract_hps(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the fundamental frequency of an input vector + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the audio sample rate + * \param *result: the pitch of N values from the array pointed to by *data + * + * This algorithm is based on the AMDF, with peak and centre clipping. It would benefit from further improvements to improve noise robustness and overall efficiency + * + * It is based on suggestion by Robert Bristow-Johnson in a discussion on the comp.dsp mailing list, subject "Reference implementation of pitch detection" + * + */ +int xtract_f0(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the fundamental frequency of an input vector + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the audio sample rate + * \param *result: the pitch of N values from the array pointed to by *data + * + * This function wraps xtract_f0, but provides the frequency of the lowest partial in the peak spectrum if f0 can't be found. + * + */ +int xtract_failsafe_f0(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the fundamental frequency of an input vector using wavelet-based method + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of elements to be considered + * \param *argv: a pointer to a double representing the audio sample rate + * \param *result: the pitch of N values from the array pointed to by *data + * + * This function uses the time-domain wavelet-based method described in Larson and Maddox (2005) and + * implemented in the dywapitchtrack library + * + * xtract_init_wavelet_f0_state() must be called exactly once prior to calling xtract_wavelet_f0() + * + */ +int xtract_wavelet_f0(const double *data, const int N, const void *argv, double *result); + + +/** \brief Convenience function to convert a frequency in Hertz to a "pitch" value in MIDI cents + * + * \param *data: not used + * \param N: not used + * \param *argv: a pointer to a double-precision floating point value representing a frequency in Hertz + * \param *result: a pointer to a double-precision floating point value representing a "pitch" in MIDI cents + * \return if *argv value causes a *result within the range 0..127, XTRACT_SUCCESS will be returned, otherwise XTRACT_ARGUMENT_ERROR + * + */ +int xtract_midicent(const double *data, const int N, const void *argv, double *result); + + +/** \brief Extract the number of non-zero elements in an input vector + * + * \param *data: a pointer to the first element in an array of doubles + * \param N: the number of elements to be considered + * \param *argv: not used + * \param *result: the number of non-zero elements in the array pointed to by *data + * + */ +int xtract_nonzero_count(const double *data, const int N, const void *argv, double *result); + +/** + * \brief Return XTRACT_SUCCESS if the 'current' value is considered a peak + * + * @param data a pointer to an array containing time series as provided by *result from xtract_last_n() where the Nth value is considered the 'current' value + * @param N an integer representing the number of elements in the time series + * @param argv a pointer to a double representing the threshold, whereby the current value will be considered a peak if it is above the average of the last N values (*data) by the threshold + * @param result a pointer to a copy of the current value if the current value is considered a peak + * + * + * @return XTRACT_SUCCESS if a peak was found or XTRACT_NO_RESULT if not + */ +int xtract_peak(const double *data, const int N, const void *argv, double *result); + + +/** @} */ + +#ifdef __cplusplus +} +#endif + +#endif + + + diff --git a/include/xtract/xtract_stateful.h b/include/xtract/xtract_stateful.h new file mode 100644 index 0000000..6a5c900 --- /dev/null +++ b/include/xtract/xtract_stateful.h @@ -0,0 +1,66 @@ +/* + * 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. + * + */ + +/** \file xtract_stateful.h: declares functions that extract features that require stateful data to be retained between frames */ +#ifndef XTRACT_STATEFUL_H +#define XTRACT_STATEFUL_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup stateful feature extraction functions and data structures + * + * Functions that extract a feature over multiple frames + * + * @{ + */ + + +#include +#include + +typedef struct xtract_last_n_state_ xtract_last_n_state; + +xtract_last_n_state *xtract_last_n_state_new(size_t capacity); +void xtract_last_n_state_delete(xtract_last_n_state *last_n_state); + + +/** + * Write a vector of the last N input values to `result` + * + * @param state a pointer to an xtract_peak_picker_state struct as allocated by xtract_peak_picker_state_new() + * @param data a pointer to a double representing the current input value + * @param N an integer representing 'N' the number of values to be written to *result + * @param argv a pointer to NULL + * @param result a pointer to an array of doubles representing the last N values, where the nth value is the current one. The array must have been allocated to size N elements and initialised by the caller + * + */ +int xtract_last_n(const xtract_last_n_state *state, const double *data, const int N, const void *argv, double *result); + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/xtract/xtract_types.h b/include/xtract/xtract_types.h new file mode 100644 index 0000000..fe75b6e --- /dev/null +++ b/include/xtract/xtract_types.h @@ -0,0 +1,48 @@ +/* + * 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. + * + */ + +/* \file xtract_types.h: declares specialised variable types used by libxtract */ + +#ifndef XTRACT_TYPES_H +#define XTRACT_TYPES_H + +#ifdef __cplusplus +extern "C" { +#endif + +/* \brief Data structure used to store amplitude data between calls to xtract_attack_time and other functions. */ +typedef struct _xtract_amp_tracker { + int count; + double previous_amp; +} xtract_amp_tracker; + +typedef struct _xtract_frame_tracker { + int frame_count; + double *previous_frame; +} xtract_frame_tracker; + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/include/xtract/xtract_vector.h b/include/xtract/xtract_vector.h new file mode 100644 index 0000000..f935da6 --- /dev/null +++ b/include/xtract/xtract_vector.h @@ -0,0 +1,188 @@ +/* + * 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. + * + */ + +/** \file xtract_vector.h: declares functions that extract a feature as a vector from an input vector */ + +#ifndef XTRACT_VECTOR_H +#define XTRACT_VECTOR_H + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \defgroup vector vector extraction functions + * + * Functions that extract a feature as a vector from an input vector + * + * @{ + */ + +/** \brief Extract frequency domain spectrum from time domain signal + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to an array of doubles, the first representing (samplerate / N), the second will be cast to an integer and determines the spectrum type (e.g. XTRACT_MAGNITUDE_SPECTRUM, XTRACT_LOG_POWER_SPECTRUM). The third argument determines whether or not the DC component is included in the output. If argv[2] == 1, then the DC component is included in which case the size of the array pointed to by *result must be N+2. For any further use of the array pointed to by *result, the value of N must reflect the (larger) array size. The fourth argument determines whether the magnitude/power coefficients are to be normalised. If argv[3] == 1, then the coefficients are normalised. + * \param *result: a pointer to an array of size N containing N/2 magnitude/power/log magnitude/log power coefficients and N/2 bin frequencies. + * + * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1 + * + * \note Before calling xtract_spectrum(), the FFT must be initialised by calling xtract_init_fft(N, XTRACT_SPECTRUM) + * + */ +int xtract_spectrum(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract autocorrelation from time domain signal using FFT based method + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the autocorrelation of N values from the array pointed to by *data + */ +int xtract_autocorrelation_fft(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Mel Frequency Cepstral Coefficients based on a method described by Rabiner + * + * \param *data: a pointer to the first element in an array of spectral magnitudes, e.g. the first half of the array pointed to by *resul from xtract_spectrum() + * \param N: the number of array elements to be considered + * \param *argv: a pointer to a data structure of type xtract_mel_filter, containing n_filters coefficient tables to make up a mel-spaced filterbank + * \param *result: a pointer to an array containing the resultant MFCC + * + * The data structure pointed to by *argv must be obtained by first calling xtract_init_mfcc + */ +int xtract_mfcc(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the Discrete Cosine transform of a time domain signal + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: a pointer to an array containing resultant dct coefficients + */ +int xtract_dct(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract autocorrelation from time domain signal using time-domain autocorrelation technique + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the autocorrelation of N values from the array pointed to by *data + */ +int xtract_autocorrelation(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Average Magnitude Difference Function from time domain signal + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the AMDF of N values from the array pointed to by *data + */ +int xtract_amdf(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Average Squared Difference Function from time domain signal + * + * \param *data: a pointer to the first element in an array of doubles representing an audio vector + * \param N: the number of array elements to be considered + * \param *argv: a pointer to NULL + * \param *result: the ASDF of N values from the array pointed to by *data + */ +int xtract_asdf(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Bark band coefficients based on a method + * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of array elements to be considered + * \param *argv: a pointer to an array of ints representing the limits of each bark band. This can be obtained by calling xtract_init_bark. + * \param *result: a pointer to an array containing resultant bark coefficients + * + * The limits array pointed to by *argv must be obtained by first calling xtract_init_bark + * + */ +int xtract_bark_coefficients(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the amplitude and frequency of spectral peaks from a magnitude spectrum + * \param *data: a pointer to an array of size N containing N magnitude/power/log magnitude/log power coefficients. (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the size of the input array (note: it is assumed that enough memory has been allocated for an output array twice the size) + * \param *argv: a pointer to an array of doubles, the first representing (samplerate / N), the second representing the peak threshold as percentage of the magnitude of the maximum peak found + * \param *result: a pointer to an array of size N * 2 containing N magnitude/power/log magnitude/log power coefficients and N bin frequencies. + * + */ +int xtract_peak_spectrum(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract the harmonic spectrum of from a of a peak spectrum + * \param *data: a pointer to the first element in an array of doubles representing the peak spectrum of an audio vector (e.g. *result from xtract_peaks). It is expected that the first half of the array pointed to by *data will contain amplitudes for each peak considered, and the the second half will contain the respective frequencies + * \param N: the size of the array pointed to by *data + * \param *argv: a pointer to an array containing the fundamental (f0) of the spectrum, and a threshold (t) where 0<=t<=1.0, and t determines the distance from the nearest harmonic number within which a partial can be considered harmonic. + * \param *result: a pointer to an array of size N containing N/2 magnitude coefficients and N/2 bin frequencies. + */ +int xtract_harmonic_spectrum(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Linear Predictive Coding Coefficients + * + * Based on algorithm in Rabiner and Juang as implemented by Jutta Degener in Dr. Dobb's Journal December, 1994. + * + * Returns N-1 reflection (PARCOR) coefficients and N-1 LPC coefficients via *result + * + * \param *data: N autocorrelation values e.g the data pointed to by *result from xtract_autocorrelation() + * \param N: the number of autocorrelation values to be considered + * \param *argv: a pointer to NULL + * \param *result: a pointer to an array containing N-1 reflection coefficients and N-1 LPC coefficients. + * + * An array of size 2 * (N - 1) must be allocated, and *result must point to its first element. + */ +int xtract_lpc(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract Linear Predictive Coding Cepstral Coefficients + * + * \param *data: a pointer to the first element in an array of LPC coeffiecients e.g. a pointer to the second half of the array pointed to by *result from xtract_lpc() + * \param N: the number of LPC coefficients to be considered + * \param *argv: a pointer to a double representing the order of the result vector. This must be a whole number. According to Rabiner and Juang the ratio between the number (p) of LPC coefficients and the order (Q) of the LPC cepstrum is given by Q ~ (3/2)p where Q > p. + * \param *result: a pointer to an array containing the resultant LPCC. + * + * An array of size Q, where Q is given by argv[0] must be allocated, and *result must point to its first element. + * + */ +int xtract_lpcc(const double *data, const int N, const void *argv, double *result); + +/** \brief Extract subbands from a spectrum + * + * \param *data: a pointer to an array of size N containing N magnitude/power/log magnitude/log power coefficients. (e.g. the first half of the array pointed to by *result from xtract_spectrum(). + * \param N: the number of elements from the array pointed to by *data to be considered + * \param *argv: A pointer to an array containing four integers. The first represents the extraction function to applied to each subband e.g. XTRACT_SUM or XTRACT_MEAN, the second represents the number of subbands required, and the third represents the frequency scale to be used for the subband bounds as defined in the enumeration xtract_subband_scales_ (libxtract.h). The fourth integer represent the start point of the subbands as a location in the input array as pointed to by *data (e.g. a value of 5 would start the subband extraction at bin 5) + * \param *result: A pointer to an array containing the resultant subband values. The calling function is responsible for allocating and freeing memory for *result. xtract_subbands() assumes that at least argv[1] * sizeof(double) bytes have been allocated. If the requested nbands extends the subband range beyond N, then the remaining bands will be set to 0. If the array pointed to by *result has more than argv[1] elements, the superfluous elements will be unchanged. + * + * xtract_subbands() divides a spectrum into subbands and applies the function given by argv[0] to the values in each subband to give a 'reduced' representation of the spectrum as *result + * + * Specifying XTRACT_OCTAVE_SUBBANDS will extract subbands at each octave from the start bin until argv[1] is reached or N is reached + * Specifying XTRACT_LINEAR_SUBBANDS will extract argv[1] equal sized subbands between the start bin and N + * + * + * It is assumed that a sensible function will be given in argv[0], and for this function argv will always be NULL. Sensible values for argv[0] are XTRACT_MEAN and XTRACT_SUM, although something like XTRACT_IRREGULARITY_K might yield interesting results. + * + */ +int xtract_subbands(const double *data, const int N, const void *argv, double *result); +/** @} */ + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/xtract/libxtract.h b/xtract/libxtract.h deleted file mode 100644 index 17540c5..0000000 --- a/xtract/libxtract.h +++ /dev/null @@ -1,440 +0,0 @@ -/* - * 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. - * - */ - -/** \mainpage - * - * LibXtract is a simple, portable, lightweight library of audio feature extraction functions. The purpose of the library is to provide a relatively exhaustive set of feature extraction primatives that are designed to be 'cascaded' to create a extraction hierarchies. - * For example, 'variance', 'average deviation', 'skewness' and 'kurtosis', all require the 'mean' of the input vector to be precomputed. However, rather than compute the 'mean' 'inside' each function, it is expected that the 'mean' will be passed in as an argument. This means that if the user wishes to use all of these features, the mean is calculated only once, and then passed to any functions that require it. - * - * This philosophy of 'cascading' features is followed throughout the library, for example with features that operate on the magnitude spectrum of a signal vector (e.g. 'irregularity'), the magnitude spectrum is not calculated 'inside' the respective function, instead, a pointer to the first element in an array containing the magnitude spectrum is passed in as an argument. - * - * Hopefully this not only makes the library more efficient when computing large numbers of features, but also makes it more flexible because extraction functions can be combined arbitrarily (one can take the irregularility of the Mel Frequency Cepstral Coefficients for example). - * - * All feature extraction functions follow the same prototype: - * - * **int xtract_function_name(const double *data, const int N, const void *argv, double *result);** - * - * \param const double *data points to an array of doubles representing the input data - * \param const int N represents the number of elementes from *data to be considered in the calculation - * \param const void *argv represents an arbitrary list of arguments. Used to pass in values required by the feature calculation - * \param double *result points to an array of doubles, or a single double represnting the result of the calculation - * - * - * It is up to the calling function to allocate enough memory for the *data, *argv, and *result, and to free it when required. Some feature extraction functions may also require an _init() function to be called in order to perform some initialisation. The struct xtract_function_descriptor_t is used to give an indication of recommended default values, and argc for the *argv array. - * - * LibXtract can be downloaded from http://www.sf.net/projects/libxtract - * - */ - -#ifndef XTRACT_H -#define XTRACT_H - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \file libxtract.h - * \brief main header file and API definition - */ - -#include "xtract_scalar.h" -#include "xtract_vector.h" -#include "xtract_delta.h" -#include "xtract_types.h" -#include "xtract_macros.h" -#include "xtract_helper.h" - -/** \defgroup libxtract API - * - * Defines a very simple API that provides access to the functions in the library - * @{ - */ - -#define XTRACT_FEATURES 62 - -/** \brief Enumeration of features, elements are used as indixes to an array of pointers to feature extracton functions */ -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 -}; - -/** \brief Enumeration of feature initialisation functions */ -enum xtract_feature_init_ { - XTRACT_INIT_MFCC = 100, - XTRACT_INIT_BARK, - XTRACT_INIT_WINDOWED -}; - -/** \brief Enumeration of feature types */ -enum xtract_feature_types_ { - XTRACT_SCALAR, - XTRACT_VECTOR, - XTRACT_DELTA -}; - -/** \brief Enumeration of mfcc types */ -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 -}; - -/** \brief Enumeration of return codes */ -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 -}; - -/** \brief Enumeration of spectrum types */ -enum xtract_spectrum_ { - XTRACT_MAGNITUDE_SPECTRUM, - XTRACT_LOG_MAGNITUDE_SPECTRUM, - XTRACT_POWER_SPECTRUM, - XTRACT_LOG_POWER_SPECTRUM -}; - -/** \brief Subband scales */ -enum xtract_subband_scales_ { - XTRACT_OCTAVE_SUBBANDS, - XTRACT_LINEAR_SUBBANDS -}; - -/** \brief Enumeration of data types*/ -typedef enum type_ { - XTRACT_FLOAT, - XTRACT_FLOATARRAY, - XTRACT_INT, - XTRACT_MEL_FILTER -} xtract_type_t; - -/** \brief Enumeration of units*/ -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; - -/** \brief Boolean */ -typedef enum { - XTRACT_FALSE, - XTRACT_TRUE -} xtract_bool_t; - -/** \brief Window types */ -enum xtract_window_types_ { - XTRACT_GAUSS, - XTRACT_HAMMING, - XTRACT_HANN, - XTRACT_BARTLETT, - XTRACT_TRIANGULAR, - XTRACT_BARTLETT_HANN, - XTRACT_BLACKMAN, - XTRACT_KAISER, - XTRACT_BLACKMAN_HARRIS -}; - -/** \brief Enumeration of vector format types*/ -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; - -/** \brief Data structure containing useful information about functions provided by LibXtract. */ -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; - -/** - * - * \brief An array of pointers to functions that perform the extraction - * - * \param *data: a pointer to the start of the input data (usually the first element in an array) - * - * \param N: the number of elements to be processed - * - * \param *argv: an abitrary number of additional arguments, used to pass additional parameters to the function being called. All arguments are compulsary! - * - * \param *result: a pointer to the first element in the result - * - * Each function will iterate over N array elements, the first of which is - * pointed to by *data. It is up to the calling function to ensure that the array is in the format expected by the function being called. - * - * For scalar and delta features, *result will point to a single value. - * - * For vector features it will point to the first element in an array. - * - * Memory for this array must be allocated and freed by the calling - * function. - * - * All functions return an integer error code as descibed in the enumeration - * return_codes_ - * - * The preprocessor macro: XTRACT must be defined before this can be used - * - * example:
- * \verbatim -#include -#define XTRACT -#include "libxtract.h" - -main () { -double values[] = {1.0, 2.0, 3.0, 4.0, 5.0}; -int N = 5; -double mean; - -xtract[MEAN]((void *)values, N, NULL, &mean); - -printf("Mean = %.2f\n", mean); -} -\endverbatim - * The calling function may additionally make some tests against the value returned by xtract - * - */ -#ifdef XTRACT_H -extern int(*xtract[XTRACT_FEATURES])(const double *data, const int N, const void *argv, double *result); - -#endif - -/** \brief A function to initialise wavelet f0 detector state */ -int xtract_init_wavelet_f0_state(void); - -/** \brief A structure to store a set of n_filters Mel filters */ -typedef struct xtract_mel_filter_ { - int n_filters; - double **filters; -} xtract_mel_filter; - -/** \brief A function to initialise a mel filter bank - * - * It is up to the caller to pass in a pointer to memory allocated for freq_bands arrays of length N. This function populates these arrays with magnitude coefficients representing the mel filterbank on a linear scale - */ -int xtract_init_mfcc(int N, double nyquist, int style, double freq_min, double freq_max, int freq_bands, double **fft_tables); - -/** \brief A function to initialise bark filter bounds - * - * A pointer to an array of BARK_BANDS ints most be passed in, and is populated with BARK_BANDS fft bin numbers representing the limits of each band - * - * \param N: the audio block size - * \param sr: The sample audio sample rate - * \param *band_limits: a pointer to an array of BARK_BANDS ints - */ -int xtract_init_bark(int N, double sr, int *band_limits); - -/** \brief An initialisation function for functions using FFT - * - * This function initialises global data structures used by functions requiring FFT functionality. It can be called multiple times with different feature names. Calling it more than once with the same feature name is not a valid operation and will result in a memory leak. - * - * \param N: the size of the FFT - * \param feature_name: the name of the feature the FFT is being used for, - * e.g. XTRACT_DCT - * - */ -int xtract_init_fft(int N, int feature_name); - -/** \brief Free memory used for fft plans - * - * This function should be used to explicitly free memory allocated for ffts by xtract_init_fft(). It is primarily intended for use if a new FFT needs to be taken with a different blocksize. If only one fft size is required then there is no need to call this function since it will be called when the program exits. - * */ -void xtract_free_fft(void); - -/** \brief Make a window of a given type and return a pointer to it - * - * \param N: the size of the window - * \param type: the type of the window as given in the enumeration window_types_ - * - */ -double *xtract_init_window(const int N, const int type); - -/** \brief Free a window as allocated by xtract_make_window() - * - * \param *window: a pointer to an array of doubles as allocated by xtract_make_window() - * - */ -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 diff --git a/xtract/xtract_delta.h b/xtract/xtract_delta.h deleted file mode 100644 index c7b3ee7..0000000 --- a/xtract/xtract_delta.h +++ /dev/null @@ -1,88 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_delta.h: declares functions that scalar or vector value from 2 or more input vectors */ - -#ifndef XTRACT_DELTA_H -#define XTRACT_DELTA_H - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \defgroup delta `delta' extraction functions - * - * Functions that extract a scalar or vector value from 2 or more input vectors - * - * @{ - */ - -#include "xtract_types.h" - -/** \brief Extract flux - * - * \note FIX: don't be lazy -- take the lnorm of the difference vector! - * An alias for xtract_lnorm() - */ -int xtract_flux(const double *data, const int N, const void *argv , double *result); - -/** \brief Extract the L-norm of a vector - * - * \param *data: a pointer to the first element in an array of doubles representing the difference between two subsequent frames of output from a vector-based feature e.g. the *result from xtract_difference_vector() - * \param N: the length of the array pointed to by *data - * \param *argv: a pointer to an array of doubles, the first representing the "norm order". The second argument represents the filter type determining what values we consider from the difference vector as given in the enumeration xtract_lnorm_filter_types_ (libxtract.h), the third sets whether we want the result to be normalised in the range 0-1 (0 = no normalise, 1 = normalise) - * \param *result: a pointer to a double representing the flux - * - */ -int xtract_lnorm(const double *data, const int N, const void *argv , double *result); -/*xtract_frame_tracker *xf */ - -/** \brief Extract attack Time */ -int xtract_attack_time(const double *data, const int N, const void *argv , double *result); -/* xtract_amp_tracker *xa */ - -/** Extract temporal decrease */ -int xtract_decay_time(const double *data, const int N, const void *argv, double *result); -/* xtract_amp_tracker *xa */ - - -/** \brief Extract the difference between two vectors - * - * \param *data a pointer to an array representing two distinct vectors, e.g. two successive magnitude spectra. - * \param N the size of the array pointed to by *data - * \param *argv a pointer to NULL - * \param *result a pointer to an array of size N / 2 representing the difference between the two input vectors. - * - * */ -int xtract_difference_vector(const double *data, const int N, const void *argv, double *result); -/*xtract_frame_tracker *xf */ -/*double frames*/ - -/** @} */ - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/xtract/xtract_helper.h b/xtract/xtract_helper.h deleted file mode 100644 index 7296f0e..0000000 --- a/xtract/xtract_helper.h +++ /dev/null @@ -1,109 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_helper.h: helper functions for making life with libxtract a bit more bearable */ - -#ifndef XTRACT_HELPER_H -#define XTRACT_HELPER_H - -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef _MSC_VER - #ifndef __cplusplus - typedef int bool; - #define false 0 - #define true 1 - #endif -#else - #include -#endif - - -/** - * \defgroup helper helper functions - * - * Declares helper functions, and their parameters. - * - * \note These functions don't necessarily conform to the prototype used in xtract_scalar.h and xtract_vector.h etc, and as such are intended to be called 'directly' rather than via the xtract[] function pointer array (libxtract.h) - * - * @{ - */ - -/** \brief Apply a window function to an array of length N - * - * \param *data a pointer to an array of doubles - * \param N the number of elements in the array pointed to by *data - * \param *argv a pointer to a window function as returned by xtract_make_window() - * \param *result a pointer to the first element an array containing the windowed data - * - * It is up to the caller to generate and free the array containing the window, and to allocate and free memory of size N to hold the data pointed to by *result - * - */ -int xtract_windowed(const double *data, const int N, const void *argv, double *result); - -/** \brief Divides the array pointed to by *data into two subframes, and applies a given feature to each subframe, returning them in a single array pointed to by result - * - * \param *data an array of doubles - * \param N the number of elements in the array pointed by *data - * \param feature an integer representing the feature to be applied to each subframe in data. This will be a value as given in the enumeration xtract_features_ (libxtract.h) - * \param *argv a pointer to the argument vector to be passed to the feature extraction function as determined by feature - * \param *result a pointer to the 'packed' results of the feature calculation. This may be passed in as *data to xtract_features_from_subframes() to calculate further features on the subframes, or xtract_difference_vector(), to get the difference between the subframes. - * - * - * It is important to ensure that any _init_*() functions that are called in preparation for functions that are called on subframes are given the subframe size as 'N', and not the frame size. i.e. if xtract_features_from_subframes() is called with N=64, and feature=XTRACT_SPECTRUM, then xtract_init_fft() should be called with N=32. - * - */ -int xtract_features_from_subframes(const double *data, const int N, const int feature, const void *argv, double *result); - -/** \brief Test whether a number is denormal */ -int xtract_is_denormal(double const d); - -/** \brief Test whether a number is a power of two */ -bool xtract_is_poweroftwo(unsigned int x); - - -/** \brief Smooth a vector - * - * \param *data a pointer to an array of doubles - * \param N the number of elements in the array pointed to by *data to be smoothed - * \param *argv a pointer to a double giving the smoothing gain - * \param *result a pointer to the first element an array containing the smoothed data - * - * \note if passing in a spectrum e.g. *result from xtract_spectrum(), then N for xtract_smoothed() should be N / 2 with respect to the N for xtract_spectrum() so only amplitude components are smoothed, not frequencies! - * - */ - int xtract_smoothed(const double *data, const int N, const void *argv, double *result); - - -/** @} */ - -#ifdef __cplusplus -} -#endif - -#endif - - - diff --git a/xtract/xtract_macros.h b/xtract/xtract_macros.h deleted file mode 100644 index 3445866..0000000 --- a/xtract/xtract_macros.h +++ /dev/null @@ -1,47 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_macros.h: defines useful public macros */ - -#ifndef XTRACT_MACROS_H -#define XTRACT_MACROS_H - -#ifdef __cplusplus -extern "C" { -#endif - -#define XTRACT_BARK_BANDS 26 -#define XTRACT_WINDOW_SIZE 1024/* dummy macro for descriptors where argc is window size */ -#define XTRACT_NONE 0 -#define XTRACT_ANY -1 -#define XTRACT_UNKNOWN -2 -#define XTRACT_MAXARGS 4 -#define XTRACT_MAX_NAME_LENGTH 64 -#define XTRACT_MAX_AUTHOR_LENGTH 128 -#define XTRACT_MAX_DESC_LENGTH 256 - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/xtract/xtract_scalar.h b/xtract/xtract_scalar.h deleted file mode 100644 index 8e24284..0000000 --- a/xtract/xtract_scalar.h +++ /dev/null @@ -1,483 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_scalar.h: declares functions that extract a feature as a single value from an input vector */ - -#ifndef XTRACT_SCALAR_H -#define XTRACT_SCALAR_H - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \defgroup scalar scalar extraction functions - * - * Functions that extract a feature as a single value from an input vector - * - * @{ - */ - -/** \brief Extract the mean of an input vector - * - * \param *data: a pointer to the first element - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the mean of N values from the array pointed to by *data - */ -int xtract_mean(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the variance of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the mean of the input vector - * \param *result: the variance of N values from the array pointed to by *data - */ -int xtract_variance(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the deviation of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the variance of the input vector - * \param *result: the deviation of N values from the array pointed to by *data - */ -int xtract_standard_deviation(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the average deviation of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the mean of the input vector - * \param *result: the average deviation of N values from the array pointed to by *data - */ -int xtract_average_deviation(const double *data, const int N, const void *argv, double *result); - - -/** \brief Extract the skewness of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to an array of doubles representing the mean and standard deviation of the input vector - * \param *result: the skewness of N values from the array pointed to by *data - */ -int xtract_skewness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the kurtosis of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to an array of values representing the mean and standard deviation of the input vector - * \param *result: the kurtosis of N values from the array pointed to by *data - */ -int xtract_kurtosis(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the mean of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to NULL - * \param *result: the mean of the spectrum pointed to by *data - */ -int xtract_spectral_mean(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the variance of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the number of elements to be considered - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to a double representing the spectral mean of the input spectrum - * \param *result: the variance of the spectrum pointed to by *data - */ -int xtract_spectral_variance(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the deviation of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to a double representing the spectral variance of the input spectrum - * \param *result: the deviation of the spectrum pointed to by *data - */ -int xtract_spectral_standard_deviation(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the average deviation of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to a double representing the spectral mean of the input spectrum - * \param *result: the average deviation of the spectrum pointed to by *data - */ -/* -int xtract_spectral_average_deviation(const double *data, const int N, const void *argv, double *result); -*/ - -/** \brief Extract the skewness of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to an array of doubles representing the spectral mean and spectral standard deviation of the input spectrum - * \param *result: the skewness of the spectrum pointed to by *data - */ -int xtract_spectral_skewness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the kurtosis of an input spectrum - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to an array of values representing the spectral mean and spectral standard deviation of the input spectrum - * \param *result: the kurtosis of the spectrum pointed to by *data - */ -int xtract_spectral_kurtosis(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the centroid of an input vector - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the centroid of the values pointed to by *data - * - * Note: for a more 'accurate' result *result from xtract_peak_spectrum() can be passed in. This gives the interpolated peak frequency locations. - * - */ -int xtract_spectral_centroid(const double *data, const int N, const void *argv, double *result); - -/** \brief Calculate the Irregularity of an input vector using a method described by Krimphoff (1994) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the irregularity of N values from the array pointed to by *data - */ -int xtract_irregularity_k(const double *data, const int N, const void *argv, double *result); - -/** \brief Calculate the Irregularity of an input vector using a method described by Jensen (1999) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the irregularity of N values from the array pointed to by *data - */ -int xtract_irregularity_j(const double *data, const int N, const void *argv, double *result); - -/** \brief Calculate the Tristimulus of an input vector using a method described by Pollard and Jansson (1982) - * - * \param *data: a pointer to the first element in an array of doubles representing a harmonic spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_harmonic_spectrum()) - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. - * \param *result: the tristimulus of N values from the array pointed to by *data - * - * These three functions provide the first, second and third order tristimulus formulae - * - */ -int xtract_tristimulus_1(const double *data, const int N, const void *argv, double *result); -int xtract_tristimulus_2(const double *data, const int N, const void *argv, double *result); -int xtract_tristimulus_3(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the smoothness of an input vector using a method described by McAdams (1999) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the smoothness of N values from the array pointed to by *data - */ -int xtract_smoothness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the spectral spread of an input vector using a method described by Casagrande(2005) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double corresponding to the spectral centroid - * \param *result: the spectral spread of N values from the array pointed to by *data - */ -int xtract_spread(const double *data, const int N, const void *argv, double *result); - -/* Zero crossing rate */ - -/** \brief Extract the zero crossing rate of an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the zero crossing rate of N values from the array pointed to by *data - */ -int xtract_zcr(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the spectral rolloff of an input vector using a method described by Bee Suan Ong (2005) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to an array containing a double representing (samplerate / N ) and a double representing the threshold for rolloff, i.e. the percentile at which the rolloff is determined, expressed as a percentage, and - * \param *result: the spectral rolloff in Hz of N values from the array pointed to by *data. This is the point in the spectrum below which argv[0] of the energy is distributed. - */ -int xtract_rolloff(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the 'total loudness' of an input vector using a method described by Moore, Glasberg et al (2005) - * - * \param *data: a pointer to the first element in an array of doubles representing a set of BARK_BANDS bark coefficients - * \param N: the number of coefficients to be considered - * \param *argv: a pointer to NULL - * \param *result: the total loudness of N values from the array pointed to by *data - * - * Note: if N = 1, the 'specific loudness' of the bark band pointed to by *data will be given by *result - * - */ -int xtract_loudness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the spectral flatness measure of an input vector, where the flatness measure (SFM) is defined as the ratio of the geometric mean to the arithmetic mean of a magnitude spectrum. - * - * \note The computation method used here is the most efficient by a significant margin, but suffers from precision problems due to the multiplication operationin the geometric mean calculation. This is particularly accute for larger values of N (>=256). However, as noted by Peeters (2003), the SFM should generally be computed on a small number of 'bands' rather than on the complete magnitude spectrum. It is therefore highly recommended that xtract_bands() is used prior to calling xtract_flatness(). - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). Alternatively the magnitudes from a number of 'subbands' can be used by using *result from xtract_bands(). - * \param N: the number of *data array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the flatness of N values from the array pointed to by *data - */ -int xtract_flatness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the LOG spectral flatness measure of an input vector - * - * \param *data: a pointer to NULL. - * \param N: not used - can safely be set to 0. - * \param *argv: a pointer to a double represnting spectral flatness. - * \param *result: the LOG spectral flatness of N values from the array pointed to by *data - * - * flatness_db = 10 * log10(flatness) - * - */ -int xtract_flatness_db(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the tonality factor of an input vector using a method described by Peeters 2003 - * - * \param *data: a pointer to NULL. - * \param N: not used - can safely be set to 0. - * \param *argv: a pointer to the LOG spectral flatness measure of an audio vector (e.g. the output from xtract_flatness_db) - * \param *result: the tonality factor of N values from the array pointed to by *data - */ -int xtract_tonality(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the noisiness of an input vector using a method described by Tae Hong Park (2000) - * - * \param *data: a pointer to NULL - * \param N: - * \param *argv: a pointer to an array containing a double represnting the number of harmonic partials in a spectrum, and a double representing the number of partials in a spectrum - * \param *result: the noisiness coefficient as calculated from argv - */ -int xtract_noisiness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the RMS amplitude of an input vector using a method described by Tae Hong Park (2000) - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the RMS amplitude of N values from the array pointed to by *data - */ -int xtract_rms_amplitude(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Inharmonicity of an input vector - * - * \param *data: a pointer to the first element in an array of doubles represeting a magnitude peak spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_peak_spectrum()) - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. - * \param *result: the inharmonicity of N values from the array pointed to by *data - */ -int xtract_spectral_inharmonicity(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the spectral crest of an input vector using a method described by Peeters (2003) - * - * \param *data: a pointer to NULL - * \param N: not used - * \param *argv: a pointer to an array containing a double representing the maximum value in a spectrum, and a double representing the mean value of a spectrum - * \param *result: the spectral crest of N values from the array pointed to by *data - */ -int xtract_crest(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Spectral Power of an input vector using a method described by Bee Suan Ong (2005) - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the spectral power of N values from the array pointed to by *data - */ -int xtract_power(const double *data, const int N, const void *argv, double *result); - -/* Odd to even harmonic ratio */ -/** \brief Extract the Odd to even harmonic ratio of an input vector - * - * \param *data: a pointer to the first element in an array of doubles representing a harmonic spectrum of size N/2, and a frequency spectrum of size N/2 (This is the output format of xtract_harmonic_spectrum()) - * \param N: the number of elements to be considered. - * \param *argv: a pointer to a double representing the fundamental frequency of the input vector. - * \param *result: the even/odd harmonic ratio of N values from the array pointed to by *data - */ -int xtract_odd_even_ratio(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Sharpness of an input vector - * - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the Sharpness of N values from the array pointed to by *data - */ -int xtract_sharpness(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Slope of an input vector using a method described by Peeters(2003) - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector, (e.g. the array pointed to by *result from xtract_spectrum(), xtract_peak_spectrum() or xtract_harmonic_spectrum()). - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the Slope of N values from the array pointed to by *data - */ -int xtract_spectral_slope(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the value of the lowest value in an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the lower limit for the search. All values in the array pointed to by *data that are below or equal to this threshold will be ignored. - * \param *result: a pointer to a value representing the lowest component in *data that falls above a given threshold. - * - * \return XTRACT_SUCCESS is a lowest value was found or XTRACT_NO_VALUE if all values - * in the array pointed to by *data are below or equal to the threshold set with *argv - * - * \note If XTRACT_NO_VALUE is returned, *result will be set to DBL_MAX - * - */ -int xtract_lowest_value(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the value of the highest value in an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL. - * \param *result: a pointer to a value representing the highest component in *data. - * - */ -int xtract_highest_value(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the sum of the values in an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: a pointer to NULL. - * \param *result: a pointer to a value representing the sum of all of the values pointed to by *data. - * - */ -int xtract_sum(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Pitch of an input vector using Harmonic Product Spectrum (HPS) analysis - * - * \param *data: a pointer to the first element in an array of doubles representing the spectrum of an audio vector (e.g. *result from xtract_spectrum). It is expected that the first half of the array pointed to by *data will contain amplitudes for each frequecy bin, and the second half will contain the respective frequencies - * \param N: The length of the vector pointed to by *data. - * \param *argv: a pointer to NULL - * \param *result: the pitch of N values from the array pointed to by *data - */ -int xtract_hps(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the fundamental frequency of an input vector - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the audio sample rate - * \param *result: the pitch of N values from the array pointed to by *data - * - * This algorithm is based on the AMDF, with peak and centre clipping. It would benefit from further improvements to improve noise robustness and overall efficiency - * - * It is based on suggestion by Robert Bristow-Johnson in a discussion on the comp.dsp mailing list, subject "Reference implementation of pitch detection" - * - */ -int xtract_f0(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the fundamental frequency of an input vector - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the audio sample rate - * \param *result: the pitch of N values from the array pointed to by *data - * - * This function wraps xtract_f0, but provides the frequency of the lowest partial in the peak spectrum if f0 can't be found. - * - */ -int xtract_failsafe_f0(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the fundamental frequency of an input vector using wavelet-based method - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of elements to be considered - * \param *argv: a pointer to a double representing the audio sample rate - * \param *result: the pitch of N values from the array pointed to by *data - * - * This function uses the time-domain wavelet-based method described in Larson and Maddox (2005) and - * implemented in the dywapitchtrack library - * - * xtract_init_wavelet_f0_state() must be called exactly once prior to calling xtract_wavelet_f0() - * - */ -int xtract_wavelet_f0(const double *data, const int N, const void *argv, double *result); - - -/** \brief Convenience function to convert a frequency in Hertz to a "pitch" value in MIDI cents - * - * \param *data: not used - * \param N: not used - * \param *argv: a pointer to a double-precision floating point value representing a frequency in Hertz - * \param *result: a pointer to a double-precision floating point value representing a "pitch" in MIDI cents - * \return if *argv value causes a *result within the range 0..127, XTRACT_SUCCESS will be returned, otherwise XTRACT_ARGUMENT_ERROR - * - */ -int xtract_midicent(const double *data, const int N, const void *argv, double *result); - - -/** \brief Extract the number of non-zero elements in an input vector - * - * \param *data: a pointer to the first element in an array of doubles - * \param N: the number of elements to be considered - * \param *argv: not used - * \param *result: the number of non-zero elements in the array pointed to by *data - * - */ -int xtract_nonzero_count(const double *data, const int N, const void *argv, double *result); - -/** - * \brief Return XTRACT_SUCCESS if the 'current' value is considered a peak - * - * @param data a pointer to an array containing time series as provided by *result from xtract_last_n() where the Nth value is considered the 'current' value - * @param N an integer representing the number of elements in the time series - * @param argv a pointer to a double representing the threshold, whereby the current value will be considered a peak if it is above the average of the last N values (*data) by the threshold - * @param result a pointer to a copy of the current value if the current value is considered a peak - * - * - * @return XTRACT_SUCCESS if a peak was found or XTRACT_NO_RESULT if not - */ -int xtract_peak(const double *data, const int N, const void *argv, double *result); - - -/** @} */ - -#ifdef __cplusplus -} -#endif - -#endif - - - diff --git a/xtract/xtract_stateful.h b/xtract/xtract_stateful.h deleted file mode 100644 index 6a5c900..0000000 --- a/xtract/xtract_stateful.h +++ /dev/null @@ -1,66 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_stateful.h: declares functions that extract features that require stateful data to be retained between frames */ -#ifndef XTRACT_STATEFUL_H -#define XTRACT_STATEFUL_H - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \defgroup stateful feature extraction functions and data structures - * - * Functions that extract a feature over multiple frames - * - * @{ - */ - - -#include -#include - -typedef struct xtract_last_n_state_ xtract_last_n_state; - -xtract_last_n_state *xtract_last_n_state_new(size_t capacity); -void xtract_last_n_state_delete(xtract_last_n_state *last_n_state); - - -/** - * Write a vector of the last N input values to `result` - * - * @param state a pointer to an xtract_peak_picker_state struct as allocated by xtract_peak_picker_state_new() - * @param data a pointer to a double representing the current input value - * @param N an integer representing 'N' the number of values to be written to *result - * @param argv a pointer to NULL - * @param result a pointer to an array of doubles representing the last N values, where the nth value is the current one. The array must have been allocated to size N elements and initialised by the caller - * - */ -int xtract_last_n(const xtract_last_n_state *state, const double *data, const int N, const void *argv, double *result); - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/xtract/xtract_types.h b/xtract/xtract_types.h deleted file mode 100644 index fe75b6e..0000000 --- a/xtract/xtract_types.h +++ /dev/null @@ -1,48 +0,0 @@ -/* - * 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. - * - */ - -/* \file xtract_types.h: declares specialised variable types used by libxtract */ - -#ifndef XTRACT_TYPES_H -#define XTRACT_TYPES_H - -#ifdef __cplusplus -extern "C" { -#endif - -/* \brief Data structure used to store amplitude data between calls to xtract_attack_time and other functions. */ -typedef struct _xtract_amp_tracker { - int count; - double previous_amp; -} xtract_amp_tracker; - -typedef struct _xtract_frame_tracker { - int frame_count; - double *previous_frame; -} xtract_frame_tracker; - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/xtract/xtract_vector.h b/xtract/xtract_vector.h deleted file mode 100644 index f935da6..0000000 --- a/xtract/xtract_vector.h +++ /dev/null @@ -1,188 +0,0 @@ -/* - * 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. - * - */ - -/** \file xtract_vector.h: declares functions that extract a feature as a vector from an input vector */ - -#ifndef XTRACT_VECTOR_H -#define XTRACT_VECTOR_H - -#ifdef __cplusplus -extern "C" { -#endif - -/** - * \defgroup vector vector extraction functions - * - * Functions that extract a feature as a vector from an input vector - * - * @{ - */ - -/** \brief Extract frequency domain spectrum from time domain signal - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to an array of doubles, the first representing (samplerate / N), the second will be cast to an integer and determines the spectrum type (e.g. XTRACT_MAGNITUDE_SPECTRUM, XTRACT_LOG_POWER_SPECTRUM). The third argument determines whether or not the DC component is included in the output. If argv[2] == 1, then the DC component is included in which case the size of the array pointed to by *result must be N+2. For any further use of the array pointed to by *result, the value of N must reflect the (larger) array size. The fourth argument determines whether the magnitude/power coefficients are to be normalised. If argv[3] == 1, then the coefficients are normalised. - * \param *result: a pointer to an array of size N containing N/2 magnitude/power/log magnitude/log power coefficients and N/2 bin frequencies. - * - * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1 - * - * \note Before calling xtract_spectrum(), the FFT must be initialised by calling xtract_init_fft(N, XTRACT_SPECTRUM) - * - */ -int xtract_spectrum(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract autocorrelation from time domain signal using FFT based method - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the autocorrelation of N values from the array pointed to by *data - */ -int xtract_autocorrelation_fft(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Mel Frequency Cepstral Coefficients based on a method described by Rabiner - * - * \param *data: a pointer to the first element in an array of spectral magnitudes, e.g. the first half of the array pointed to by *resul from xtract_spectrum() - * \param N: the number of array elements to be considered - * \param *argv: a pointer to a data structure of type xtract_mel_filter, containing n_filters coefficient tables to make up a mel-spaced filterbank - * \param *result: a pointer to an array containing the resultant MFCC - * - * The data structure pointed to by *argv must be obtained by first calling xtract_init_mfcc - */ -int xtract_mfcc(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the Discrete Cosine transform of a time domain signal - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: a pointer to an array containing resultant dct coefficients - */ -int xtract_dct(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract autocorrelation from time domain signal using time-domain autocorrelation technique - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the autocorrelation of N values from the array pointed to by *data - */ -int xtract_autocorrelation(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Average Magnitude Difference Function from time domain signal - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the AMDF of N values from the array pointed to by *data - */ -int xtract_amdf(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Average Squared Difference Function from time domain signal - * - * \param *data: a pointer to the first element in an array of doubles representing an audio vector - * \param N: the number of array elements to be considered - * \param *argv: a pointer to NULL - * \param *result: the ASDF of N values from the array pointed to by *data - */ -int xtract_asdf(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Bark band coefficients based on a method - * \param *data: a pointer to the first element in an array of doubles representing the magnitude coefficients from the magnitude spectrum of an audio vector, (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of array elements to be considered - * \param *argv: a pointer to an array of ints representing the limits of each bark band. This can be obtained by calling xtract_init_bark. - * \param *result: a pointer to an array containing resultant bark coefficients - * - * The limits array pointed to by *argv must be obtained by first calling xtract_init_bark - * - */ -int xtract_bark_coefficients(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the amplitude and frequency of spectral peaks from a magnitude spectrum - * \param *data: a pointer to an array of size N containing N magnitude/power/log magnitude/log power coefficients. (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the size of the input array (note: it is assumed that enough memory has been allocated for an output array twice the size) - * \param *argv: a pointer to an array of doubles, the first representing (samplerate / N), the second representing the peak threshold as percentage of the magnitude of the maximum peak found - * \param *result: a pointer to an array of size N * 2 containing N magnitude/power/log magnitude/log power coefficients and N bin frequencies. - * - */ -int xtract_peak_spectrum(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract the harmonic spectrum of from a of a peak spectrum - * \param *data: a pointer to the first element in an array of doubles representing the peak spectrum of an audio vector (e.g. *result from xtract_peaks). It is expected that the first half of the array pointed to by *data will contain amplitudes for each peak considered, and the the second half will contain the respective frequencies - * \param N: the size of the array pointed to by *data - * \param *argv: a pointer to an array containing the fundamental (f0) of the spectrum, and a threshold (t) where 0<=t<=1.0, and t determines the distance from the nearest harmonic number within which a partial can be considered harmonic. - * \param *result: a pointer to an array of size N containing N/2 magnitude coefficients and N/2 bin frequencies. - */ -int xtract_harmonic_spectrum(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Linear Predictive Coding Coefficients - * - * Based on algorithm in Rabiner and Juang as implemented by Jutta Degener in Dr. Dobb's Journal December, 1994. - * - * Returns N-1 reflection (PARCOR) coefficients and N-1 LPC coefficients via *result - * - * \param *data: N autocorrelation values e.g the data pointed to by *result from xtract_autocorrelation() - * \param N: the number of autocorrelation values to be considered - * \param *argv: a pointer to NULL - * \param *result: a pointer to an array containing N-1 reflection coefficients and N-1 LPC coefficients. - * - * An array of size 2 * (N - 1) must be allocated, and *result must point to its first element. - */ -int xtract_lpc(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract Linear Predictive Coding Cepstral Coefficients - * - * \param *data: a pointer to the first element in an array of LPC coeffiecients e.g. a pointer to the second half of the array pointed to by *result from xtract_lpc() - * \param N: the number of LPC coefficients to be considered - * \param *argv: a pointer to a double representing the order of the result vector. This must be a whole number. According to Rabiner and Juang the ratio between the number (p) of LPC coefficients and the order (Q) of the LPC cepstrum is given by Q ~ (3/2)p where Q > p. - * \param *result: a pointer to an array containing the resultant LPCC. - * - * An array of size Q, where Q is given by argv[0] must be allocated, and *result must point to its first element. - * - */ -int xtract_lpcc(const double *data, const int N, const void *argv, double *result); - -/** \brief Extract subbands from a spectrum - * - * \param *data: a pointer to an array of size N containing N magnitude/power/log magnitude/log power coefficients. (e.g. the first half of the array pointed to by *result from xtract_spectrum(). - * \param N: the number of elements from the array pointed to by *data to be considered - * \param *argv: A pointer to an array containing four integers. The first represents the extraction function to applied to each subband e.g. XTRACT_SUM or XTRACT_MEAN, the second represents the number of subbands required, and the third represents the frequency scale to be used for the subband bounds as defined in the enumeration xtract_subband_scales_ (libxtract.h). The fourth integer represent the start point of the subbands as a location in the input array as pointed to by *data (e.g. a value of 5 would start the subband extraction at bin 5) - * \param *result: A pointer to an array containing the resultant subband values. The calling function is responsible for allocating and freeing memory for *result. xtract_subbands() assumes that at least argv[1] * sizeof(double) bytes have been allocated. If the requested nbands extends the subband range beyond N, then the remaining bands will be set to 0. If the array pointed to by *result has more than argv[1] elements, the superfluous elements will be unchanged. - * - * xtract_subbands() divides a spectrum into subbands and applies the function given by argv[0] to the values in each subband to give a 'reduced' representation of the spectrum as *result - * - * Specifying XTRACT_OCTAVE_SUBBANDS will extract subbands at each octave from the start bin until argv[1] is reached or N is reached - * Specifying XTRACT_LINEAR_SUBBANDS will extract argv[1] equal sized subbands between the start bin and N - * - * - * It is assumed that a sensible function will be given in argv[0], and for this function argv will always be NULL. Sensible values for argv[0] are XTRACT_MEAN and XTRACT_SUM, although something like XTRACT_IRREGULARITY_K might yield interesting results. - * - */ -int xtract_subbands(const double *data, const int N, const void *argv, double *result); -/** @} */ - -#ifdef __cplusplus -} -#endif - -#endif -- cgit v1.2.3