-- -- -- -- -- -- -- -- -- -- -- -- -- -
| |
## | |
## | Micro/Voice |
## | Voice Synthesis Function Library |
## | Clipper Summer '87 Edition |
## | Ver. 1.00 |
## | |
## | Written by Steve Badaracco |
## | |
## | DataBlaze Solutions |
## | 48 Park Street |
## | Willimantic, CT 06226-3638 |
## | |
## -- -- -- -- -- -- -- -- -- -- -- -- -- -
###########################################


To print this manual, type the following to DOS:
COPY MVCLIP87.DOC PRN (and press Return)


INTRODUCTION AND PRODUCT INFORMATION

Micro/Voice was written by Steve Badaracco for use on the
IBM PC family of computers (PC, PS/2, and 100% compatibles),
using Clipper Summer '87 under MS-DOS 3.x or later. It has
been made available for personal, private use. You may freely
distribute this software with the following restrictions:

a) The program shall be distributed ONLY in the ORIGINAL
unmodified form, including this documentation.

b) NO FEE may be charged.

c) FOR-PROFIT use without a License is PROHIBITED.

d) The program may NOT be INCLUDED or BUNDLED or
otherwise sold with other goods or services.
Exceptions may be granted ONLY upon written request.

e) Commercial users MUST register. Site License is
available, call.

This is USER SUPPORTED SOFTWARE. If you use it, and find
it of value, please register your copy by sending $19.95
PER USER COPY ($34.95 Commercial) along with the filled out
registration form, to the author at the above address.
In other words, each user (programmer) must register his or
her own copy. Again, site licenses are available on request.
Make checks payable to Steve Badaracco.

Your registration form (and fee) entitles you to a free
upgrade of registration status to the Clipper 5.0 edition
of Micro/Voice as soon as this becomes available, as well
as technical support for both editions.

For an additional $11.95 PER USER COPY ($16.95 Commercial)
with your registration form (and fee), you can purchase the
Micro/Voice Comprehensive Dictionary, a disk-based repository
of non-phonetic English words which provide Micro/Voice with
a "smarter" vocabulary. Along with the dictionary, you will
receive the MVCustom utility which enables you to create or
modify a "custom" dictionary with additional entries available
to Micro/Voice IN PARALLEL with the Comprehensive Dictionary.

All dictionaries for the Clipper editions are arranged in
familiar DBF format, and require no indices. Micro/Voice
accesses entries virtually instantly using a binary search.

Again, Micro/Voice is a hardware-specific programming tool,
designed to work on IBM PC and PS/2 hardware, and 100%
compatibles. Micro/Voice has NOT been tested under all possible
runtime conditions, and comes with no warranty, expressed or
implied, as to usability, "safety", or fitness for a particular
use. In no event will DataBlaze Solutions, or the author, be
liable for any direct, indirect, or consequential damages, real
or imagined, resulting from the use of the Micro/Voice code or
its associated utilities.

Micro/Voice for Clipper Summer '87 Manual Page 1


DISTRIBUTION FILES

The following files are distributed as version 1.00:

MVCLIP87.LIB 40581 6-10-90 1:00a Function Code Library

MVCLIP87.DOC 26171 6-10-90 1:00a This manual

MVDEMO.PRG 6280 6-10-90 1:00a Main demo

MVREADER.PRG 4331 6-10-90 1:00a Text reader demo

MVDEMO.OBJ 3581 6-10-90 1:00a Main demo, compiled

MVREADER.OBJ 1493 6-10-90 1:00a Text reader demo, compiled

MVREADER.TXT 229 6-10-90 1:00a Sample file for text reader

SYSTEM01.DCT 428 6-10-90 1:00a Sample "main dictionary"

MYCUSTOM.DCT 362 6-10-90 1:00a Sample "custom dictionary"



TRADEMARKS

Micro/Voice - DataBlaze Solutions

Clipper - Nantucket Corporation

Turbo Link - Borland International

PLINK86plus - Phoenix Technologies Ltd.

BLINKER Dynamic Overlay
Linker - Blink, Inc.

IBM, PC, PS/2,
and PC-DOS - International Business Machines Corporation

Microsoft Overlay Linker,
and MS-DOS - Microsoft Corporation
















Micro/Voice for Clipper Summer '87 Manual Page 2


ABOUT MICRO/VOICE

