Most aspects of the operation can be customized by changing options. This can be enforced by TTSCP commands, in configuration files and on the command line. Basically, an option is an option name/option value pair. There are a few possible option types: number, string, yes/no, character, and a few enumerated types.
Almost all individual options are documented in
this document. If you strongly suspect this section of
documentation to be out-of date, the reliable list of all built-in
long options can be found in src/options.lst. (See approximately
line 320 and below. Every line represents at most one option for every
option class as explained below. The option name is quoted; its
semantics is usually explained following the option.) You can also
list the option names and types using eposd -H.
There are four classes of options: static options, global options, language options and voice options. For instance, switching a voice in fact means switching to another set of voice options, while the language options, global options and static options stay the same.
Every voice is language specific (implies a specific language). That's why switching the language automatically switches the voice to the voice defined as default or the last active one for this particular language. (It is of course possible to use the same configuration file to setup a similarly sounding voice for every language if desired.) It is also important to distinguish between a voice and an inventory. An inventory is a set of speaker-dependent files used as a base for voice, that is, a mode of speech. Multiple different voices may use the same inventory, and may even sound quite different depending on various configuration options. A user of moderate expertise will be able to modify the voice dependent configuration files, but not the inventory files. Also, the inventories may often be distributed externally to Epos, while sample voices based on them may either be included with Epos, or with the segment inventory, or their creation may be completely left to the user.
A set of voice options should completely describe a voice. A set of language options should completely describe a language, except for voice-specific behavior. A set of global options should cover language independent aspects of operation. It should be understood that a set of options may employ various references to other information, especially filenames (of language dependent transcription rules, voice dependent segment inventories etc.)
Some language and/or voice specific options may have suitable defaults for all but specific languages/voices. That's why there is a corresponding language option for every voice option to default to if unspecified for a given voice. Likewise, there is a global option for every language option to default to. Therefore, adding a new language or voice options doesn't necessarily imply adding them to each language or voice configuration file, if a reasonable default can be suggested.
The difference between global and static options is subtler and not that important for most users. All voice specific, language specific and also global options are implemented as user specific, that is, each TTSCP control connection may assign a different value to them at the same time. For some options however, which are of even more global impact, this may make little sense. These are termed static. Assigning a value to a static option causes the value to change even for other concurrent users.
Whenever an option name is given, it is first understood as a voice option (of the current voice); if there is no such voice option, the name is treated as a language option, then as a global/static option. To override this order, you can prefix an option with "S:", "C:", "L:" or "V:". This will restrict the search to static, global, language or voice options, respectively. (This is automatically done with configuration files, because every configuration file describes either a language or a voice, or it is unrelated to the current language and voice altogether.)
Each option has an associated type, which is indicated with each option in the documentation. Mostly these are traditional types like booleans, strings, and non-negative numbers. Others are limited to a fixed choice of values (e.g. "mono" or "stereo"), yet others are limited to a choice of values which depends on other configuration (e.g. on the levels of descriptions, on the available encoding mapping files, or on the current list of language configurations). With all these options it is impossible to set the option to a syntactically impossible value, although it is easy to set the option to a value which makes little sense.
Several string-typed options (especially the language, voice and soft option lists) have special behavior if they appear multiple times within the configuration (not limited to the configurations files!). In contrast with almost all options which take the last value offered, these special options concatenate all the supplied values and separate them by colons. This makes sense, as all these option values are syntactically colon separated lists of strings.
If you need to set an autoconcatenating option to a different value, you need first to reset it first by supplying an empty string to it. This does set it to the empty string as opposed to concatenating a colon and an empty string to the previous value.
Whenever the program starts up, it reads a number of configuration
files, setting up the initial (default) values of the options.
These are located under /usr/local/share/epos (unless overidden
at configure/compile time or
with the --base_dir option on the command line). By convention,
configuration file names have the ".ini" suffix.
(On a Windows NT-like operating system, you can use the
HKEY_LOCAL_MACHINE\SOFTWARE\Epos\Setup
registry key to set the value of Path to a path leading
to the configuration files. This value can still be overridden
by the command line.)
Unless overridden, three files in /usr/local/share/epos/cfg will be processed
to setup the global configuration: fixed.ini, epos.ini and
either ansi.ini or rtf.ini (depending on the preferred
output format if colored output is turned on -- either ANSI escape sequences
or RTF are supported at the moment; other markup formats can be added easily).
By convention, fixed.ini contains the standard global and static configuration
values used by a given installation and rarely or never changes, while
epos.ini contains less permanent parameters and temporary values.
The global parameters include a list of languages, or language
configurations which will be parsed when the global configuration is set up.
Every language .ini file in turn contains a list of voices to be
configured for this particular language. Language configuration files
are located under /usr/local/share/epos/lng/*/*.ini, voice configuration files
under /usr/local/share/epos/inv/*/*.ini, where * represents any string
listed in the list of languages (or voices for a language). Go see the real
files under /usr/local/share/epos/cfg/*.ini for an example.
A configuration file contains one option per line (empty lines are ignored).
Each option is a name-value pair, separated with whitespace. A string value
may be (and sometimes must be, e.g. if it begins with whitespace) enclosed
in double quotes. Every configuration
file is associated with a certain option set, that is, it contains either just
global options, or options related to some language or voice. (In the latter
two cases, the name option identifies the language or voice properly.)
Sometimes it is not convenient or possible to encode all configuration files in the same character encoding. For example, a character encoding may be language dependent. But it is even possible for different lines of the same file to use different encodings. You can switch character encodings for the same file ufrom timeto time as well, but there may be minor incompatibilities in recent code. In this documentation, references to UNIX should be read as "tested on Linux, implemented using POSIX compliant interfaces and expected to be easy to get working on any other UNIX clone".
Epos uses the autoconf package to avoid portability pitfalls
within the UNIX world. Features like syslog are welcomed
and used, but only if the corresponding system header file is detected
by autoconf.
For sound output, OSS is preferred (if detected); otherwise, the Portable Audio library conveniently provided with Epos is used.
On the QNX operating system, Epos can be controlled not only over
a TCP-based TTSCP implementation, but also using a QNX specific
interprocess communication interface. See src/qnxipc.cc
for details; be however aware that this code has never been completely
debugged because of a drop in our motivation. You could help debug
this easily if you really need this and provide us with a QNX machine.
See the arch/win directory for architectural differences from UNIX.
Be aware of the following three differences of Epos's behavior
on these operating systems: the mmsystem (Microsoft Multimedia System)
library is used instead of /dev/dsp (Open Sound System) for speech output;
Epos compiles and runs as an NT service named ttscp, instead of a UNIX-style
daemon; you can use registry to locate the configuration files.
In order to make service installation and registry access available,
it is necessary to build and run the instserv utility before
running Epos. That utility, if run with the letter u on its
command line, can also uninstall the ttscp service, but it doesn't
remove any registry values.
You should use the Visual C++ compiler for compiling Epos, but you
don't need it for running Epos. The Borland C++ Builder and Watcom C++
used to work a long time ago, too. Ask us for help with these compilers
if necessary. Please refer to the WELCOME file on
how to proceed step by step with Visual C++.
File input and output modules are not going to work
with Windows sockets (whose incompatible implementation
of the select call doesn't allow file decriptors at all).
If you do enable the writefs option, Epos will crash
after the first writing error such as disk full.
Don't try to enable the readfs option.
The port was roughly done and found possible, but it is
not maintained. Ask us if you need it. Files specific
for this port can be currently found at
arch/win-ce.
An experienced Windows user can get a good estimate of this port's behavior from reading the sections on other versions of Windows. The same holds for Windows XP embedded.
We don't support these DOS successors very strongly now,
but these ports used to work. If you want to try out,
you should probably comment out the HAVE_WINSVC_H line
in src/config.h after running arch/win/configure.bat.
This will force Epos to compile not as a Windows NT service, but
as an ordinary UNIX-style daemon. In fact, the way Epos is written,
it will decide to run as a daemon if it can't connect to the service
controller anyway.
The same holds for MS DOS, but as MS DOS offers no sound playback interface, you'll have to comment out portions of source code here and there to make Epos e.g. produce wave files. Good luck and don't even try to use 16-bit compilers, please.
Please contact the authors for advice with any OS significantly different from the UNIX and Windows families. However, the approximate requirements are:
Note that the architectural requirements are only a guideline and are enforced rather for lack of energy for debugging Epos on every perverse 36-bit machine with PDP byte ordering. Epos supports big endian architectures, but the corresponding code still needs to be tested. The integers and pointers can be any size not less than 32 bits as long as the integers are not longer than pointers. If they were, a single code change would do the port.
TCP/IP networking is not strictly necessary, but if you don't have it, you can either try to adapt the QNX IPC proxy for your favourite IPC interface, or you can build the monolithic binary of Epos.
A bourne-compatible shell is helpful, as it allows to run a configure
script. Otherwise you have to write a src/config.h file by hand
as we have done with the Windows ports. A plain old make utility
helps the compilation process if your OS can emulate a UNIX development
environment a little bit.
The header files mostly define basic interfaces for individual Epos components.
Reading the ones related to a specific piece of code may often clarify things.
Lots of global data declarations live in common.h; others (especially
small, library-like functions) can be found in interf.h.
If you have any code or development related comment or question about Epos, send
it to the Epos development mailing list
epos@braille.mff.cuni.cz. You are also encouraged to subscribe to the
list first by sending a mail containing only the text subscribe epos to
mailto:listserv@braille.mff.cuni.cz>.
Please spend a few seconds by trying to look up the answer in the documentation first.