festival-freebsoft-utils

3.1 The Concept of 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 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:

text ¶

Text. The event value is a string containing the given text.

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.

sound ¶

Sound icon. The value is a string containing a file name of a sound file, either absolute, or relative to the sound-icon-directory variable value.

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.

key ¶

A key (as on keyboard). The value is a string containing key description in the format defined by the Speech Synthesis Interface Protocol, SSIP in SSIP.

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. See events.scm, for more details.

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:

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 (event-type mappings). event-type is one of the symbols logical, text, sound, character, key. mappings is an alist with the elements of the form (value new-event-type new-event-value).

See the default variable value for an example.

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

set-event-mapping! event-type event-value new-event-type new-event-value ¶

Ensure the event of event-type and event-value is mapped to the event of new-event-type new-event-value.

Example:

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

3.2 Word Substitution

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

word-mapping ¶

Alist mapping words to events. Each entry of the list is of the form ("word" event-type event-value). If word is encountered in the input text, it is replaced by the given event.

3.3 Signalling Capital Characters

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

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

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

3.4 Reading Punctuation Characters

Through the punctuation modes, 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:

punctuation-pronunciation ¶

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

("!" "exclamation" "mark")

3.5 Avoiding Initial 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 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:

(require 'nopauses)

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

inhibit-initial-pauses ¶

When set to a non-nil value, initial pauses are inhibited.

3.6 Tokenization

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 eou_tree.

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.

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.

3.7 Voice Selection

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

language-codes ¶

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

voice-select-defaults ¶

Alist of default voice parameters. Each alist entry is of the form (name value), where value can be either the actual parameter value or nil, meaning the value is unspecified.

3.8 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, See Voice Selection.

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

4.1 util.scm

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

Macros and functions mostly available in Lisp dialects:

when condition body-form ... ¶

If and only if condition is true, evaluate body-forms.

unless condition body-form ... ¶

If and only if condition is false, evaluate body-forms.

prog1 form ... ¶

Evaluate all forms and return the return value of the first one.

let* bindings body-form ... ¶

The same as let except that variable bindings are applied sequentially rather than in parallel.

unwind-protect* protected-form cleanup-form ... ¶

Evaluate protected-form, and after it is finished, whether successfully or with errors, evaluate all cleanup-forms. If protected-form was evaluated successfully, return its return value.

Unlike Festival’s unwind-protect, unwind-protect* accepts multiple cleanup-forms and evaluates them even when protected-form doesn’t signal an error.

first list ¶

second list ¶

third list ¶

fourth list ¶

Return first, second, third or fourth element of list, respectively.

butlast list ¶

Return the list without its last element. If list is empty, return an empty list.

min x y ¶

Return minimum of the two numeric values x and y.

max x y ¶

Return maximum of the two numeric values x and y.

abs x ¶

Return absolute value of x.

remove-if test list ¶

Return list with elements, for which the test call returns non-nil, removed. The order of list elements is preserved. test must be a function of a single argument.

identity object ¶

Return object.

complement function ¶

Return a function that is equivalent to function except that it returns the opposite truth value to the return value of function.

apply* function arglist ¶

The same as apply, except that it also works if function is given as a string.

dolist (var items) body-form ... ¶

Loop over items and perform body-forms over each of them, binding it to the variable var (unevaluated).

add-hook hook-variable hook-function to-end? ¶

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

assoc-set list key value ¶

Add the key-value pair to the association list and return the resulting list. Contingent previously list entries stored under key are removed from the resulting list.

avalue-get key alist ¶

Find the first alist element of the form (key* value), where key* is string-equal to key, and return value.

avalue-set! key alist value ¶

Destructively set the value* of the first alist element of the form (key* value*) to value. Return alist.

avg . args ¶

Return average value of args.

dirname path ¶

Return the directory part of path.

make-temp-filename template ¶

Return name of a (probably non-existent) temporary file. template is a basename of the file, that is formatted with the format function and must contain exactly one %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 make_tmp_filename function.

with-temp-file filename body ¶

Macro that binds newly generated temporary file name to a local variable filename and then performs body. The macro ensures the temporary file is deleted after finishing body in any way.

string-replace string from to ¶

Replace all occurrences of from by to in string and return the result.

Festival specific utilities:

item.has_feat item feature ¶

Return true if and only if item has feature set.

langvar symbol ¶

Return language dependent value stored under symbol. First, the variable named symbol.language, where language is the language name as stored in the Language parameter is checked and if it is unbound, symbol’s value is returned.

current-voice-coding ¶

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

utt-relation-top-items utt relation ¶

Return a list of top level items in relation in utt.

do-relation-items (var utterance relation) body-form ... ¶

Loop over relation items of utterance, performing body-forms for each of them, binding it to the variable var. The macro arguments var and relation are not evaluated.

do-relation-top-items (var utterance relation) body-form ... ¶

Similar to do-relation-items, but loops only over the relation’s top items.

4.2 Wave form handling

There are some utility functions to help handling wave forms:

wave-concat waves ¶

Append wave forms and return the resulting wave form. waves must be a list of wave forms to append.

wave-subwave wave from-time to-time ¶

Return the part of wave form that starts at from-time and finishes at to-time. Both times are in seconds.

wave-load filename ¶

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

wave-utt wave ¶

Create and return an utterance, that contains just the Wave relation holding wave.

wave-import-utt filename ¶

Create and return an utterance, that contains just the Wave relation holding a wave loaded from filename via the function wave-load.

4.3 oo.scm

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:

define-wrapper (function arg ...) wrapper-name . body) ¶

