
An Open Book
Unbound

Supplement for SSIL 
Programmers








 
systems for people with disabilities
PO Box 83
Worcester  WR3 8TU
Tel:  0905  754577		Int:  +44  905  754577
Fax:  0905  754559	Int:  +44  905  754559	
OBPS101U.1



   Contents





System Supplement 
2


1   The Dictionary and Numbers Files
2

2   The Numbers File
3

        2.1   Example of Numbers File
4

        2.2   Some Examples
5

3   DEDIT  -
     Exceptions Dictionary Editor
6

4   Installing without the install
     program
10

5   Supported Features
13

6   Special Features


14



Programmer's Supplement
16


1   SSIL Supported Commands
16

2   The Phoneme Mapping Files
17

3   Technical Notes
19

4   Install Notes
20




   System Supplement




Introduction

This supplement is for experienced users or those who are 
developing software using the Series 2 Speech 
Synthesiser Interface Library (SSIL) driver.  It is 
primarily intended for non-UK users and describes the 
SSIL driver command set and features.


1   The Dictionary and Numbers Files

The Series 2 Synthesiser SSIL driver has an Exceptions 
Dictionary for each language. The Exceptions Dictionary 
is user definable and is normally located in c:\apollo2 or 
c:\windows with the filename xxxx.dic  (Where xxxx is 
the numeric country code of the language.  This must be 
identical to the rom#id= parameter in APOLLO2.INI.)  
If an Exceptions Dictionary or Numbers file for a 
particular language does not exist then there will be no 
exceptions for that language.

You can edit each Exceptions Dictionary using the 
DEDIT utility supplied.  See section 6 in this manual for 
instructions on using DEDIT.
The xxxx.num files tell the driver how to pronounce 
numbers for each language.  You may create and edit 
these files using a text editor.


2   The Numbers File

The first thirty lines of the Numbers File define how 
numbers are split when they are read.

In more detail, the first line of the Numbers File defines 
which characters are used for the decimal point, separator 
and minus sign.

The second and third line define what is said for the 
decimal point and minus characters.

Line four defines the maximum number of digits that 
Apollo 2 SSIL driver will try to break up into tens, 
hundreds, thousands and millions.

The lines following that up to line thirty define how the 
digits are actually split.



2.1   Example of the first thirty lines of a
        Numbers File:

.,-
 point 
 minus 
12
>9 digits split
/000000000 thousand million 
/0000000++ thousand million and 
/000++++?? thousand million, 
/0++?????? thousand and 
/+???????? thousand, 
>6 digits split
/000000 million 
/0000++ million and 
/++++?? million, 
>3 digits split
/000 thousand 
/0++ thousand and 
/+?? thousand, 
>2 digits split
/00 hundred 
/++ hundred and 
=
=
=
=
=
=
=
=
=




The symbols used in the above example have the 
following meanings:

0			zero digit
+			non-zero digit
?			either zero or non-zero digit

2.2   Some Examples

Line six:		/000000000 thousand million
defines that if a digit, n, is followed by nine zeros then it 
is "n thousand million".

Line seven: 	/0000000++ thousand million and
defines that if a digit, n, is followed by seven zeros and 
the last two digits and non-zero then it is, "n thousand 
million and" the two non-zero digits.

Lines thirty one onwards in the Numbers File just define 
what is said for each of the number zero to ninety nine.



3   DEDIT  -  Exceptions Dictionary Editor

This program will create or edit an Exceptions 
Dictionary.  This file contains pronunciation changes for 
commonly mispronounced words.  There is a separate 
Exceptions Dictionary for each language.  The program 
has its own prompt file called prompt.dic (not required 
for English alphabet) which contains not only the 
program prompts but also details of the alphabet to be 
used (the order and, for each character, its lower case and 
uppercase forms).  Any other prompt files are intended 
for languages other than English.

DEDIT has two command line parameters:

-afilename	defines the Exceptions Dictionary 
			(english.dic is the default)

-pfilename	defines DEDIT's prompt file 
			(prompt.dic is the default)

For use with the Apollo 2 SSIL driver you will need to 
specify filenames as xxxx.dic for example

	dedit  -a0044.dic  <ENTER>



An Exceptions Dictionary consists of a list of exceptions 
listed in order.  Each exception consists of a search string, 
and a replacement string.  There are 2 types of exception:

1.  The search string is replaced ONLY if it is a 
whole word.  This type of exception is distinguished 
in the editor with an "arrows both way" character.  
A whole word is delimited by a space or carriage 
return.

2.  The search string is replaced if it "starts" a word 
(or it is a whole word).  This type of exception is 
distinguished in the editor with an "arrow left" 
character.

A "string" is a set of up to 38 characters.  These can be 
anything that the computer can accept.  However, in the 
search string a space is not permitted and any lower case 
letter is converted to its upper case equivalent.

To enter unusual codes depress the <ALT> key, and 
whilst it is depressed type in the decimal code on the 
number pad.  Finally, release the <ALT> key.



In the editor keys have the following functions:

<F1>				Display the help screen
<F4>				Switch between displaying spaces
					as spaces and spaces as dots (*)
 <up arrow>			Move up one entry
<down arrow>			Move down one entry
<PgUp>				Move up a screenful of entries
<PgDn>				Move down a screenful of entries
<CTRL> and <PgUp>	Move to first entry
<CTRL> and <PgDn>	Move to last entry

When you are not editing an entry:

<F2>				Find an exception:  Key in the
					search string and press <ENTER>
<ENTER>			Start editing the current entry
<CTRL> and <ENTER>	Replace the current entry
<INS>				Insert a new entry into the
					dictionary
<DEL>/<BkSp>		Delete the current entry
<F9>				Save the dictionary
<ESC>				Save the dictionary and finish the
					program
<Q>					Quit the program without saving
					the changes



When you are editing an entry:

<F3>				Switch between  1) "whole word
					only" and  2) "start of word"
