Edinburgh Speech Tools  2.4-release
EST_filter.h
1 /*************************************************************************/
2 /* */
3 /* Centre for Speech Technology Research */
4 /* University of Edinburgh, UK */
5 /* Copyright (c) 1995,1996 */
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
35
36
37 #ifndef __EST_FILTER_H__
38 #define __EST_FILTER_H__
39
40 #include "EST_Wave.h"
41 #include "EST_FMatrix.h"
42 #include "EST_Track.h"
43
44 #define DEFAULT_PRE_EMPH_FACTOR 0.95
45 #define DEFAULT_FILTER_ORDER 199
46
47 /**@name FIR filters
48
49 Finite impulse response (FIR) filters which are useful for band-pass,
50 low-pass and high-pass filtering.
51
52 FIR filters perform the following operation:
53
54 $y_t=\sum_{i=0}^{O-1} c_i \; x_{t-i}$
55
56 where $$O$$ is the filter order, $$c_i$$ are the filter coefficients,
57 $$x_t$$ is the input at time $$t$$ and $$y_t$$ is the output at time
58 $$t$$. Functions are provided for designing the filter (i.e. finding
59 the coefficients).
60
61 */
62
63 //@{
64
65 /** General purpose FIR filter. This function will filter the
66 waveform {\tt sig} with a previously designed filter, given as {\tt
67 numerator}. The filter coefficients can be designed using one of the
68 designed functions, e.g. \Ref{design_FIR_filter}.
69
70 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter,
71 @see FIRfilter, FIRlowpass_filter, FIRhighpass_filter
72
73 */
74
75 void FIRfilter(EST_Wave &in_sig, const EST_FVector &numerator,
76  int delay_correction=0);
77
78
79 /** General purpose FIR filter. This function will filter the
80 waveform {\tt sig} with a previously designed filter, given as {\tt
81 numerator}. The filter coefficients can be designed using one of the
82 designed functions, e.g. \Ref{design_FIR_filter} .
83
84 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter,
85 @see FIRfilter, FIRlowpass_filter, FIRhighpass_filter
86 */
87
88 void FIRfilter(const EST_Wave &in_sig, EST_Wave &out_sig,
89  const EST_FVector &numerator, int delay_correction=0);
90
91 /** General purpose FIR double (zero-phase) filter. This function
92 will double filter the waveform {\tt sig} with a previously designed
93 filter, given as {\tt numerator}. The filter coefficients can be
94 designed using one of the designed functions,
95 e.g. \Ref{design_FIR_filter}. Double filtering is performed by
96 filtering the signal normally, reversing the waveform, filtering
97 again and reversing the waveform again. Normal filtering will impose a
98 lag on the signal depending on the order of the filter. By filtering
99 the signal forwards and backwards, the lags cancel each other out and
100 the output signal is in phase with the input signal.
101
102 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter,
103 @see FIRfilter, FIRlowpass_filter, FIRhighpass_filter
104 */
105 void FIR_double_filter(EST_Wave &in_sig, EST_Wave &out_sig,
106  const EST_FVector &numerator);
107
108 /** Quick function for one-off low pass filtering. If repeated lowpass
109 filtering is needed, first design the required filter using
110 \Ref{design_lowpass_filter}, and then use \Ref{FIRfilter} to do the actual
111 filtering.
112
113 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter, FIRfilter, FIRhighpass_filter, FIRlowpass_filter
114
115 @param in_sig input waveform, which will be overwritten
116 @param freq
117 @param order number of filter coefficients, eg. 99
118 */
119
120 void FIRlowpass_filter(EST_Wave &sigin, int freq, int order=DEFAULT_FILTER_ORDER);
121
122 /** Quick function for one-off low pass filtering. If repeated lowpass
123 filtering is needed, first design the required filter using
124 \Ref{design_lowpass_filter}, and then use \Ref{FIRfilter} to do the actual
125 filtering.
126
127 @param in_sig input waveform
128 @param out_sig output waveform
129 @param freq cutoff frequency in Hertz
130 @param order number of filter coefficients , e.g. 99
131
132 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter, FIRfilter, FIRhighpass_filter
133 */
134
135 void FIRlowpass_filter(const EST_Wave &in_sig, EST_Wave &out_sig,
136  int freq, int order=DEFAULT_FILTER_ORDER);
137
138 /** Quick function for one-off high pass filtering. If repeated lowpass
139 filtering is needed, first design the required filter using
140 design_lowpass_filter, and then use FIRfilter to do the actual
141 filtering.
142
143 @param in_sig input waveform, which will be overwritten
144 @param freq cutoff frequency in Hertz
145 @param order number of filter coefficients, eg. 99
146
147 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter
148 @see FIRfilter, FIRlowpass_filter, FIRhighpass_filter
149 */
150
151 void FIRhighpass_filter(EST_Wave &in_sig, int freq, int order);
152
153 /** Quick function for one-off high pass filtering. If repeated highpass
154 filtering is needed, first design the required filter using
155 design_highpass_filter, and then use FIRfilter to do the actual
156 filtering.
157
158 @param in_sig input waveform
159 @param out_sig output waveform
160 @param freq cutoff frequency in Hertz
161 @param order number of filter coefficients, eg. 99
162
163 @see design_FIR_filter, design_lowpass_FIR_filter, design_highpass_FIR_filter
164 @see FIRfilter, FIRlowpass_filter, FIRhighpass_filter
165 */
166 void FIRhighpass_filter(const EST_Wave &sigin, EST_Wave &out_sig,
167  int freq, int order=DEFAULT_FILTER_ORDER);
168
169
170 /** Quick function for one-off double low pass filtering.
171
172 Normal low pass filtering (\Ref{FIRlowpass_filter}) introduces a time delay.
173 This function filters the signal twice, first forward and then backwards,
174 which ensures a zero phase lag. Hence the order parameter need only be
175 half what it is for (\Ref{FIRlowpass_filter} to achieve the same effect.
176
177 @param in_sig input waveform, which will be overwritten
178 @param freq cutoff frequency in Hertz
179 @param order number of filter coefficients, eg. 99
180
181 @see FIRhighpass_filter
182 */
183 void FIRhighpass_double_filter(EST_Wave &sigin, int freq,
184  int order=DEFAULT_FILTER_ORDER);
185
186 /** Quick function for one-off double low pass filtering.
187
188 Normal low pass filtering (\Ref{FIRlowpass_filter}) introduces a time delay.
189 This function filters the signal twice, first forward and then backwards,
190 which ensures a zero phase lag. Hence the order parameter need only be
191 half what it is for (\Ref{FIRlowpass_filter} to achieve the same effect.
192
193 @param in_sig input waveform
194 @param out_sig output waveform
195 @param freq cutoff frequency in Hertz
196 @param order number of filter coefficients, eg. 99
197
198 @see FIRhighpass_filter
199
200 */
201 void FIRhighpass_double_filter(const EST_Wave &int_sig, EST_Wave &out_sig,
202  int freq, int order=DEFAULT_FILTER_ORDER);
203
204 /** Quick function for one-off zero phase high pass filtering.
205
206 Normal high pass filtering (\Ref{FIRhighpass_filter}) introduces a time delay.
207 This function filters the signal twice, first forward and then backwards,
208 which ensures a zero phase lag. Hence the order parameter need only be
209 half what it is for (\Ref{FIRhighpass_filter} to achieve the same effect.
210
211 @param in_sig input waveform, which will be overwritten
212 @param freq cutoff frequency in Hertz
213 @param order number of filter coefficients, eg. 99
214
215 @see FIRlowpass_filter
216 */
217 void FIRlowpass_double_filter(EST_Wave &sigin, int freq,
218  int order=DEFAULT_FILTER_ORDER);
219
220 /** Quick function for one-off zero phase high pass filtering.
221
222 Normal high pass filtering (\Ref{FIRhighpass_filter}) introduces a time delay.
223 This function filters the signal twice, first forward and then backwards,
224 which ensures a zero phase lag. Hence the order parameter need only be
225 half what it is for (\Ref{FIRhighpass_filter} to achieve the same effect.
226
227 @param in_sig input waveform
228 @param out_sig output waveform
229 @param freq cutoff frequency in Hertz
230 @param order number of filter coefficients, eg. 99
231
232 @see FIRlowpass_filter
233 */
234 void FIRlowpass_double_filter(const EST_Wave &in_sig, EST_Wave &out_sig,
235  int freq, int order=DEFAULT_FILTER_ORDER);
236
237 //@}
238
239 /**@name Linear Prediction filters
240
241 The linear prediction filters are used for the analysis and synthesis of
242 waveforms according the to linear prediction all-pole model.
243
244 The linear prediction states that the value of a signal at a given
245 point is equal to a weighted sum of the previous P values, plus a
246 correction value for that point:
247
248 $s_{n} = \sum_{i=1}^{P} a_{i}.s_{n-i} + e_{n}$
249
250 Given a set of coefficients and the original signal, we can use this
251 equation to work out e, the {\it residual}. Conversely given the
252 coefficients and the residual signal, an estimation of the original
253 signal can be calculated.
254
255 If a single set of coefficients were used for the entire waveform, the
256 filtering process would be simple. It is usual however to have a
257 different set of coefficients for every frame, and there are many
258 possible ways to switch from one coefficient set to another so as not
259 to cause discontinuities at the frame boundaries.
260 */
261
262 //@{
263
264 /** Synthesize a signal from a single set of linear prediction
265 coefficients and the residual values.
266
267 @param sig the waveform to be synthesized
268 @param a a single set of LP coefficients
269 @param res the input residual waveform
270 */
271 void lpc_filter(EST_Wave &sig, EST_FVector &a, EST_Wave &res);
272
273 /** Filter the waveform using a single set of coefficients so as to
274 produce a residual signal.
275
276 @param sig the speech waveform to be filtered
277 @param a a single set of LP coefficients
278 @param res the output residual waveform
279 */
280
281 void inv_lpc_filter(EST_Wave &sig, EST_FVector &a, EST_Wave &res);
282
283 /** Synthesize a signal from a track of linear prediction coefficients.
284 This function takes a set of LP frames and a residual and produces a
285 synthesized signal.
286
287 For each frame, the function picks an end point, which is half-way
288 between the current frame's time position and the next frame's. A
289 start point is defined as being the previous frame's end. Using these
290 two values, a portion of residual is extracted and passed to
291 \Ref{lpc_filter} along with the LP coefficients for that frame. This
292 function writes directly into the signal for the values between start
293 and end;
294
295 @param sig the waveform to be synthesized
296 @param lpc a track of time positioned LP coefficients
297 @param res the input residual waveform
298 */
299
300 void lpc_filter_1(EST_Track &lpc, EST_Wave & res, EST_Wave &sig);
301
302 /** Synthesize a signal from a track of linear prediction coefficients.
303 This function takes a set of LP frames and a residual and produces a
304 synthesized signal.
305
306 This is functionally equivalent to \Ref{lpc_filter_1} except it
307 reduces the residual by 0.5 before filtering. Importantly it is
308 about three times faster than \Ref{lpc_filter_1} but in doing so uses
309 direct C buffers rather than the neat C++ access function. This
310 function should be regarded as temporary and will be deleted after
311 we restructure the low level classes to give better access.
312
313 @param sig the waveform to be synthesized
314 @param lpc a track of time positioned LP coefficients
315 @param res the input residual waveform
316 */
317
318 void lpc_filter_fast(EST_Track &lpc, EST_Wave & res, EST_Wave &sig);
319
320 /** Produce a residual from a track of linear prediction coefficients
321 and a signal using an overlap add technique.
322
323 For each frame, the function estimates the local pitch period and
324 picks a start point one period before the current time position and an
325 end point one period after it.
326
327 A portion of residual corresponding to these times is then produced
328 using \Ref{inv_lpc_filter}. The resultant section of residual is then
329 overlap-added into the main residual wave object.
330
331 @param sig the speech waveform to be filtered
332 @param lpc a track of time positioned LP coefficients
333 @param res the output residual waveform
334 */
335
336 void inv_lpc_filter_ola(EST_Wave &sig, EST_Track &lpc, EST_Wave &res);
337
338 //@}
339
340 /**@name Pre/Post Emphasis filters.
341
342 These functions adjust the spectral tilt of the input waveform.
343
344 */
345
346 //@{
347
348 /** Pre-emphasis filtering. This performs simple high pass
349 filtering with a one tap filter of value {\tt a}. Normal values of a
350 range between 0.95 and 0.99. */
351
352 void pre_emphasis(EST_Wave &sig, float a=DEFAULT_PRE_EMPH_FACTOR);
353
354 /** Pre-emphasis filtering. This performs simple high pass
355 filtering with a one tap filter of value {\tt a}. Normal values of a
356 range between 0.95 and 0.99. */
357
358
359 void pre_emphasis(EST_Wave &sig, EST_Wave &out,
360  float a=DEFAULT_PRE_EMPH_FACTOR);
361
362 /** Post-emphasis filtering. This performs simple low pass
363 filtering with a one tap filter of value a. Normal values of a range
364 between 0.95 and 0.99. The same values of {\tt a} should be used when
365 pre- and post-emphasizing the same signal. */
366
367 void post_emphasis(EST_Wave &sig, float a=DEFAULT_PRE_EMPH_FACTOR);
368
369 /** Post-emphasis filtering. This performs simple low pass
370 filtering with a one tap filter of value a. Normal values of a range
371 between 0.95 and 0.99. The same values of {\tt a} should be used when
372 pre- and post-emphasizing the same signal. */
373
374 void post_emphasis(EST_Wave &sig, EST_Wave &out,
375  float a=DEFAULT_PRE_EMPH_FACTOR);
376
377 //@}
378
379 /**@name Miscellaneous filters.
380
381 Some of these filters are non-linear and therefore don't fit the
383
384 */ //@{
385
386 /** Filters the waveform by means of median smoothing.
387
388 This is a sort of low pass filter which aims to remove extreme values.
389 Median smoothing works examining each sample in the wave, taking all
390 the values in a window of size {\tt n} around that sample, sorting
391 them and replacing that sample with the middle ranking sample in the
392 sorted samples.
393
394 @param sig waveform to be filtered
395 @param n size of smoothing window
396
397 */
398
399 void simple_mean_smooth(EST_Wave &c, int n);
400
401 //@}
402
403 #endif /* __EST_FILTER_H__ */
404