MULTISPEECH.CONF(5)

NAME
multispeech.conf - Multispeech configuration file

DESCRIPTION
On startup multispeech expects to find it's configuration in /etc/multispeech.conf and ~/.multispeechrc. The user settings provided by ~/.multispeechrc always take precedence over the system-wide ones from /etc/multispeech.conf. And all these settings in turn can be overridden by an extra configuration file specified via the command line. Being started as Speech Dispatcher module, multispeech treats the file specified in command line as an extension of global configuration. Options specified there override ones from the main system configuration file, but ~/.multispeechrc takes precedence over the both.
 Some configuration options are mandatory, so at least one of these files must exist.

SYNTAX
The syntax is quite simple.

Lines started from the ‘#’ character are treated as comments. Blank lines are ignored. Each option entry looks like follows:

keyword = value

Case is significant.

All options are logically grouped by sections. Each section is started by its name in square brackets on a separate line.

CLIENT INTERACTION CONTROL OPTIONS
These options are grouped in the section named ‘frontend’. These options are as follows:

charset
    Input charset should be specified by its name. Available names can be found in /usr/share/i18n/SUPPORTED or wherever else it is on your system. By default this option is not set so current locale setting is used.

native_voices
    Enable native voice control embedded commands.

dtk_voices
    Enable DECtalk voice control embedded commands.

These two options control inline parameters parsing. In the default state only native voices are enabled, so multispeech behaves as it used to and accepts only special inline commands formed by emacspeak. When dtk voices are enabled, multispeech recognizes DECtalk inline commands and tries to emulate some subset of the DECtalk voice control capabilities. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable the option. Nothing prevents to keep both options enabled simultaneously. In this case DECtalk inline commands will be accepted as well as the native ones. If both options are disabled, then inline commands detection and parsing will not be performed at all.

GENERAL AUDIO OUTPUT CONTROL OPTIONS
Section name is ‘audio’. It contains following options:

device
    Default device for all audio output (speech, sounds and tones). If it is not specified explicitly, then system default will be used. The DSP device specifications (such as ‘/dev/dsp’) are allowed here as well as the ALSA ones. Invoke ‘multispeech -l’ to get list of all available devices on your system.

general_volume
    Volume level applied to all audio output in general. It should be in the range of (0.0..1.0]. When this option is not specified the default value 0.8 is used.

latency
    Audio output latency in seconds. Special value 0.0 implies that reasonable latency will be chosen automatically by system. Normally this option should not be set up explicitly. Do it only if you are pretty unsatisfied by the default.

async_operation
    This option enables truly asynchronous audio stream operation. Normally it is absolutely not necessary, thus, disabled by default, but theoretically there can be some circumstances where it would be preferable. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable.

pulseaudio_direct
    This option allows direct usage of PulseAudio API for ‘pulse’ and ‘default’ devices when ‘pulse’ device is present in the system. If it is disabled, these devices will be accessed via native host API bridge. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable.

SOUNDS PLAYING CONTROL OPTIONS
Section name is ‘sounds’. It contains several options that affect sound file playing capability:

device
    Sound files playing device. This setting overwrites general default and allows one to play sound files on a separate audio device. The DSP device specifications (such as ‘/dev/dsp’) are accepted here as well as the ALSA ones. Invoke ‘multispeech -l’ to get list of all available devices on your system.

volume
    Relative volume level for sound files playing. It is 1.0 by default.

asynchronous
    This option enables or disables to play sound files simultaneously with other audio activities, such as speech and tone signals producing. It is enabled by default. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable.

TONE SIGNALS PRODUCING CONTROL OPTIONS
Section name is ‘tones’. It consists of the following options:

device
    Tones producing device. This setting overwrites general default and allows one to use a separate device for tone signals. The DSP device specifications (such as ‘/dev/dsp’) are accepted here as well as the ALSA ones. Invoke ‘multispeech -l’ to get list of all available devices on your system.

volume
    Relative volume level for tone signals producing. It is 1.0 by default.

sampling
    Sampling frequency for generated tone signals. It is 44100 by default.

asynchronous
    This option enables or disables to produce tone signals simultaneously with other audio activities, such as speech and sound files playing. It is enabled by default. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable.

GENERAL SPEECH CONTROL OPTIONS
Section name is ‘speech’. These options affect speech output in general:

device
    Speech output device. This setting overwrites general default and allows one to produce speech on a separate audio device. The DSP device specifications (such as ‘/dev/dsp’) are accepted here as well as the ALSA ones. Invoke ‘multispeech -l’ to get list of all available devices on your system.

volume
    Relative volume level for speech output. It is 1.0 by default.

language
    This option specifies the language to speak. Allowed values are: ‘en’ for English, ‘ru’ for Russian, ‘de’ for German, ‘fr’ for French, ‘es’ for Spanish, ‘pt’ for Portuguese, ‘it’ for Italian or ‘autodetect’ for automatic detection from the text nature. By default language is autodetected. The language then may be changed on the fly during runtime by respective commands.

