Mercurial > hg > libxtract

comparison include/xtract/xtract_vector.h @ 254:39f1f8cf6756

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Move xtract inside "include" directory
author Jamie Bullock <jamie@jamiebullock.com>
date Fri, 07 Nov 2014 12:49:21 +0000
parents
children
comparison
equal deleted inserted replaced
253:17531082a918 254:39f1f8cf6756
1 /*
2 * Copyright (C) 2012 Jamie Bullock
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to
6 * deal in the Software without restriction, including without limitation the
7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8 * sell copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20 * IN THE SOFTWARE.
21 *
22 */
23
24 /** \file xtract_vector.h: declares functions that extract a feature as a vector from an input vector */
25
26 #ifndef XTRACT_VECTOR_H
27 #define XTRACT_VECTOR_H
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 /**
34 * \defgroup vector vector extraction functions
35 *
36 * Functions that extract a feature as a vector from an input vector
37 *
38 * @{
39 */
40
41 /** \brief Extract frequency domain spectrum from time domain signal
42 *
43 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
44 * \param N: the number of array elements to be considered
45 * \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.
46 * \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.
47 *
48 * The magnitude/power coefficients are scaled to the range 0-1 so that for a given coefficient x, 0 <= x <= 1
49 *
50 * \note Before calling xtract_spectrum(), the FFT must be initialised by calling xtract_init_fft(N, XTRACT_SPECTRUM)
51 *
52 */
53 int xtract_spectrum(const double *data, const int N, const void *argv, double *result);
54
55 /** \brief Extract autocorrelation from time domain signal using FFT based method
56 *
57 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
58 * \param N: the number of array elements to be considered
59 * \param *argv: a pointer to NULL
60 * \param *result: the autocorrelation of N values from the array pointed to by *data
61 */
62 int xtract_autocorrelation_fft(const double *data, const int N, const void *argv, double *result);
63
64 /** \brief Extract Mel Frequency Cepstral Coefficients based on a method described by Rabiner
65 *
66 * \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()
67 * \param N: the number of array elements to be considered
68 * \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
69 * \param *result: a pointer to an array containing the resultant MFCC
70 *
71 * The data structure pointed to by *argv must be obtained by first calling xtract_init_mfcc
72 */
73 int xtract_mfcc(const double *data, const int N, const void *argv, double *result);
74
75 /** \brief Extract the Discrete Cosine transform of a time domain signal
76 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
77 * \param N: the number of array elements to be considered
78 * \param *argv: a pointer to NULL
79 * \param *result: a pointer to an array containing resultant dct coefficients
80 */
81 int xtract_dct(const double *data, const int N, const void *argv, double *result);
82
83 /** \brief Extract autocorrelation from time domain signal using time-domain autocorrelation technique
84 *
85 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
86 * \param N: the number of array elements to be considered
87 * \param *argv: a pointer to NULL
88 * \param *result: the autocorrelation of N values from the array pointed to by *data
89 */
90 int xtract_autocorrelation(const double *data, const int N, const void *argv, double *result);
91
92 /** \brief Extract Average Magnitude Difference Function from time domain signal
93 *
94 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
95 * \param N: the number of array elements to be considered
96 * \param *argv: a pointer to NULL
97 * \param *result: the AMDF of N values from the array pointed to by *data
98 */
99 int xtract_amdf(const double *data, const int N, const void *argv, double *result);
100
101 /** \brief Extract Average Squared Difference Function from time domain signal
102 *
103 * \param *data: a pointer to the first element in an array of doubles representing an audio vector
104 * \param N: the number of array elements to be considered
105 * \param *argv: a pointer to NULL
106 * \param *result: the ASDF of N values from the array pointed to by *data
107 */
108 int xtract_asdf(const double *data, const int N, const void *argv, double *result);
109
110 /** \brief Extract Bark band coefficients based on a method
111 * \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().
112 * \param N: the number of array elements to be considered
113 * \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.
114 * \param *result: a pointer to an array containing resultant bark coefficients
115 *
116 * The limits array pointed to by *argv must be obtained by first calling xtract_init_bark
117 *
118 */
119 int xtract_bark_coefficients(const double *data, const int N, const void *argv, double *result);
120
121 /** \brief Extract the amplitude and frequency of spectral peaks from a magnitude spectrum
122 * \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().
123 * \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)
124 * \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
125 * \param *result: a pointer to an array of size N * 2 containing N magnitude/power/log magnitude/log power coefficients and N bin frequencies.
126 *
127 */
128 int xtract_peak_spectrum(const double *data, const int N, const void *argv, double *result);
129
130 /** \brief Extract the harmonic spectrum of from a of a peak spectrum
131 * \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
132 * \param N: the size of the array pointed to by *data
133 * \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.
134 * \param *result: a pointer to an array of size N containing N/2 magnitude coefficients and N/2 bin frequencies.
135 */
136 int xtract_harmonic_spectrum(const double *data, const int N, const void *argv, double *result);
137
138 /** \brief Extract Linear Predictive Coding Coefficients
139 *
140 * Based on algorithm in Rabiner and Juang as implemented by Jutta Degener in Dr. Dobb's Journal December, 1994.
141 *
142 * Returns N-1 reflection (PARCOR) coefficients and N-1 LPC coefficients via *result
143 *
144 * \param *data: N autocorrelation values e.g the data pointed to by *result from xtract_autocorrelation()
145 * \param N: the number of autocorrelation values to be considered
146 * \param *argv: a pointer to NULL
147 * \param *result: a pointer to an array containing N-1 reflection coefficients and N-1 LPC coefficients.
148 *
149 * An array of size 2 * (N - 1) must be allocated, and *result must point to its first element.
150 */
151 int xtract_lpc(const double *data, const int N, const void *argv, double *result);
152
153 /** \brief Extract Linear Predictive Coding Cepstral Coefficients
154 *
155 * \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()
156 * \param N: the number of LPC coefficients to be considered
157 * \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.
158 * \param *result: a pointer to an array containing the resultant LPCC.
159 *
160 * An array of size Q, where Q is given by argv[0] must be allocated, and *result must point to its first element.
161 *
162 */
163 int xtract_lpcc(const double *data, const int N, const void *argv, double *result);
164
165 /** \brief Extract subbands from a spectrum
166 *
167 * \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().
168 * \param N: the number of elements from the array pointed to by *data to be considered
169 * \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)
170 * \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.
171 *
172 * 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
173 *
174 * Specifying XTRACT_OCTAVE_SUBBANDS will extract subbands at each octave from the start bin until argv[1] is reached or N is reached
175 * Specifying XTRACT_LINEAR_SUBBANDS will extract argv[1] equal sized subbands between the start bin and N
176 *
177 *
178 * 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.
179 *
180 */
181 int xtract_subbands(const double *data, const int N, const void *argv, double *result);
182 /** @} */
183
184 #ifdef __cplusplus
185 }
186 #endif
187
188 #endif