Introduction

This document details SAM's interface with 16-bit SSIL drivers.

Using this document you should also be able to configure new SSIL drivers to work with SAM, and therefore with Hal, Supernova and Cicero.  (That's if an SSIL driver for your speech synthesizer is not already distributed with SAM.)

SAM to SSIL Interface files

Each SSIL driver most be stored in a separate sub-directory and requires an SIF file to register it with SAM.  The SAMSSIL module of SAM scans all SIF files in all sub-directories when it starts up.

This SAM driver consists of 4 DLLs and an EXE:

• SAMSSILB.  The main 32-bit end of the driver.
• SAMSSILC.  A thunking interface for Windows 95. (Not NT.)
• SAMSSILA.  16-bit end of the thunk for communication with 16-bit SSIL DLLs.
• SAMSSILD.  A 16-bit interface to the Windows NT server.
• SAMSSILE.  A 16-bit application for Windows NT to use SSIL drivers.
  

SSIL Installation File - SIF

The SIF files describe the available 16-bit SSIL drivers that the SAM to SSIL interface can use.  Because some SSIL drivers need to be copied into the Windows directory and some have a common SSIL.INI file, SAMSSILB will copy the relevant files to the correct place, making the appropriate INI file modifications when you change synthesizer.

Having an INI file modification section avoids the need for duplicated directories and drivers where only one line in the INI file is different.

WARNING.  When you change synthesizer driver SAM will DELETE the old SSIL files from wherever it copied them to. Therefore you should only make modifications to SSIL drivers and associated files in the original source directory.

To force SAMSSIL to re-copy an SSIL driver just use its configuration dialog box and hit ENTER, without changing the synthesizer selection

The sections in each SIF file are as follows:

It is mandatory to have an [SSIL Driver] section.

SIF files must be stored in the sub-directory that contains the  SSIL driver. You can have more than one SIF file per driver. SIF files are never copied anywhere.

[SSIL Driver] ; this section is required

Description= Text description of synthesizer and it's connection.

DLLname= Name of the actual SSIL driver DLL.

DestinationDirectory= Identifier of directory to install the driver DLL to:
                1 = SAMSSILB directory
                2 = Windows directory
                3 = Windows system directory
                4 = Leave it in the source directory
                5 = Custom (see below)

SafeDetect=

0 - Driver cannot safely detect a synthesizer.

1 - Driver detects a synthesizer safely.  This means that this driver can be loaded, and DR_OPENDRIVER and DR_OPENUNIT can be used.  These functions should return "failed" if the correct synthesizer is not present and should succeed if it is. They should not crash, hang the machine, if the synthesizer is not present.  The driver should also be able to be loaded and unloaded more than once in a single Windows session, and you must be able to reopen a closed driver without 1st unloading the driver DLL.
                   
If this is set to 1 then SAM will try to use this driver when it is searching for a synthesizer. If both DR_OPENDRIVER and DR_OPENUNIT return TRUE (success) SAM will assume that the synthesizer has been detected successfully. If either return FALSE SAM will unload the driver.

NT=
0 - Driver cannot be safely used under NT. Such drivers may crash, or otherwise fail to work because they access hardware directly.

1 - Driver can be safely used under NT.  Only some of the drivers are flagged as "Working under NT".  We have only flagged those drivers that we have been able to test. Some other drivers may work but have not been tested by us.

ContextSwitch=
This setting determines how SAM tells the driver to change voice parameters.

0 - Driver does not use context switching in the SSIL driver.  This is the best option if you want reliable voice command changes.  This is the default option.

1 - Driver uses context switching.  This may speed up the response time in some drivers. However, you may find that some voice commands are not reliable.  If you use the same voice (name, speed, pitch, etc.) for all of your software then this is the faster method.

[INI File] ; this section is optional

INIname= Name of INI file that needs to be modified (if any).

DestinationDirectory=     Identifier of directory to copy the INI file to:
                1 = SAMSSILB directory
                2 = Windows directory
                3 = Windows system directory
                4 = Leave it in the source directory
                5 = Custom (see below)

[INI Modifications]
NumberOfMods= Number of modifications to make to the above INI file

ModXSection= Heading of the section to be modified

ModXLabel= Label of the entry to be modified

ModXEntry= The value to assign to the modified entry

(where X lies between 1 and NumberOfMods)


Custom configurations

If the destination directory is 5 then the source directory should be the FULL PATH to the directory of the driver DLL.  No files will be copied.  Use this option if the SSIL DLL has to be in a different location.  If you are building one you can set the SourceDirectory to
point to your build directory.