\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename festival-freebsoft-utils.info
@set VERSION 0.10
@settitle festival-freebsoft-utils @value{VERSION}
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex vr cp
@comment %**end of header
@copying
This manual is for festival-freebsoft-utils, version @value{VERSION}.

Copyright @copyright{} 2004, 2005, 2006, 2007, 2008 Brailcom, o.p.s.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation

Alternatively, you can distribute this manual under the same
conditions as festival-freebsoft-utils itself:

@quotation
festival-freebsoft-utils is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.

WAusers is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
MA 02110-1301 USA.
@end quotation
@end copying

@dircategory Sound
@direntry
* Festival Freebsoft Utilities: (festival-freebsoft-utils).  Festival utilities used by the Freebsoft project.
@end direntry

@titlepage
@title festival-freebsoft-utils
@subtitle for version @value{VERSION}
@author Milan Zamazal
@author Brailcom, o.p.s.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top festival-freebsoft-utils

@insertcopying
@end ifnottex

@menu
* Motivation::                  What is festival-freebsoft-utils?
* Installation::                How to install it.
* User Customization::          Configuration variables.
* Reference Manual::            Description of all available functions.
* Contact::                     Authors, mailing lists, Web pages.

* Copying This Manual::         GNU Free Documentation License.
* Index::                       Concept, function and variable.
@end menu

@c ****************************************************************************

@node Motivation
@chapter Motivation
@cindex Festival
@cindex Speech Dispatcher

Festival is a powerful and extensible speech synthesis system, able to
handle the whole text-to-speech process.  The aim of
festival-freebsoft-utils is to further extend Festival facilities, to
the level providing complete set of features required by
@ref{Top,Speech Dispatcher,,speech-dispatcher,Speech Dispatcher Manual}.  As a side
effect, festival-freebsoft-utils introduces interesting functionality,
generalizing the text-to-speech system to a text-to-sound system.

Festival is well suited to the speech synthesis process itself, but
lacks some end-user features, especially those needed for application
sound output.  festival-freebsoft-utils tries to fill this gap, thus
making Festival suitable for screen readers and other speech output
software, used especially by the blind and visually impaired people.

Main features of festival-freebsoft-utils are:

@itemize @bullet
@item
Generalized concept of input events.  festival-freebsoft-utils allows
not only plain text synthesis, but also insertion of sounds and
logical event mapping.

@item
Spell mode.

@item
Capital letter signalling.

@item
Punctuation modes, for reading or not reading punctuation characters.

@item
Function wrapping support.

