I. Important informations

For Ubuntu 12.04 and 14.04 users:

Yu must have Wine version min. 1.7.18 to run Ivona voices!

All required software (excluding sd_sapi module itself)
you can install directly from my PPA. To add it to source list
simple type commands:

sudo add-apt-repository ppa:ethanak/milena
sudo apt-get update


Then you can install software:
sudo apt-get install sapi4linux python-pyspda python-sapilektor libsapilektor-utils

Rest of user should prepare development files of libao, sndfile and python.
If your system uses pulseaudio, you should also provide development files
for pulseaudio library. For sapi server list of needed packages is
included.


II. Install and test pyspda module.
   Ubuntu users should skip this chapter
   and install python-pyspda directly from ppa

Due to some unknown reasons this module sometimes may not work on your system,
so we should check it before any serious work.

Download  from http://tts.polip.com/files/sapi/ and unpack latest version
of pyspda sources. Go to pyspda folder and enter commands:

./configure
make
make audio_test

After last command you should hear one or two sound. Rising sound means
libao driver works, falling means pulse driver works (if compiled).


If you get the error "cannot find libao driver" - probably you have
broken alsa driver in libao (existing in some Debian distributions).
Problem is known - see:
http://stackoverflow.com/questions/8963915/libao-example-doesnt-work-when-compiled-as-python-module
Test your libao driver with command:

ldd -r /usr/lib/ao/plugins-4/libalsa.so > /dev/null

If you get error like "undefined symbol: ao_is_big_endian" - you must compile
libao from source applying this patch:
http://tts.polip.com/files/sapi/ao_alsa.c.diff
(thanks, Andrei, for working solution!)


If you still can't hear any sound, probably pyspda can't work on your system
and rest of installation process has no sense. Please search help on
list, or contact me directly via email.

Now you must run command: 'make install' as root, for example:
sudo make install

One of problematic part is installed.

III. Install Sapi4Linux client software

Ubuntu users should install libsapilektor-utils from ppa
and skip this part.

Download libsapilektor from:

http://tts.polip.com/files/sapi/libsapilektor_0.1.10.orig.tar.gz
(or newer if exists)

Unpack it and type commands:

make
sudo make install

It will install sapilektor in /usr/local hierarchy. If you prefer
installing directly in /usr, type instead:

make prefix=/usr
sudo make prefix=/usr install

At now we cannot test installed software - we have no server yet.

IV. Install Sapi4Linux server files

Ubuntu users should install sapi4linux from my ppa.
Server will be unpacked into /usr/lib/sapi4linux folder
all needed third-party software will be downloaded during
instalation. Additionally, install_sapi_server command
will be available as softlink to /usr/lib/sapi4linux/install_server.sh
If you install files from ppa, skip rest of this chapter.

Prepare system for server. You will need:

1. wine in version minimum 1.4 (1.7.18 to run Ivona voices)
2. xvfb (virtual X driver) - required to run wine in separated graphic
3. x11-utils (commands xprop and xdpyinfo) and
4. xautomation (command xte) - required to automatize installation script
5. icewm (window manager) - required by automatic installer to put focus
   on lastly open window
6. netcat (command nc) - required to control server
7. python - required to run sapilektor configuration program
8. findutils, unzip, p7zip and wget required to prepare all files

Download installer from:
http://tts.polip.com/files/sapi/sapi4linux-netinstall-0.1.7.tar.gz
(or newer if exists) and unpack it somewhere. It's important
to unpack it to some place where it will be accessible all the time
(running server will need files from this folder). If you want,
you can do it as root and put this folder somewhere in /usr/local
hierarchy to avoid accidental damages.

Now enter into this folder with cd command.
If you installed this folder as root, you must now enter command:

bash srvcreator.sh


Also, you can run srvcreator.sh to download all required software
even if not in root mode.

V. Running server first time

Enter into directory sapi4linux (as above) and run:

./install_server.sh

Ubuntu users may use simply install_sapi_server command without
entering /usr/lib/sapi4linux directory.

This command will install and run SAPI server in some specific environment:

1) It will run xvfb on display :20 to avoid conflicts with your graphic
environment and to make possible running server even without graphic
2) It will create special Wine prefix .winesapi and install mssapi and voices
in ~/.winesapi folder

After a while installer should run the server. Please type command:

sapiconfig -n

If everything is OK, it will display configuration with tree Microsoft voices
(Mike, Mary and Sam). Now you can save your configuration with command:

sapiconfig -n -s

and test your working server with for example:

sapitest hello world