Micro/Voice is not a talking program, per se. It is not
an April Fools' Day joke to install on a friend's computer.
This is a serious programming tool for use by developers.
Future editions of Micro/Voice are planned, to support C and
Pascal. This edition is for programmers using The Clipper
Compiler (Summer '87 version, in this case), marketed by
Nantucket Corporation.

Micro/Voice is a set, or LIBRARY, of functions written in
assembly language, C, and, yes ... Clipper. Some are
directly callable from your program, and others are
"internal", i.e. called by other functions in the library.
The latter you needn't worry about, and the former are
fully documented on the pages that follow.

Although the IBM PC family of computers is equipped with
about the most rudimentary type of speaker, never intended
for true generation of speech or music, system programmers
have accepted the implied challenge to make the thing talk.
The best solution to date is to feed specially formatted
binary data out the hardware port to the speaker device.

Experts on the subject of English pronunciation have pretty
much come to an agreement that all of the sounds in our
language boil down to combinations of 35 "phonemes", or
basic verbal noises. The binary data required to produce
any one of these phonemes is about 570 bytes, or a little
over 1/2-K. The natural tendency would be to store this
20K overhead on disk, but the headaches of dealing with the
external file at runtime must be taken into account. More
importantly, the flow of "speech" would be bottlenecked by
the particular disk speed of the hardware involved, including
a sharing bottleneck if the application in question is running
on a local area network.

An alternate approach is to load the overhead into RAM with
the program which will be using it, making the access to the
critical "speaker food" independent of disk and network access
constraints. This is the solution as implemented by
Micro/Voice, which is why adding speech to a Clipper program
bears a cost of 20K data loaded in RAM (as part of the EXE,
not pool memory), as well as the required code to provide
the functionality to the speaker. This code size will vary
depending on what routines you link into your program from
the Micro/Voice function code library. If you use ALL the
functions in the library, which is very unlikely, the code
PLUS the data will amount to about 40,000 bytes in your final
EXE size. If your program is very large, consider one of the
new dynamic overlay linkers on the the market; Clipper 5.0
will not have the first, and perhaps not even the fastest,
best, or easiest to use dynamic overlay linker in its package,
so shop around.




Micro/Voice for Clipper Summer '87 Manual Page 3


PROGRAMMING MICRO/VOICE

One hardware constraint to be reckoned with is the processing
speed of the workstation running your application, which will
bear directly on the speed and pitch of speech. So before
you "say a word", Micro/Voice must be initiated with some
information on speed and resolution factors, as well as desired
space between words. In fact these may vary widely with the
end user's own taste (and hearing), and are good candidates for
placement in some user profile. Functions are also provided in
the library to alter these settings after initiation (you could
SET a hot KEY for the user to drive this).

Program sequence will look something like this:
1) Initiate
2) Fine-tune settings if necessary, or at will
3) Translate English words and/or phoneme strings into
packed format (the "script") for the speech module
4) Call the speech module with the packaged "script"


INITIATION

If initiation has not been performed, none of the other
functions will work; not a whisper will come from the speaker.
Initiation is straightforward; call the v_init() function with
information on speaker settings and, optionally, dictionary
files to search during translation.


FINE-TUNING

After initiation, the fine-tuning functions allow the user to
"play" with the speed and pitch of the speech. Normally,
these functions would be embedded in SET KEY procedures:
v_setsound() turns speech on and off
v_setdelay() varies speed of sounds sent to the speaker
v_setres() varies resolution of sound
v_setspace() varies pause between words


TRANSLATION

These functions convert text to/from "packaged" speech form:
v_pack() converts phoneme string to script
v_wpack() converts text string to script
v_apack() converts acronym string to script
v_unpack() converts script to phoneme string


SPEECH

Finally, the "script" of the speech is delivered to the
speaker:
v_pkspeak() speak a packaged script
v_speak() package and speak a phoneme string


Micro/Voice for Clipper Summer '87 Manual Page 4


V_INIT() FUNCTION

Purpose: Initiate Micro/Voice internals, open dictionaries

Syntax: v_init( [ [,
[, [, [,] ] ] ] ] )

Arguments: is full DOS filename for a main dictionary
DEFAULT IS NO MAIN DICTIONARY.

is full DOS filename for a secondary, or
"custom" dictionary. If ONLY one
dictionary is to be used, specify it as
, because will be ignored.
DEFAULT IS NO SECONDARY DICTIONARY.

is a resolution factor, which is one of
1, 2, 4, 6, or 8. DEFAULT IS 1.

is a speed/delay factor in the range 1..100.
Combination of resolution and speed/delay
will yield the clearest speech for your
hardware. For example:
res = 1, speed/delay = 19 for PS/2-60
Higher speed/delay factor results in slower
speech (lower pitch), which is necessary on
a faster machine. Likewise, higher
resolution results in much faster speech,
which requires that the speed/delay be
increased to compensate. DEFAULT IS 20.

