7. Quick start

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.

7.1 Basic command line options

Festival’s basic calling method is as

festival [options] file1 file2 ...

Options may be any of the following

-q

start Festival without loading ‘init.scm’ or user’s ‘.festivalrc’

-b

--batch

After processing any file arguments do not become interactive

-i

--interactive

After processing file arguments become interactive. This option overrides any batch argument.

--tts

Treat file arguments in text-to-speech mode, causing them to be rendered as speech rather than interpreted as commands. When selected in interactive mode the command line edit functions are not available

--command

Treat file arguments in command mode. This is the default.

--language LANG

Set the default language to LANG. Currently LANG may be one of english, spanish or welsh (depending on what voices are actually available in your installation).

--server

After loading any specified files go into server mode. This is a mode where Festival waits for clients on a known port (the value of server_port, default is 1314). Connected clients may send commands (or text) to the server and expect waveforms back. See section Server/client API. Note server mode may be unsafe and allow unauthorised access to your machine, be sure to read the security recommendations in Server/client API

--script scriptfile

Run scriptfile as a Festival script file. This is similar to to --batch but it encapsulates the command line arguments into the Scheme variables argv and 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’.

--heap NUMBER

The Scheme heap (basic number of Lisp cells) is of a fixed size and cannot be dynamically increased at run time (this would complicate garbage collection). The default size is 210000 which seems to be more than adequate for most work. In some of our training experiments where very large list structures are required it is necessary to increase this. Note there is a trade off between size of the heap and time it takes to garbage collect so making this unnecessarily big is not a good idea. If you don’t understand the above explanation you almost certainly don’t need to use the option.

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.

7.2 Sample command driven session

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.

Typing help will give you more information, that is help 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 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 you. So

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 quit may 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.

7.3 Getting some help

If no audio is generated then you must check to see if audio is properly initialized on your machine. See section 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 parentheses).

For more up to date information on Festival regularly check the Festival Home Page at

http://www.cstr.ed.ac.uk/projects/festival.html

Further help is available by mailing questions to

festival-help@cstr.ed.ac.uk

Although we cannot guarantee the time required to answer you, we will do our best to offer help.

Bug reports should be submitted to

festival-bug@cstr.ed.ac.uk

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.

This document was generated by Alan W Black on December 2, 2014 using texi2html 1.82.