BackTalk 1.2 - System Speech for OS/2    (c) 1996 Jim Little
                                         (c) 1996 Samuel Audet

Revised and modified BackTalk project by Samuel Audet <guardia@cam.org>  

Original copy, idea and copyrights goes to Jim Little <jiml@teleport.com> 
and his Power User section available at OS/2 E-Zine!.

Installation
~~~~~~~~~~~~
Ok, here's the big picture.  Rsynth 2.2 crashes in Warp 4, and you may have
some chipmunk voice problem with Rsynth 2.1, and also Rsynth 2.2 processes
faster with its multithreading.  Most of time, one of them is going to work
correctly.  If you can't get either working, let me know, I got some kludge
in my tool case.

A couple of queries will ask about MR/2 ICE and which Rsynth version you
want to install.

Be sure to have EMX runtime librairies installed.  You can get those on
ftp://hobbes.nmsu.edu/os2/unix/emx09c/emxrt.zip

After installation, you can delete all the *.h, *.c, *.def and 'makefile'
if you desire.  Those are source codes.

A folder will be created, where you can find all the objects needed to
control the scripts that came with this packages as well as the main Speech
Queue.

I. Speech Queue .CMD file
~~~~~~~~~~~~~~~~~~~~~~~~~
The speech queue (SPEECHQ.CMD) is the only program that actually uses SAY.EXE
to generate speech.  The other programs simply place their messages in a queue
for SPEECHQ to handle.  Therefore, SPEECHQ.CMD must be running before any of
the other speech programs will work. 

SPEECHQ.CMD must be located in the same directory as SAY.EXE.  If you
used INSTALL.CMD, the file is already there.  Normally, SPEECHQ will 
say, "Speech Enabled" when it is started. If you hear "Unable to delete
blahblah", naughty naughty... next time try to end it with "Stop Speech",
instead of Closing the window.  Now reboot. :)

You might try to use 16 bit sound ouput, but Rsynth doesn't handle it
always well.  To do so, edit SPEECHQ.CMD and add '-b 16' to 'synth' like
this:

synth='SAY -b 16 '

II. CMU Pronunciation Dictionary
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
RSynth sounds much better if you install the optional dictionary.  This
dictionary can be found online on Derek Decker's web site.  The URL is
http://www.cris.com/~djd/products.html.  To install the dictionary, do the
following:

1. Stop the speech queue if it is active.
2. Copy the plain-text dictionary file into the RSynth directory.
3. Make sure you have plenty of hard drive space.  (15MB should be enough.)
3. Type "mkdictdb cmudict.04 adict.db" at a command prompt in the RSynth
   directory.  Use the appropriate filename in place of cmudict.04 if it
   changed.
4. Ignore errors.  (They represent multiple pronounciations or punctuations
                    not support by this freeware text to speech program)
5. Wait.
   ...a long time.
   ...a very, very, very long time.
   (We're talking at least an hour here.  Fortunately, you can multitask!)
6. When it's done, restart the speech queue and marvel at the frog prince's
   transformation.  You can delete the cmudict.04 file.

III. SPKMAIL.CMD
~~~~~~~~~~~~~~~~
The most useful program included with this project is SPKMAIL.CMD.  When
this program is installed with your e-mail program, you will be notified by
voice whenever new mail arrives.  This is particularly useful if you leave
your mailer running but minimized while you are connected to the Internet.
SPKMAIL reads the author and the subject of any new message, preventing the
need to bring up your mailer every time new mail arrives.

SPKMAIL requires an e-mail program that supports REXX exits.  I've used it
successfully with PMMail 1.51 to 1.53 and MR/2 ICE 1.10.

PMMail:
~~~~~~~
1. Open PMMail.
2. Select "Utilities Settings..." from the "Account" menu.
3. Click the "REXX Exits" tab.
4. Check the "Message Receive Exit" checkbox.
5. Enter the full pathname to and including SPKMAIL.CMD, if not located in
   PMMAIL.EXE's directory, in the corresponding entry field.
6. Press OK.

MR/2 ICE:
~~~~~~~~~
1. Copy flip.exe (located in \flip) where MR2I.EXE resides.
2. Edit SPKMAIL.CMD and change 'flip = 1'.
2. Open MR/2 ICE.
3. Select "Filter maintenance..." from the "Utilities" menu.
4. Press the "New" button.
5. Enter a description, such as "New message."
6. Enter a tag (in the lone right text entry), such as "New."
8. Check the "Link to REXX" checkbox.
9. Enter the full pathname to and including SPKMAIL.CMD, if not located in
   MR2I.EXE's directory, in the corresponding entry field.
10. Press OK.
11. Press Done.

IV. How can I implant speech in my REXX scripts?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At the beginning of your REXX script, after the initial /* */, insert the
following command:

queuename='REXXSPEECH'
rc = rxqueue('Set', queuename)

Thereafter, instead of using 'say' use 'queue' to speech things:

queue 'hello!'

V. Speech Clock and Speech Timer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
SPCHTIME.CMD will speak the time at a lap specified using the "mins" or
"secs" variable found in the file.  You can also specify civil time (AM PM
thing) or the international time (24 hours).  Look in SPCHTIME.CMD for more
information.

SPCHTMR.CMD is a timer, which has the ability to speak a message and to
specify the laps of time between them.  It also has an urgent mode, that
gets activated if the urgent mode toggle time is greater than 0.  The
urgent mode has its own message and laps time too.  And finally, the alert
message, which gets spoken when the timer has finished counting.

You can specify default values directly in SPCHTMR.CMD.  Please, refer to
it for more information.  Or you can use the command line to override the
defaults.

-t1  countdown time (minutes)
-l1  laps time (seconds)
-m1  message

-t2  time remaining to switch in urgent mode (minutes)
-l2  laps time in urgent mode (seconds)
-m2  message in urgent mode

-m3  alert message when timer has stopped

-?   Help screen

ie.: c:\> spchtmr -t1 45 -t2 15 -m1 for your dentist rendezvous -m2 for
     your VERY VERY important dentist rendezvous -l1 300 -l2 120 -m3 Your
     dentist rendezvous!!

Yes, that does fit on the command line.  Therefor, you can execute it from
agendas that support execution of programs.  Be aware that REXX scripts
aren't the program themselves, it's CMD.EXE that is the program. So to
execute a REXX script when the agenda or calendar (whatever) DOES NOT
specify that it can run REXX, you have to execute the following:

X:\OS2\CMD.EXE /C SPCHTMR.CMD -t1 ...


Both scripts can be safely terminated by closing the window in which they
are executing.

VI. Feedback
~~~~~~~~~~~~
I'm very interested in any other practical (or not so practical)
applications of speech you can think of.  Send any ideas, REXX programs, or
wacky flights of fancy to me via email at Samuel Audet <guardia@cam.org>.

VII. Acknowledgements
~~~~~~~~~~~~~~~~~~~~~
Thanks for Jim Little for making this up, so I could optimize it. :)

Many thanks go to Nick Ing-Simmons (nik@tiuk.ti.com) for writing RSynth and
to Derek J. Decker (djd@cris.com) for porting it to OS/2 (version 2.2
rules, but crashed in Warp 4, fix it please!).

Thanks also to Cheng-Yang Tan (cytan@tristan.tn.cornell.edu) for writing
UPTIME.EXE.

Thanks to the unknown artistic genious that created the icons I stole.  If
you recognize any of these icons as your own, let me know so I can give you
credit.