is the space-between-words factor,
in the range 1..10. DEFAULT is 1.

Returns: A numeric value:
0 success: no dictionaries were specified, or
else any specified dictionaries were opened
1 if a main dictionary was specified, but could not
be opened (not a fatal error, but NO dictionaries
will be used in this case)
2 if a secondary dictionary was specified, but could
not be opened (not a fatal error, but no custom
dictionary will be used in this case)
3 if a secondary dictionary was specified, but
neither the main nor the secondary dictionaries
could be opened (not a fatal error, but NO
dictionaries will be used in this case)

Comments: All arguments are optional. However, if you specify
an argument, then any arguments "to the left" of it
must be specified or else their places occupied by
dummy values (i.e. expressions of a invalid type).

Example: v_init( "system.dct", .f., 1, 18, 2 )
One dictionary is used, resolution is 1,
speed/delay is 18, 2 logical spaces between words.


Micro/Voice for Clipper Summer '87 Manual Page 5


V_SETSOUND() FUNCTION

Purpose: Turn sound on or off

Syntax: v_setsound( [] )

Arguments: .T. turns sound on, .F. turns it off
If argument is omitted, no change is made.

Returns: A logical value: the original sound status

Example: v_setsound( !v_setsound() ) && toggles sound on/off


V_SETDELAY() FUNCTION

Purpose: Adjusts speed/delay

Syntax: v_setdelay( [] )

Arguments: a speed/delay factor in the range 1..100
If argument is omitted, no change is made.

Returns: A numeric value: the original speed/delay factor

Example: ? v_setdelay( 32 ) && prints 32


V_SETRES() FUNCTION

Purpose: Adjusts resolution

Syntax: v_setres( [] )

Arguments: a resolution factor, which must be
one of 1, 2, 4, 6, or 8
If argument is omitted, no change is made.

Returns: A numeric value: the original resolution factor

Example: v_setres( if(v_setres()=1,2,min(8,v_setres()+1)) )
This code will properly increment resolution factor.


V_SETSPACE() FUNCTION

Purpose: Adjusts space between words

Syntax: v_setspace( [] )

Arguments: number of logical spaces between words
If argument is omitted, no change is made.

Returns: A numeric value: the original space between words

Example: v_setspace( 3 ) && plenty of space between words


Micro/Voice for Clipper Summer '87 Manual Page 6


V_PACK() FUNCTION

Purpose: Converts a phoneme string to a script string
which can be pronounced by v_pkspeak()

Syntax: v_pack( )

Arguments: a phoneme string (see table below)
with spaces between words, and hyphens
(-) separating phonemes within each word
V_pack() is case insensitive.

Returns: A script string, or else an empty string if
an error occurred

Example: v_pkspeak( v_pack("k-ae-t") ) && says "cat"
Functionally equivalent to: v_speak("k-ae-t")

TABLE OF PHONEMES

In each example, the sound in question is capitalized.
A as in shAde ( sh-A-d )
AE as in mAn ( m-AE-n )
AH as in fAther ( f-AH-tz-uh-r )
AW as in bOy ( b-AW-ee )
B as in Bus ( B-uh-s )
CH as in CHill ( CH-ih-l )
D as in Dog ( D-aw-g )
EE as in kEEp ( k-EE-p )
EH as in wEst ( w-EH-s-t )
F as in Fig ( F-ih-g )
G as in waG ( w-ae-G )
H as in Hen ( H-eh-n )
I as in pIE ( p-I )
IH as in thIn ( th-IH-n )
J as in Jam ( J-ae-m )
K as in maKe ( m-a-K )
L as in List ( L-ih-s-t )
M as in Moose ( M-oo-s )
N as in Nut ( N-uh-t )
OH as in sOda ( s-OH-d-uh )
OO as in fOOd ( f-OO-d )
P as in maP ( m-ae-P )
R as in hoRse ( h-aw-R-s )
S as in Suit ( S-oo-t )
SH as in wiSH ( w-ih-SH )
T as in buTTer ( b-uh-T-uh-r )
TH as in maTH ( m-ae-TH )
TZ as in moTHer ( m-uh-TZ-uh-r )
U as in shIrt ( sh-U-r-t )
UH as in Unto ( UH-n-t-oo )
V as in oVal ( oh-V-uh-l )
W as in poWer ( p-ae-W-uh-r )
WH as in WHen ( WH-eh-n )
Y as in Yellow ( Y-eh-l-oh-oo )
Z as in Zebra ( Z-ee-b-r-uh )


