Edinburgh Speech Tools  2.1-release
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
EST_Wave.h
1  /*************************************************************************/
2  /* */
3  /* Centre for Speech Technology Research */
4  /* University of Edinburgh, UK */
5  /* Copyright (c) 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  /* Author : Paul Taylor and Alan W Black */
35  /* Rewritten : Richard Caley */
36  /* ------------------------------------------------------------------- */
37  /* EST_Wave Class header file */
38  /* */
39  /*************************************************************************/
40 
41 #ifndef __Wave_H__
42 #define __Wave_H__
43 
44 #include <cstdio>
45 #include "EST_Featured.h"
46 #include "EST_rw_status.h"
47 #include "EST_types.h"
48 
49 class EST_Track;
50 class EST_String;
51 class EST_TokenStream;
52 
53 
54 /** \class EST_Wave
55  * \brief A class for storing digital waveforms.
56  * The waveform is stored as an array of 16 bit shorts.
57  * Multiple channels are supported, but if no channel information
58  * is given the 0th channel is accessed.
59  *
60  * The waveforms can be of any sample rate, and can be changed to
61  * another sampling rate using the \ref resample function.
62 
63 */
64 class EST_Wave : public EST_Featured
65 {
66 protected:
67  EST_SMatrix p_values;
68 
69  int p_sample_rate;
70 
71  void default_vals(int n=0, int c=1);
72  void free_wave();
73  void copy_data(const EST_Wave &w);
74  void copy_setup(const EST_Wave &w);
75 
76 public:
77 
78  static const int default_sample_rate;
79  static const int default_num_channels;
80 
81  /// default constructor
82  EST_Wave();
83  /// copy constructor
84  EST_Wave(const EST_Wave &a);
85 
86  EST_Wave(int n, int c, int sr);
87 
88  /// Construct from memory supplied by caller
89  EST_Wave(int samps, int chans,
90  short *memory, int offset=0, int sample_rate=default_sample_rate,
91  int free_when_destroyed=0);
92 
93  ~EST_Wave();
94 
95 
96  /**@name Access functions for finding amplitudes of samples */
97  ///@{
98 
99  /** return amplitude of sample <tt>i</tt> from channel <tt>
100  channel</tt>. By default the 0th channel is selected. This
101  function can be used for assignment.
102  */
103  short &a(int i, int channel = 0);
104  short a(int i, int channel = 0) const;
105  INLINE short &a_no_check(int i, int channel = 0)
106  { return p_values.a_no_check(i,channel); }
107  INLINE short a_no_check(int i, int channel = 0) const
108  { return p_values.a_no_check(i,channel); }
109  INLINE short &a_no_check_1(int i, int channel = 0)
110  { return p_values.a_no_check_1(i,channel); }
111  INLINE short a_no_check_1(int i, int channel = 0) const
112  { return p_values.a_no_check_1(i,channel); }
113 
114 
115  /** explicit set_a, easier to wrap than assignment
116  */
117  INLINE short set_a(int i, int channel = 0, short val = 0)
118  { return a(i,channel) = val; }
119 
120  /** return amplitude of sample <tt>i</tt> from channel <tt>
121  channel</tt>. By default the 0th channel is selected.
122  */
123  short operator()(int i, int channel) const
124  { return a(i,channel); }
125 
126  /** return amplitude of sample <tt>i</tt> from channel 0.
127  */
128  short operator()(int i) const
129  { return a(i,0); }
130 
131  /** Version of a() that returns zero if index is out of array
132  bounds. This is particularly useful in signal processing when
133  you want to have windows going off the end of the waveform. */
134  short &a_safe(int i, int channel = 0);
135 
136  /// return the time position in seconds of the ith sample
137  float t(int i) const { return (float)i/(float)p_sample_rate; }
138  ///@}
139 
140  /**@name Information functions */
141  ///@{
142  /// return the number of samples in the waveform
143  int num_samples() const { return p_values.num_rows();}
144  /// return the number of channels in the waveform
145  int num_channels() const { return p_values.num_columns(); }
146  /// return the sampling rate (frequency)
147  int sample_rate() const { return p_sample_rate; }
148  /// Set sampling rate to <tt>n</tt>
149  void set_sample_rate(const int n){p_sample_rate = n;}
150  /// return the size of the waveform, i.e. the number of samples.
151  int length() const { return num_samples();}
152  /// return the time position of the last sample.
153  float end(){ return t(num_samples()-1); }
154 
155  /// Can we look N samples to the left?
156  bool have_left_context(unsigned int n) const
157  { return p_values.have_rows_before(n); }
158 
159  /** returns the file format of the file from which the waveform
160  was read. If the waveform has not been read from a file, this is set
161  to the default type */
162 
163  EST_String sample_type() const { return f_String("sample_type","short"); }
164  void set_sample_type(const EST_String t) { f_set("sample_type", t); }
165 
166  EST_String file_type() const { return f_String("file_type","riff"); }
167  void set_file_type(const EST_String t) { f_set("file_type", t); }
168 
169  /// A string identifying the waveform, commonly used to store the filename
170  EST_String name() const { return f_String("name"); }
171 
172  /// Sets name.
173  void set_name(const EST_String n){ f_set("name", n); }
174 
175  ///@}
176 
177  const EST_SMatrix &values() const { return p_values; }
178  EST_SMatrix &values() { return p_values; }
179 
180  /**@name Waveform manipulation functions */
181  ///@{
182 
183  /// resize the waveform
184  void resize(int num_samples, int num_channels = EST_ALL, int set=1)
185  { p_values.resize(num_samples, num_channels, set); }
186 
187  /// Resample waveform to <tt>rate</tt>
188  void resample(int rate);
189 
190  /** multiply all samples by a factor <tt>gain</tt>. This checks for
191  overflows and puts them to the maximum positive or negative value
192  as appropriate.
193  */
194  void rescale(float gain,int normalize=0);
195 
196  // multiply samples by a factor contour. The factor_contour track
197  // should contains factor targets at time points throughout the wave,
198  // between which linear interpolation is used to calculate the factor
199  // for each sample.
200  void rescale( const EST_Track &factor_contour );
201 
202  /// clear waveform and set size to 0.
203  void clear() {resize(0,EST_ALL);}
204 
205  void copy(const EST_Wave &from);
206 
207  void fill(short v=0, int channel=EST_ALL);
208 
209  void empty(int channel=EST_ALL) { fill(0,channel); }
210 
211  void sample(EST_TVector<short> &sv, int n)
212  { p_values.row(sv, n); }
213  void channel(EST_TVector<short> &cv, int n)
214  { p_values.column(cv, n); }
215 
216  void copy_channel(int n, short *buf, int offset=0, int num=EST_ALL) const
217  { p_values.copy_column(n, buf, offset, num); }
218  void copy_sample(int n, short *buf, int offset=0, int num=EST_ALL) const
219  { p_values.copy_row(n, buf, offset, num); }
220 
221  void set_channel(int n, const short *buf, int offset=0, int num=EST_ALL)
222  { p_values.set_column(n, buf, offset, num); }
223  void set_sample(int n, const short *buf, int offset=0, int num=EST_ALL)
224  { p_values.set_row(n, buf, offset, num); }
225 
226 
227  void sub_wave(EST_Wave &sw,
228  int offset=0, int num=EST_ALL,
229  int start_c=0, int nchan=EST_ALL);
230 
231  void sub_wave(EST_Wave &sw,
232  int offset=0, int num=EST_ALL,
233  int start_c=0, int nchan=EST_ALL) const
234  { ((EST_Wave *)this)->sub_wave(sw, offset, num, start_c, nchan); }
235 
236  ///@}
237 
238  /**@name File i/o functions */
239  ///@{
240 
241  /** Load a file into the waveform. The load routine attempts to
242  automatically determine which file type is being loaded. A
243  portion of the waveform can be loaded by setting
244  `offset` to the sample position from the beginning and
245  `length` to the number of required samples after this. */
246  EST_read_status load(const EST_String filename,
247  int offset=0,
248  int length = 0,
249  int rate = default_sample_rate);
250 
251  EST_read_status load(EST_TokenStream &ts,
252  int offset=0,
253  int length = 0,
254  int rate = default_sample_rate);
255 
256  EST_read_status load(const EST_String filename,
257  const EST_String filetype,
258  int offset=0,
259  int length = 0,
260  int rate = default_sample_rate);
261 
262  EST_read_status load(EST_TokenStream &ts,
263  const EST_String filetype,
264  int offset=0,
265  int length = 0,
266  int rate = default_sample_rate);
267 
268  /** Load a file of type `filetype` into the waveform. This
269  can be used to load unheadered files, in which case the fields
270  `sample_rate`, `sample_type`, `bo` and `nc` are used
271  to specify the sample rate, type, byte order and number of
272  channels. A portion of the waveform can be loaded by setting
273  `offset` to the sample position from the beginning and
274  `length` to the number of required samples after this.
275  */
276  EST_read_status load_file(const EST_String filename,
277  const EST_String filetype, int sample_rate,
278  const EST_String sample_type, int bo, int nc,
279  int offset = 0, int length = 0);
280  EST_read_status load_file(EST_TokenStream &ts,
281  const EST_String filetype, int sample_rate,
282  const EST_String sample_type, int bo, int nc,
283  int offset = 0, int length = 0);
284 
285  /** Save waveform to a file called `filename` of file
286  format `EST_filetype`.
287  */
288  EST_write_status save(const EST_String filename,
289  const EST_String EST_filetype = "");
290 
291  EST_write_status save(FILE *fp,
292  const EST_String EST_filetype = "");
293 
294  EST_write_status save_file(const EST_String filename,
295  EST_String filetype,
296  EST_String sample_type, int bo, const char *mode = "wb");
297 
298  EST_write_status save_file(FILE *fp,
299  EST_String filetype,
300  EST_String sample_type, int bo);
301 
302  EST_write_status save_file_header(FILE *fp,
303  EST_String ftype,
304  EST_String stype, int obo);
305  EST_write_status save_file_data(FILE *fp,
306  EST_String ftype,
307  EST_String stype, int obo);
308  //@}
309 
310  /// Assignment operator
311  EST_Wave& operator = (const EST_Wave& w);
312  /** Add to existing wave in serial. Waveforms must have the same
313  number of channels.
314  */
315  EST_Wave& operator +=(const EST_Wave &a);
316  /** Add wave in parallel, i.e. make wave <tt>a</tt> become new
317  channels in existing waveform.
318  */
319  EST_Wave& operator |=(const EST_Wave &a);
320 
321  /// print waveform
322  friend ostream& operator << (ostream& p_values, const EST_Wave &sig);
323 
324  // integrity check *** debug
325  void integrity() const { p_values.integrity() ; }
326 
327 };
328 
330 
331 int operator != (EST_Wave a, EST_Wave b);
332 int operator == (EST_Wave a, EST_Wave b);
333 
334 #endif /* __Wave_H__ */
INLINE const T & a_no_check(int row, int col) const
const access with no bounds check, care recommend
Definition: EST_TMatrix.h:183
A class for storing digital waveforms. The waveform is stored as an array of 16 bit shorts...
Definition: EST_Wave.h:64
EST_read_status load(const EST_String filename, int offset=0, int length=0, int rate=default_sample_rate)
Definition: EST_Wave.cc:178
EST_Wave & operator+=(const EST_Wave &a)
Definition: EST_Wave.cc:579
void set_sample_rate(const int n)
Set sampling rate to n
Definition: EST_Wave.h:149
void column(EST_TVector< T > &cv, int c, int start_r=0, int len=-1)
Make the vector cv a window onto column c
Definition: EST_TMatrix.cc:556
int num_columns() const
return number of columns
Definition: EST_TMatrix.h:180
int length() const
return the size of the waveform, i.e. the number of samples.
Definition: EST_Wave.h:151
void row(EST_TVector< T > &rv, int r, int start_c=0, int len=-1)
Make the vector rv a window onto row r
Definition: EST_TMatrix.cc:534
void copy_column(int c, T *buf, int offset=0, int num=-1) const
Definition: EST_TMatrix.cc:420
void set_name(const EST_String n)
Sets name.
Definition: EST_Wave.h:173
void rescale(float gain, int normalize=0)
Definition: EST_Wave.cc:501
INLINE short set_a(int i, int channel=0, short val=0)
Definition: EST_Wave.h:117
EST_write_status save(const EST_String filename, const EST_String EST_filetype="")
Definition: EST_Wave.cc:350
EST_Wave()
default constructor
Definition: EST_Wave.cc:61
EST_Wave & operator=(const EST_Wave &w)
Assignment operator.
Definition: EST_Wave.cc:573
int num_channels() const
return the number of channels in the waveform
Definition: EST_Wave.h:145
float t(int i) const
return the time position in seconds of the ith sample
Definition: EST_Wave.h:137
int num_samples() const
return the number of samples in the waveform
Definition: EST_Wave.h:143
bool have_left_context(unsigned int n) const
Can we look N samples to the left?
Definition: EST_Wave.h:156
short & a(int i, int channel=0)
Definition: EST_Wave.cc:126
short operator()(int i) const
Definition: EST_Wave.h:128
EST_String name() const
A string identifying the waveform, commonly used to store the filename.
Definition: EST_Wave.h:170
friend ostream & operator<<(ostream &p_values, const EST_Wave &sig)
print waveform
Definition: EST_Wave.cc:623
float end()
return the time position of the last sample.
Definition: EST_Wave.h:153
void resize(int num_samples, int num_channels=EST_ALL, int set=1)
resize the waveform
Definition: EST_Wave.h:184
short & a_safe(int i, int channel=0)
Definition: EST_Wave.cc:150
int sample_rate() const
return the sampling rate (frequency)
Definition: EST_Wave.h:147
EST_read_status load_file(const EST_String filename, const EST_String filetype, int sample_rate, const EST_String sample_type, int bo, int nc, int offset=0, int length=0)
Definition: EST_Wave.cc:286
void copy_row(int r, T *buf, int offset=0, int num=-1) const
Definition: EST_TMatrix.cc:381
Template vector.
Definition: EST_TVector.h:145
void set_row(int n, const T *buf, int offset=0, int num=-1)
Definition: EST_TMatrix.cc:466
void resize(int rows, int cols, int set=1)
resize matrix
EST_Wave & operator|=(const EST_Wave &a)
Definition: EST_Wave.cc:603
void clear()
clear waveform and set size to 0.
Definition: EST_Wave.h:203
int num_rows() const
return number of rows
Definition: EST_TMatrix.h:178
void resample(int rate)
Resample waveform to rate
Definition: EST_Wave.cc:487
EST_String sample_type() const
Definition: EST_Wave.h:163
short operator()(int i, int channel) const
Definition: EST_Wave.h:123
void set_column(int n, const T *buf, int offset=0, int num=-1)
Definition: EST_TMatrix.cc:478