fallback
    This option specifies the language that will be chosen when it should be changed, but autodetection fails. Any supported language may be specified here, of course, except of ‘autodetect’. Of course, the language declared as a fallback must be available itself. See below about language related options.

LANGUAGE RELATED SPEECH CONTROL OPTIONS
There is a separate section for each supported language named ‘en’ for English, ‘ru’ for Russian, ‘de’ for German, ‘fr’ for French, ‘es’ for Spanish, ‘pt’ for Portuguese and ‘it’ for Italian. These sections contain quite the same collection of options that affect speech on a specific language. Actual speech engine is chosen by the key option ‘engine’. By default it is ‘espeak’ for all languages. If it is explicitly not set or set as ‘disabled’ then the language will not be available in Multispeech and no resources will be spent for it. Actual choice vary from language to language, but these two values are always legitimate. It is not necessary to define speech engine for each language, but at least one must be defined. It is wise to define speech engine for only those languages that are actually to be used or define speech engine for all languages in global configuration and then locally disable some of them that are not needed.

Each language specific section consists of the following options:

engine
    TTS engine specification. Allowed values are as follows:

freephone - English speech with Freephone and Mbrola voice ‘en1’;
ru_tts - Russian speech with Ru_tts speech synthesizer;
espeak - all supported languages with Espeak TTS engine;
mbrola - English, German, French, Spanish, Portuguese and Italian speech produced by Mbrola in conjunction with Espeak as a preprocessor;
user - user defined TTS engine.

priority
    Language detection priority. Any integer value is allowed. During autodetection languages are probed in the ascending order of their priority values. It is 0 by default.

volume
    Specific voice loudness relatively to the general speech volume level. It is 1.0 by default.

pitch
    Specific voice pitch adjustment relative to it's normal level. It is 1.0 by default. Greater value causes higher pitch.

rate
    Relative speech rate for specific voice. It is 1.0 by default. Higher value causes quicker speech.

acceleration
    Apply additional speech tempo acceleration. Speech rate will be changed by specified difference in percents compared to the original tempo. Positive values cause speech acceleration while the negative ones actually imply slowing it down. Default value is 0 so no additional tempo change is applied.

char_pitch
    Relative voice pitch control applied to the single letters pronunciation. By default 1.0 is suggested.

char_rate
    Relative speech rate control applied to the single letters pronunciation. By default 1.0 is suggested.

caps_factor
    Voice pitch factor for capital letters. By default it is 1.2 so capital letters are pronounced by slightly higher pitch.

speak_numbers
    This option affects numbers speaking. When it is ‘yes’ or ‘on’, digits are treated as if they belong to the native alphabet and, therefore, do not cause language switching. When it is ‘no’ or ‘off’, digits are treated as foreign symbols causing switch to another language that will be the fallback one or some other according to the language priority settings. It is ‘yes’ by default.

MBROLA RELATED OPTIONS
Section named ‘mbrola’ contains some options affecting multispeech interaction with mbrola speech engine:

executable
    Path to the Mbrola executable. If only program name is specified (as it is by default) then environment variable PATH will be examined and all paths mentioned there will be searched.

voices
    Path to the directory where Mbrola voice files are stored. By default ‘/usr/share/mbrola’ is suggested.

MBROLA VOICES ASSIGNMENT
These voices are used by Mbrola backend in conjunction with Espeak. To see the list of the voices supported by Espeak try to invoke ‘espeak --voices’. Only Mbrola voices are allowed here. Also make sure that you have corresponding Mbrola voices itself. See Espeak documentation for further details.

en
    English voice. By default ‘en1’ is used.

de
    German voice. By default ‘de6’ is used.

fr
    French voice. By default ‘fr4’ is used.

es
    Spanish voice. By default ‘es1’ is used.

pt
    Portuguese voice. By default ‘br3’ is used.

it
    Italian voice. By default ‘it3’ is used.

FREEPHONE RELATED OPTIONS
Section named ‘freephone’ is devoted to freephone speech backend. Here are the following options:

executable
    Path to the Freephone executable. If only program name is specified (as it is by default) then environment variable PATH will be examined and all paths mentioned there will be searched.

lexicon
    Path to the lexical database. By default ‘/usr/share/freespeech/enlex.db’ is suggested.

RU TTS RELATED OPTIONS
Section named ‘ru_tts’ consists of options that control multispeech interaction with ru_tts speech synthesizer:

executable
    Path to the Ru_tts executable. If only program name is specified (as it is by default) then environment variable PATH will be examined and all paths mentioned there will be searched.

lexicon
    Path to the lexical database. By default ‘/usr/share/freespeech/rulex.db’ is suggested.

log
    Optional file to collect unknown words. This file must be writable for the Multispeech user. The collected data can be used later to improve lexical database. No such file is suggested by default so unknown words are not stored.

expressiveness
    Relative voice pitch variation level. The default value is 1.0. It is the normal intonation. Value 0.0 causes absolutely monotonic speech.