<BkSp>				Deletes a character

You will notice that some exceptions are duplicated e.g. 
"AVE" and "AVE.".  This is done to make "AVE." say 
"Avenue period" when punctuation is set to on.  If the 
exception was entered without the full stop, then with 
punctuation on it would not say "period".

If you have a new exception to enter press the key 
marked <INS>.

If you wish to edit an already existing exception, use the 
up and down cursor keys until the exception you want to 
edit is highlighted and then press the <ENTER> key. 

That exception will then be used as a template for a new 
exception.  Edit your exception, pressing the <ENTER> 
key after you have entered the word to replace, and again 
after its replacement string.

N.B.  If when editing you change the string that will be 
replaced, when done this will be added to your Exceptions 
Dictionary alongside the exception you used as a template.  
Also, if you have HAL running while you use DEDIT, the 
words and replacements will be spoken as you edit them


4   Installing without the INSTALL program

If you have a non-standard configuration, or wish to have 
more control over the installation procedure, you should 
refer to these instructions for installing the driver.

Copy the main driver file and configuration file 
APOLLO2.DLL and APOLLO2.INI to your Windows 
directory.  (This is usually c:\windows.)

Create a directory c:\apollo2 and copy all the *.dic and 
*.num and *.pho files into here.  Edit dictionarypath= 
in APOLLO2.INI to tell the driver where the directory is. 
See section 4 of the User Supplement The Configuration 
File  -  APOLLO2.INI.

To be able to edit the Exceptions Dictionary you will 
need the DEDIT program, so copy dedit.exe and 
prompt.dic into c:\apollo2. prompt.dic is not required if 
you are using English.

Edit APOLLO2.INI and set TYPE= to either com or 
europa depending on which synthesiser you have.

	If you have an Apollo 2;

Edit APOLLO2.INI and set ComPort= to the COM port 
number that your Apollo 2 is plugged into.  The default is 
1. You may need to change this to use COM2: if you 
have a mouse plugged into COM1:.  If you have a mouse, 
make sure that your mouse driver is set to the correct port 
number, and not the port that the Apollo 2 is plugged 
into. 

