<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
from ../festival.texi on 2 August 2001 -->
<TITLE>Festival Speech Synthesis System - 7 Quick start</TITLE>
</HEAD>
<BODY bgcolor="#ffffff">
Go to the <A HREF="festival_1.html">first</A>, <A HREF="festival_6.html">previous</A>, <A HREF="festival_8.html">next</A>, <A HREF="festival_35.html">last</A> section, <A HREF="festival_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC18" HREF="festival_toc.html#TOC18">7 Quick start</A></H1>
<P>
This section is for those who just want to know the absolute basics
to run the system.
</P>
<P>
<A NAME="IDX49"></A>
<A NAME="IDX50"></A>
<A NAME="IDX51"></A>
Festival works in two fundamental modes, <EM>command mode</EM> and
<EM>text-to-speech mode</EM> (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.
</P>
<H2><A NAME="SEC19" HREF="festival_toc.html#TOC19">7.1 Basic command line options</A></H2>
<P>
<A NAME="IDX52"></A>
Festival's basic calling method is as
</P>
<PRE>
festival [options] file1 file2 ...
</PRE>
<P>
Options may be any of the following
</P>
<DL COMPACT>
<DT><CODE>-q</CODE>
<DD>
start Festival without loading <TT>`init.scm'</TT> or user's
<TT>`.festivalrc'</TT>
<DT><CODE>-b</CODE>
<DD>
<DT><CODE>--batch</CODE>
<DD>
<A NAME="IDX53"></A>
After processing any file arguments do not become interactive
<DT><CODE>-i</CODE>
<DD>
<DT><CODE>--interactive</CODE>
<DD>
<A NAME="IDX54"></A>
After processing file arguments become interactive. This option overrides
any batch argument.
<DT><CODE>--tts</CODE>
<DD>
<A NAME="IDX55"></A>
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
<DT><CODE>--command</CODE>
<DD>
<A NAME="IDX56"></A>
Treat file arguments in command mode. This is the default.
<DT><CODE>--language LANG</CODE>
<DD>
<A NAME="IDX57"></A>
Set the default language to <VAR>LANG</VAR>. Currently <VAR>LANG</VAR> may be
one of <CODE>english</CODE>, <CODE>spanish</CODE> or <CODE>welsh</CODE> (depending on
what voices are actually available in your installation).
<DT><CODE>--server</CODE>
<DD>
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 <CODE>server_port</CODE>, default is 1314). Connected
clients may send commands (or text) to the server and expect
waveforms back. See section <A HREF="festival_28.html#SEC130">28.3 Server/client API</A>. Note server mode
may be unsafe and allow unauthorised access to your
machine, be sure to read the security recommendations in
section <A HREF="festival_28.html#SEC130">28.3 Server/client API</A>
<DT><CODE>--script scriptfile</CODE>
<DD>
<A NAME="IDX58"></A>
<A NAME="IDX59"></A>
Run scriptfile as a Festival script file. This is similar to
to <CODE>--batch</CODE> but it encapsulates the command line arguments into
the Scheme variables <CODE>argv</CODE> and <CODE>argc</CODE>, 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 <TT>`festival/examples/saytext'</TT>.
<DT><CODE>--heap NUMBER</CODE>
<DD>
<A NAME="IDX60"></A>
<A NAME="IDX61"></A>
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.
</DL>
<P>
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.
</P>
<H2><A NAME="SEC20" HREF="festival_toc.html#TOC20">7.2 Sample command driven session</A></H2>
<P>
Here is a short session using Festival's command interpreter.
</P>
<P>
Start Festival with no arguments
<PRE>
$ festival
Festival Speech Synthesis System 1.4.2:release July 2001
Copyright (C) University of Edinburgh, 1996-2001. All rights reserved.
For details type `(festival_warranty)'
festival>
</PRE>
<P>
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 <KBD>TAB</KBD> key.
</P>
<P>
Typing <CODE>help</CODE> will give you more information, that is <CODE>help</CODE>
without any parenthesis. (It is actually a variable name whose value is a
string containing help.)
</P>
<P>
<A NAME="IDX62"></A>
<A NAME="IDX63"></A>
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
<PRE>
festival> (car '(a d))
a
festival> (+ 34 52)
86
</PRE>
<P>
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.
</P>
<P>
<A NAME="IDX64"></A>
<A NAME="IDX65"></A>
Utterances can consist of various types (See section <A HREF="festival_14.html#SEC50">14.2 Utterance types</A>),
but the simplest form is plain text. We can create an utterance
and save it in a variable
<PRE>
festival> (set! utt1 (Utterance Text "Hello world"))
#<Utterance 1d08a0>
festival>
</PRE>
<P>
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.
</P>
<P>
<A NAME="IDX66"></A>
Although this creates an utterance it doesn't do anything else.
To get a waveform you must synthesize it.
<PRE>
festival> (utt.synth utt1)
#<Utterance 1d08a0>
festival>
</PRE>
<P>
<A NAME="IDX67"></A>
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 <CODE>Text</CODE>. It is possible to
individually call the modules by hand but you just wanted it to talk didn't
you. So
<PRE>
festival> (utt.play utt1)
#<Utterance 1d08a0>
festival>
</PRE>
<P>
will send the synthesized waveform to your audio device. You should
hear "Hello world" from your machine.
</P>
<P>
<A NAME="IDX68"></A>
To make this all easier a small function doing these three steps exists.
<CODE>SayText</CODE> simply takes a string of text, synthesizes it and sends it
to the audio device.
<PRE>
festival> (SayText "Good morning, welcome to Festival")
#<Utterance 1d8fd0>
festival>
</PRE>
<P>
Of course as history and command line editing are supported <KBD>c-p</KBD>
or up-arrow will allow you to edit the above to whatever you wish.
</P>
<P>
Festival may also synthesize from files rather than simply text.
<PRE>
festival> (tts "myfile" nil)
nil
festival>
</PRE>
<P>
<A NAME="IDX69"></A>
<A NAME="IDX70"></A>
The end of file character <KBD>c-d</KBD> will exit from Festival and
return you to the shell, alternatively the command <CODE>quit</CODE> may
be called (don't forget the parentheses).
</P>
<P>
<A NAME="IDX71"></A>
<A NAME="IDX72"></A>
Rather than starting the command interpreter, Festival may synthesize
files specified on the command line
<PRE>
unix$ festival --tts myfile
unix$
</PRE>
<P>
<A NAME="IDX73"></A>
<A NAME="IDX74"></A>
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 <TT>`text2wave'</TT> program. This is a festival script that
will take a file (or text from standard input) and produce a single
waveform.
</P>
<P>
<A NAME="IDX75"></A>
An example use is
<PRE>
text2wave myfile.txt -o myfile.wav
</PRE>
<P>
Options exist to specify the waveform file type, for example if
Sun audio format is required
<PRE>
text2wave myfile.txt -otype snd -o myfile.wav
</PRE>
<P>
Use <TT>`-h'</TT> on <TT>`text2wave'</TT> to see all options.
</P>
<H2><A NAME="SEC21" HREF="festival_toc.html#TOC21">7.3 Getting some help</A></H2>
<P>
<A NAME="IDX76"></A>
If no audio is generated then you must check to see if audio is
properly initialized on your machine. See section <A HREF="festival_23.html#SEC96">23 Audio output</A>.
</P>
<P>
In the command interpreter <KBD>m-h</KBD> (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. <KBD>m-s</KBD> will synthesize and say
the same information, but this extra function is really just for show.
</P>
<P>
<A NAME="IDX77"></A>
The lisp function <CODE>manual</CODE> will send the appropriate command to an
already running Netscape browser process. If <CODE>nil</CODE> 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
<PRE>
festival> (manual "Accessing an utterance")
</PRE>
<P>
Another related function is <CODE>manual-sym</CODE> 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 <KBD>m-m</KBD> and will display the appropriate section for
the given symbol.
</P>
<P>
Note also that the <KBD>TAB</KBD> key can be used to find out the name
of commands available as can the function <CODE>Help</CODE> (remember the
parentheses).
</P>
<P>
For more up to date information on Festival regularly check
the Festival Home Page at
<PRE>
<A HREF="http://www.cstr.ed.ac.uk/projects/festival.html">http://www.cstr.ed.ac.uk/projects/festival.html</A>
</PRE>
<P>
Further help is available by mailing questions to
<PRE>
festival-help@cstr.ed.ac.uk
</PRE>
<P>
Although we cannot guarantee the time required to answer you, we
will do our best to offer help.
</P>
<P>
<A NAME="IDX78"></A>
Bug reports should be submitted to
<PRE>
festival-bug@cstr.ed.ac.uk
</PRE>
<P>
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.
</P>
<P><HR><P>
Go to the <A HREF="festival_1.html">first</A>, <A HREF="festival_6.html">previous</A>, <A HREF="festival_8.html">next</A>, <A HREF="festival_35.html">last</A> section, <A HREF="festival_toc.html">table of contents</A>.
</BODY>
</HTML>
