This section is for those who just want to know the absolute basics to run the system.
Festival works in two fundamental modes, command mode and text-to-speech mode (tts-mode). In command mode, information (in files or through standard input) is treated as commands and is interpreted by a Scheme interpreter. In tts-mode, information (in files or through standard input) is treated as text to be rendered as speech. The default mode is command mode, though this may change in later versions.
Festival's basic calling method is as
festival [options] file1 file2 ...
Options may be any of the following
welsh(depending on what voices are actually available in your installation).
server_port, default is 1314). Connected clients may send commands (or text) to the server and expect waveforms back. See section 28.3 Server/client API. Note server mode may be unsafe and allow unauthorised access to your machine, be sure to read the security recommendations in section 28.3 Server/client API
--batchbut it encapsulates the command line arguments into the Scheme variables
argc, so that Festival scripts may process their command line arguments just like any other program. It also does not load the the basic initialisation files as sometimes you may not want to do this. If you wish them, you should copy the loading sequence from an example Festival script like `festival/examples/saytext'.
In command mode, if the file name starts with a left parenthesis, the name itself is read and evaluated as a Lisp command. This is often convenient when running in batch mode and a simple command is necessary to start the whole thing off after loading in some other specific files.
Here is a short session using Festival's command interpreter.
Start Festival with no arguments
$ festival Festival Speech Synthesis System 1.4.3:release Dec 2002 Copyright (C) University of Edinburgh, 1996-2002. All rights reserved. For details type `(festival_warranty)' festival>
Festival uses the a command line editor based on editline for terminal input so command line editing may be done with Emacs commands. Festival also supports history as well as function, variable name, and file name completion via the TAB key.
help will give you more information, that is
without any parenthesis. (It is actually a variable name whose value is a
string containing help.)
Festival offers what is called a read-eval-print loop, because it reads an s-expression (atom or list), evaluates it and prints the result. As Festival includes the SIOD Scheme interpreter most standard Scheme commands work
festival> (car '(a d)) a festival> (+ 34 52) 86
In addition to standard Scheme commands a number of commands specific to speech synthesis are included. Although, as we will see, there are simpler methods for getting Festival to speak, here are the basic underlying explicit functions used in synthesizing an utterance.
Utterances can consist of various types See section 14.2 Utterance types, but the simplest form is plain text. We can create an utterance and save it in a variable
festival> (set! utt1 (Utterance Text "Hello world")) #<Utterance 1d08a0> festival>
The (hex) number in the return value may be different for your installation. That is the print form for utterances. Their internal structure can be very large so only a token form is printed.
Although this creates an utterance it doesn't do anything else. To get a waveform you must synthesize it.
festival> (utt.synth utt1) #<Utterance 1d08a0> festival>
This calls various modules, including tokenizing, duration,. intonation
etc. Which modules are called are defined with respect to the type
of the utterance, in this case
Text. It is possible to
individually call the modules by hand but you just wanted it to talk didn't
festival> (utt.play utt1) #<Utterance 1d08a0> festival>
will send the synthesized waveform to your audio device. You should hear "Hello world" from your machine.
To make this all easier a small function doing these three steps exists.
SayText simply takes a string of text, synthesizes it and sends it
to the audio device.
festival> (SayText "Good morning, welcome to Festival") #<Utterance 1d8fd0> festival>
Of course as history and command line editing are supported c-p or up-arrow will allow you to edit the above to whatever you wish.
Festival may also synthesize from files rather than simply text.
festival> (tts "myfile" nil) nil festival>
The end of file character c-d will exit from Festival and
return you to the shell, alternatively the command
be called (don't forget the parentheses).
Rather than starting the command interpreter, Festival may synthesize files specified on the command line
unix$ festival --tts myfile unix$
Sometimes a simple waveform is required from text that is to be kept and played at some later time. The simplest way to do this with festival is by using the `text2wave' program. This is a festival script that will take a file (or text from standard input) and produce a single waveform.
An example use is
text2wave myfile.txt -o myfile.wav
Options exist to specify the waveform file type, for example if Sun audio format is required
text2wave myfile.txt -otype snd -o myfile.wav
Use `-h' on `text2wave' to see all options.
If no audio is generated then you must check to see if audio is properly initialized on your machine. See section 23 Audio output.
In the command interpreter m-h (meta-h) will give you help on the current symbol before the cursor. This will be a short description of the function or variable, how to use it and what its arguments are. A listing of all such help strings appears at the end of this document. m-s will synthesize and say the same information, but this extra function is really just for show.
The lisp function
manual will send the appropriate command to an
already running Netscape browser process. If
nil is given as an
argument the browser will be directed to the tables of contents of the
manual. If a non-nil value is given it is assumed to be a section title
and that section is searched and if found displayed. For example
festival> (manual "Accessing an utterance")
Another related function is
manual-sym which given a symbol will
check its documentation string for a cross reference to a manual
section and request Netscape to display it. This function is
bound to m-m and will display the appropriate section for
the given symbol.
Note also that the TAB key can be used to find out the name
of commands available as can the function
Help (remember the
For more up to date information on Festival regularly check the Festival Home Page at
Further help is available by mailing questions to
Although we cannot guarantee the time required to answer you, we will do our best to offer help.
Bug reports should be submitted to
If there is enough user traffic a general mailing list will be created so all users may share comments and receive announcements. In the mean time watch the Festival Home Page for news.
Go to the first, previous, next, last section, table of contents.