Wrap function with arguments arg ... by the code body. Given function arguments must match the arguments of the wrapped function. 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 define-wrapper arguments is evaluated.

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

oo-ensure-function-wrapped 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.

oo-unwrapped function-name ¶

Return the original definition of a wrapped function.

Example use:

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

You can also wrap parameters, set by Param.set:

Param.wrap name wrapper-name . body ¶

Wrap access to parameter name by code body. If the given parameter is accessed, its wrapper is invoked instead of just returning the parameter value. wrapper-name is the same as in define-wrapper.

Macro next-value is automatically defined within body. It returns the parameter value, either plain or modified by another wrapper.

Example use of parameter wrapping:

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

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

glet* bindings . body ¶

Similar to let* (see util.scm) except that the variables in bindings are bound dynamically instead of lexically. All variables in bindings must be global variables.

4.4 events.scm

For introductory and configuration information about events see The Concept of Events. The event module provides the following functions to synthesize events:

event-synth type value ¶

Synthesize event of type, which may be one of the following symbols: logical, text, sound, character, key. event is the event value that must correspond to the event type.

event-play type value ¶

Play event. The type and value arguments are the same as in event-synth.

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

_debug_on*

Turn on debugging. That means every processed event is logged. _debug_off is just a prefix, it can be followed by any symbol constituent characters.

_debug_off*

Turn the debugging off. _debug_off is just a prefix, it can be followed by any symbol constituent characters.

4.5 spell-mode.scm

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

(tts_file "file" 'spell)

4.6 cap-signalization.scm

Defines mode that allows signalling of capital letters through the logical event capital. See Signalling Capital Characters, for more details.

set-cap-signalization-mode mode ¶

If mode is true, enable capital letter signalling, otherwise disable it.

4.7 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.

set-punctuation-mode mode ¶

Set punctuation mode to mode. mode may be one of the following symbols: all meaning all the punctuation characters are read, none meaning no punctuation characters are read, and default that switches to the default Festival behavior corresponding to the current language and voice.

See Reading Punctuation Characters, for information about punctuation mode configuration.

4.8 tokenize.scm

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

next-chunk text ¶

Get the next part of text and create an utterance containing the corresponding tokens. A list of two elements, the utterance and the remaining unprocessed part of text, is returned.

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

(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)))))