@item
Speech Dispatcher Festival output interface.  For more information
about Speech Dispatcher, see @url{http://www.freebsoft.org/speechd} or
@ref{Top,Speech Dispatcher,,speech-dispatcher,Speech Dispatcher manual}.
@end itemize

@cindex home page
Up-to-date information about festival-freebsoft-utils can be found at
its home page
@url{http://www.freebsoft.org/festival-freebsoft-utils/}.

@c ****************************************************************************

@node Installation
@chapter Installation

festival-freebsoft-utils was tested with Festival 1.4.3.  Other
versions of Festival may or may not work.

Having SoX (@url{http://sox.sourceforge.net}) installed is strongly
recommended, many festival-freebsoft-utils functions don't work
without it.

As Festival does not support UTF-8 encoding, festival-freebsoft-utils
uses the iconv utility for character coding conversions.  iconv is a
standard part of some (e.g. GNU) operating systems, if you don't have
it you can install it as a part of the libiconv library available at
@url{http://www.gnu.org/software/libiconv/}.

Installation itself is easy, just copy all the @file{*.scm} files to
one of the directories present in the Festival's load-path.  This is
typically @file{/usr/share/festival/}, you can get the exact list of
the directories by evaluating @code{load-path} in the Festival command
line interface.  Then you can load the whole system at Festival
startup by adding the line

@lisp
(require 'speech-dispatcher)
@end lisp

to the Festival initialization file (typically
@file{/etc/festival.scm} system wide or @file{~/.festivalrc} for a
particular user).  Note you needn't do this for Speech Dispatcher
operation as Speech Dispatcher invokes this call itself.

@c ****************************************************************************

@node User Customization
@chapter User Customization

You can customize festival-freebsoft-utils through several user
variables described in the following sections.  This chapter is
primarily focused on Speech Dispatcher users and other users not using
festival-freebsoft-utils directly.  For a complete usage description
see @ref{Reference Manual}.

@cindex @code{SayText}
Most of the extensions presented here don't work with usual Festival
functions such as @code{SayText}, which are too limited in their use.
You must use either the Speech Dispatcher functions,
@ref{speech-dispatcher.scm}, or the event speaking functions,
@ref{events.scm}, to utilize the features like word substitution,
capital signalling or punctuation modes.

@menu
* Events::                      Basic event handling.
* Word Substitution::           Substituting events for certain words.
* Capital Letters::             Capital letter signalling.
* Punctuation Characters::      Pronouncing punctuation characters.
* Initial Pauses::              Avoiding initial pauses.
* Tokenization::                Utterance chunking.
* Voice Selection::             Configuring voices and languages.
* Speech Dispatcher::           Using with Speech Dispatcher.
@end menu

@node Events
@section The Concept of Events
@cindex events

Default Festival interfaces expect text on their inputs, either in a
plain form or in the form of some markup.  The event module
generalizes the concept of input to @emph{events}.  Event is a general
input object that can represent not only text, but also a pre-defined
sound or an object just mapping to another input object.

Currently the following kinds of events are supported:

@table @code
@item text
@cindex text
Text.  The event value is a string containing the given text.

@item ssml
@cindex SSML
Text represented in the SSML 1.0 markup.  The event value is a string
containing the given text.  Please note that festival-freebsoft-utils
does not provide conforming SSML implementation and implements only a
limited subset of the standard.  Moreover, due to the limitations of
the built-in Festival XML parser, SSML markup texts must be provided
in the target encoding of the document languages.

@item sound
@cindex sound
@vindex sound-icon-directory
Sound icon.  The value is a string containing a file name of a sound
file, either absolute, or relative to the @code{sound-icon-directory}
variable value.

@item character
@cindex character
Single character.  The value is a string containing the character.

The difference between character events and text events is that
characters may be spoken in a different way than ordinary
single-letter texts.

@item key
@cindex key
@cindex Speech Synthesis Interface Protocol
A key (as on keyboard).  The value is a string containing key
description in the format defined by the Speech Synthesis Interface
Protocol, @ref{Top,SSIP,,ssip,SSIP}.

@item logical
@cindex logical
Symbolic event name, usually mapped to another event.  The value is an
arbitrary symbol.  Logical event values starting with the underscore
character are considered special and shouldn't be generally used.
@xref{events.scm}, for more details.
@end table

Any event may be mapped to another event.  Before
festival-freebsoft-utils functions process an event, they check for
its mapping and if the event is mapped to another event, it is
replaced by the target event.  Event mapping is defined by the
following variable:

@vtable @code
@item event-mappings
Maps events of any supported kind (i.e. logical, text, sound,
character, key) to other events (typically to text or sound events).
All logical events used must be defined here, other kinds of events
are processed in some default way if there are not defined in this
variable.

The variable contains an alist whose elements are of the form
@code{(@var{event-type} @var{mappings})}.  @var{event-type} is one of
the symbols @code{logical}, @code{text}, @code{sound},
@code{character}, @code{key}.  @var{mappings} is an alist with the
elements of the form @code{(@var{value} @var{new-event-type}
@var{new-event-value})}.

See the default variable value for an example.
@end vtable

For a convenience, there is a function that allows you to add or
replace single event mappings in the @code{event-mappings} variable in
an easier way than redefining the whole variable value:

@ftable @code
@item set-event-mapping! @var{event-type} @var{event-value} @var{new-event-type} @code{new-event-value}
Ensure the event of @var{event-type} and @var{event-value} is mapped
to the event of @var{new-event-type} @code{new-event-value}.
@end ftable

Example:

@lisp
(set-event-mapping! 'logical 'hello 'text "Hello, world!")
@end lisp

@node Word Substitution
@section Word Substitution

You can map words to events.  This is useful especially when you want
to replace some words by sounds.

@vtable @code
@item word-mapping
Alist mapping words to events.  Each entry of the list is of the form
@code{("@var{word}" @var{event-type} @var{event-value})}.  If
@var{word} is encountered in the input text, it is replaced by the
given event.
@end vtable

@node Capital Letters
@section Signalling Capital Characters

When capital character signalling is enabled,
@ref{cap-signalization.scm}, capital characters are signalled via the
@code{capital} logical event.  By default the event is mapped on the
sound event @code{capital}.  If you want to change it, change the
logical mapping, as is described in @ref{Events}.

For example, the following code in your @file{~/.festivalrc} changes
the sound signalling to saying the word @emph{capital}:

@lisp
(require 'events)
(set-event-mapping! 'logical 'capital 'text "capital")
@end lisp

@node Punctuation Characters
@section Reading Punctuation Characters

Through the punctuation modes, @ref{punctuation.scm}, you can force
Festival to speak all punctuation characters.  Since the default
English voices don't have defined pronunciation of some punctuation
characters, it is provided through the following variable:

@vtable @code
@item punctuation-pronunciation
Alist of punctuation characters and their word forms.  Each entry in
the list is of the form @code{("@var{character}" "@var{word}" ...},
where @var{character} is the pronounced character and @var{word}s are
the words of its pronunciation.  Please note you must put each word
inside separate double quotes.  Example entry:

@lisp
("!" "exclamation" "mark")
@end lisp
@end vtable

@node Initial Pauses
@section Avoiding Initial Pauses
@cindex pauses

Festival inserts initial pause in each synthesized utterance.  There
is a good reason for it---speech starts from silence and thus the
first diphone of the synthesized sample should be @emph{pause-first
phoneme}.

However there are some situations when the initial pause is
undesirable.  For instance, when reading characters in a speech
enabled editor, the initial pauses slow down the reading.  So
festival-freebsoft-utils provide a way to disable the initial pause by
making its effective duration zero.

First, you must load the corresponding code:

@lisp
(require 'nopauses)
@end lisp

After this, there is a variable available controlling the initial
pause insertion:

@vtable @code
@item inhibit-initial-pauses
When set to a non-@code{nil} value, initial pauses are inhibited.
@end vtable

@node Tokenization
@section Tokenization

@cindex eou_tree
If you use the festival-freebsoft-utils tokenizer instead of the
Festival built-in tokenizer, you can put additional limits on the
tokenization process besides the @code{eou_tree}.

@vtable @code
@item max-number-of-tokens
Maximum number of tokens in a single utterance.  Utterance chunking is
performed in such a way that each produced utterance contains at most
this number of tokens.

@item max-number-of-token-chars
Maximum number of characters within a single token.  If a token
contains more characters than is stated by this limit, it is split
into smaller tokens.
@end vtable

@node Voice Selection
@section Voice Selection

@cindex voices
@cindex languages
You can configure languages and voices used by the SSML, Speech
Dispatcher and other interfaces supporting the mechanism with the
following variables:

@vtable @code
@item language-codes
Alist mapping ISO language codes to Festival language names.  Each
alist entry is of the form @code{("@var{language-code}"
@var{language-name})}, where @var{language-code} is an ISO language
code as used by Speech Dispatcher and @code{language-name} is the
corresponding Festival language name.  Optionally, the alist elements
can have the extended form @code{(@var{language-code}
@var{language-name} . @var{dialects})}, where @var{dialects} is a list
of pairs @code{(@var{dialect-code} @var{dialect-name})}.
@var{dialect-code} is the part of the language code after a hyphen or
underscore and @var{dialect-name} is the dialect name used by
Festival voices.

@item voice-select-defaults
Alist of default voice parameters.  Each alist entry is of the form
@code{(@var{name} @var{value})}, where @var{value} can be either the
actual parameter value or @code{nil}, meaning the value is
unspecified.
@end vtable

@node Speech Dispatcher
@section Using with Speech Dispatcher

One of the primary goals of festival-freebsoft-utils is to serve as a
Speech Dispatcher interface to Festival.  festival-freebsoft-utils is
required by Speech Dispatcher for the use of Festival as the speech
synthesis backend.  

In order to use festival-freebsoft-utils with Speech Dispatcher, you
need not to make any special festival-freebsoft-utils arrangements.
Just configure it as is described in the previous sections.  It is
particularly recommended to configure available languages if you want
to use Festival for other languages than English, @xref{Voice
Selection}.

This version of festival-freebsoft-utils requires Speech Dispatcher
0.5 or higher.

@c ****************************************************************************

@node Reference Manual
@chapter Reference Manual

festival-freebsoft-utils consists of several modules described in the
following sections.

@menu
* util.scm::                    Miscellaneous utility functions.
* wave.scm::                    Wave form handling.
* oo.scm::                      Object oriented programming.
* events.scm::                  Generalized input events.
* spell-mode.scm::              Spelling mode.
* cap-signalization.scm::       Capital letter signalization.
* punctuation.scm::             Punctuation reading modes.
* tokenize.scm::                Alternative tokenization written in SIOD.
* multiwave.scm::               Returning multiple wave forms for an event.
* voice-select.scm::            Selecting voices and languages.
* prosody-param.scm::           Changing prosodic parameters.
* ssml-mode.scm::               Partial SSML support.
* fileio.scm::                  File utilities.
* recode.scm::                  Character set conversions.
* speech-dispatcher.scm::       Speech Dispatcher interface.
@end menu

@node util.scm
@section util.scm

This module contains miscellaneous utilities useful in general SIOD
and Festival programming.

Macros and functions mostly available in Lisp dialects:

@ftable @code
@item when @var{condition} @var{body-form} @var{...}
If and only if @var{condition} is true, evaluate @code{body-form}s.

@item unless @var{condition} @var{body-form} @var{...}
If and only if @var{condition} is false, evaluate @code{body-form}s.

@item prog1 @var{form} @var{...}
Evaluate all forms and return the return value of the first one.

@item let* @var{bindings} @var{body-form} @var{...}
The same as @code{let} except that variable bindings are applied
sequentially rather than in parallel.

@item unwind-protect* @var{protected-form} @var{cleanup-form} @var{...}
Evaluate @var{protected-form}, and after it is finished, whether
successfully or with errors, evaluate all @var{cleanup-form}s.  If
@var{protected-form} was evaluated successfully, return its return
value.

Unlike Festival's @code{unwind-protect}, @code{unwind-protect*}
accepts multiple @var{cleanup-form}s and evaluates them even when
@var{protected-form} doesn't signal an error.

@item first @var{list}
@item second @var{list}
@item third @var{list}
@item fourth @var{list}
Return first, second, third or fourth element of @var{list}, respectively.

@item butlast @var{list}
Return the @var{list} without its last element.  If @var{list} is
empty, return an empty list.

@item min @var{x} @var{y}
Return minimum of the two numeric values @var{x} and @var{y}.

@item max @var{x} @var{y}
Return maximum of the two numeric values @var{x} and @var{y}.

@item abs @var{x}
Return absolute value of @var{x}.

@item remove-if @var{test} @var{list}
Return @var{list} with elements, for which the @var{test} call returns
non-@code{nil}, removed.  The order of list elements is preserved.
@var{test} must be a function of a single argument.

@item identity @var{object}
Return @var{object}.

@item complement @var{function}
Return a function that is equivalent to function except that it
returns the opposite truth value to the return value of function.

@item apply* @var{function} @var{arglist}
The same as @code{apply}, except that it also works if @var{function}
is given as a string.

@item dolist (@var{var} @var{items}) @var{body-form} @var{...}
@cindex looping
Loop over @var{items} and perform @var{body-form}s over each of them,
binding it to the variable @var{var} (unevaluated).

@item add-hook @var{hook-variable} @var{hook-function} @var{to-end?}
Add @var{hook-function} to @var{hook-variable} if it is not already
present there.  @var{hook-variable} must be a variable containing a
list.  If @var{to-end?} is true, add @var{hook-function} to the end of
the list contained in @var{hook-variable}, otherwise add it to the
beginning.

@item assoc-set @var{list} @var{key} @var{value}
Add the @var{key}-@var{value} pair to the association @code{list} and
return the resulting list.  Contingent previously @var{list} entries
stored under @var{key} are removed from the resulting list.

@item avalue-get @var{key} @var{alist}
Find the first @var{alist} element of the form
@code{(@var{key*} @code{value})}, where @var{key*} is
@code{string-equal} to @var{key}, and return @var{value}.

@item avalue-set! @var{key} @var{alist} @var{value}
Destructively set the @var{value*} of the first @var{alist} element of
the form @code{(@var{key*} @code{value*})} to @var{value}.  Return
@var{alist}.

@item avg . @var{args}
@cindex math functions
Return average value of @var{args}.

@item dirname @var{path}
Return the directory part of @var{path}.

@item make-temp-filename @var{template}
Return name of a (probably non-existent) temporary file.
@var{template} is a basename of the file, that is formatted with the
@code{format} function and must contain exactly one @code{%s} sequence
to be replaced with a variable part of the file name.

Actually, this function is somewhat limited by the available Festival
system interface.  So it is not safe, the file may be created before
it is actually used or the function may fail with an error.  But for
simple purposes the function should work fine and it shouldn't be
worse than the standard @code{make_tmp_filename} function.

@item with-temp-file @var{filename} @var{body}
Macro that binds newly generated temporary file name to a local
variable @var{filename} and then performs @var{body}.  The macro
ensures the temporary file is deleted after finishing @var{body} in
any way.

@item string-replace @var{string} @var{from} @var{to}
Replace all occurrences of @var{from} by @var{to} in @var{string} and
return the result.
@end ftable

Festival specific utilities:

@ftable @code
@item item.has_feat @var{item} @var{feature}
Return true if and only if @var{item} has @var{feature} set.

@item langvar @var{symbol}
Return language dependent value stored under @var{symbol}.  First, the
variable named @var{symbol.language}, where @var{language} is the
language name as stored in the @code{Language} parameter is checked and
if it is unbound, @var{symbol}'s value is returned.

@item current-voice-coding
Return character coding of the currently selected voice in Festival.
The coding is taken from the @code{coding} attribute of the voice
description, if it is undefined or @code{nil}, ISO@ 8859-1 coding is
assumed.  The @code{coding} voice attribute is introduced by
festival-freebsoft-utils, it is not a standard Festival feature.

@item utt-relation-top-items @var{utt} @var{relation}
Return a list of top level items in @var{relation} in @code{utt}.

@item do-relation-items (@var{var} @var{utterance} @var{relation}) @var{body-form} @var{...}
@cindex looping
Loop over @var{relation} items of @var{utterance}, performing
@var{body-form}s for each of them, binding it to the variable
@var{var}.  The macro arguments @var{var} and @var{relation} are not
evaluated.

@item do-relation-top-items (@var{var} @var{utterance} @var{relation}) @var{body-form} @var{...}
Similar to @code{do-relation-items}, but loops only over the
relation's top items.
@end ftable

@node wave.scm
@section Wave form handling
@cindex wave forms

There are some utility functions to help handling wave forms:

@ftable @code
@item wave-concat @var{waves}
Append wave forms and return the resulting wave form.  @var{waves}
must be a list of wave forms to append.

@item wave-subwave @var{wave} @var{from-time} @var{to-time}
Return the part of @var{wave} form that starts at @var{from-time} and
finishes at @var{to-time}.  Both times are in seconds.

@item wave-load @var{filename}
@cindex Ogg Vorbis
@cindex Vorbis
Load and return a wave form from @var{filename}.  This function is
similar to @code{wave.load}, but more sound file formats (most
significantly Ogg Vorbis, if your SoX installation supports it) can be
loaded.

@item wave-utt @var{wave}
Create and return an utterance, that contains just the @code{Wave}
relation holding @var{wave}.

@item wave-import-utt @var{filename}
Create and return an utterance, that contains just the @code{Wave}
relation holding a wave loaded from @var{filename} via the function
@code{wave-load}.
@end ftable

@node oo.scm
@section oo.scm

@cindex wrappers
Sometimes it is useful to extend a Festival function in some way.
Standard Festival functions don't provide easy to use means for it.
This module tries to fill the gap.

The following macro allows you to wrap a defined function:

@ftable @code
@item define-wrapper (@var{function} @var{arg ...}) @var{wrapper-name} . @var{body})
Wrap @var{function} with arguments @var{arg ...} by the code
@var{body}.  Given function arguments must match the arguments of the
wrapped function.  @var{wrapper-name} is a symbol uniquely identifying
the wrapper, it allows redefinition of the wrapper.  One function can
be wrapped by any number of wrappers.  None of the @code{define-wrapper}
arguments is evaluated.

@cindex next-func
Within @var{body}, a function named @code{next-func} is automatically
defined.  It returns the next wrapper or the original function.
Please note @code{next-func} is a function, not a variable, so its
typical invocation looks as follows: @code{((next-func) @var{arg} @var{...})}.

@item oo-ensure-function-wrapped @var{function-name}
If a wrapped function gets redefined, its wrapper is lost.  If you
want to ensure the function is still wrapped before its use, you may
call this function, with its symbol name as the argument.

@item oo-unwrapped @var{function-name}
Return the original definition of a wrapped function.
@end ftable

Example use:

@lisp
festival> (define (foo x) (+ x 42))
#<CLOSURE (x) (+ x 42)>
festival> (foo 1)
43
festival> (define-wrapper (foo x) my-foo-wrapper (print "Foo called.") ((next-func) x))
nil
festival> (foo 1)
"Foo called."
43
@end lisp

@cindex @code{Param.set}
You can also wrap parameters, set by @code{Param.set}:

@ftable @code
@item Param.wrap @var{name} @var{wrapper-name} . @var{body}
Wrap access to parameter @var{name} by code @var{body}.  If the given
parameter is accessed, its wrapper is invoked instead of just
returning the parameter value.  @var{wrapper-name} is the same as in
@code{define-wrapper}.

@cindex @code{next-value}
Macro @code{next-value} is automatically defined within @var{body}.
It returns the parameter value, either plain or modified by another
wrapper.
@end ftable

Example use of parameter wrapping:

@lisp
festival> (Param.set 'foo 42)
#<feats 0x8169950>
festival> (Param.wrap foo foo-w (+ (next-value) 1))
nil
festival> (Param.get 'foo)
43
@end lisp

And finally, the @code{glet*} macro allows you to dynamically bind a
global variable value:

@ftable @code
@item glet* @var{bindings} . @var{body}
Similar to @code{let*} (@pxref{util.scm}) except that the variables in
@var{bindings} are bound dynamically instead of lexically.  All
variables in @var{bindings} must be global variables.
@end ftable

@node events.scm
@section events.scm

For introductory and configuration information about events see
@ref{Events}.  The event module provides the following functions to
synthesize events:

@ftable @code
@item event-synth @var{type} @var{value}
Synthesize event of @var{type}, which may be one of the following
symbols: @code{logical}, @code{text}, @code{sound}, @code{character},
@code{key}.  @var{event} is the event value that must correspond to
the event type.

@item event-play @var{type} @var{value}
Play event.  The @var{type} and @var{value} arguments are the same as
in @code{event-synth}.
@end ftable

Logical events starting with underscore are reserved for special
purposes.  Currently, the following special purpose logical events are
recognized:

@table @code
@cindex @code{_debug_on}
@item _debug_on*
Turn on debugging.  That means every processed event is logged.
@code{_debug_off} is just a prefix, it can be followed by any symbol
constituent characters.

@cindex @code{_debug_off}
@item _debug_off*
Turn the debugging off.  @code{_debug_off} is just a prefix, it can be
followed by any symbol constituent characters.
@end table

@node spell-mode.scm
@section spell-mode.scm
@cindex @code{spell}

Defines spelling mode, i.e. the mode in which the input text is
spelled rather than read in the usual way.  The @code{spell} mode is a
normal Festival mode, so you can use it after loading this module
immediately, e.g.

@example
(tts_file "file" 'spell)
@end example

@node cap-signalization.scm
@section cap-signalization.scm

Defines mode that allows signalling of capital letters through the
logical event @code{capital}.  @xref{Capital Letters}, for more details.

@ftable @code
@item set-cap-signalization-mode @var{mode}
If @var{mode} is true, enable capital letter signalling, otherwise
disable it.
@end ftable

@node punctuation.scm
@section punctuation.scm

Sometimes it is useful to get read all the punctuation characters
present in the synthesized text (for exact information about the text)
and sometimes it is useful to read no punctuation character (for
faster reading).  Punctuation modes allow you to tell Festival,
whether it should read punctuation characters or not.

@ftable @code
@item set-punctuation-mode @var{mode}
Set punctuation mode to @var{mode}.  @var{mode} may be one of the
following symbols: @code{all} meaning all the punctuation characters
are read, @code{none} meaning no punctuation characters are read, and
@code{default} that switches to the default Festival behavior
corresponding to the current language and voice.
@end ftable

@xref{Punctuation Characters}, for information about punctuation mode
configuration.

@node tokenize.scm
@section tokenize.scm

Festival's tokenization is implemented mostly in C++, so it is
impossible to use it when extending Festival.  The @code{tokenize}
module provides an alternative tokenization implemented in SIOD, that
can be used wherever needed.

@ftable @code
@item next-chunk @var{text}
Get the next part of @var{text} and create an utterance containing the
corresponding tokens.  A list of two elements, the utterance and the
remaining unprocessed part of @var{text}, is returned.
@end ftable

@cindex @code{SayText}
An alternative @code{SayText} function, splitting the text into
smaller pieces (and thus speeding up the start of speech) might be
implemented as follows:

@lisp
(define (SayText* text)
  (if (not (equal? text ""))
      (let ((utt-text (next-chunk text)))
        (let ((utt (car utt-text))
              (text (cadr utt-text)))
          (utt.play (utt.synth utt))
          (SayText* text)))))
@end lisp

@node multiwave.scm
@section multiwave.scm
@cindex multiple wave forms

Sometimes it is convenient to return multiple synthesized wave forms
instead of a single wave form.  There are two typical situations when
this can happen:

@itemize @bullet
@item
@cindex long texts
You want to synthesize a long text and you don't want to wait until it
is all synthesized, you want to play the resulting audio as soon as
possible.  The text can be cut into smaller pieces, returning the
corresponding wave forms in a sequence.

@item
@cindex resampling
The resulting wave form is a mixture of a synthesized texts and sound
icons, of different rates or other sound sample parameters.
Concatenating them together may reduce the resulting sound quality.
So the different sound parts may be better returned separately.
@end itemize

The @file{multiwave.scm} module provides the following interface for
those purposes:

@ftable @code
@item multi-synth @var{type} @var{value}
This function is similar to the @code{event-synth} function
(@pxref{events.scm}), except that it doesn't return an utterance
containing the resulting wave form.  Instead, it setups the synthesis
for the following @code{multi-next} calls.

@item multi-next
Return the next wave form of the last event synthesized via the
@code{multi-synth} function.  If there is no next wave form, return
@code{nil}.

If you synthesize an SSML text, the function may return a
non-@code{nil} symbol instead of a wave form.  Then the symbol is a
name of the mark just reached.

@item multi-clear
Throw away the synthesized data.  You usually don't need to call this
function as the data is cleared on the next @code{multi-synth} call
automatically, but the function may be useful under special
circumstances.
@end ftable

@node voice-select.scm
@section voice-select.scm

The voice-select module provides a mechanism for voice and language
selection.  For its configuration information, see @xref{Voice
Selection}.

The following voice selection functions are available:

@ftable @code
@item voice-list
Return the list of names of all available voices.  Unlike the list
returned by the standard Festival function @code{voice.list}, the list
includes all registered voices.

@item voice-list-language-codes
Return the list of names, language codes and dialect codes of all
available voices.  Each element of the returned list is of the form
@code{(@var{name} @var{language-code} @var{dialect-code})}, where all
the elements of the tripple are symbols.  If the language code or the
dialect code is not known for the voice, the corresponding element is
@code{nil}.

@item current-language-voices
Return a list of all the voices available for the current language.

@item select-voice @var{language} @var{dialect} @var{gender} @var{age} @var{variant} @var{name}
Select voice according to the specified parameters and return its name.
@var{language} is the language name, @var{dialect} is a @var{language}
dialect name.  @var{gender} can be one of the symbols @code{male} or
@code{female} (the value is currently ignored).  @code{age} is age of
the speaker in years given as a number.  @code{variant} is a positive
integer that selects one of several voices, if more than one voice is
selected by all other parameters.  @var{name} can be a particular
voice name.

Each of the function arguments can have @code{nil} as its value.  In
such a case, default value of the corresponding parameter is used.
If there is no default value, the parameter is not considered in the
selection process.

If more than one voice matches, one of the matched voices is selected.
If no voice satisfying all the given parameters is available, some
voice satisfying the most important parameters is selected.

@item select-voice* @var{lang-code} @var{gender} @var{age} @var{variant} @var{name}
Like @code{select-voice}, except that language and dialect are
specified by an ISO @var{lang-code}.

@item reset-voice
Reset currently selected voice parameters to their default values.
@end ftable
    
Additionally, there is a variable holding information about voice
properties currently in effect for the purpose of voice selection by
the @code{voice-select} function:

@vtable @code
@item voice-select-current-defaults
Alist containing current voice properties used by voice selection.
@end vtable

@node prosody-param.scm
@section prosody-param.scm

Ever wished to be able to change prosodic parameters in Festival
easily and in a uniform way for different voices?  Well, here are the
appropriate functions.  They are no way guaranteed to work for all
voices, since each voice can have its own unique way of prosody
handling.  But they should work for typical cases.

@ftable @code
@item set-pitch @var{value}
Set mean pitch of the voice to @var{value} and return the old pitch
value.  @var{value} is given in Hertz.

@item set-pitch-range @var{value}
Set the pitch range of the voice to @var{value} and return the old
pitch range value.  The value is in percents of the mean pitch, its
clear meaning is not defined.

@item set-volume @var{value}
Set volume to the given @var{value} and return the old volume value.
@var{value} must be in the range 0--1 from silence to maximum (the
default).

@item set-rate @var{value}
Set voice rate to @var{value} and return the old rate value.
@var{value} is in the range 0.1--10 from the slowest to the fastest.
The value 1 corresponds to the normal voice speed, other values
multiply the voice speed appropriately.
@end ftable

The @var{value} argument of all the functions above may also be a
function of a single argument accepting the current parameter value
and returning its new value.  The following convenience functions
return functions which adjust the parameter values appropriately:

@ftable @code
@item prosody-shifted-value @var{shift}
Return a function modifying the value by adding @var{shift} to it.

@item prosody-relative-value @var{coef}
Return a function modifying the value by multiplying it by @var{coef}.
@end ftable

Example setting doubling the current voice speed:

@lisp
(set-rate (prosody-relative-value 2))
@end lisp

When you switch to a different voice, prosody parameters get lost.
festival-freebsoft-utils offers a way to restore them, using the
following functions:

@ftable @code
@item change-prosody @var{function} @var{value}
Similar to the @code{set-*} functions described above, except it
additionally saves the set prosodic value.  @var{function} is one of
the @code{set-*} functions and @var{value} is its parameter value.

@item restore-prosody
Set prosodic parameters according to their current saved values.

@item reset-prosody
Reset the list of the saved prosodic values.  Note, it just deletes
the saved settings and doesn't actually change the current prosodic
parameters.
@end ftable

@node ssml-mode.scm
@section ssml-mode.scm

@cindex SSML
festival-freebsoft-utils provides a text processing mode partially
supporting the SSML 1.0 markup.  You can process a SSML file in the
following way in the Festival prompt:

@lisp
(tts_file "/the/path/to/the/file" 'ssml)
@end lisp

Moreover, there are some particular SSML processing functions
available:

@ftable @code
@item ssml-say @var{text}
Speak the given SSML @var{text}.

@item ssml-parse @var{text}
Parse the given SSML @var{text} for later processing by the
@code{ssml-next-chunk} function.

@item ssml-next-chunk
Return next utterance containing tokens from the last SSML text parsed
by @code{ssml-parse} or a mark name.  If there is no next utterance or
mark, return @code{nil}.  The returned utterance contains only the
@code{Token} relation and is intended to be further processed with the
@code{utt.synth} function.  The returned mark name is a non-@code{nil}
symbol.

@item ssml-speak-chunks
Speak the SSML text processed by @code{ssml-parse}.
@end ftable

The @code{ssml-parse} and @code{ssml-next-chunk} functions are
intended to be used when you want to synthesize an SSML text, but not
to speak it immediately.  A sample use of those functions for a
hypothetic @code{ssml-say*} function similar to @code{ssml-say} might
be as follows:

@lisp
(define (ssml-say* text)
  (ssml-parse text)
  (ssml-say*-1))

(define (ssml-say*-1)
  (let ((utt (ssml-next-chunk)))
    (if utt
        (begin
          (cond
           ((symbol? utt)
            (print utt))
           (utt
            (utt.play (utt.synth utt))))
          (ssml-say*-1)))))
@end lisp

If you need quick synthesizer response, avoid the DOCTYPE declaration
in your SSML data.  The DOCTYPE declaration takes an observable time
when processed in the Festival's XML parser.

festival-freebsoft-utils does not provide conforming SSML
implementation and implements only a limited subset of the standard.
Moreover, due to the limitations of the built-in Festival XML parser,
SSML markup texts that contain non-ASCII characters can only be
processed with the @code{ssml-parse} and @code{ssml-next-chunk}
functions and must be provided in the UTF-8 encoding.

It is not easy to fully support SSML in Festival.  Contingent support
and contributions are welcome.

@node fileio.scm
@section fileio.scm

Functions in this module try to help to improve Festival file
input/output.

@ftable @code
@item with-open-file (@var{variable} @var{filename} &optional @var{how}) @var{body-form} ...
Open file named @var{filename} in mode @var{how} (for reading if not
provided) and bind it to a newly created local @var{variable}.
Execute @var{body-form}s in that context.

@item read-file @var{filename}
Read and return whole contents of the file named @var{filename}.

@item write-file @var{filename} @var{string}
Write @var{string} to a file named @var{filename}.

@item make-read-line-state
Create and return a state object required by the function
@code{read-line}.

@item read-line @var{file} @var{state}
Read a single line from @var{file} and return it without the final
newline character.  If there is no next line in @var{file}, return
@code{nil}.  @var{state} is a state as initially returned by the
@code{make-read-line-state} function.

The typical @code{read-line} usage idiom is:

@lisp
(let ((state (make-read-line-state))
      (f (fopen "..."))
      (line t))
  (while line
    (set! line (read-line f state))
    ...))
@end lisp
@end ftable

@node recode.scm
@section recode.scm

Festival doesn't support different character sets directly.  But it is
8-bit clean and you can use whatever character coding you like if you
can process it in the form of 8-bit characters.  The
@code{recode.scm} module offers the following functions to convert
between different character sets:

@ftable @code
@item recode @var{string} @var{from-coding} @var{to-coding}
Return given @var{string}, originally encoded in @var{from-coding},
recoded to @var{to-coding}.

@vindex recode-special-utf8-translations
@item recode-utf8->current @var{string}
Return given @var{string}, originally encoded in @code{UTF-8}, recoded
to the coding of the current voice.

Before applying normal recoding this function translates strings as
specified in @code{recode-special-utf8-translations} variable.  This
allows you to convert some unicode characters in a special way,
e.g. to translate empty space to space (thus separating words around
it).  @code{recode-special-utf8-translations} contains lists of two
elements, the converted substring and its translation.
@end ftable

The recoding functions use the @code{iconv} program and temporary
files to convert between character sets.  There is no known better
way to do the conversions.

@node speech-dispatcher.scm
@section speech-dispatcher.scm

This module provides Speech Dispatcher interface.  You need it if you
want to use Festival as a Speech Dispatcher output text-to-speech
system.  The module defines functions required by the Speech
Dispatcher Festival output module and user configuration variables,
see @ref{Speech Dispatcher}.

@cindex @code{speechd-speak}
To ease debugging, for each Speech Dispatcher function which returns
a wave form, there is defined a corresponding function of the same
name with star appended, that returns an utterance instead of wave
form.  For instance, the function @code{speechd-speak} returns a wave
form (and can be used only in server mode), while the function
@code{speechd-speak*} returns an utterance.

@c ****************************************************************************

@node Contact
@chapter How to contact us
@cindex author
@cindex contact

The author of festival-freebsoft-utils is Milan Zamazal
@email{pdm@@freebsoft.org}.  The home page of festival-freebsoft-utils
is @url{http://www.freebsoft.org/festival-freebsoft-utils/}.

@cindex bugs
@cindex mailing list
You can contact us with your comments, questions, suggestions, patches
or anything at the Speech Dispatcher mailing list
@email{speechd@@freebsoft.org}.  Bug reports can be sent to the e-mail
address @email{festival-freebsoft-utils@@bugs.freebsoft.org}.

@cindex Free(b)soft project
festival-freebsoft-utils is part of the Free(b)soft project aimed at
making computers accessible to blind and sorely visually impaired
people.  The home page of the project is
@url{http://www.freebsoft.org}.

@c ****************************************************************************

@node Copying This Manual
@appendix GNU Free Documentation License

@cindex FDL, GNU Free Documentation License
@center Version 1.2, November 2002

@include fdl.texi

@c ****************************************************************************

@node Index
@unnumbered Index

@printindex cp

@bye

@c  LocalWords:  texinfo setfilename freebsoft utils settitle syncodeindex fn
@c  LocalWords:  cp ky vr dircategory direntry titlepage vskip pt filll dir url
@c  LocalWords:  insertcopying ifnottex cindex scm SayText emph vindex xref var
@c  LocalWords:  vtable alist ftable nopauses speechd util prog dolist assoc oo
@c  LocalWords:  avg args dirname basename tmp langvar concat subwave utt arg
@c  LocalWords:  func foo Param synth FDL fdl texi printindex festivalrc pre
@c  LocalWords:  Tokenization eou tokenizer tokenization backend signalization
@c  LocalWords:  tokenize multiwave avalue glet pxref tts cadr