Micro/Voice for Clipper Summer '87 Manual Page 7


V_WPACK() FUNCTION

Purpose: Converts a text string to a script string
which can be pronounced by v_pkspeak()

Syntax: v_wpack( )

Arguments: an ascii text string, which is
processed as follows:
1 - All punctuation is resolved to spaces.
Punctuation = <>{}|\*~`^_'",;:?!-()[]
2 - Each normal word in the string is looked
up in the main dictionary (if open).
3 - Each word not found there is looked up
in the custom dictionary (if open).
4 - Each word not found in EITHER dictionary
is converted to script form to be
pronounced the way it is written.
5 - Each "word" containing any of the special
characters /&$%+=@# or any numerals, or a
period (.) which falls within the word, is
processed as an acronym, to be "spelled
out" one character at a time.
V_wpack() is case insensitive.

Returns: A script string, or else an empty string if
an error occurred

Example: v_pkspeak( v_wpack("cat") ) && says "cat"


V_APACK() FUNCTION

Purpose: Converts an acronym string to a script string
which can be pronounced by v_pkspeak()

Syntax: v_apack( )

Arguments: an acronym string, which may contain
spaces between "words", each of which is
processed as an acronym, to be "spelled out"
one character at a time.
The following characters are recognized and
spelled out (others are ignored):
ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/&$%+=@#
V_apack() is case insensitive.

Returns: A script string, or else an empty string if
an error occurred

Example: v_pkspeak( v_apack("#1") ) && says "number one"







Micro/Voice for Clipper Summer '87 Manual Page 8


V_UNPACK() FUNCTION

Purpose: Converts a script string to a phoneme string

Syntax: v_unpack( )

Arguments: a script string from v_pack(),
v_wpack(), or v_apack().

Returns: A phoneme string, with spaces between words and
hyphens separating phonemes, or else an empty
string if an error occurred

Example: ? v_unpack( v_pack("i s-ee") ) && prints "I S-EE"


V_SPEAK() FUNCTION

Purpose: Speaks a phoneme string

Syntax: v_speak( )

Arguments: a phoneme string

Returns: .F. if sound is off, otherwise .T.

Example: ? v_speak( "i s-ee" ) && says "I see"


V_PKSPEAK() FUNCTION

Purpose: Speaks a script string

Syntax: v_pkspeak( )

Arguments: a script string from v_pack(),
v_wpack(), or v_apack().

Returns: .F. if sound is off, otherwise .T.

Example: ? v_pkspeak( v_wpack("I see") ) && says "I see"


















Micro/Voice for Clipper Summer '87 Manual Page 9

REGISTRATION FORM
Micro/Voice Voice Synthesis Function Library
Clipper Summer '87 Edition

DataBlaze Solutions
48 Park Street
Willimantic, CT 06226-3638

Please fill out a separate registration form for each programmer who
will be using the products. Site licenses available on request.

USER NAME: ________________________________ DATE: ________

COMPANY: __________________________________________________

ADDRESS: __________________________________________________

CITY, ST: __________________________ ___ ZIP: _________

PHONE: (WORK)__________________ (HOME)__________________


1. Micro/Voice Library, Clipper Summer '87 Edition
Includes registration of current copy, registration upgrade to
Clipper 5.0 edition when released, and technical support of both.

One copy for personal nonprofit use only ($19.95) $_______

One copy for commercial use ($34.95) $_______


2. Micro/Voice Comprehensive Dictionary #1 (over 2,000 entries)
Includes Comprehensive Dictionary of non-phonetic words for
Micro/Voice, plus MVCustom program to create and maintain
your own custom dictionaries. This product is being offered
to users who register their copy of the Micro/Voice Library.

One copy for personal nonprofit use only ($11.95) $_______

One copy for commercial use ($16.95) $_______

Diskette size for dictionary and MVCustom:
[ ] 3-1/2" [ ] 5-1/4" [ ] Both

Connecticut residents add 8% tax $_______

Shipping & handling ($1.00 PER DISKETTE) $_______

Total enclosed (check or money order, no COD's) $
Please make checks payable to: Steve Badaracco. =======

Signature: ____________________________

I [ ] DO / [ ] DO NOT wish to receive notices concerning
enhancements and bug fixes to Micro/Voice Clipper editions,
new expanded dictionaries, and upcoming editions of
Micro/Voice for C and for PASCAL.
(Please include name and number of most currently visited
Bulletin Board if you do wish to receive notices.)