Edit APOLLO2.INI and set Baudrate= to the baud rate 
that your Apollo 2 is set to.  This will be 9600 baud 
unless you have a baud rate switching lead.

	If you have an Europa 2 PC Card;

If you have changed the default card port address, edit 
APOLLO2.INI and set CardPort= to the decimal value 
of the card port. Refer to the Series 2 Synthesizer User 
Guide for information about the Europa 2 port addresses.

To Configure 'An Open Book' for use with the Apollo 2: 

Edit OPENBOOK.INI and change driver= to 
driver=APOLLO2.  The location of OPENBOOK.INI 
depends on which version of An Open Book you have.

This tells 'An Open Book' to use the Series 2 driver rather 
than the DECtalk driver, or any other driver.

When you first run 'An Open Book' you may find that the 
default voice settings are for the DECtalk synthesiser.  
These parameters are not suited to the synthesiser so you 
will have to change the voice settings.  The INSTALL 
program supplied does this for you, but you can also do 
this manually.

To change to the proper default settings you need to 
change the voice pitch to 7, which is labelled as Medium, 
and change the voice tone to 12.  This will give you to the 
default settings.  Note that you will have to do this for 
both the Reading voice and the Menu voice.  You may 
also need to set the Italic, Bold and Underline voices if 
you select certain scanning modes.

You may find it helpful to create a 
openbook/settings/apollo2.ini file with the synthesisers 
default settings in, or make changes in the 
openbook/settings/default.ini file, which is the file that 
'An Open Book' uses to remember synthesiser voice 
settings. 



5   Supported Features

The Series 2 SSIL driver supports the following features:

	*	Works with processors from 8086 through to
		80486
	*	Up to 16 preset voices, user definable in a
		configuration file
	*	Intermediate stop and throw away pending
		speech
	*	Spell Mode - pronunciation of each character
	*	Index Marking for words (and characters in
		spell mode) providing speech progress
		feedback
	*	Text labels for parameter values (these are
		always in English)
	*	Accepts all 256 ANSI Characters as input
	*	Speech Rate Control
	*	Volume Control
	*	Pitch Control
	*	Intonation Control
	*	Punctuation announcement on/off
	*	Multiple language support with multiple
		Exceptions Dictionaries
	*	Word and phrase pause control
	*	Configuration file containing many more
		voice parameter settings
	*	Supports COM1-4: with multiple baud rates
	*	Phoneme mode (see notes below)


6   Special Features

The Series 2 Synthesiser has a different set of phonemes 
for each language.  For languages other than English the 
SSIL phoneme set may be inappropriate, as some of their 
sounds are not represented.  The synthesiser driver uses a 
set of mapping files (xxxx.pho in c:\apollo2) which 
contain translation information for converting from SSIL 
phonemes to Series 2 synthesiser phonemes. There is a 
separate mapping file for each language ROM, each file 
being selected as appropriate whenever you change 
language.

Currently there is only one map file supplied, 0044.pho, 
which works for UK English.

You can only have one synthesiser unit at a time handled 
by one driver.

The Apollo 2 and Europa 2 have some additional 
parameters; markspace, breath, hypermode and 
voicesource that you can set in APOLLO2.INI for the 
preset voices.  However, head size, voicing, frication, 
aspiration, are not directly supported.  See the Series 2 
Synthesiser user manual and APOLLO2.INI file for more 
information.

You can select gender by choosing an synthesiser voice 
with the gender= command in APOLLO2.INI.  There are 
6 preset voices to choose from.  See the Apollo 2 manual 
for more information.

Phrase pause controls both inter-sentence and inter-
phrase pausing, therefore sentence pause control is not 
used.

The parallel port interface to the Apollo 2 is not yet 
supported.



   Programmer's Supplement




1   SSIL Supported Commands

The Driver fully supports all the functions described in 
the SSIL-Driver Interface specification.
 
It supports the following in-line SSIL commands:

>	push context
<	pop context
=	set parameter
+	increase parameter
-	decrease parameter


