If you wish to use Festival within some other application there are a number of possible interfaces.
Festival includes a full programming language, Scheme (a variant of Lisp) as a powerful interface to its speech synthesis functions. Often this will be the easiest method of controlling Festival's functionality. Even when using other API's they will ultimately depend on the Scheme interpreter.
Scheme commands (as s-expressions) may be simply written in files and interpreted by Festival, either by specification as arguments on the command line, in the interactive interpreter, or through standard input as a pipe. Suppose we have a file `hello.scm' containing
;; A short example file with Festival Scheme commands (voice_rab_diphone) ;; select Gordon (SayText "Hello there") (voice_don_diphone) ;; select Donovan (SayText "and hello from me")
From the command interpreter we can execute the commands in this file by loading them
festival> (load "hello.scm") nil
Or we can execute the commands in the file directly from the shell command line
unix$ festival -b hello.scm
The `-b' option denotes batch operation meaning the file is loaded and then Festival will exit, without starting the command interpreter. Without this option `-b' Festival will load `hello.scm' and then accept commands on standard input. This can be convenient when some initial set up is required for a session.
Note one disadvantage of the batch method is that time is required for Festival's initialisation every time it starts up. Although this will typically only be a few seconds, for saying short individual expressions that lead in time may be unacceptable. Thus simply executing the commands within an already running system is more desirable, or using the server/client mode.
Of course its not just about strings of commands, because Scheme is a
fully functional language, functions, loops, variables, file access,
arithmetic operations may all be carried out in your Scheme programs.
Also, access to Unix is available through the system
function. For many applications directly programming them in Scheme is
both the easiest and the most efficient method.
A number of example Festival scripts are included in `examples/'. Including a program for saying the time, and for telling you the latest news (by accessing a page from the web). Also see the detailed discussion of a script example in See section 29.1 POS Example.
The simplest use of Festival (though not the most powerful) is simply using it to directly render text files as speech. Suppose we have a file `hello.txt' containing
Hello world. Isn't it excellent weather this morning.
We can simply call Festival as
unix$ festival --tts hello.txt
Or for even simpler one-off phrases
unix$ echo "hello " | festival --tts
This is easy to use but you will need to wait for Festival to start up and initialise its databases before it starts to render the text as speech. This may take several seconds on some machines. A socket based server mechanism is provided in Festival which will allow a single server process to start up once and be used efficiently by multiple client programs.
Note also the use of Sable for marked up text, see section 10 XML/SGML mark-up.
Sable allows various forms of additional information in text, such as
phrasing, emphasis, pronunciation, as well as changing voices, and
inclusion of external waveform files (i.e. random noises). For many
application this will be the preferred interface method. Other text
modes too are available through the command line by using
auto-text-mode-alist.
Festival offers a BSD socket-based interface. This allows Festival to run as a server and allow client programs to access it. Basically the server offers a new command interpreter for each client that attaches to it. The server is forked for each client but this is much faster than having to wait for a Festival process to start from scratch. Also the server can run on a bigger machine, offering much faster synthesis.
Note: the Festival server is inherently insecure and may allow arbitrary users access to your machine.
Every effort has been made to minimise the risk of unauthorised access
through Festival and a number of levels of security are provided.
However with any program offering socket access, like httpd,
sendmail or ftpd there is a risk that unauthorised access
is possible. I trust Festival's security enough to often run it on my
own machine and departmental servers, restricting access to within our
department. Please read the information below before using
the Festival server so you understand the risks.
The following access control is available for Festival when running as a server. When the server starts it will usually start by loading in various commands specific for the task it is to be used for. The following variables are used to control access.
server_port
server_log_file
server_deny_list
server_access_list
server_passwd
(set_server_safe_functions FUNCNAMELIST)
--ttw uses.
(set_server_safe_functions
'(tts_return_to_client tts_text tts_textall Parameter.set))
Its is strongly recommend that you run Festival in server mode as userid
nobody to limit the access the process will have, also running it
in a chroot environment is more secure.
For example suppose we wish to allow access to all machines in the CSTR
domain except for holmes.cstr.ed.ac.uk and
adam.cstr.ed.ac.uk. This may be done by the following two
commands
(set! server_deny_list '("holmes\\.cstr\\.ed\\.ac\\.uk"
"adam\\.cstr\\.ed\\.ac\\.uk"))
(set! server_access_list '("[^\\.]*\\.cstr\\.ed\\.ac\\.uk"))
This is not complete though as when DNS is not working holmes and
adam will still be able to access the server (but if our DNS
isn't working we probably have more serious problems). However the
above is secure in that only machines in the domain cstr.ed.ac.uk
can access the server, though there may be ways to fix machines to
identify themselves as being in that domain even when they are not.
By default Festival in server mode will only accept client connections
for localhost.
An example client program called `festival_client' is included with the system that provides a wide range of access methods to the server. A number of options for the client are offered.
--server
--port
--output FILENAME
--ttw option uses this as does the
use of the Festival command utt.send.wave.client. If
an output waveform file is received by `festival_client'
and no output file has been given the waveform is discarded with
an error message.
--passwd PASSWD
--ttw option is used, a passwd is required and
none specified access will be denied.
--prolog FILE
--ttw which otherwise
does not offer any way to send commands as well as the text to the
server.
--otype OUTPUTTYPE
nist, but, ulaw,
riff, ulaw and others as supported by the Edinburgh
Speech Tools Library are valid. You may use raw too but note that
Festival may return waveforms of various sampling rates depending on the
sample rates of the databases its using. You can of course make
Festival only return one particular sample rate, by using
after_synth_hooks. Note that byte order will be native machine of the
client machine if the output format allows it.
--ttw
festival_client useful
in many simple applications. Although you can connect to the server
and send arbitrary Festival Scheme commands, this option automatically
does what is probably what you want most often. When specified
this options takes text from the specified file (or stdin),
synthesizes it (in one go) and saves it in the specified output
file. It basically does the following
(Parameter.set 'Wavefiletype '<output type>) (tts_textall " <file/stdin contents> ")))Note that this is best used for small, single utterance texts as you have to wait for the whole text to be synthesized before it is returned.
--aucommand COMMAND
FILE will be set when COMMAND is executed.
--async
--ttw
causes the text to be synthesized utterance by utterance and be sent back
in separated waveforms. Using --aucommand each waveform my
be played locally, and when `festival_client' is interrupted
the sound will stop. Getting the client to connect to an audio
server elsewhere means the sound will not necessarily stop when
the `festival_client' process is stopped.
--withlisp
send_client. If this option
is specified the Lisp expressions are printed to standard out,
otherwise this information is discarded.
A typical example use of `festival_client' is
festival_client --async --ttw --aucommand 'na_play $FILE' fred.txt
This will use `na_play' to play each waveform generated for the
utterances in `fred.txt'. Note the single quotes so that
the $ in $FILE isn't expanded locally.
Note the server must be running before you can talk to it. At present Festival is not set up for automatic invocations through `inetd' and `/etc/services'. If you do that yourself, note that it is a different type of interface as `inetd' assumes all communication goes through standard in/out.
Also note that each connection to the server starts a new session. Variables are not persistent over multiple calls to the server so if any initialization is required (e.g. loading of voices) it must be done each time the client starts or more reasonably in the server when it is started.
A PERL festival client is also available in `festival/examples/festival_client.pl'
The client talks to the server using s-expression (Lisp). The server will reply with and number of different chunks until either OK, is returned or ER (on error). The communicatotion is synchronous, each client request can generate a number of waveform (WV) replies and/or Lisp replies (LP) and terminated with an OK (or ER). Lisp is used as it has its own inherent syntax that Festival can already parse.
The following pseudo-code will help defined the protocol as well as show typical use
fprintf(serverfd,"%s\n",s-expression);
do
ack = read three character acknowledgemnt
if (ack == "WV\n")
read a waveform
else if (ack == "LP\n")
read an s-expression
else if (ack == "ER\n")
an error occurred, break;
while ack != "OK\n"
The server can send a waveform in an utterance to the client through the
function utt.send.wave.client; The server can send a lisp
expression to the client through the function
As well as offerening an interface through Scheme and the shell some users may also wish to embedd Festival within their own C++ programs. A number of simply to use high level functions are available for such uses.
In order to use Festival you must include `festival/src/include/festival.h' which in turn will include the necessary other include files in `festival/src/include' and `speech_tools/include' you should ensure these are included in the include path for you your program. Also you will need to link your program with `festival/src/lib/libFestival.a', `speech_tools/lib/libestools.a', `speech_tools/lib/libestbase.a' and `speech_tools/lib/libeststring.a' as well as any other optional libraries such as net audio.
The main external functions available for C++ users of Festival are.
void festival_initialize(int load_init_files,int heapsize);
int festival_say_file(const EST_String &filename);
TRUE or FALSE
depending on where this was successful.
int festival_say_text(const EST_String &text);
TRUE or FALSE
depending on where this was successful.
int festival_load_file(const EST_String &filename);
TRUE or FALSE
depending on where this was successful.
int festival_eval_command(const EST_String &expr);
TRUE or FALSE depending on where this was successful.
int festival_text_to_wave(const EST_String &text,EST_Wave &wave);
TRUE or
FALSE depending on where this was successful.
Many other commands are also available but often the above will be sufficient.
Below is a simple top level program that uses the Festival functions
int main(int argc, char **argv)
{
EST_Wave wave;
int heap_size = 210000; // default scheme heap size
int load_init_files = 1; // we want the festival init files loaded
festival_initialize(load_init_files,heap_size);
// Say simple file
festival_say_file("/etc/motd");
festival_eval_command("(voice_ked_diphone)");
// Say some text;
festival_say_text("hello world");
// Convert to a waveform
festival_text_to_wave("hello world",wave);
wave.save("/tmp/wave.wav","riff");
// festival_say_file puts the system in async mode so we better
// wait for the spooler to reach the last waveform before exiting
// This isn't necessary if only festival_say_text is being used (and
// your own wave playing stuff)
festival_wait_for_spooler();
return 0;
}
A simpler C only interface example is given inf `festival/examples/festival_client.c'. That interface talks to a festival server. The code does not require linking with any other EST or Festival code so is much smaller and easier to include in other programs. The code is missing some functionality but not much consider how much smaller it is.
Initial support for talking to a Festival server from java is included from version 1.3.0 and initial JSAPI support is included from 1.4.0. At present the JSAPI talks to a Festival server elsewhere rather than as part of the Java process itself.
A simple (Pure) Java festival client is given `festival/src/modules/java/cstr/festival/Client.java' with a wraparound script in `festival/bin/festival_client_java'.
See the file `festival/src/modules/java/cstr/festival/jsapi/ReadMe' for requirements and a small example of using the JSAPI interface.
Go to the first, previous, next, last section, table of contents.