This manual documents SpeechD-Up, version 0.5.

Copyright © 2005, 2006 Brailcom, o.p.s.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License.''

You can also (at your option) distribute this manual under the GNU General Public License:

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of the license is included in the section entitled ``GNU General Public License''

spechd-up is a very simple simple interface from Speakup to Speech Dispatcher making it possible to use Speakup with software synthesis. Speakup is a kernel-based screen reader allowing blind and visually impaired people to use the computer.

Installation
************

(This is not a description on how-to install SpeechD-Up itself, this is a description of all the necessary steps to make SpeakUp work with software synthesis using Speechd-Up. For how to install SpeechD-Up itself, please see the file INSTALL in the distribution tarball.)

SpeakUp can't use software synthesis directly because SpeakUp lives in the so called ``kernel space'' and software synthesizers live in the so called ``user space''. These are two different parts of your system and the communication between them is quite difficult. The approach to make SpeakUp work with software synthesis is the following one: Speakup provides a device, usually called /dev/softhsynth, where it sends all the commands to the synthesizers. Then there is a very simple application (or rather a daemon) called Speechd-Up listening on this device and passing all the requests for synthesis to Speech Dispatcher, which then in turn talks to your chosen synthesizer (be it Festival, Flite or something else).

If you want to use SpeakUp with software synthesis, you need to setup all this chain. It might not be easy, but you might later use Speech Dispatcher also for other accessibility applications. Or otherwise: chances are that you already have a great part of this up and running. Let's suppose you are starting from the scratch (if you have something already running, just make sure this is true and skip the step).

 1. Install your favorite speech synthesizer

     To be able to use software synthesis, you first need to install some software synthesizer. We strongly recommend a Free Software package ``Festival'' for it's many capabilities, support of multiple languages, quite good quality of some voices and quick responses. However, you might chose any of the synthesizers supported by Speech Dispatcher (please see http://www.freebsoft.org/doc/speechd/speech-dispatcher_10.html#SEC10)

     Read the installation instructions for your chosen synthesizer and install it. There are Debian packages for both Festival and Flite.

 2. Make sure the synthesizer works

     There is usually some simple way how to check if the synthesizer works. For festival, run festival and type in:

     (SayText "Hello world")

     Don't continue unless you know the synthesizer works.

 3. Install Speech Dispatcher

     You can get more information about Speech Dispatcher from http://www.freebsoft.org/speechd. You can either use a pre-compiled package (see your distribution repositories) or download the tarball from the above internet address and follow the instructions in the file INSTALL.

     If you are running Debian, you can install the following packages: speech-dispatcher, libspeechd1 and libspeechd1-dev. The latest one is important too since you will have to compile SpeechD-Up yourself.

 4. Make sure Speech Dispatcher works correctly

     You can test whether Speech Dispatcher works with a simple client called spd-say distributed along with Speech Dispatcher. (You might later find this package useful for many practical purposes.) It has many parameters, so you can even test if the rate and pitch settings work correctly etc.

          spd-say "Hello world!"
          spd-say -r 90 -p -70 "This is quick and deep"

     If this doesn't work, please examine Speech Dispatcher documentation for possible problems (info speech-dispatcher). You might want to see the logfiles of Speech Dispatcher itself and of its output module you are using.

 5. Install Speechd-Up

     You can download Speechd-Up source code from http://www.freebsoft.org/speechd-up. Unpack it with tar -xvzf speechd-up-0.1.tar.gz and follow the instructions in the file INSTALL in the source tree.

 6. Make sure SpeechD-Up can communicate with Speech Dispatcher

     You can test if SpeechD-Up can communicate with Speech Dispatcher by executing (as root)

          speechd-up --run-single --probe

     If you hear something, everything in SpeechD-Up works except connecting to the SpeakUp's device (which was not attempted in this test).

 7. Install SpeakUp

     You have probably done that already, but you must make sure you compiled SpeakUp with support of software synthesis. You must have SpeakUp compiled with the softsynth module and you must create the appropriate device with

          cd /dev
          mknod softsynth c 10 26

     Please see http://www.linux-speakup.org/ for how to obtain and install SpeakUp. You might also want to look at the Speakup's User Guide here: http://www.linux-speakup.org/spkguide.txt

     After having installed Speakup, if softsynth is your default synthesis device, you must switch to it:

          echo sftsyn >/proc/speakup/synth_name

     This should load the appropriate kernel module (if compiled as a module) automatically.

     If you run into problems here, please examine modprobe -l) for the speakup_sftsyn module and/or try to load it manually with modprobe. If this doesn't work, there is some problem with your instalation of Speakup.

 8. Make sure SpeechD-Up works

     Now you are at the point when you can invoke SpeechD-Up as an application in the foreground and see if everything works ok.

          speechd-up -s

     The application should keep running and you should hear something.  When you switch to another console, you should be able to use SpeakUp normally with your software synthesis.

     If this doesn't work, please look at SpeechD-Ups logfile in /var/log/speechd-up.log. You can also increase the loging level of SpeechD-Up as shown bellow

          speechd-up -s -l 5

     and examine the logs again.

 9. Make Speech Dispatcher and SpeechD-Up start automatically

     This part is distribution specific. It can be left out provided you will manually 1) start your synthesizer 2) start Speech-Dispatcher 3) switch Speakup to the sftsyn device 4) start SpeechD-Up each time you want to use software synthesis with Speakup (in this order).

     Under Debian, Speech Dispatcher already starts automatically from /etc/init.d/speech-dispatcher and it should not be difficult to create /etc/init.d/speechd-up by modifying the script for Speech Dispatcher and then adding a link to it to /etc/rc2.d/S21speechd-up. You must only make sure it starts *after* Speech Dispatcher.

     If this doesn't work, please test again if all the components work well as described above.

 10. It's somehow slow etc...

     You might find the new software synthesis is rather slow with SpeakUp compared to the hardware synthesizers, and they have some other deficiencies. On today's hardware, this is not a fault of Speech Dispatcher or software synthesis in general. Speakup was not formerly designed with software synthesis in mind and neither now this is its main focus. Please don't think software synthesis is generally inferior to hardware synthesis because of this. We actually believe quite the opposite is true: The hardware synthesizer, unless they are programable, will never achieve the huge possibilities of extensible software synthesizers. See Problems

