Edinburgh Speech Tools  2.4-release
doc/estlicence.md
1 Licence, Installation and acknowledgements {#estlicence}
2 =====================================
3 
4 [TOC]
5 
6 # Licence {#licence}
7 Since version 1.2.0 we are distributing the Edinburgh Speech Tools
8 under a free software lince similar to the X11 one. Basically the
9 system is free for anyone to use commercially or otherwise
10 without further permission.
11 
12 
13 Hence the current copy policy is
14 
15  Centre for Speech Technology Research
16  University of Edinburgh, UK
17  Copyright (c) 1994-1999
18  All Rights Reserved.
19 
20  Permission is hereby granted, free of charge, to use and distribute
21  this software and its documentation without restriction, including
22  without limitation the rights to use, copy, modify, merge, publish,
23  distribute, sublicense, and/or sell copies of this work, and to
24  permit persons to whom this work is furnished to do so, subject to
25  the following conditions:
26  1. The code must retain the above copyright notice, this list of
27  conditions and the following disclaimer.
28  2. Any modifications must be clearly marked as such.
29  3. Original authors' names are not deleted.
30  4. The authors' names are not used to endorse or promote products
31  derived from this software without specific prior written
32  permission.
33 
34  THE UNIVERSITY OF EDINBURGH AND THE CONTRIBUTORS TO THIS WORK
35  DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
36  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT
37  SHALL THE UNIVERSITY OF EDINBURGH NOR THE CONTRIBUTORS BE LIABLE
38  FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
39  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
40  AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
41  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
42  THIS SOFTWARE.
43 
44 
45 # Acknowledgments {#estacknowledgements}
46 
47 ## Copyright
48 
49  - 1994-1999, Centre for Speech Technology, University of Edinburgh
50 
51 ## Authors
52 
53  - [Paul Taylor](http://www.cstr.ed.ac.uk/~pault)
54  - [Richard Caley](http://www.cstr.ed.ac.uk/~rjc)
55  - [Alan W. Black](http://www.cstr.ed.ac.uk/~awb)
56  - [Simon King](http://www.cstr.ed.ac.uk/~simonk)
57 
58 
59 During 1994-1999, the above people were supported by the UK Physical
60 Science and Engineering Research Council though grants GR/J55106,
61 GR/K54229, GR/L53250, by Sun microsystems, AT&T and Reuters.
62 
63 ### Other contributors
64 
65 We are extremely grateful to the following people who have made their
66 code available for general use. We should make it clear that these
67 people did not directly participate in the development of the library
68 and hence cannot be held responsible for any problems we have introduced
69 in the use of their code.
70 
71  - **Markus Mummer**: Waveform re-sampling routine (rateconv)
72  - **Tony Robinson**: Provided cepstral and LPC routines
73  - **Richard Tobin and LTG**: RXP, an XML parser.
74  - **Paul Bagshaw**: The pitch tracker
75  - **Craig Reese and John Campbell**: ulaw conversion routines
76  - **Paradigm Associates and George Carrett**: Scheme in one defun.
77  - **Theo Veenker (Utrecht University)**: IRIX audio support.
78  - **Rick Woudenberg**: Inspiration for the design of the wave class
79  - **Borja Etxebarria**: LPC reflection coefficients
80  - **Simmule Turner and Rich Salz**: editline command line editing library
81  - **Henry Spencer**: for his regex code taken from the FreeBSD 2.1.5 distribution.
82  - **The Regents of the University of California**: for some string comparison code.
83 
84 
85 # What is new {#estwhatsnew}
86 
87 Since the last public release, 1.1.1, January 1999, there have been
88 a number of enhancements to the library system
89 
90 ## Free licence
91 
92 To make the system more useful for more people and place
93 it properly in the free software community the system is now free
94 for both commercial and non-commercial use alike.
95 
96 ## Utterance consolidation
97 
98 A number of tidy ups have been performed on the
99 `EST_Utterance` and related classes. This makes
100 the interface cleaner and should have littel affect on existsing code.
101 
102 ## Generalization of Features
103 
104 Any new object can become a feature value after simple registration
105 of the object through a provided macro. We also make much
106 more use of this.
107 
108 ## SIOD tidy up
109 
110 Scheme is no longer "in one defun" but "in one directory". The
111 system was split out into separate files. New objects are now
112 held as `EST_Val` and it is easier to add new
113 objects to the system.
114 
115 ## C++ class documentation
116 
117 We now include documentation on a per class basis using
118 doxygen and markdown for more general
119 descriptions and examples. This has improved the coverage and quality
120 of low level documentation for all classes in the system.
121 
122 ## Tilt Analysis/Resynthesis
123 
124 For intonation analysis the tilt code has been completely rewritten.
125 
126 
127 
128 # Installation {#estinstall}
129 
130 ## Release notes {#estinstallrnotes}
131 
132 While previous versions of the speech tools were primarily released solely
133 to support the Festival Speech Synthesis System, the Edinburgh Speech
134 Tools Library now contains sufficiently useful tools that it is of use
135 in its own right.
136 
137 Although hope that the speech tools has stabilised to a certain extent
138 and less structural changes will occur in future versions we don't
139 guarantee future compatibility, although every effort will be made to
140 make upgrading as easy as possible. In addition, we warn that while
141 several programs and routines are quite mature, others are young and
142 have not be rigorously tested. Please do not assume these programs work.
143 
144 ## Requirements {#estinstallreq}
145 
146 In order to compile and install the Edinburgh Speech Tools you
147 need the following
148 
149 ### GNU Make
150 
151  Any recent version, the various `make`
152  programs that come with different UNIX systems are wildly
153  varying and hence it makes it too difficult to write
154  Makefiles which are portable, so we
155  depend on a version of `make` which is
156  available for all of the platforms we are aiming at.
157 
158 ### A C++ compiler
159 
160 The system was developed primarily with GNU C++ version 2.7.2, but
161 we also have compiled it successfully with a number of
162 other versions of gcc, Sun CC and Visual C.
163 
164 Hopefully we have now sanitized the code sufficiently to to make it
165 possible for ports to other C++ compilers without too much difficulty.
166 But please note C++ is not a fully standardized language and each
167 compiler follows the incomplete standard to various degrees. Often
168 there are many but simple problems when porting to new C++ compilers.
169 We are trying to deal with this by increasing our support. However, it
170 is likely that small changes will be required for C++ compilers we have
171 not yet tested the system under.
172 
173 However we feel this is stable enough to make it worthwhile attempting
174 ports to other C++ compilers that we haven't tried yet.
175 
176 Before installing the speech tools it is worth ensuring you have a fully
177 installed and working version of your C++ compiler. Most of the
178 problems people have had in installing the speech tools have been due to
179 incomplete or bad compiler installation. It might be worth checking if
180 the following program works, if you don't know if anyone has used your
181 C++ installation before.
182 
183  #include <iostream>
184  int main (int argc, char **argv)
185  {
186  std::cout << "Hello world\n";
187  }
188 
189 
190 ### Supported Systems
191 
192 We have successfully compiled and tested the speech tools on the
193 following systems, except where specified we include support for
194 both shared and static versions of the libraries:
195 
196  - *Sun Sparc Solaris 2.5.1/2.6/2.7*: GCC 2.7.2, GCC 2.8.1, SunCC 4.1, egcs 1.1.1, egcs 1.1.2
197  - *Sun Sparc SunOS 4.1.3*: GCC 2.7.2 (static only)
198  - *Intel Solaris 2.5.1*: GCC 2.7.2
199  - *FreeBSD for Intel 2.1.7, 2.2.1, 2.2.6 (aout), 2.2.8 (aout), 3.x (elf)*: GCC 2.7.2.1 (static only)
200  - *Linux (2.0.30) for Intel (RedHat 4.[012]/5.[01]/6.0)*: GCC 2.7.2, GCC 2.7.2/egcs-1.0.2, egcs-1.1.2
201  - *Windows NT 4.0*, *Windows95*, *Windows 98*: GCC with egcs (from [cygwin](http://www.cygwin.com/) b20.1), VisualC; 5.0. (static only)
202 
203 
204 As stated before, C++ compilers are not standard and it is non-trivial to
205 find the correct dialect which compiles under all. We recommend the
206 use of GCC 2.7.2 if you can use it, it is the most likely one to
207 work. Some of the compilers listed above produce a large number of
208 warnings when compileing the code.
209 
210 Previous versions of the system have successfully compiled under SGI
211 IRIX 5.3, OSF (Alphas) and HPUX but at time of writing this we have not
212 yet rechecked this version.
213 
214 ### Java Support
215 
216 The *java* directory contains optional Java
217 classes which give some access to *speech tools* facilities from Java
218 programs. This has been created to support the *fringe* graphical
219 interface. There are two levels of support enabled by the
220 *JAVA* and *JAVA_CPP* options in the
221 `config` file. *JAVA* compiles some
222 very basic classes intended to allow very simple simulation of *speech tools*
223 facilities in pure programs. *JAVA_CPP*
224 compiles classes which use the Java native interface to provide
225 access to the actual *speech tools* C++ classes.
226 
227 ### Windows 95/98/NT Port
228 
229 We have done two ports of this code to Windows machines, one uses the
230 *cygwin* package, which provides a Unix like environment under on
231 Win32 systems, the other is a native port using *VisualC*.
232 
233 For our full *Windows NT* and *Windows 95/98* ports we use the Cygnus Cygwin environment (version b20.1) available from [http://cygwin.com/].
234 *Windows 98* is significantly more stable than *Windows 95*, especially
235 when many processes are started and stopped as is the case when
236 compiling with Cygwin. We **strongly** reccomend 98
237 rather than 95 be used if at all possible. However with both 95 and 98
238 you can expect Windows to occasionally lock up or complain it is
239 unable to start new processes or otherwise missbehave. You will be
240 restarting windows regularly. A Windows NT system should not have
241 these problems.
242 
243 The port using Visual C does not
244 provide all of the features of the Unix and Cygwin versions. You
245 will need access to a Unix or Cygwin system to create the makefiles
246 used for the Visual C compilation.
247 
248 
249 Both Cygwin and Visual C ports have a number of limitations.
250 
251 #### Shared library creation is not supported
252 Creation of Windows *DLLs* is different
253 enough from creation of Unix shared libraries that the
254 support does not carry directly accross, and we haven't
255 yet had time to work on it.
256 
257 #### Java not supported
258 Because the Java support is related to the creation of
259 shared libraries, this is also not yet implemented for
260 Windows.
261 
262 #### Command line editing limited
263 Because of the limiots of the Windows DOS console
264  window, the command line editing in
265  *siod* is less reliable (for instance
266  on very long lines).
267 
268 #### (Visual C) Networking not supported
269 Networking under Win32 is different from Unix in a
270 number of fairly fundamental ways, we haven't tackled
271 this at all.
272 
273 There are no doubt other differences we have not noticed. We don't use
274 Windows for any of our work and so the Windows builds of our systems
275 don't get the extensive use the UNIX builds do.
276 
277 ## Building speech tools {#estinstallbuild}
278 
279 ### Configuration
280 
281 All compile-time configuration for the system is done through the user
282 definable file *config/config*. You must create this
283 file before you can compile the library. An example is given in
284 *config/config-dist*, copy it and change its permissions
285 to give write access
286 
287  cd config
288  cp config-dist config
289  chmod +w config
290 
291 In many cases no further changes will be required, but it might
292 be worth checking the contents of this file just in case. Where
293 possible the system will automatically config itself.
294 
295 
296 Type
297 
298  gnumake info
299 
300 
301 This will create the local config files and display what it
302 thinks your system is.
303 
304 
305 If this is not suitable for your machine then
306 edit your *config/config*. In most cases
307 the default will be the best option. If you are unsure about
308 what you should change you probabaly shouldn't change anything.
309 
310 
311 As of 1.3.1 due to conflicts in copyright we have dropped *GNU Readline*
312 support and replaced it with a differently licenced alternative which
313 does not imposes the restrictions of the GPL. *editline* is a free
314 command line editor library. We have added substantially to it,
315 including support for long lines, incremental search and completion.
316 However as it has not yet been tested on many systems it is still
317 optional, though is on by default.
318 
319 For Linux we now fully support shared libraries and even recommend
320 them. However if you are going to do a lot of development and
321 don't understand the consequences of shared libraries and getting
322 *LD_LIBRARY_PATH* correct (or what that is) we
323 recommend you compile unshared, the default. If you are going to
324 simply run the speech tools (and festival) then shared is a reasonable
325 option. Uncomment the line in the *config/config* file:
326 
327  # SHARED = 1
328 
329 Shared support under Solaris is complete for all the speech tools.
330 If you need to exec festival scripts using a version of
331 festival built with shared libaries, you must either execute
332 them from a featureful shell (e.g. *bash*),
333 install the shared libraries in a standard place or explicitly
334 set *LD_LIBRARY_PATH*. Solaris's standard
335 shell doesn't support script excutaiton of shells within shells.
336 
337 Simple choices for common set ups are given near the top of this
338 file. But for some sub-systems you will also need to change pathnames for
339 external library support.
340 
341 
342 At present read *config/ReadMe* for details of changing
343 basic configuration.
344 
345 
346 On systems (and versions of systems) we have not yet encountered
347 you may need to create `config/systems/<PROCESSOR>_<OS><OSVERSION>.mak`
348 files. Often you need only copy an existing one (other version or
349 similar system) to get it to work. Typically the only real differences
350 are when there are major differences in the default C++ compiler
351 (e.g. RedHat 5.0 to RedHat 5.1). If you do need to add a new
352 systems configuration file please let as know so we can include it
353 in the standard distribution.
354 
355 ### Compilation
356 
357 Once you have configured *config/config* you
358 can compile the system.
359 
360  gnumake
361 
362 Note this must be **gnumake**, which may be called *make* on
363 your system, or *gmake* or *gnumake*. This will compile all
364 library functions and all the executables. If you wish to only compile
365 the library itself then use
366 
367  gnumake make_library
368 
369 Note that if you compile with *-g* (uncommenting *DEBUG = 1*
370 is *config/config* the library and the corresponding binaries will
371 be large. Particulary the executables, you will need in order of 150
372 megabytes to compile the system, if your C++ libraries are not compiled
373 as shared libraries. If you compile without *-g* the whole library
374 directory is about 12 megabytes on Linux (which has shared libraries for
375 *libstdc++* or about 26 megabytes of Sparc Solaris (which does not
376 have a shared library *libstdc++* by default). This is almost
377 entirely due to the size of the executables. C++ does not make small
378 binaries.
379 
380 
381 In general we have made the system compile with no warnings. However
382 for some compilers this has proved to be near impossible. SunOS include
383 files have a number of system declarations missing, so many system functions
384 (e.g. *fprintf*) will appear to be undeclared. Sun's CC compiler
385 also likes to complain about missing source for some code even though
386 the code exists within our system and is deliberately in separate files
387 ro make it modular.
388 
389 
390 To test the system after compilation
391 
392  gnumake test
393 
394 ## Installation {#estinstallinstalling}
395 
396 
397 All executables are linked to from *speech_tools/bin* and you
398 should add that to your *PATH* in order to use them.
399 
400 
401 Include files are *speech_tools/include/* and the three
402 generated libraries are *speech_tools/lib/libestools.a*,
403 *speech_tools/lib/libestbase.a* and
404 *speech_tools/lib/libestring.a*. For most cases the three
405 will be required.
406 
407 
408 If space is a preminium, compiled with the shared option (binaries
409 will be then be substantially smaller) and you can delete all
410 *.o* files.
411 
412 Some aspects of the system have further dependencies which depend
413 of the option selected at compile time. Specifically the readline
414 libraries and Netaudio libraries.
415 
416 
417 ## Building on Windows 95/98/NT {#estinstallbuildwind}
418 
419 There are two ways to build the system under Windows. The
420 Cygwin system provides a unix-like
421 environment in which you can perform a compilation as described in the
422 previous sections. Cygwin is probably the
423 best choice if you can use that route.
424 
425 
426 Visual C provides an environment much further from the Unix systems
427 our code is developed on, this places some limits on the Visual C port,
428 especially in areas relating to networking. The remainder of this
429 section describes how to compile with Visual C.
430 
431 ### Creating *VCMakefile*
432 
433 We compile using the *nmake* program which comes with
434 Visual C. This is a fairly standard *make*
435 implementation, but is not as flexible as the *GNU make*
436 we use for our normal builds. So, in order to
437 compile with *nmake* new *Makefile* files
438 are needed. These can be created from the Unix makefiles using
439 
440  gnumake VCMakefile
441  Creating VCMakefile for .
442  Creating VCMakefile for include
443  Creating VCMakefile for include/unix
444  [...]
445 
446 Obviously you will need either a unix machine or the
447 Cygwin system to do this. Sharing the
448 compilation directory between unix and Windows machines, for instance
449 using *samba*.
450 
451 
452 ### Configuration
453 
454 As for unix compilations, the Visual C compilation process is
455 controlled by a configuration file. In this case it is called
456 *vc_config_make_rules*. A version is included in
457 the distribution, as *vc_config_make_rules-dist*,
458 copy this into place as follows:
459 
460  cd config
461  cp vc_config_make_rules-dist vc_config_make_rules
462  chmod +w vc_config_make_rules
463 
464 You probably don't need to change this default configuration.
465 
466 ### Building
467 
468 To build the system:
469 
470  nmake /nologo /fVCMakefile
471 
472 This should build the libraries and executables, and also the test
473 programs in *testsuite*. However there is currently
474 no way to automatically test the system, Indeed some of the test
475 programs will fail under Visual C due to differences in file nameing
476 conventions.
477 
478