Use 'sapitest -h' and 'sapilektor -h' to get all command line options.

In your ~/bin directory (will be created if not exists) you will get command
sapi_server.sh, which you can use to run or restart server.

VI. Installing other SAPI voices.

Please read README file in sapi4linux directory. Server was tested with Ivona
voices and I made short test with some Acapela voice. Acapela demo works only
one hour without restart. Latest sapi4linux provides automatical installer
for Acapela (infovox3) voices.

Orpheus voices are supported by latest sapi4linux and sapilektor - but installer
is still inaccessible, and due to very poor quality of these voices I'm not
interested with spending even 5 minutes on accessible installer for Orpheus.

Nuance Vocalizer is not supported yet.

VII. Installing python binding for sapilektor

Again, Ubuntu users may simply install python-sapilektor from ppa
and skip the rest of this part (I promise - last time).

Download python module from:
http://tts.polip.com/files/sapi/python-sapilektor_0.1.0.orig.tar.gz
(or newer if exists)

Unpack the archive, enter into unarchived folder and type commands:

./configure
make
sudo make install

You can check installation running:
make speech_test

VIII. Installing sd_sapi module for speech-dispatcher

As this module is under development now, it's required to install it
manually!

Download and unpack:
http://tts.polip.com/files/sapi/speechd-sapi-0.1.4.tar.gz
(or newer if exists)

Enter into speechd-sapi directory. Create symbolic link

Ubuntu:
sudo ln -sf `pwd`/sd_sapi /usr/lib/i386-linux-gnu/speech-dispatcher-modules/sd_sapi
(or similar for amd64 architecture)

Rest of world:
su -c 'ln -sf `pwd`/sd_sapi /usr/lib/speech-dispatcher-modules/sd_sapi'
(or something similar depending on distribution)

If user running speech-dispatcher is not the same as you, ensure
your homedir is readable to this user:

chmod 755 ~

Copy (as root) configuration file to speech-dispatcher directory. For Ubuntu:

cp sapi.conf /etc/speech-dispatcher/modules/

You will never need to edit this file - running module copies it into
~/.sd_sapi and reads it's content every time it's changed.

Edit your speech-dispatcher configuration (as root):

Locate first line beginning with 'AddModule' and insert after this line:

AddModule "sapi" "sd_sapi" "sapi.conf"

Now restart speech-dispatcher. You can test the module with:

spd-say -o sapi 'this is test'

If you use Orca, enter:

spd-say -w -o sapi 'this is test'; sleep 1

Now you can restart Orca. In speech configuration you will have 'sapi'
synthesiser and voices from your sapilektor configuration.

Use with care - module is very fresh and may crash! Probably you should
have second Orca profile for tests only!

IX. Remarks:

SAPI synthesizers are slow, so don't expect very fast Orca reaction.

At now the module can speak in German, English and Polish languages.
Very initial Swedish language support is added in 0.1.3 version.
Also initial version of Russian (as base for Cyrillic script languages)
is added in 0.1.4 version.

For other latin alphabet based languages it's necessary to create
very simple Python class (see germanizer.py as example) and edit
sd_sapi file to properly recognize language module. For example:

- Italian will be spoken probably properly, but characters and
  key names will be spoken as english words
  
- for Spanish you could simply make copy of Germanizer class,
  give some nice name to class and in line containing:
  untrans="
  change existing string (probably) to:
  "áÁéÉíÍóÓúÚýÝñÑ".
  It will allow Spanish stress to be properly spoken.
  You must also edit sd_sapi file and add proper switch
  before last 'else' in function get_phraser
  

For cyrillic based languages it's necessary to create class based on
Cyrillizer and use it as base for particular language modules.

Feel free to contact me off list - my email address you will find
in README files and each source file!

X. Known issues:

Ivona voices when demo mode expires displays some ugly window with also
ugly informations like 'voice expired'. While we run server in virtual X
screen we cannot click 'ok' on this window. In effect we have deadlock:
client waits for server reply while serwer waits for Ivona window.

Infovox3 demo voices in theory should run one hour after wine reboots.
In fact sometimes even system reboot does not cause these voices to run next hour,
we still hear nice sentence like 'thanks for testing our voice'.
In effect after one hour of tests sapi server must be stopped and reinstalled.

Latest sapi_server.sh file probably reboots wine correctly (and Infovox3 voices
should run next hour without restart) - but sometimes you should reinstall server.

It's not possible to run Ivona demo together with Infovox3 demo longer than 1 hour
without reinstalling.