4.9 multiwave.scm

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:

• 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.
• 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.

The multiwave.scm module provides the following interface for those purposes:

multi-synth type value ¶

This function is similar to the event-synth function (see events.scm), except that it doesn’t return an utterance containing the resulting wave form. Instead, it setups the synthesis for the following multi-next calls.

multi-next ¶

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

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

multi-clear ¶

Throw away the synthesized data. You usually don’t need to call this function as the data is cleared on the next multi-synth call automatically, but the function may be useful under special circumstances.

4.10 voice-select.scm

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

The following voice selection functions are available:

voice-list ¶

Return the list of names of all available voices. Unlike the list returned by the standard Festival function voice.list, the list includes all registered voices.

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 (name language-code 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 nil.

current-language-voices ¶

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

select-voice language dialect gender age variant name ¶

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

Each of the function arguments can have 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.

select-voice* lang-code gender age variant name ¶

Like select-voice, except that language and dialect are specified by an ISO lang-code.

reset-voice ¶

Reset currently selected voice parameters to their default values.

Additionally, there is a variable holding information about voice properties currently in effect for the purpose of voice selection by the voice-select function:

voice-select-current-defaults ¶

Alist containing current voice properties used by voice selection.

4.11 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.

set-pitch value ¶

Set mean pitch of the voice to value and return the old pitch value. value is given in Hertz.

set-pitch-range value ¶

Set the pitch range of the voice to value and return the old pitch range value. The value is in percents of the mean pitch, its clear meaning is not defined.

set-volume value ¶

Set volume to the given value and return the old volume value. value must be in the range 0–1 from silence to maximum (the default).

set-rate value ¶

Set voice rate to value and return the old rate value. 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.

The 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:

prosody-shifted-value shift ¶

Return a function modifying the value by adding shift to it.

prosody-relative-value coef ¶

Return a function modifying the value by multiplying it by coef.

Example setting doubling the current voice speed:

(set-rate (prosody-relative-value 2))

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

change-prosody function value ¶

Similar to the set-* functions described above, except it additionally saves the set prosodic value. function is one of the set-* functions and value is its parameter value.

restore-prosody ¶

Set prosodic parameters according to their current saved values.

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.

4.12 ssml-mode.scm

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:

(tts_file "/the/path/to/the/file" 'ssml)

Moreover, there are some particular SSML processing functions available:

ssml-say text ¶

Speak the given SSML text.

ssml-parse text ¶

Parse the given SSML text for later processing by the ssml-next-chunk function.

ssml-next-chunk ¶

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

ssml-speak-chunks ¶

Speak the SSML text processed by ssml-parse.

The ssml-parse and 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 ssml-say* function similar to ssml-say might be as follows:

(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)))))

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 ssml-parse and 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.

4.13 fileio.scm

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

with-open-file (variable filename &optional how) body-form ... ¶

Open file named filename in mode how (for reading if not provided) and bind it to a newly created local variable. Execute body-forms in that context.

read-file filename ¶

Read and return whole contents of the file named filename.

write-file filename string ¶

Write string to a file named filename.

make-read-line-state ¶

Create and return a state object required by the function read-line.

read-line file state ¶

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

The typical read-line usage idiom is:

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

4.14 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 recode.scm module offers the following functions to convert between different character sets:

recode string from-coding to-coding ¶

Return given string, originally encoded in from-coding, recoded to to-coding.

recode-utf8->current string ¶

Return given string, originally encoded in UTF-8, recoded to the coding of the current voice.

Before applying normal recoding this function translates strings as specified in 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). recode-special-utf8-translations contains lists of two elements, the converted substring and its translation.

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

4.15 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 Using with Speech Dispatcher.

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 speechd-speak returns a wave form (and can be used only in server mode), while the function speechd-speak* returns an utterance.