Edinburgh Speech Tools  2.1-release
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
EST_sigpr_utt.h
1 /*************************************************************************/
2 /* */
3 /* Centre for Speech Technology Research */
4 /* University of Edinburgh, UK */
5 /* Copyright (c) 1995,1996 */
6 /* All Rights Reserved. */
7 /* */
8 /* Permission is hereby granted, free of charge, to use and distribute */
9 /* this software and its documentation without restriction, including */
10 /* without limitation the rights to use, copy, modify, merge, publish, */
11 /* distribute, sublicense, and/or sell copies of this work, and to */
12 /* permit persons to whom this work is furnished to do so, subject to */
13 /* the following conditions: */
14 /* 1. The code must retain the above copyright notice, this list of */
15 /* conditions and the following disclaimer. */
16 /* 2. Any modifications must be clearly marked as such. */
17 /* 3. Original authors' names are not deleted. */
18 /* 4. The authors' names are not used to endorse or promote products */
19 /* derived from this software without specific prior written */
20 /* permission. */
21 /* */
22 /* THE UNIVERSITY OF EDINBURGH AND THE CONTRIBUTORS TO THIS WORK */
23 /* DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING */
24 /* ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT */
25 /* SHALL THE UNIVERSITY OF EDINBURGH NOR THE CONTRIBUTORS BE LIABLE */
26 /* FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES */
27 /* WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN */
28 /* AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, */
29 /* ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF */
30 /* THIS SOFTWARE. */
31 /* */
32 /*************************************************************************/
33 
34 #ifndef __EST_SIGPR_UTT_H__
35 #define __EST_SIGPR_UTT_H__
36 
37 #include "sigpr/EST_sigpr_frame.h"
38 #include "sigpr/EST_Window.h"
39 #include "EST_Track.h"
40 #include "EST_Wave.h"
41 
42 #define DEFAULT_WINDOW_NAME "hamming"
43 #define DEFAULT_FRAME_FACTOR 2.0
44 
45 /* Note: some of these functions deliberately don't have
46  doxygen style comments, mainly because they are, or will be
47  superseded soon.
48 */
49 
50 /** @defgroup FunctionsForGeneratingTracks Functions for generating Tracks
51  */
52 
53 /**@defgroup Functionsforusewithframebasedprocessing Functions for use with frame based processing
54  @ingroup FunctionsForGeneratingTracks
55 
56 In the following functions, the input is a EST_Wave waveform,
57 and the output is a (usually multi-channel) EST_Track. The
58 track must be set up appropriately before hand. This means the track
59 must be resized accordingly with the correct numbers of frame and
60 channels.
61 
62 The positions of the frames are found by examination of the **time**
63 array in the EST_Track, which must be filled prior to the function
64 call. The usual requirement is for fixed frame analysis, where each
65 analysis frame is, say, 10ms after the previous one.
66 
67 A common alternative is to perform pitch-synchronous
68 analysis where the time shift is related to the local pitch period.
69 
70 */
71 
72 ///@{
73 
74 /** Produce a single set of coefficients from a waveform. The type of
75  coefficient required is given in the argument `type`.
76 
77  \param type { Possible types are:
78  - **lpc**: linear predictive coding
79  - **cep**: cepstrum coding from lpc coefficients
80  - **melcep**: Mel scale cepstrum coding via fbank
81  - **fbank**: Mel scale log filterbank analysis
82  - **lsf**: line spectral frequencies
83  - **ref**: Linear prediction reflection coefficients
84  - **power**:
85  - **f0**: srpd algorithm
86  - **energy**: root mean square energy
87  }
88 
89 The order of the analysis is calculated from the number of
90 channels in `fv`. The positions of the analysis
91 windows must be given by filling in the track's time array.
92 
93 This function windows the waveform at the intervals given by the track
94 time array. The length of each window is `factor * the local time shift`.
95 The windowing function is given by `wf`.
96 
97  @param sig input waveform
98  @param fv {output coefficients. These have been pre-allocated and the
99  number of channels in a indicates the order of the analysis.}
100  @param type the types of coefficients to be produced. "lpc", "cep" etc
101  @param factor {the frame length factor, i.e. the analysis frame length
102  will be this times the local pitch period.}
103 
104  @param wf function for windowing. See Windowing mechanisms
105 */
106 void sig2coef(EST_Wave &sig, EST_Track &a, EST_String type,
107  float factor = 2.0,
108  EST_WindowFunc *wf = EST_Window::creator(DEFAULT_WINDOW_NAME));
109 
110 /** Produce multiple coefficients from a waveform by repeated calls to
111  sig2coef.
112 
113 @param sig: input waveform
114 @param fv: output coefficients. These have been pre-allocated and the
115  number of channels in a indicates the order of the analysis.
116 @param op: Features structure containing options for analysis order,
117  frame shift etc.
118 @param slist: list of types of coefficients required, from the set of
119 possible types that sig2coef can take.
120 */
121 void sigpr_base(EST_Wave &sig, EST_Track &fv, EST_Features &op,
122  const EST_StrList &slist);
123 
124 /** Calculate the power for each frame of the waveform.
125 
126 @param sig: input waveform
127 @param a: output power track
128 @param factor: the frame length factor, i.e. the analysis frame length
129  will be this times the local pitch period.
130 */
131 void power(EST_Wave &sig, EST_Track &a, float factor);
132 
133 /** Calculate the rms energy for each frame of the waveform.
134 
135 This function calls
136 \ref sig2energy
137 
138 
139 @param sig input waveform
140 @param a output coefficients
141 @param factor optional: the frame length factor, i.e. the analysis frame length
142  will be this times the local pitch period.
143 
144 */
145 void energy(EST_Wave &sig, EST_Track &a, float factor);
146 
147 
148 /** Mel scale filter bank analysis. The Mel scale triangular filters
149 are computed via an FFT (see \ref fastFFT). This routine is required
150 for Mel cepstral analysis (see \ref melcep). The analysis of each
151 frame is done by \ref sig2fbank.
152 
153 A typical filter bank analysis for speech recognition might use log
154 energy outputs from 20 filters.
155 
156 @param sig: input waveform
157 @param fbank: the output. The number of filters is determined from the number
158  size of this track.
159 @param factor: the frame length factor, i.e. the analysis frame length
160  will be this times the local pitch period
161 @param wf: function for windowing. See \ref {Windowing mechanisms}
162 @param up: whether the filterbank analysis should use
163  power rather than energy.
164 @param take_log: whether to take logs of the filter outputs
165 
166 @see sig2fbank
167 @see melcep
168 */
169 void fbank(EST_Wave &sig,
170  EST_Track &fbank,
171  const float factor,
172  EST_WindowFunc *wf = EST_Window::creator(DEFAULT_WINDOW_NAME),
173  const bool up = false,
174  const bool take_log = true);
175 
176 /** Mel scale cepstral analysis via filter bank analysis. Cepstral
177 parameters are computed for each frame of speech. The analysis
178 requires \ref fbank . The cepstral analysis of the filterbank outputs
179 is performed by \ref fbank2melcep .
180 
181 A typical Mel cepstral coefficient (MFCC) analysis for speech recognition
182 might use 12 cepstral coefficients computed from a 20 channel filterbank.
183 
184 
185 @param sig input: waveform
186 @param mfcc_track: the output
187 @param factor: the frame length factor, i.e. the analysis frame length
188  will be this times the local pitch period
189 @param fbank_order: the number of Mel scale filters used for the analysis
190 @param liftering_parameter: for filtering in the cepstral domain
191  See \ref fbank2melcep
192 @param wf: function for windowing. See \ref Windowing mechanisms
193 @param include_c0: whether the zero'th cepstral coefficient is to be included
194 @param up: whether the filterbank analysis should use
195  power rather than energy.
196 
197 @see fbank
198 @see fbank2melcep
199 */
200 void melcep(EST_Wave &sig,
201  EST_Track &mfcc_track,
202  float factor,
203  int fbank_order,
204  float liftering_parameter,
205  EST_WindowFunc *wf = EST_Window::creator(DEFAULT_WINDOW_NAME),
206  const bool include_c0 = false,
207  const bool up = false);
208 
209 ///@}
210 
211 
212 /**@defgroup PitchF0DetectionAlgorithmfunctions Pitch/F0 Detection Algorithm functions
213  @ingroup FunctionsForGeneratingTracks
214 
215 These functions are used to produce a track of fundamental frequency
216 (F0) against time of a waveform.
217 */
218 
219 ///@{
220 
221 
222 /** Top level pitch (F0) detection algorithm. Returns a track
223 containing evenly spaced frames of speech, each containing a F0 value
224 for that point.
225 
226 At present, only the \ref srpd pitch tracker is implemented, so
227 this is always called regardless of what `method`
228 is set to.
229 
230 @param sig: input waveform
231 @param fz: output f0 contour
232 @param op: parameters for pitch tracker
233 @param method: pda method to be used.
234 */
235 void pda(EST_Wave &sig, EST_Track &fz, EST_Features &op, EST_String method="");
236 
237 
238 /** Top level intonation contour detection algorithm. Returns a track
239 containing evenly spaced frames of speech, each containing a F0 for that
240 point. `icda` differs from \ref pda in that the contour is smoothed,
241 and unvoiced portions have interpolated F0 values.
242 
243 @param sig: input waveform
244 @param fz: output f0 contour
245 @param speech: {Interpolation is controlled by the `speech` track. When
246 a point has a positive value in the speech track, it is a candidate
247 for interpolation. }
248 @param op: parameters for pitch tracker
249 @param method: pda method to be used.
250 */
251 void icda(EST_Wave &sig, EST_Track &fz, EST_Track &speech,
252  EST_Option &op, EST_String method = "");
253 
254 /** Create a set sensible defaults for use in pda and icda.
255 
256 */
258 
259 
260 /** Super resolution pitch tracker.
261 
262 srpd is a pitch detection algorithm that produces a fundamental
263 frequency contour from a speech waveform. At present only the super
264 resolution pitch determination algorithm is implemented. See (Medan,
265 Yair, and Chazan, 1991) and (Bagshaw et al., 1993) for a detailed
266 description of the algorithm.
267 
268 Frames of data are read in from `sig` in
269 chronological order such that each frame is shifted in time from its
270 predecessor by `pda_frame_shift`. Each frame is
271 analysed in turn.
272 
273 
274 The maximum and minimum signal amplitudes are initially found over the
275 duration of two segments, each of length N_min samples. If the sum of
276 their absolute values is below two times
277 noise_floor, the frame is classified as
278 representing silence and no coefficients are calculated. Otherwise, a
279 cross correlation coefficient is calculated for all n from a period in
280 samples corresponding to `min_pitch`
281 to a period in samples corresponding to
282 `max_pitch`, in steps
283 of `decimation_factor`. In calculating the
284 coefficient only one in `decimation_factor`
285 samples of the two segments are used. Such down-sampling permits rapid
286 estimates of the coefficients to be calculated over the range
287 N_min <= n <= N_max. This results in a cross-correlation track for the
288 frame being analysed.
289 
290 Local maxima of the track with a coefficient value above a specified
291 threshold form candidates for the fundamental period. The threshold is
292 adaptive and dependent upon the values `v2uv_coeff_thresh`,
293 `min_v2uv_coef_thresh `, and `v2uv_coef_thresh_rati_ratio`. If the previously
294 analysed frame was classified as unvoiced or silent (which is the
295 initial state) then the threshold is set to
296 `v2uv_coef_thresh`. Otherwise, the previous
297 frame was classified as being voiced, and the threshold is set equal
298 to [\-r] `v2uv_coef_thresh_rati_ratio`
299 times the cross-correlation coefficient
300 value at the point of the previous fundamental period in the former
301 coefficients track. This product is not permitted to drop below
302 `v2uv_coef_thresh`.
303 
304 If no candidates for the fundamental period are found, the frame is classified
305 as being unvoiced. Otherwise, the candidates are further processed to identify
306 the most likely true pitch period. During this additional processing, a
307 threshold given by `anti_doubling_thres` is used.
308 
309 If the `peak_tracking` flag is set to true,
310 biasing is applied to the cross-correlation track as described in
311 (Bagshaw et al., 1993).
312 
313 @param sig: input waveform
314 @param op: options regarding pitch tracking parameters
315 @param op.min_pitch: minimum permitted F0 value
316 @param op.max_pitch: maximum permitted F0 value
317 @param op.pda_frame_shift: analysis frame shift
318 @param op.pda_frame_length: analysis frame length
319 @param op.lpf_cutoff: cut off frequency for low pass filtering
320 @param op.lpf_order: order of low pass filtering (must be odd)
321 @param op.decimation
322 @param op.noise_floor
323 @param op.min_v2uv_coef_thresh
324 @param op.v2uv_coef_thresh_ratio
325 @param op.v2uv_coef_thresh
326 @param op.anti_doubling_thresh
327 @param op.peak_tracking
328 
329 */
330 void srpd(EST_Wave &sig, EST_Track &fz, EST_Features &options);
331 
332 /** Smooth selected parts of an f0 contour. Interpolation is
333 controlled by the <tt>speech</tt> track. When a point has a positive
334 value in the speech track, it is a candidate for interpolation.
335 */
336 void smooth_phrase(EST_Track &c, EST_Track &speech, EST_Features &options,
337  EST_Track &sm);
338 
339 /** Smooth all the points in an F0 contour*/
340 void smooth_portion(EST_Track &c, EST_Option &op);
341 
342 ///@}
343 
344 
345 /**@defgroup DeltaandAccelerationcoefficients Delta and Acceleration coefficients
346  @ingroup FunctionsForGeneratingTracks
347 
348 Produce delta and acceleration coefficients from a set of coefficients
349 or the waveform.
350 */
351 
352 ///@{
353 
354 /** Produce a set of delta coefficients for a track
355 
356 The delta function is used to produce a set of coefficients which
357 estimate the rate of change of a set of parameters. The output track
358 `d` must be setup before hand, i.e. it must have
359 the same number of frames and channels as `tr`.
360 
361 @param tr: input track of base coefficients
362 @param d: output track of delta coefficients.
363 @param regression_length: number of previous frames on which delta
364  estimation is calculated on.
365 */
366 void delta(EST_Track &tr, EST_Track &d, int regression_length = 3);
367 
368 /** Produce multiple sets of delta coefficients from a waveform.
369 
370  Calculate specified types of delta coefficients. This function is
371  used when the base types of coefficients haven't been calculated.
372  This function calls sig2coef to calculate the base types from which
373  the deltas are calculated, and hence the requirements governing the
374  setup of `fv` for sig2coef also hold here.
375 
376 @param sig: input waveform
377 @param fv: output coefficients. These have been pre-allocated and the
378  number of channels in a indicates the order of the analysis.
379 @param op: Features structure containing options for analysis order,
380  frame shift etc.
381 @param slist: list of types of delta coefficients required.
382 */
383 void sigpr_delta(EST_Wave &sig, EST_Track &fv, EST_Features &op,
384  const EST_StrList &slist);
385 
386 /** Produce multiple sets of acceleration coefficients from a waveform
387 
388  Calculate specified types of acceleration coefficients. This function
389  is used when the base types of coefficient haven't been calculated.
390  This function calls sig2coef to calculate the base types from which
391  the deltas are calculated, and hence the requirements governing the
392  setup of `fv` for sig2coef also hold here.
393 
394 @param sig: input waveform
395 @param fv: output coefficients. These have been pre-allocated and the
396  number of channels in a indicates the order of the analysis.
397 @param op: Features structure containing options for analysis order,
398  frame shift etc.
399 @param slist: list of types of acceleration coefficients required.
400 
401 
402 The delta function is used to produce a set of coefficients which
403 estimate the rate of change of a set of parameters.
404 */
405 void sigpr_acc(EST_Wave &sig, EST_Track &fv, EST_Features &op,
406  const EST_StrList &slist);
407 
408 ///@}
409 
410 /* Convert a track containing coefficients of one type to a track
411 containing coefficients of another.
412 
413 @param in_track input set of coefficients
414 @param out_track input set of coefficients
415 @param out_name name of desired output coefficients.
416 @param in_name optional: often it is possible to determine the type of
417 the input coefficients from the channel names. If this is not possible or
418 these names should be ignored, the `in_type` parameter can be used.
419 
420 */
421 void convert_track(EST_Track &in_track, EST_Track &out_track,
422  const EST_String &out_type,
423  const EST_String &in_type = "");
424 
425 
426 
427 #endif /* __EST_SIGPR_UTT_H__ */
428 
A class for storing digital waveforms. The waveform is stored as an array of 16 bit shorts...
Definition: EST_Wave.h:64
static Func * creator(const char *name, bool report_error=false)
Return the creation function for the given window type.
Definition: EST_Window.cc:216
void delta(EST_Track &tr, EST_Track &d, int regression_length=3)
Definition: delta.cc:49
void energy(EST_Wave &sig, EST_Track &a, float factor)
Definition: sigpr_utt.cc:442
void power(EST_Wave &sig, EST_Track &a, float factor)
Definition: sigpr_utt.cc:420
void melcep(EST_Wave &sig, EST_Track &mfcc_track, float factor, int fbank_order, float liftering_parameter, EST_WindowFunc *wf=EST_Window::creator(DEFAULT_WINDOW_NAME), const bool include_c0=false, const bool up=false)
Definition: sigpr_utt.cc:536
void sig2coef(EST_Wave &sig, EST_Track &a, EST_String type, float factor=2.0, EST_WindowFunc *wf=EST_Window::creator(DEFAULT_WINDOW_NAME))
Definition: sigpr_utt.cc:397
void icda(EST_Wave &sig, EST_Track &fz, EST_Track &speech, EST_Option &op, EST_String method="")
void srpd(EST_Wave &sig, EST_Track &fz, EST_Features &options)
Definition: pda.cc:85
void default_pda_options(EST_Features &al)
Definition: pda.cc:227
void smooth_phrase(EST_Track &c, EST_Track &speech, EST_Features &options, EST_Track &sm)
Definition: smooth_pda.cc:54
void sigpr_delta(EST_Wave &sig, EST_Track &fv, EST_Features &op, const EST_StrList &slist)
Definition: sigpr_utt.cc:307
void EST_WindowFunc(int size, EST_TBuffer< float > &r_window, int window_centre)
Function which creates a window.
Definition: EST_Window.h:52
void pda(EST_Wave &sig, EST_Track &fz, EST_Features &op, EST_String method="")
Definition: pda.cc:51
void smooth_portion(EST_Track &c, EST_Option &op)
void sigpr_acc(EST_Wave &sig, EST_Track &fv, EST_Features &op, const EST_StrList &slist)
Definition: sigpr_utt.cc:300
void fbank(EST_Wave &sig, EST_Track &fbank, const float factor, EST_WindowFunc *wf=EST_Window::creator(DEFAULT_WINDOW_NAME), const bool up=false, const bool take_log=true)
Definition: sigpr_utt.cc:492
void sigpr_base(EST_Wave &sig, EST_Track &fv, EST_Features &op, const EST_StrList &slist)
Definition: sigpr_utt.cc:136