1Installation 2************ 3 4 This section describes how to install Festival from source in a new 5location and customize that installation. 6 7* Menu: 8 9* Requirements:: Software/Hardware requirements for Festival 10* Configuration:: Setting up compilation 11* Site initialization:: Settings for your particular site 12* Checking an installation:: But does it work ... 13 14Requirements 15============ 16 17 In order to compile Festival you first need the following source 18packages 19 20`festival-2.4-release.tar.gz' 21 Festival Speech Synthesis System source 22 23`speech_tools-2.4-release.tar.gz' 24 The Edinburgh Speech Tools Library 25 26`festlex_NAME.tar.gz' 27 The lexicon distribution, where possible, includes the lexicon 28 input file as well as the compiled form, for your convenience. 29 The lexicons have varying distribution policies, but are all free 30 except OALD, which is only free for non-commercial use (we are 31 working on a free replacement). In some cases only a pointer to 32 an ftp'able file plus a program to convert that file to the 33 Festival format is included. 34 35`festvox_NAME.tar.gz' 36 You'll need a speech database. A number are available (with 37 varying distribution policies). Each voice may have other 38 dependencies such as requiring particular lexicons 39 40`festdoc_2.0.tar.gz' 41 Full postscript, info and html documentation for Festival and the 42 Speech Tools. The source of the documentation is available in the 43 standard distributions but for your conveniences it has been 44 pre-generated. 45 46 In addition to Festival specific sources you will also need 47 48_A UNIX machine_ 49 Currently we have compiled and tested the system under Solaris 50 (2.5(.1), 2.6, 2.7, 2.8 and 2.9), SunOS (4.1.3), FreeBSD 3.x, 4.x Linux 51 (Redhat 4.1, 5.0, 5.1, 5.2, 6.[012], 7.[01], 8.0, 9, FC1 and other Linux 52 distributions), and it should work under OSF (Dec Alphas) SGI 53 (Irix), HPs (HPUX). But any standard UNIX machine should be 54 acceptable. We have now successfully ported this version to 55 Windows XP, Windows NT and Windows 95 (using the Cygnus GNU win32 56 environment). This is still a young port but seems to work. 57 58_A C++ compiler_ 59 Note that C++ is not very portable even between different versions 60 of the compiler from the same vendor. Although we've tried very 61 hard to make the system portable, we know it is very unlikely to 62 compile without change except with compilers that have already 63 been tested. The currently tested systems are 64 * Sun Sparc Solaris 2.5, 2.5.1, 2.6, 2.7, 2.9: GCC 2.95.1, GCC 65 3.2 66 67 * FreeBSD for Intel 3.x and 4.x GCC 2.95.1, GCC 3.0 68 69 * Linux for Intel (RedHat 4.1/5.0/5.1/5.2/6.0/7.x/8.0): GCC 70 2.7.2, GCC 2.7.2/egcs-1.0.2, egcs 1.1.1, egcs-1.1.2, GCC 71 2.95.[123], GCC "2.96", GCC 3.0, GCC 3.0.1, GCC 3.2, GCC 3.2.1 72 GCC 3.2.3, GCC 3.3.2 73 74 * Windows NT 4.0: GCC 2.7.2 plus egcs (from Cygnus GNU win32 75 b19), Visual C++ PRO v5.0, Visual C++ v6.0 76 Note if GCC works on one version of Unix it usually works on 77 others. 78 79 We have compiled both the speech tools and Festival under Windows 80 NT 4.0 and Windows 95 using the GNU tools available from Cygnus. 81 http://www.cygwin.com/ 82 83_GNU make_ 84 Due to there being too many different `make' programs out there we 85 have tested the system using GNU make on all systems we use. 86 Others may work but we know GNU make does. 87 88_Audio hardware_ 89 You can use Festival without audio output hardware but it doesn't 90 sound very good (though admittedly you can hear less problems with 91 it). A number of audio systems are supported (directly inherited 92 from the audio support in the Edinburgh Speech Tools Library): 93 NCD's NAS (formerly called netaudio) a network transparent audio 94 system (which can be found at 95 `ftp://ftp.x.org/contrib/audio/nas/'); `/dev/audio' (at 8k ulaw 96 and 8/16bit linear), found on Suns, Linux machines and FreeBSD; 97 and a method allowing arbitrary UNIX commands. *Note Audio 98 output::. 99 100 Earlier versions of Festival mistakenly offered a command line editor 101interface to the GNU package readline, but due to conflicts with the GNU 102Public Licence and Festival's licence this interface was removed in 103version 1.3.1. Even Festival's new free licence would cause problems as 104readline support would restrict Festival linking with non-free code. A 105new command line interface based on editline was provided that offers 106similar functionality. Editline remains a compilation option as it is 107probably not yet as portable as we would like it to be. 108 109 In addition to the above, in order to process the documentation you 110will need `TeX', `dvips' (or similar), GNU's `makeinfo' (part of the 111texinfo package) and `texi2html' which is available from 112`http://wwwcn.cern.ch/dci/texi2html/'. 113 114 However the document files are also available pre-processed into, 115postscript, DVI, info and html as part of the distribution in 116`festdoc-1.4.X.tar.gz'. 117 118 Ensure you have a fully installed and working version of your C++ 119compiler. Most of the problems people have had in installing Festival 120have been due to incomplete or bad compiler installation. It might be 121worth checking if the following program works if you don't know if 122anyone has used your C++ installation before. 123 #include <iostream.h> 124 int main (int argc, char **argv) 125 { 126 cout << "Hello world\n"; 127 } 128 129 Unpack all the source files in a new directory. The directory will 130then contain two subdirectories 131 speech_tools/ 132 festival/ 133 134Configuration 135============= 136 137 First ensure you have a compiled version of the Edinburgh Speech 138Tools Library. See `speech_tools/INSTALL' for instructions. 139 140 The system now supports the standard GNU `configure' method for set 141up. In most cases this will automatically configure festival for your 142particular system. In most cases you need only type 143 gmake 144 and the system will configure itself and compile, (note you need to 145have compiled the Edinburgh Speech Tools `speech_tools-1.2.4' first. 146 147 In some case hand configure is require. All of the configuration 148choice are held in the file `config/config' 149 150 For the most part Festival configuration inherits the configuration 151from your speech tools config file (`../speech_tools/config/config'). 152Additional optional modules may be added by adding them to the end of 153your config file e.g. 154 ALSO_INCLUDE += clunits 155 Adding and new module here will treat is as a new directory in the 156`src/modules/' and compile it into the system in the same way the 157`OTHER_DIRS' feature was used in previous versions. 158 159 If the compilation directory being accessed by NFS or if you use an 160automounter (e.g. amd) it is recommend to explicitly set the variable 161`FESTIVAL_HOME' in `config/config'. The command `pwd' is not reliable 162when a directory may have multiple names. 163 164 There is a simple test suite with Festival but it requires the three 165basic voices and their respective lexicons install before it will work. 166Thus you need to install 167 festlex_CMU.tar.gz 168 festlex_OALD.tar.gz 169 festlex_POSLEX.tar.gz 170 festvox_don.tar.gz 171 festvox_kedlpc16k.tar.gz 172 festvox_rablpc16k.tar.gz 173 If these are installed you can test the installation with 174 gmake test 175 176 To simply make it run with a male US English voiuce it is sufficient 177to install just 178 festlex_CMU.tar.gz 179 festlex_POSLEX.tar.gz 180 festvox_kallpc16k.tar.gz 181 182 Note that the single most common reason for problems in compilation 183and linking found amongst the beta testers was a bad installation of GNU 184C++. If you get many strange errors in G++ library header files or link 185errors it is worth checking that your system has the compiler, header 186files and runtime libraries properly installed. This may be checked by 187compiling a simple program under C++ and also finding out if anyone at 188your site has ever used the installation. Most of these installation 189problems are caused by upgrading to a newer version of libg++ without 190removing the older version so a mixed version of the `.h' files exist. 191 192 Although we have tried very hard to ensure that Festival compiles 193with no warnings this is not possible under some systems. 194 195 Under SunOS the system include files do not declare a number of 196system provided functions. This a bug in Sun's include files. This 197will causes warnings like "implicit definition of fprintf". These are 198harmless. 199 200 Under Linux a warning at link time about reducing the size of some 201symbols often is produced. This is harmless. There is often 202occasional warnings about some socket system function having an 203incorrect argument type, this is also harmless. 204 205 The speech tools and festival compile under Windows95 or Windows NT 206with Visual C++ v5.0 using the Microsoft `nmake' make program. We've 207only done this with the Professional edition, but have no reason to 208believe that it relies on anything not in the standard edition. 209 210 In accordance to VC++ conventions, object files are created with 211extension .obj, executables with extension .exe and libraries with 212extension .lib. This may mean that both unix and Win32 versions can be 213built in the same directory tree, but I wouldn't rely on it. 214 215 To do this you require nmake Makefiles for the system. These can be 216generated from the gnumake Makefiles, using the command 217 gnumake VCMakefile 218 in the speech_tools and festival directories. I have only done this 219under unix, it's possible it would work under the cygnus gnuwin32 220system. 221 222 If `make.depend' files exist (i.e. if you have done `gnumake depend' 223in unix) equivalent `vc_make.depend' files will be created, if not the 224VCMakefiles will not contain dependency information for the `.cc' 225files. The result will be that you can compile the system once, but 226changes will not cause the correct things to be rebuilt. 227 228 In order to compile from the DOS command line using Visual C++ you 229need to have a collection of environment variables set. In Windows NT 230there is an installation option for Visual C++ which sets these 231globally. Under Windows95 or if you don't ask for them to be set 232globally under NT you need to run 233 vcvars32.bat 234 See the VC++ documentation for more details. 235 236 Once you have the source trees with VCMakefiles somewhere visible 237from Windows, you need to copy `peech_tools\config\vc_config-dist' to 238`speech_tools\config\vc_config' and edit it to suit your local 239situation. Then do the same with `festival\config\vc_config-dist'. 240 241 The thing most likely to need changing is the definition of 242`FESTIVAL_HOME' in `festival\config\vc_config_make_rules' which needs 243to point to where you have put festival. 244 245 Now you can compile. cd to the speech_tools directory and do 246 nmake /nologo /fVCMakefile 247and the library, the programs in main and the test programs should be 248 compiled. 249 250 The tests can't be run automatically under Windows. A simple test to 251check that things are probably OK is: 252 main\na_play testsuite\data\ch_wave.wav 253which reads and plays a waveform. 254 Next go into the festival directory and do 255 nmake /nologo /fVCMakefile 256to build festival. When it's finished, and assuming you have the 257 voices and lexicons unpacked in the right place, festival should run 258just as under unix. 259 260 We should remind you that the NT/95 ports are still young and there 261may yet be problems that we've not found yet. We only recommend the 262use the speech tools and Festival under Windows if you have significant 263experience in C++ under those platforms. 264 265 Most of the modules `src/modules' are actually optional and the 266system could be compiled without them. The basic set could be reduced 267further if certain facilities are not desired. Particularly: `donovan' 268which is only required if the donovan voice is used; `rxp' if no XML 269parsing is required (e.g. Sable); and `parser' if no stochastic paring 270is required (this parser isn't used for any of our currently released 271voices). Actually even `UniSyn' and `UniSyn_diphone' could be removed 272if some external waveform synthesizer is being used (e.g. MBROLA) or 273some alternative one like `OGIresLPC'. Removing unused modules will 274make the festival binary smaller and (potentially) start up faster but 275don't expect too much. You can delete these by changing the 276`BASE_DIRS' variable in `src/modules/Makefile'. 277 278Site initialization 279=================== 280 281 Once compiled Festival may be further customized for particular 282sites. At start up time Festival loads the file `init.scm' from its 283library directory. This file further loads other necessary files such 284as phoneset descriptions, duration parameters, intonation parameters, 285definitions of voices etc. It will also load the files `sitevars.scm' 286and `siteinit.scm' if they exist. `sitevars.scm' is loaded after the 287basic Scheme library functions are loaded but before any of the 288festival related functions are loaded. This file is intended to set 289various path names before various subsystems are loaded. Typically 290variables such as `lexdir' (the directory where the lexicons are held), 291and `voices_dir' (pointing to voice directories) should be reset here 292if necessary. 293 294 The default installation will try to find its lexicons and voices 295automatically based on the value of `load-path' (this is derived from 296`FESTIVAL_HOME' at compilation time or by using the `--libdir' at 297run-time). If the voices and lexicons have been unpacked into 298subdirectories of the library directory (the default) then no site 299specific initialization of the above pathnames will be necessary. 300 301 The second site specific file is `siteinit.scm'. Typical examples 302of local initialization are as follows. The default audio output method 303is NCD's NAS system if that is supported as that's what we use normally 304in CSTR. If it is not supported, any hardware specific mode is the 305default (e.g. sun16audio, freebas16audio, linux16audio or mplayeraudio). 306But that default is just a setting in `init.scm'. If for example in 307your environment you may wish the default audio output method to be 8k 308mulaw through `/dev/audio' you should add the following line to your 309`siteinit.scm' file 310 (Parameter.set 'Audio_Method 'sunaudio) 311 Note the use of `Parameter.set' rather than `Parameter.def' the 312second function will not reset the value if it is already set. 313Remember that you may use the audio methods `sun16audio'. 314`linux16audio' or `freebsd16audio' only if `NATIVE_AUDIO' was selected 315in `speech_tools/config/config' and your are on such machines. The 316Festival variable `*modules*' contains a list of all supported 317functions/modules in a particular installation including audio support. 318Check the value of that variable if things aren't what you expect. 319 320 If you are installing on a machine whose audio is not directly 321supported by the speech tools library, an external command may be 322executed to play a waveform. The following example is for an imaginary 323machine that can play audio files through a program called `adplay' 324with arguments for sample rate and file type. When playing waveforms, 325Festival, by default, outputs as unheadered waveform in native byte 326order. In this example you would set up the default audio playing 327mechanism in `siteinit.scm' as follows 328 (Parameter.set 'Audio_Method 'Audio_Command) 329 (Parameter.set 'Audio_Command "adplay -raw -r $SR $FILE") 330 For `Audio_Command' method of playing waveforms Festival supports 331two additional audio parameters. `Audio_Required_Rate' allows you to 332use Festivals internal sample rate conversion function to any desired 333rate. Note this may not be as good as playing the waveform at the 334sample rate it is originally created in, but as some hardware devices 335are restrictive in what sample rates they support, or have naive 336resample functions this could be optimal. The second addition audio 337parameter is `Audio_Required_Format' which can be used to specify the 338desired output forms of the file. The default is unheadered raw, but 339this may be any of the values supported by the speech tools (including 340nist, esps, snd, riff, aiff, audlab, raw and, if you really want it, 341ascii). 342 343 For example suppose you run Festival on a remote machine and are not 344running any network audio system and want Festival to copy files back to 345your local machine and simply cat them to `/dev/audio'. The following 346would do that (assuming permissions for rsh are allowed). 347 (Parameter.set 'Audio_Method 'Audio_Command) 348 ;; Make output file ulaw 8k (format ulaw implies 8k) 349 (Parameter.set 'Audio_Required_Format 'ulaw) 350 (Parameter.set 'Audio_Command 351 "userhost=`echo $DISPLAY | sed 's/:.*$//'`; rcp $FILE $userhost:$FILE; \ 352 rsh $userhost \"cat $FILE >/dev/audio\" ; rsh $userhost \"rm $FILE\"") 353 Note there are limits on how complex a command you want to put in the 354`Audio_Command' string directly. It can get very confusing with respect 355to quoting. It is therefore recommended that once you get past a 356certain complexity consider writing a simple shell script and calling 357it from the `Audio_Command' string. 358 359 A second typical customization is setting the default speaker. 360Speakers depend on many things but due to various licence (and resource) 361restrictions you may only have some diphone/nphone databases available 362in your installation. The function name that is the value of 363`voice_default' is called immediately after `siteinit.scm' is loaded 364offering the opportunity for you to change it. In the standard 365distribution no change should be required. If you download all the 366distributed voices `voice_rab_diphone' is the default voice. You may 367change this for a site by adding the following to `siteinit.scm' or per 368person by changing your `.festivalrc'. For example if you wish to 369change the default voice to the American one `voice_ked_diphone' 370 (set! voice_default 'voice_ked_diphone) 371 Note the single quote, and note that unlike in early versions 372`voice_default' is not a function you can call directly. 373 374 A second level of customization is on a per user basis. After 375loading `init.scm', which includes `sitevars.scm' and `siteinit.scm' 376for local installation, Festival loads the file `.festivalrc' from the 377user's home directory (if it exists). This file may contain arbitrary 378Festival commands. 379 380Checking an installation 381======================== 382 383 Once compiled and site initialization is set up you should test to 384see if Festival can speak or not. 385 386 Start the system 387 $ bin/festival 388 Festival Speech Synthesis System 2.0:release July 2004 389 Copyright (C) University of Edinburgh, 1996-2004. All rights reserved. 390 For details type `(festival_warranty)' 391 festival> ^D 392 If errors occur at this stage they are most likely to do with 393pathname problems. If any error messages are printed about 394non-existent files check that those pathnames point to where you 395intended them to be. Most of the (default) pathnames are dependent on 396the basic library path. Ensure that is correct. To find out what it 397has been set to, start the system without loading the init files. 398 $ bin/festival -q 399 Festival Speech Synthesis System 1.4.3:release Jan 2003 400 Copyright (C) University of Edinburgh, 1996-2003. All rights reserved. 401 For details type `(festival_warranty)' 402 festival> libdir 403 "/projects/festival/lib/" 404 festival> ^D 405 This should show the pathname you set in your `config/config'. 406 407 If the system starts with no errors try to synthesize something 408 festival> (SayText "hello world") 409 Some files are only accessed at synthesis time so this may show up 410other problem pathnames. If it talks, you're in business, if it 411doesn't, here are some possible problems. 412 413 If you get the error message 414 Can't access NAS server 415 You have selected NAS as the audio output but have no server running 416on that machine or your `DISPLAY' or `AUDIOSERVER' environment variable 417is not set properly for your output device. Either set these properly 418or change the audio output device in `lib/siteinit.scm' as described 419above. 420 421 Ensure your audio device actually works the way you think it does. 422On Suns, the audio output device can be switched into a number of 423different output modes, speaker, jack, headphones. If this is set to 424the wrong one you may not hear the output. Use one of Sun's tools to 425change this (try `/usr/demo/SOUND/bin/soundtool'). Try to find an audio 426file independent of Festival and get it to play on your audio. Once 427you have done that ensure that the audio output method set in Festival 428matches that. 429 430 Once you have got it talking, test the audio spooling device. 431 festival> (intro) 432 This plays a short introduction of two sentences, spooling the audio 433output. 434 435 Finally exit from Festival (by end of file or `(quit)') and test the 436script mode with. 437 $ examples/saytime 438 439 A test suite is included with Festival but it makes certain 440assumptions about which voices are installed. It assumes that 441`voice_rab_diphone' (`festvox_rabxxxx.tar.gz') is the default voice and 442that `voice_ked_diphone' and `voice_don_diphone' 443(`festvox_kedxxxx.tar.gz' and `festvox_don.tar.gz') are installed. 444Also local settings in your `festival/lib/siteinit.scm' may affect 445these tests. However, after installation it may be worth trying 446 gnumake test 447 from the `festival/' directory. This will do various tests 448including basic utterance tests and tokenization tests. It also checks 449that voices are installed and that they don't interfere with each other. 450These tests are primarily regression tests for the developers of 451Festival, to ensure new enhancements don't mess up existing supported 452features. They are not designed to test an installation is successful, 453though if they run correctly it is most probable the installation has 454worked. 455