female_voice
    When this option is ‘yes’ the alternative female voice is used instead of the default (male) one.

decimal_point
decimal_comma
    These options enable or disable treating point and comma inside a number as decimal separator. By default both are enabled. Use ‘yes’ or ‘on’ to enable and ‘no’ or ‘off’ to disable.

interclause_gap_factor
    The factor applied to all interclause gap durations.

comma_gap_factor
dot_gap_factor
semicolon_gap_factor
colon_gap_factor
question_gap_factor
exclamation_gap_factor
    the factors applied to the durations of the gaps implied by the corresponding punctuations.

intonational_gap_factor
    The factor applied to the duration of intonational gaps not caused by punctuations.

ESPEAK RELATED OPTIONS
Interaction with espeak TTS engine is controlled by the options grouped in section ‘espeak’:

executable
    Path to the Espeak executable. If only program name is specified (as it is by default) then environment variable PATH will be examined and all paths mentioned there will be searched.

en
    English voice specification. By default ‘en’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

ru
    Russian voice specification. By default ‘ru’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

de
    German voice specification. By default ‘de’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

fr
    French voice specification. By default ‘fr’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

es
    Spanish voice specification. By default ‘es’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

pt
    Portuguese voice specification. By default ‘pt’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

it
    Italian voice specification. By default ‘it’ is suggested. Invoke ‘espeak --voices’ to see all available alternatives.

USER DEFINED TTS BACKEND OPTIONS
The section name is ‘user’. The following options are grouped here:

command
    Shell command to perform TTS transformation. This command must accept text on the standard input and produce sound stream on the standard output. It should be a simple command, pipes or other shell complications are not allowed here, but command line arguments may be specified. Moreover, there are several special keywords recognized by Multispeech and replaced by actual values internally just before execution. This mechanism allows Multispeech to pass current speech parameters to the TTS engine. These keywords are as follows:

%lang - replaced by the language id string;
%pitch - replaced by relative voice pitch value;
%rate - replaced by relative speech rate value;
%freq - replaced by the sampling frequency value.

The last keyword is replaced only when freq_control is enabled (see below).

format
    Produced sound stream sample format. The following values are allowed here:

s8 - signed 8 bits;
u8 - unsigned 8 bits;
s16 - signed 16 bits.

Leave this option commented out if sound stream is produced in a format that can be detected automatically, such as wave file for instance.

sampling
    Produced sound stream sampling frequency in Hz. Assumed 22050 by default. This option is ignored when sound stream format is autodetected.

stereo
    Set to ‘yes’ if produced sound stream is stereo. By default it is assumed mono. This option is ignored when sound stream format is autodetected.

freq_control
    Set this option to ‘yes’ if TTS engine accepts sampling frequency specification (as mbrola does, for instance) and you wish to make use of this capability. This option allows ‘%freq’ keyword replacement in command line. Leave commented out if unsure.

charset
    Character set in which the TTS engine accepts it's input. Available charset names can be found in /usr/share/i18n/SUPPORTED or wherever else it is on your system. By default this option is not set so current locale setting is used.

SPEECH DISPATCHER MODULE RELATED OPTIONS
The section name is ‘spd’. The following options are grouped here:

version
    Speech Dispatcher version. Usually it is correctly guessed automatically, but you can specify it explicitly when compatibility issues take place.

sound_icons
    Path to the directory where multispeech will search sound icon files when acting as Speech Dispatcher module. By default ‘/usr/share/sounds/sound-icons’ is suggested.

use_voice_language
    This option defines multispeech behaviour when synthesis_voice and language settings are passed by
     Speech Dispatcher in a single request. If it is ‘yes’ or ‘on’, language will be chosen according to the specified voice, otherwise, when it is ‘no’ or ‘off’, the last setting in packet will take precedence. By default this option is ‘yes’.

accept_explicit_language
    This option enables or disables explicit language choice by Speech Dispatcher. When disabled, language can be chosen only via synthesis_voice. Use the word ‘yes’ or ‘on’ to enable and the word ‘no’ or ‘off’ to disable. By default this option is enabled.

ignore_unknown_voice
    When this option is ‘yes’ or ‘on’, Speech Dispatcher
     requests to set synthesis_voice with unknown name are ignored. Otherwise, when it is ‘no’ or ‘off’, such requests are treated as if the voice name was ‘NULL’. This special name is used for so-called default voice that allows multispeech to utilize language autodetection mechanism. Though language still can be changed explicitly by Speech Dispatcher if enabled. This option is ‘no’ by default.

index_marks
    This option enables or disables index marks support. When it is ‘yes’ or ‘on’, index marks are reported correctly, but it is necessary to split message at the point of index mark. If such side effect is somewhat inconvenient, it may be better to turn off index marks support by setting this option to ‘no’ or ‘off’. By default index marks support is enabled.

SEE ALSO
espeak(1), freephone(1), mbrola(1), multispeech(1), ru_tts(1), speech-dispatcher(1).

AUTHOR
Igor B. Poretsky <poretsky@mlbox.ru>.