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 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 key, and whilst it is depressed type in the decimal code on the number pad. Finally, release the key. In the editor keys have the following functions: Display the help screen Switch between displaying spaces as spaces and spaces as dots (*) Move up one entry Move down one entry Move up a screenful of entries Move down a screenful of entries and Move to first entry and Move to last entry When you are not editing an entry: Find an exception: Key in the search string and press Start editing the current entry and Replace the current entry Insert a new entry into the dictionary / Delete the current entry Save the dictionary Save the dictionary and finish the program Quit the program without saving the changes When you are editing an entry: Switch between 1) "whole word only" and 2) "start of word" 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 . 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 key. That exception will then be used as a template for a new exception. Edit your exception, pressing the 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