It supports the following parameter selectors:

c	context
P	preset voice
o	output mode
l	language
r	rate
v	volume
p	average pitch
i	intonation
!	punctuation level
space	word pause
,	phrase pause
s	spell all
g	gender

No other parameters are supported.  They will be ignored.


2   The Phoneme Mapping Files

Phoneme mode needs to be used with care.  The 
conversion from SSIL to Dolphin phonemes may not be a 
single 1 to 1 mapping.

The phoneme mapping file translates from the SSIL 
phoneme set to the Dolphin phoneme set.  There is a 
separate mapping file for each language you are using.

Each phoneme mapping file (.pho) is generated with the 
program photophs.exe .  This converts a .phs file, 
containing the mapping table, into a binary file, readable 
by the device driver.  Thus for each .pho file there is a 
corresponding .phs file.  You can edit the .phs file with a 
text editor.

The .phs file contains a translation table, one phoneme 
per line. The spacing and layout is fairly critical as 
photophs does not do much checking.  The first number 
is the SSIL phoneme number.  This is followed by the 
Dolphin phoneme sequence equivalent to the SSIL 
phoneme, contained within double quotes.

The remainder of the line is a comment, which describes 
the SSIL phoneme.

You can have up to two Dolphin phonemes for each SSIL 
phoneme.  To enter values greater than 127 precede the 
ASCII value in decimal with a backslash.

To create a new .phs file it is recommended that you start 
with an existing file, such as 0044.phs (English) and 
modify it.

Note that the phonemes are different from the embedded 
phoneme commands described in Appendix three of the 
Series 2 Synthesiser User Guide.  To create a new 
phoneme mapping table you will need to know the 
Apollo's internal phoneme table, which is best done by 
experiment.  Phoneme symbols are regularly updated as 
Dolphin Systems improve its synthesizer speech quality.


3   Technical Notes

There is a locking system implemented to prevent 
unlimited recursion.  When the driver does a call-back, 
the application may call the driver with un_speak() 
during this call back (at least 'An Open Book' does).  To 
prevent problems, un_update()'s are prevented from 
occurring during the applications call to un_speak().  
This causes a problem because the synthesiser may start 
speaking, but the driver has not finished sending the next 
phrase to the synthesiser, and thus call backs are disabled, 
preventing the application from finding out where the 
speech has got to.  In practice this means that with a slow 
baud rate (300 or 1200 baud), the word tracking cursor 
may not start to track the actual words being spoken, until 
the call to un_speak() is finished.

If the driver loses comunications with the synthesiser, it 
will continue to try for about 2 seconds.  If it still fails 
then it will attempt to simulate the call backs to the 
application.  Thus if the synthesiser is unplugged or 
switched off, the application may freeze for a few 
seconds before the driver recovers.  As soon as the driver 
re-establishes communications with the Apollo 2 the 
system will return to normal. 


4   Install Notes

The program INSTALL does the following. 

It copies the driver into your Windows directory.  It 
creates a directory called apollo2 on the drive containing 
your Windows directory and copies the driver support 
files into it.

If you select 'An Open Book' installation (which is the 
default), it will change OPENBOOK.INI so it specifies 
the Apollo 2 driver, and then change 
openbook\settings\default.ini to the default voice settings 
of the Apollo 2.  It sets each of the five 'An Open Book' 
voices (Reading, Italic, Bold, Underline & Menu) to the 
default Apollo 2 settings.  It also saves back-up copies of 
these files.  It assumes that the settings directory is 
c:\openbook\settings.

The INSTALL program has the following return values 
which you can check for in a batch file using 
ERRORLEVEL.

0   	OK successful installation, or command line option
	? selected.
1   	'An Open Book' not installed, or not found.
2   	'An Open Book' settings file can't be found.
3   	Windows not installed, or wrong windows directory
	name.
4   	Illegal command line option(s).
System Supplement

System Supplement

Page   -   2

Page   -   3

SSIL Programmer's Supplement

SSIL Programmer's Supplement

Page   -   20

Page   -   19




