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 */
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
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
49Finite impulse response (FIR) filters which are useful for band-pass,
50low-pass and high-pass filtering.
51
52FIR filters perform the following operation:
53
54\[y_t=\sum_{i=0}^{O-1} c_i \; x_{t-i}\]
55
56where \‍(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
59the coefficients).
60
61*/
62
63//@{
64
65/** General purpose FIR filter. This function will filter the
66waveform {\tt sig} with a previously designed filter, given as {\tt
67numerator}. The filter coefficients can be designed using one of the
68designed 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
75void 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
80waveform {\tt sig} with a previously designed filter, given as {\tt
81numerator}. The filter coefficients can be designed using one of the
82designed 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
88void 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
92will double filter the waveform {\tt sig} with a previously designed
93filter, given as {\tt numerator}. The filter coefficients can be
94designed using one of the designed functions,
95e.g. \Ref{design_FIR_filter}. Double filtering is performed by
96filtering the signal normally, reversing the waveform, filtering
97again and reversing the waveform again. Normal filtering will impose a
98lag on the signal depending on the order of the filter. By filtering
99the signal forwards and backwards, the lags cancel each other out and
100the 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*/
105void 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
109filtering is needed, first design the required filter using
110\Ref{design_lowpass_filter}, and then use \Ref{FIRfilter} to do the actual
111filtering.
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
120void 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
123filtering is needed, first design the required filter using
124\Ref{design_lowpass_filter}, and then use \Ref{FIRfilter} to do the actual
125filtering.
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
135void 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
139filtering is needed, first design the required filter using
140design_lowpass_filter, and then use FIRfilter to do the actual
141filtering.
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
151void FIRhighpass_filter(EST_Wave &in_sig, int freq, int order);
152
153/** Quick function for one-off high pass filtering. If repeated highpass
154filtering is needed, first design the required filter using
155design_highpass_filter, and then use FIRfilter to do the actual
156filtering.
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*/
166void 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
172Normal low pass filtering (\Ref{FIRlowpass_filter}) introduces a time delay.
173This function filters the signal twice, first forward and then backwards,
174which ensures a zero phase lag. Hence the order parameter need only be
175half 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*/
183void 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
188Normal low pass filtering (\Ref{FIRlowpass_filter}) introduces a time delay.
189This function filters the signal twice, first forward and then backwards,
190which ensures a zero phase lag. Hence the order parameter need only be
191half 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*/
201void 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
206Normal high pass filtering (\Ref{FIRhighpass_filter}) introduces a time delay.
207This function filters the signal twice, first forward and then backwards,
208which ensures a zero phase lag. Hence the order parameter need only be
209half 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*/
217void 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
222Normal high pass filtering (\Ref{FIRhighpass_filter}) introduces a time delay.
223This function filters the signal twice, first forward and then backwards,
224which ensures a zero phase lag. Hence the order parameter need only be
225half 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*/
234void 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
241The linear prediction filters are used for the analysis and synthesis of
242waveforms according the to linear prediction all-pole model.
243
244The linear prediction states that the value of a signal at a given
245point is equal to a weighted sum of the previous P values, plus a
246correction value for that point:
247
248\[s_{n} = \sum_{i=1}^{P} a_{i}.s_{n-i} + e_{n}\]
249
250Given a set of coefficients and the original signal, we can use this
251equation to work out e, the {\it residual}. Conversely given the
252coefficients and the residual signal, an estimation of the original
253signal can be calculated.
254
255If a single set of coefficients were used for the entire waveform, the
256filtering process would be simple. It is usual however to have a
257different set of coefficients for every frame, and there are many
258possible ways to switch from one coefficient set to another so as not
259to cause discontinuities at the frame boundaries.
260*/
261
262//@{
263
264/** Synthesize a signal from a single set of linear prediction
265coefficients 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*/
271void 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
274produce 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
281void inv_lpc_filter(EST_Wave &sig, EST_FVector &a, EST_Wave &res);
282
283/** Synthesize a signal from a track of linear prediction coefficients.
284This function takes a set of LP frames and a residual and produces a
285synthesized signal.
286
287For each frame, the function picks an end point, which is half-way
288between the current frame's time position and the next frame's. A
289start point is defined as being the previous frame's end. Using these
290two values, a portion of residual is extracted and passed to
291\Ref{lpc_filter} along with the LP coefficients for that frame. This
292function writes directly into the signal for the values between start
293and 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
300void lpc_filter_1(EST_Track &lpc, EST_Wave & res, EST_Wave &sig);
301
302/** Synthesize a signal from a track of linear prediction coefficients.
303This function takes a set of LP frames and a residual and produces a
304synthesized signal.
305
306This is functionally equivalent to \Ref{lpc_filter_1} except it
307reduces the residual by 0.5 before filtering. Importantly it is
308about three times faster than \Ref{lpc_filter_1} but in doing so uses
309direct C buffers rather than the neat C++ access function. This
310function should be regarded as temporary and will be deleted after
311we 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
318void lpc_filter_fast(EST_Track &lpc, EST_Wave & res, EST_Wave &sig);
319
320/** Produce a residual from a track of linear prediction coefficients
321and a signal using an overlap add technique.
322
323For each frame, the function estimates the local pitch period and
324picks a start point one period before the current time position and an
325end point one period after it.
326
327A portion of residual corresponding to these times is then produced
328using \Ref{inv_lpc_filter}. The resultant section of residual is then
329overlap-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
336void inv_lpc_filter_ola(EST_Wave &sig, EST_Track &lpc, EST_Wave &res);
337
338//@}
339
340/**@name Pre/Post Emphasis filters.
341
342These functions adjust the spectral tilt of the input waveform.
343
344*/
345
346//@{
347
348/** Pre-emphasis filtering. This performs simple high pass
349filtering with a one tap filter of value {\tt a}. Normal values of a
350range between 0.95 and 0.99. */
351
352void pre_emphasis(EST_Wave &sig, float a=DEFAULT_PRE_EMPH_FACTOR);
353
354/** Pre-emphasis filtering. This performs simple high pass
355filtering with a one tap filter of value {\tt a}. Normal values of a
356range between 0.95 and 0.99. */
357
358
359void 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
363filtering with a one tap filter of value a. Normal values of a range
364between 0.95 and 0.99. The same values of {\tt a} should be used when
365pre- and post-emphasizing the same signal. */
366
367void post_emphasis(EST_Wave &sig, float a=DEFAULT_PRE_EMPH_FACTOR);
368
369/** Post-emphasis filtering. This performs simple low pass
370filtering with a one tap filter of value a. Normal values of a range
371between 0.95 and 0.99. The same values of {\tt a} should be used when
372pre- and post-emphasizing the same signal. */
373
374void post_emphasis(EST_Wave &sig, EST_Wave &out,
375 float a=DEFAULT_PRE_EMPH_FACTOR);
376
377//@}
378
379/**@name Miscellaneous filters.
380
381Some of these filters are non-linear and therefore don't fit the
382normal paradigm.
383
384*/ //@{
385
386/** Filters the waveform by means of median smoothing.
387
388This is a sort of low pass filter which aims to remove extreme values.
389Median smoothing works examining each sample in the wave, taking all
390the values in a window of size {\tt n} around that sample, sorting
391them and replacing that sample with the middle ranking sample in the
392sorted samples.
393
394@param sig waveform to be filtered
395@param n size of smoothing window
396
397*/
398
399void simple_mean_smooth(EST_Wave &c, int n);
400
401//@}
402
403#endif /* __EST_FILTER_H__ */
404