Invoking
********

Usage: speechd-up [options]

-d or --run-deamon
     Run as a deamon in the background.

-s or --run-single
     Run as an application on the foreground.

-l or --log-level
     Sets the logging level. Accepted values are numbers 1 to 5. Five means the most verbose logging.

-L or --log-file
     Specifies the path to the file where logs are stored.

-D or --device
     Selects the device where Speakup sends it's output.

-c or --coding
     Indicates which character coding your console uses. For possible values, please see `iconv --list'. This option is important if your console is not in iso-8859-1! (It doesn't work with ``utf-8'' and other multibyte encoding because of kernel related issues with this encoding. You must run your console in a unibyte encoding like for example one of the ``iso-8859-*'' set, sorry.)

-i or --language
     Specifies the language to use. You must provide a 2 character ISO 839 language code (such as ``en'', ``de'', ``fr'', ``cs''). This language will be set via Speech Dispatcher and if you have a synthesizer configured for it, Speakup should talk this language. It is currently not possible to switch languages on-fly because of limitations of Speakup.

-t or --dont-init-tables
     SpeechD-Up tries to init some Speakups /proc tables on its start. Most important, it changes /proc/characters and /proc/chartab so that punctuation, capital letters recognition and various other language dependent things are handled inside Speech Dispatcher and in the synthesizer. This is crucial for internationalization. You can however disable this if you want to modify the tables manually for some reason and don't like speechd-up overwriting them. (Do not expect Speakup to work for other languages than English in that case, unless you know what you are doing and can do the necessary changes manually.)

-p or --probe
     Runs SpeechD-Up in the probe mode. This means that SpeechD-Up will do everything as as ordinary, but won't try to open the SpeakUp device. It just speaks a message and terminates (indicating so in the logfiles). This is meant for testing.

-v or --version
     Print version and copyright info.

-h or --help
     Print a short help.

Examples:

If the device where Speakup talks to userspace is /dev/sftsyn2 and your console is in iso-8859-2, then you can use:

     speechd-up --device="/dev/sftsyn2/" --coding "iso-8859-2"

Please use this for debugging or sending bug-reports

     speechd-up -s -l 5 -L "/tmp/speechd-up.log"

Configuration
*************

There is a configuration file available in /etc/speechd-up.conf or /usr/local/etc/speechd-up.conf or similar location based on your instalation.

You can influence such options as the path to the Speakup softsynth device, default language and character encoding set, also some charactersitics of Speechd-Up behaviour. Please read comments provided inside the configuration file to learn what options are available and what are their possible values.

Problems
********

There are many known problems with Speakup/SpeechD-Up. You might want to consider using some user-space assistive technologies if you want to use software synthesis on the console. Such technologies are speechd-el, Emacspeak, SuSE Blinux and Yasr. We however believe the Speakup/SpeechD-Up combination is useful even though it has the described deficiencies.

  * (Fixed: Speaking characters and keys is slow)

     The original issue was fixed (but see bellow). If you are still not happy with the performance while reading characters and typing in, then you are using a synthesizer which is both slow and lacking support for caching (use Festival, it does caching with Speech Dispatcher and keys reading is instant).

  * Characters behave like KEYS for synthesizer configuration

     The way Speakup passes individual characters makes it impossible to tell whether this character originated as a key or while the user was moving the cursor on the screen and the already present letters are being read. We believe it is important to carry the proper information when pressing keys (like capitalization), so SpeechD-Up handles these messages as keys.

     Also space, tab and various other whitespace characters are not reported as a characters/keys as this is impossible to achieve with current Speakups implementation. It is impossible if the word ``space'' in input originated by the user pressing the SPACE key or by encountering this word inside a document being read on the screen.

  * (Fixed: It doesn't speak my language / it uses some weird character set)

     If you still experience this issue, you are probably doing one of this

       * Using a wide character encoding like UTF-8. This is not supported for inherent issues with wide characters inside the kernel.

       * Not running speechd-up with the -c parameter and specifying the proper character set your console uses or not setting the SpeakupCoding option in the configuration file. Alternatively, you may not be specifying the language to use. You can choose a language either in Speech Dispatcher configuration or via --language or in the speechd-up.conf configuration file.

       * Running speechd-up with the -t or --dont-init-tables. This option is incompatible with internationalization.

     If this is not true, please contact us on speechd@bugs.freebsoft.org.

  * The spelling/punctuation modes of my favorite synthesizer don't work.

     Speakup uses it's own very simple spelling and punctuation substitution and doesn't allow the TTS to use it's own user-specified rules.

  * It doesn't work in UTF-8

     UTF-8 should work as long as you only use characters encountered in the basic ASCII. So English should work. But Speakup doesn't really support UTF-8 in any way (nor it can, there is no UTF-8 support inside the kernel -- just workarounds targeted at visual interpretation; the kernel virtual terminal drivers contain many barriers for accessibility).

  * Punctuation and capital letters recognition doesn't properly work

     This is an issue again related to Speakups design. It is currently being worked on.

  * I can't switch languages or synthesizers on fly

     The way the interface Speakup -- Speech Dispatcher is designed, this is not possible.  You can switch them statically in Speech Dispatcher's configuration though. If you use SpeakUp's identification "*:speechd-up:*" you can even choose a synthesizer specifically for Speakup.

  * Any other more advanced thing doesn't work or something is too slow or ... There are many problems for software speech with how this interface is done and with how Speakup is designed. It's probably still better to use Speakup with a hardware synthesizer, if you have the possibility. Speakup was not designed with user space software synthesis in mind and the necessary changes would probably be too difficult now. There were many important design decisions made which are very reasonable for hardware synthesizers, but they just don't mix well with software synthesis.

     On the other hand, experience shows people still find this interface to software speech synthesis useful, mostly because of lack of anything else. Also, it seems the future of accessibility technologies lies in the software synthesis (extensible, etc.) as machines get faster. That's the reason why we provide this application and we will try to help you if you have problems or questions.

Contacts and Reporting Bugs
***************************

If you are seeking for support or you want to make some suggestion, please contact us at users@lists.freebsoft.org.

If you believe you found a bug in SpeechD-Up, we will be very grateful if you let us know about it. Please do it by email on the address speechd@bugs.freebsoft.org, but please don't send us messages larger than half a megabyte unless we ask you.

How You Can Help
****************

If you want to contribute to the development of Speech Dispatcher, we will be very happy if you do so. Please contact us on speechd@lists.freebsoft.org.

There is a short, definitively not exhaustive, list of how you can help us and other users.

  * Donate money: We are a non-profit organization and we can't work without funding. Brailcom, o.p.s. created Speech Dispatcher and speechd-up and also works on other projects to help blind and visually impaired users of computers (like speechd-el). We build on Free Software and GNU/Linux, because we believe this is the right way. But it won't be possible when we have no money. Currently, funding is the main limiting factor for us in developing more and better accessibility solutions. http://www.freebsoft.org/

  * Report bugs: Every user, even if he can't give us money and he is not a programmer, can help us very much by just using our software and telling us about the bugs and inconveniences he encounters. A good user community that reports bugs is a crucial part of development of a good Free Software package.  We can't test our software under all circumstances and on all platforms, so each constructive bug report is highly appreciated. You can report bugs in SpeechD-Up on speechd@bugs.freebsoft.org.

  * Help us with project: Please look at http://www.freebsoft.org/ to find information about our projects. There is a plenty of work still to be done for the blind and visually impaired people to make their work with computers easier.

  * Spread a word about Speech Dispatcher and Free Software: You can help us, and the whole community around Free Software, just by telling your friends about the amazing world of Free Software. It doesn't have to be just about Speech Dispatcher, you can tell them about other project or about Free Software in general. Remember that Speech Dispatcher could only arise out of understanding of some people of the principles and ideas behind Free Software. And this is mostly the same for the rest of the Free Software world. See http://www.gnu.org/ for more information about GNU/Linux and Free Software.

GNU General Public License
**************************

Version 2, June 1991

     [file gpl.texi not included]

GNU Free Documentation License
******************************

Version 1.2, November 2002

     [file fdl.texi not included]