#$Id$

Here is some brief documentation on  using  ViaVoice TTS under
ALSA.

* Why Do I Need ALSA?

The original Emacspeak speech server for ViaVoice used OSS for
communicating with the sound device. This server will work under
OSS emulation with ALSA. However this also means you dont get the
benefits of ALSA, e.g., the ability for multiple programs to use
the sound device at the same time.  The new ViaVoice ALSA server
is a well-behaved ALSA application that allows other ALSA
applications full access to the sound device while ViaVoice is
speaking.  As an example, The ViaVoice server using ALSA calls
allows you to listen to MP3 files while not losing TTS.

*What Do I Need?

You need the following to be able to use the ALSA server:

0)  A relatively modern Linux installation; I've tested this
    under FC2 and FC3 running a 2.6.X kernel.

1)  A sound card supported by ALSA.

2)  ALSA configured to leverage ALSA's mixer plugin (see next
    section).

3)  ViaVoice TTS libraries for producing speech output.

* Building ALSA Support For ViaVoice

The ViaVoice ALSA support is not pre-built by default; this is to
allow the default to be the original OSS server. The ALSA server
will become the default in about a year's time (or when most
users are running ALSA-based systems) which ever is earlier.

Here are the steps to build the ALSA support.
If *any* of these fail, then you are not prepared to run the ALSA
server on your machine.

0)  Set up ALSA to use the mixer plugin.
    ALSA reads a configuration file in your home directory called .asounrdc.
    You can copy the sample asoundrc
    file from the servers/linux-outloud directory to you home
    directory as .asoundrc to make the ALSA mixer plugin be the
    default.
    
    This will allow applications that use ALSA to open the sound
    device at the  same time.

1)  Test that the configuration worked by running aplay to play a
    file.
    If it works,  make sure you can play multiple sounds at the
    same time using aplay.

2)    Change to the Emacspeak servers/linux-outloud directory.
3)    make atcleci.so
      The above will compile the ALSA ViaVoice server.
4)    If it built successfully, start the TTS server by running
      ../outloud
      If it worked, you will here the server announce itself as
      "ViaVoice Using ALSA".


5)    If you hear the above message and  the server is ssstill
      running, execute TCL command 
      tts_selftest
      to test the server.
6)    If all goes well, Emacspeak can now use the ALSA ViaVoice
      server.

* What If It Breaks?

You get to keep both pieces. Remove the atcleci.so file that was
built in the previous section, and the Emacspeak ViaVoice server
will revert to using OSS.

* Auditory Icons

Once you start running the ALSA server, you set Emacspeak to use
aplay --- and not the old OSS play --- to play auditory icons.
You can do this by configuring Emacs custom variable emacspeak-play-program.


* Playing MP3 Streams

You can play MP3 streams while running the ALSA ViaVoice server,
but without losing speech as you would under OSS. You need to
make sure that the MP3 player you use is also using ALSA.

Here are some tips:

0)    If using mpg321 from the shell, make sure you're passing
      the "-o alsa" option.

1)    Use command madplay to decode the mp3 stream and pipe it to
      aplay.You can  most easily do this using the 
      etc/amadplay
      script that is part of Emacspeak.

2)    RealAudio streams. Unfortunately trplayer is built as an
      OSS application. If you launch trplayer to play realaudio
      streams, you will lose TTS output until that program
      terminates.

      Note: ALSA OSS emulation (program aoss) is a possible
      solution to this problem, but unfortunately the output of
      trplayer becomes extremely choppy when run in this
      mode. It's time someone wrote a new trplayer for
      RealPlayer 10 anyway.


Local variables:
 mode: outline
 paragraph-separate: "[ ]*$"
end:
