DECtalk™  Software 
Programmer's Guide

April  1998

This guide contains an introduction to DECtalk Software and the DECtalk Software API.





Revision and Update Information:

Operating System:	Microsoft Windows 95
	Microsoft Windows NT
	DIGITAL UNIX
	

Software Version: 	DECtalk Version 4.5
 



Digital Equipment Corporation
Maynard, Massachusetts
April 1998
The information in this document is subject to change without notice and should not 
be construed as a commitment by Digital Equipment Corporation. Digital Equipment 
Corporation assumes no responsibility for any errors that might appear in this 
document.

No responsibility is assumed for the use or reliability of software or equipment that is not supplied by Digital Equipment Corporation or its affiliated companies.

© Digital Equipment Corporation 1997, 1998.

All Rights Reserved.
Printed in U.S.A.

The following are trademarks of Digital Equipment Corporation: 
DEC, DECtalk, DIGITAL, VAX, and the DIGITAL logo.

Intel is a trademark of Intel Corporation. Microsoft Word for Windows is a registered trademark and Windows 95 and Windows NT are trademarks of the Microsoft Corporation. RoboHELP is a registered trademark of Blue Sky Software Company.  SoundBlaster is a registered trademark of Creative Labs, Inc. UNIX and DIGITAL UNIX are registered trademarks in the United States and other countries licensed exclusively through X/Open Company, Ltd.  Motif is a registered trademark of Open Software Foundation, Inc.

This document was prepared using Microsoft Word 97 to generate MS Word 6.0/95 compatible files. The online help system was prepared with Microsoft Word 97 and the RoboHELP 4.0 help authoring tool.

Contents
Preface	vii
Purpose and Audiences	vii
Structure	vii
What's New in DECtalk V4.5?	viii
What's New in DECtalk V4.4?	ix
Conventions	xi
Chapter 1 - Introduction to DECtalk Software	1-1
DECtalk Software Features and Functions	1-2
Latest Version of Speech-Synthesis Technology from DIGITAL	1-2
Letter Mode, Word Mode, and Clause Mode	1-2
Short Command Strings	1-2
High-Quality Speech and Word Pronunciation Accuracy	1-2
Pronunciation Heuristics	1-3
DECtalk Software Components	1-3
Sample Program Applet	1-3
Speak Program Applet	1-5
Text-to-Speech DDE Server	1-6
Programming Aids	1-6
DECtalk Software APIs	1-6
DECtalk Software In-Line Commands	1-6
DECtalk Software Dictionaries	1-7
Using the Components	1-9
Application Programmer	1-9
General User	1-9
How It Works	1-11
Chapter 2 - Using the Program Applets to Learn DECtalk Software Basics	2-1
Starting the Sample Applet and Opening a Text File	2-2
Inserting DECtalk Software In-Line Commands (Syntax Rules)	2-4
Additional Syntax Rules	2-5
Changing Speaking Voice	2-6
Editing a Text File and Changing the Speaking Rate	2-8
Overview of the User Dictionary Build Tool	2-10
Building a User Dictionary	2-12
Using the DECtalk Software Speak Applet	2-16
Running DECtalk Software from Other Applications	2-19
Step 1 - Creating a Word Macro and Associating it with a File or Document Template (for Word 7.0)	2-20
Step 2 - Associating the Macro with a Toolbar Button	2-23
Step 3 - Launching and Configuring the DECtalk Software Text-to-Speech Server	2-25
Step 4 - Speaking Text in a Microsoft Word .doc File with the DECtalk TTS Server	2-27
Using the Say Command-Line Applet	2-29
Chapter 3 - Introduction to the DECtalk Software API	3-1
The Core API Calls	3-4
TextToSpeechSpeak	3-4
Important Text-Queuing Information	3-5
Clause-Based Synthesis	3-5
Callback Routines and Window Procedures	3-6
Error Messages	3-7
Index Mark Messages	3-8
Buffer Messages	3-8
Audio Output Control Calls	3-11
Blocking Synchronization Call	3-11
Control and Status Calls	3-11
Special Text-To-Speech Modes	3-12
Wave-File Mode	3-12
Log-File Mode	3-13
Speech-To-Memory Mode	3-13
Dictionary Calls (UNIX only)	3-18
Creating a User Dictionary	3-18
Loading the Main Dictionary	3-18
Loading the User Dictionary	3-19
Dictionary Calls (Windows only)	3-19
Creating a User Dictionary	3-19
Loading the Main Dictionary	3-20
Loading the User Dictionary	3-21
Sample Programs (UNIX only)	3-22
Building Sample Programs	3-23
Header Files	3-23
Shareable Libraries	3-24
Sample Programs (Windows only)	3-25
Chapter 4 - How to do Multi-Language Programming	4-1
Starting a language	4-2
Selecting a language	4-2
Closing a language	4-2
Example	4-3
Glossary
Index


Figures
Figure 1-1 Visual Overview of the Sample Program Applet	1-4
Figure 1-2 Visual Overview of the Speak Program Applet	1-5
Figure 1-3 In-Line Command Components	1-7
Figure 1-4 Flow of the DECtalk Software Text-To-Speech Conversion Process	1-11
Figure 2-1 Starting the Sample Applet and Opening a Text File	2-2
Figure 2-2 Rules for DECtalk Software In-Line Command Syntax	2-4
Figure 2-3 Changing DECtalk Software Voices	2-7
Figure 2-4 Editing a Text File and Changing the Speaking Rate	2-8
Figure 2-5 Components of the User Dictionary Build Tool	2-10
Figure 2-6 Building a User Dictionary	2-12
Figure 2-7 Saving and Compiling the Dictionary	2-14
Figure 2-8 Using the DECtalk Software Speak Applet	2-16
Figure 2-9 Highlighting Spoken Text	2-18
Figure 2-10 Creating a Word Macro	2-20
Figure 2-11 Associating the Macro with a Toolbar Button	2-23
Figure 2-12 Launching and Configuring the DECtalk Server	2-25
Figure 2-13 Speaking Text in a Microsoft Word .doc File with the DECtalk Software TTS Server	2-27

Tables
Table 2-1 Starting the Sample Applet and Opening a Text File	2-3
Table 2-2 DECtalk Voices and their Associated Values	2-6
Table 2-3 Changing Voices	2-7
Table 2-4 Editing a Text File and Changing the Speaking Rate	2-9
Table 2-5 Building a User Dictionary	2-13
Table 2-6 Saving and Compiling the Dictionary	2-15
Table 2-7 Using the DECtalk Speak Application	2-17
Table 2-8 Creating a Word Macro	2-21
Table 2-9 Associating the Macro with a Toolbar Button	2-24
Table 2-10 Launching and Configuring the DECtalk TTS Server	2-26
Table 2-11 Speaking Text in a Microsoft Word .doc file with the DECtalk TTS Server	2-28
Table 3-1 Text-To-Speech Calls by Category	3-2
Table 3-2 API Control and Status Calls	3-11
Table 3-3 Special Text-To-Speech Modes	3-12

Preface
Purpose and Audiences
This guide, DECtalk Software Programmer's Guide, is for the application programmer who wants to design and build text-to-speech applications with DECtalk Software. This guide should be used in conjunction with the DECtalk Software Reference Guide and the DECtalk Software Installation Guide.
Structure
This guide's design gives you quick and easy access to information. Its organization can help you easily learn about new topics and perform specific tasks related to the use of the program applets or development of a DECtalk Software application.
The guide is organized as follows:
Chapter 1
Introduction to DECtalk Software
Chapter 2
Using the Program Applets to Learn DECtalk Software Basics
Chapter 3
Introduction to the DECtalk Software API
Chapter 4
How to do Multi-Language Programming
DECtalk Software Implementations and Licensing
DECtalk Software is packaged to run on the Digital UNIX, Windows NT, and Windows 95 operating systems. The DECtalk Software documentation library is designed as a single library of hardcopy and online documentation for all platforms. Each of the DECtalk Software implementations and its supporting documentation is charted in the following table.

DECtalk Software for Digital UNIX
The UNIX Runtime kit is factory installed with the UNIX operating system gives you access to the following DECtalk Software applications: mailtalk, say, speak, emacspeak, and DECface. In order to develop your own DECtalk Software applications, you must order the DECtalk Software Developer's kit. DECtalk Software Developer's kit gives you access to the DECtalk Software API and some sample C programs.

What's New in DECtalk V4.5?
DECtalk Software V4.5 for Windows 95 and Windows NT contains the following new features:
Distributed on CD-ROM.
Year 2000 support speaks four-digit year specifications as four-digit year specifications, for example, the year 1998 is spoken as nineteen ninety eight, and speaks 2-digit year specifications as a 2-digit number without asssuming the century, for example, the year 98 is spoken as ninety eight.
United Kingdom English is added.
SAPI mark syntax (\mrk=\ tag) is working.  The TextData interface now accepts tagged text.  The \mrk=\ tag is the only tag supported.  Other tags are ignored.
ITTSBufNotifySink: The BookMark and WordPosition interfaces are now functional. The timing of the TextDataStarted and TextDataDone notifications is corrected.
ITTSNotifySink: The Visual interface is now functional; the timing of the AudioStart and AudioStop notifications is corrected.
DECtalk Software V4.5 provides better indexing performance than previous versions.
Multi-Language (ML) support is functional.
Sample programs Speak and dtsample are updated to Multi-Language (ML)functionality. All sample applets are ML-compliant code. Some sample applets demonstrate ML-application programming. 
The User Dictionary compiler now handles accent characters (extended ASCII).
OLE notification support, AudioStart and AudioStop, now returned.
The current DECtalk Software implementation of the Microsoft Speech API (SAPI) is described in the appendix3.txt file that is included with the DECtalk Software installation files.

What's New in DECtalk V4.4?
DECtalk Software version 4.4 contains the following new features:
Support for multiple instances of the text-to-speech objects in a single process.
A new startup function, TextToSpeechStartupEx(), has been added to complement the platform specific TextToSpeechStartup() function for Windows. The Windows startup function supports windowing messages, while the new extended startup function supports callbacks. On UNIX, both startup functions work similar to the Windows extended startup function, in other words, they support callbacks not window messages.
A new document, the DECtalk Software Reference Guide, has been added. This guide provides an overview and reference listings of the DECtalk Software in-line commands. It also contains a listing of all reference tables for phonemic symbols, stress and syntactic symbols, tone tables, and homographs.
E-mail parsing has been added to the Mode in-line command.
Changes have been made to the UNIX code to allow for posix thread changes.
Implementation of the TextToSpeechReset() function has been changed.
The TextToSpeechPause() function has been made asynchronous.
New license specific return values have been added to the startup functions, TextToSpeechStartup() and TextToSpeechStartupEx(). They are MMSYSERR_ALLOCATED and MMSYSERR_NOTENABLED.
The ttsapi header file (ttsapi.h) was modified for 4.4. The following is a list of changes that were made.
Symbol in TTSAPI.H
Old Value
New Value
OUTPUT_TO_AF_DEVICE
01000000
no longer exists
OUTPUT_TO_MME_DEVICE
80000000
no longer exists
OWN_AUDIO_DEVICE
10000000
00000001
REPORT_OPEN_ERROR
20000000
00000002
DO_NOT_USE_AUDIO_DEVICE
40000000
80000000

For compatibility reasons, the INDEX_MARK and MESSAGE_BUFFER symbols were changed. The variables were renamed to force a recompile of any code that uses the old names since the values were not guaranteed to mean the same thing between 4.2A and 4.4. 
Old Symbol
Value
New Symbol
Value
INDEX_MARK
0
TTS_MSG_INDEX_MARK
1
MESSAGE_BUFFER
1
TTS_MSG_BUFFER
0


TTS_MSG_STATUS
2

The callback routines defined in both TextToSpeechStartup and TextToSpeechStartupEx have been changed.
The old callback routine, defined in DECtalk Software 4.2A was defined as:
Callback (DWORD param1, LONG param2, LONG userDefined) 
param1:
Type of callback (INDEX_MARK or MEMORY_BUFFER) or error 
param2:
For INDEX_MARK, this would be the index mark value

For MEMORY_BUFFER, this would be a pointer to the memory buffer
userDefined:
Pointer to user-defined data that was passed in TextToSpeechStartup()

The new callback routine, defined in DECtalk Software 4.4 is defined as:
Callback (DWORD param1, LONG param2, LONG userDefined, UINT uiMsg)
param1:
For TTS_MSG_STATUS, this will indicate the error/status code
param2:
For TTS_MSG_BUFFER, this will be a pointer to the memory buffer

For TTS_MSG_INDEX_MARK, this will be the index mark value

For TTS_MSG_STATUS, this is additional information for the error/status.
userDefined:
Pointer to user-defined data that was passed in TextToSpeechStartup()
uiMsg:
TTS_MSG_BUFFER for memory buffers

TTS_MSG_STATUS for error and status information

TTS_MSG_INDEX_MARK for index marks

DECtalk.lib has been placed in \Program Files\DECtalk\lib.
The 8 kHz, 16 bit mono output is now supported.
Conventions
The following conventions are used in this guide:
Convention
Meaning
enter
Enter means type the required information and press the Enter key.
mouse
Mouse refers to any pointing device, such as a mouse, a puck, or a stylus.
MB1
MB1 indicates the left mouse button.
click 
Click means to press and release MB1. 
Double click 
Double click means to press and release MB1 twice in rapid succession without moving the mouse.
drag
The phrase drag means to press and hold MB1, move the mouse, and then release MB1 when the pointer is in the desired position.
Ctrl/x
Press the Ctrl key while you press another key.
Menu ⇒Command
The right arrow key indicates an abbreviated instruction for choosing a command from a menu. For example, File ⇒Exit  means pull down the File menu, move the pointer to the Exit command, and release MB1. 
Courier type
Courier type indicates text that is typed or displayed on the screen. This is most often used for program code examples.
User Input
Boldface type in interactive examples indicates information you enter from the keyboard. For example: 
A:>SETUP
XX YY and 
XXn YYn
In DECtalk Software in-line command syntax, XX and YY indicate options and parameters. When more than one choice of options or parameters is allowed, the symbol XXn or YYn with n replaced by a numeral indicates each option or parameter in the symbolic representations, such as [:phoneme XX1 XX2 YY]. Note that the number of characters in the symbolic representation does NOT represent the number of characters allowed in the actual option or parameter name.
DD and DDn
In DECtalk Software in-line command syntax, DD indicates a decimal (base 10) value. When more than one decimal values are allowed, the symbol DDn with n replaced by a numeral represents each allowed value, such as [:volume XX DD1 DD2]. Note that the number of characters in the symbolic representation does NOT represent the number of characters allowed in the actual decimal value.
Conventions used in API calls
bold
Bold text indicates call names, data structures, and field names. 
Italics
Italic text indicates call arguments and emphasizes important information.
Unless otherwise noted, press Enter after typing responses to command prompts.


Chapter 1-
Introduction to DECtalk Software
DECtalk Software provides programming resources to support application solutions that require text-to-speech output. This chapter provides a general overview of DECtalk Software. Topics include: 
DECtalk Software Features and Functions
DECtalk Software Components
Text-to-Speech DDE Server
Programming Aids
Using the Components
How it works
DECtalk Software Features and Functions
DECtalk Software enables applications to extend  the capabilities of your personal computer by turning text files into spoken words.  With only a standard PC sound card for audio output, the programming resources provided by DECtalk Software allow applications to accurately read ASCII text from a variety of sources, such as electronic mail and word processors. Nine different voices are provided, and users can control voice pitch, rate of speech, and word or phrase emphasis. 
Latest Version of Speech-Synthesis Technology from DIGITAL
DECtalk Software contains the latest version of DECtalk Software speech synthesis. This incorporates a number of improvements from earlier versions of DECtalk and is a software-only version.
Letter Mode, Word Mode, and Clause Mode
DECtalk Software can immediately speak single characters without waiting for an entire clause to be buffered. DECtalk Software also provides normal clause buffering for natural speech. DECtalk Software can speak letters, words, phrases, clauses, paragraphs, and whole documents. DECtalk Software allows the application to terminate speech immediately instead of waiting for the buffered text to complete processing. 
Short Command Strings
Many of the DECtalk Software in-line command strings, such as change rate, change voice, start, stop, and index marks can be abbreviated for greater ease of use in applications. 
High-Quality Speech and Word Pronunciation Accuracy
DECtalk Software speech retains its high quality. In addition, functionality and acoustic phonetic quality are improved. Also, DECtalk Software has a large built-in dictionary that enables accurate pronunciation of individual words as well as enhancing their rhythmic naturalness. 
Pronunciation Heuristics
DECtalk Software includes pronunciation heuristics that recognize and parse unpronounceable sequences, such as sequences of uppercase initials (FBI, AAA, and so forth) and sequences with no vowels (CBS, NBC, for example).
DECtalk Software Components
DECtalk Software components include:
Sample and Speak program applets (dtsample.exe and speak.exe)
A command-line program that speaks text (say.exe)
Programming aids, including the API, voice-control commands, and the User-Dictionary Build Tool
Text-to-Speech Services including the Dynamic Data Exchange (DDE) Text-to-Speech server.
Sample code for the Sample program applet, the command line program (say.exe), and a speech-to-memory sample program. 
Sample Program Applet
The Sample program applet and components are provided to give you some ideas on how to get started with your application. Both the graphic user interface and source components used to develop that user interface are included as part of the Sample program. See  Figure 1-1 for a visual overview of the DECtalk Sample Application dialog.  See the Using the Program Applets to Learn DECtalk Software Basics for additional description of the Sample program. Note that available languages not installed with the DECtalk Software are grayed out on the Languages menu.  Languages shown in dark lettering are installed and ready to be used.
Figure 1-1 Visual Overview of the Sample Program Applet

Legend

Dialog



  Menu bar: File, Edit, Speak, Voice, Rate, Languages, and Help menus

Start, pause, and stop push buttons



Speech speed-control slider



Edit window for text input



Speak Program Applet
The Speak program applet is included as a practical example of how the DECtalk Software API can be used to produce an innovative Text-To-Speech application that maximizes user interaction through a highly graphical interface.  Figure 1-2 shows a visual overview of the Speak program applet.
Figure 1-2 Visual Overview of the Speak Program Applet

Legend

Menu bar: File, Edit, and Help menus

Speech speed-control slider

Voice-activation buttons 

Start, pause, and stop push buttons

Edit window for text input


* Note that the faces become cartoon characters when using VGA 16-color mode.

Text-to-Speech DDE Server
The DECtalk Software Text-to-Speech server makes it possible for any Windows application that can call DDE and that contains ASCII English text to speak that text through DECtalk Software. The server is launched automatically whenever you start Microsoft Mail or manually whenever you click on the Text-to-Speech server icon in the DECtalk Software program group.
Programming Aids 
The DECtalk Software programming aids include the application programmer's interface (API), in-line commands, and User Dictionary Build Tool. Each component is introduced in this section and explained in detail in Chapter 3.
DECtalk Software APIs
DECtalk Software contains two APIs: the DECtalk Software API (DAPI) and the Microsoft Speech Application Programmer's Interface (SAPI).  The DECtalk Software documentation set describes the DAPI interface.  Refer to Microsoft documentation and/or the Microsoft web site for information about SAPI. 
The DECtalk Software Text-To-Speech API is a DIGITAL extension to the MPC (Multimedia PC) API specified by the Windows operating system.
The API function set gives you a flexible method of using and controlling DECtalk Software functionality from within your application. These functions perform a wide range of tasks associated with the Text-To-Speech system. See the DECtalk Software Programmer's Guide for the complete list of API functions.
DECtalk Software In-Line Commands
DECtalk Software includes in-line commands that control voice characteristics. You can use these commands to perform simple voice-control operations, such as changing the speaking rate or speaking voice while DECtalk Software is speaking. In-line commands can be inserted into the text entered into the edit window or box available in most applications supplied with DECtalk Software.  In-line commands also can be included in data buffers passed to the DECtalk Software DLLs by way of various TextToSpeech...() API calls.  For more information, see the DECtalk Software Reference Guide.
DECtalk Software also has a more complex set of voice-control commands to modify the characteristics of each voice, control intonation and stress within written text, or to create special effects, such as singing. 
In-line commands have special syntax rules and components that you need to use when you insert them into files. A few simple commands and command components are illustrated in Figure 1-3. Refer to the DECtalk Software Reference Guide and online help for more information on voice-control in-line commands.
Figure 1-3 In-Line Command Components


Legend


In-line commands are inserted into ASCII text files, begin with a colon, and are always inserted between brackets. (The command here tells DECtalk Software to speak this line at 150 words per minute.) Most commands have parameters (For example, : rate 150  = rate of 150 words per minute.)

Two or more commands can be inserted after each other by enclosing each command within a set of square brackets. (For example, the rate and voice selections are shown here.)

Phonetic spellings of words can be included also.  Phonetic spellings are enclosed within a set of square brackets. (For example, [r'iyliy] for really )   Note: if you want to use phonetic spellings, you must use the [:phoneme arpabet speak on] command to turn on recognition of phonetic spellings.)


	DECtalk Software Dictionaries
DECtalk Software has two pronunciation dictionaries - a large internal (built-in) dictionary and a user-defined dictionary. With the large built-in dictionary, you can easily use many proper names and normally unpronounceable sequences, such as uppercase initials, in their applications. With the user dictionary build tool, you can load application-specific words, or cultural or language-specific terms into the user dictionary. A sample user-dictionary file is installed with the software.
Using the Components
DECtalk Software applications and application-building components are intended for two specific audiences: the application programmer and the general user of text-to-speech applications developed with the DECtalk Software API.
Application Programmer

As a DECtalk Software application programmer, you can use the DECtalk Software programming aids and API components to create applications that use DECtalk Software. These applications can incorporate text files and use DECtalk Software in-line commands as permanent parts of the application.
General User

The general user converts ASCII text files to speech by using an application that incorporates DECtalk Software.  By using an abbreviated set of DECtalk Software in-line commands and the user-defined dictionary, the general user can fine-tune the basic pronunciation and voice characteristics defined in the application.
How It Works 
DECtalk Software converts English language ASCII text into speech output through a speech synthesizer. The two ways to feed text into the speech synthesizer are: 
Through the DECtalk sample application user interface. 
	or
By way of programming calls in your own application program using the DECtalk Software API. 
The flow of the text-to-speech process is shown in Figure 1-4.
Figure 1-4 Flow of the DECtalk Software Text-To-Speech Conversion Process

Legend


Text is selected for processing by DECtalk Software.

A sentence parser breaks the input stream into separate words and locates some clause boundaries (indicated by commas and other punctuation marks as well as by special words loaded in the DECtalk Software internal dictionary). The sentence parser also recognizes and deals with phonemic symbols and commands that you might have added to the input text.
A word parser breaks words into their component parts, dividing words by their final pronounceable form. Strings of text that do not form pronounceable English words are spelled out letter by letter. A number formatter is used if the text contains numerals. The number formatter applies the rules for many common number formats and converts the numbers into English words. 

A dictionary lookup routine searches the pronunciation dictionaries. DECtalk Software has a built-in dictionary of many commonly used words. DECtalk Software also has a user dictionary for programmers and general users that can be filled with words specific to an application. This dictionary and how to load it are described in Chapter 3. 
A letter-to-sound module uses a set of English pronunciation rules to assign phonemic form and lexical stress patterns to words not found in the dictionary. See Chapter 3 for more information on modifying the phonemic form of words, and the DECtalk Software Reference Guide for enhancing special voice qualities, such as emphasis and singing.

A phrase structure module recombines all phonemic output from the dictionary search and other modules. Duration of phonemes and pitch commands is computed for the clause, and appropriate sound variants are selected for those phonemes that can be pronounced in more than one way.
The phoneme-to-voice module processes clauses passed from the phrase structure module and converts them to control signals for the speech synthesizer. This module modifies the clauses by changing the phonemes/allophones into parameters that determine the natural resonant frequencies of the vocal tract (formants), and sound source amplitudes. The control parameters are sent to the speech synthesizer for output.

The DIGITAL speech synthesizer computes a speech waveform with acoustic characteristics that are determined by the synthesizer control commands.


Chapter 2-
Using the Program Applets to Learn DECtalk Software Basics
This chapter introduces the basic operations involved in DECtalk Software voice and program control. If you are a general user, this chapter gives you the information you need to use the Sample, Speak, and User Dictionary Build Tool program applets. If you are an application programmer and not familiar with DECtalk Software, this chapter introduces the basic voice and program control functions used to control DECtalk Software from within an application program. Topics include:
Starting the sample applet and opening a text file
Inserting DECtalk Software in-line commands
Changing voice selections
Editing a text file and changing the speaking rate
Overview of the User Dictionary Build Tool
Building a user dictionary
Using the DECtalk Software Speak applet
Running DECtalk Software from other applications
Using the Say command-line applet
Starting the Sample Applet and Opening a Text File
The fastest way to start learning about DECtalk Software is by using the Sample program applet to convert an ASCII text file to speech. After you start the program applet and speak a text file, you can then learn more about controlling voice characteristics through DECtalk Software in-line commands and the user dictionary, which are covered later in this chapter. 
Figure 2-1 Starting the Sample Applet and Opening a Text File

Table 2-1 Starting the Sample Applet and Opening a Text File
Task/Location

Action
Result
Speaking a File using the Sample Applet
DECtalk Software program group (1)
1.
Double click the Sample applet icon (2)
The Sample applet dialog is displayed. (3)

2.
Pull down the Language menu and select the language of your choice.


3.
Pull down the File menu and select Open. (4)
The Open a File dialog box is displayed. (5)
Open File dialog box (5)
4.
Select the file you want DECtalk Software to speak. (6)
The file is displayed in the Sample applet dialog.(7)
Start button (8) 
5.
Click the start button. 
DECtalk Software starts speaking the file.
Pause and stop buttons (9) (10)
6.
Click the Pause or Stop button as needed. 
DECtalk Software pauses or stops the speaking session. 
Speaking a File using Drag and Drop
File manager with text file name visible (not shown here)
1.
Click the file name, and drag to sample applet dialog or to the minimized DECtalk Software icon. 
The file is spoken.
Inserting DECtalk Software In-Line Commands (Syntax Rules) 
Before you can use DECtalk Software in-line commands to modify speech output, you need to know the proper syntax with which to include those commands into a text file. Figure 2-2 illustrates the rules of DECtalk Software in-line command syntax.  For complete details about DECtalk Software in-line commands, see the DECtalk Software Reference Guide.
Figure 2-2 Rules for DECtalk Software In-Line Command Syntax

Legend
(
Enclose every command within brackets. 
(
Some commands have an alternate command to simplify input.  Here the :name command and its argument Betty can be replaced by the alternate command :nb.
( 
Begin every command with a colon. 
(
Separate each command name and its option or parameter from the command name text by a valid word boundary marker.  The valid word boundary markers are a space and a  tab. A space is used here.
(
Include several options and parameters within the same brackets if the command allows more than one option and parameter.  In this example, the option and parameter grouping modifies the [:dv] command.
(
If you give two conflicting commands, DECtalk Software uses the last command in the sequence. In this example, DECtalk Software uses Paul's voice.
(
If you enable phoneme interpretation by using the [:phoneme arpabet speak on] command, you can include phonetic spelling for text-to-speech synthesis.  The phonetic spelling replaces the actual spelling and is enclosed within brackets.  In this example, the phonetic spelling of word really (r'iyliy) is included.
Additional Syntax Rules
If the value in a [:dv] command is too low, DECtalk Software uses the minimum valid value. If the value is too high, it uses the maximum valid value.
After you enter a command, that command applies to the remaining text until it is overridden by another command. For example, the command [:nk] invokes Kit's voice on all entered text until you enter another voice-selection command.
Invalid commands are ignored. By setting the [:error speak] command, you can receive an audible warning that an invalid command has been entered.
Do not put arpabet parameters within the brackets for another command.
DECtalk Software interprets text between brackets as phonemes only after the [:phoneme arpabet speak on] command is sent to the application. If [:phoneme arpabet speak on] has not been sent, DECtalk Software interprets the brackets and characters between them literally. The [:phoneme arpabet speak off] command must be sent with literal characters if you want to insert brackets in normal text.
If the command [:phoneme arpabet speak on] is set and you forget the right bracket ( ] ), DECtalk Software attempts to interpret all text following the ASCII text as phonemes, skipping over illegal letter combinations. The resulting text sounds garbled. Enter a right bracket to fix this problem.
Changing Speaking Voice
You can change a speaking voice by inserting DECtalk Software commands into the edit window of the Sample program applet dialog or by selecting text and then selecting a different name from the Voice pull-down menu in the Sample program applet dialog. Voice changes made with commands are permanent for the session and remain intact as long as the command remains in the file. Voice changes made from the menu only remain in effect as long as the current DECtalk Software session is running. Each voice selection is inserted into the command [:nXX], where XX is a value representing one of the voices. Table 2-2 lists the names and their corresponding values. 
You can change voices with a command as shown in the following example.
[:nb] Hello. I'm Betty.
You can also change voices in the middle of a sentence.
[:np] This is a demo [:nb] of a sudden change in voice.
If a voice-change request occurs in the middle of a sentence, DECtalk Software automatically pauses. The pause is the equivalent of inserting a comma, or about half a second.
[:np] This is a demo, [:nb] of a sudden change in voice.
Table 2-2 DECtalk Voices and their Associated Values
Name
Value
Name
Value
Paul 
P
Betty 
B
Harry
H
Ursula
U
Frank
F
Wendy
W
Dennis 
D
Rita
R
Kit 
K


Figure 2-3 Changing DECtalk Software Voices

Table 2-3 Changing Voices
Task/Location

Action
Result
Using the Voice menu
Sample applet dialog (1) 
1.
Select the desired speaking voice from the Voice menu. (2)


2.
Press the start button. (3)
The entire file or selected section is spoken.
Using DECtalk Software in-line commands
Sample applet dialog (1)
1.
Insert commands in the text at the points where you want a new voice to take effect.(4)
DECtalk Software changes the speaking voice at the point where you insert commands.
Editing a Text File and Changing the Speaking Rate 
DECtalk Software lets you edit text - select, cut, paste, append other text files - that is displayed in the Sample program applet window and then play segments or all of the edited text.
You can also increase and decrease the rate at which DECtalk Software speaks a file or a section of a file. 
Figure 2-4 Editing a Text File and Changing the Speaking Rate


Table 2-4 Editing a Text File and Changing the Speaking Rate
Task/Location

Action
Result
Editing the text
DECtalk Software Sample applet dialog (1)
1.
Select the range of text you want to edit. (2)


2.
Use cut, copy, paste, and delete selections from the Edit pull-down menu  (3)  to manipulate the selected text.  You can also insert text and DECtalk Software commands by placing the cursor anywhere in the text and typing.


3.
Click on the Start button. (4)
DECtalk Software speaks the edited file in the new, edited format.
Playing selected text
DECtalk Software Sample applet dialog (1)
1.
Select the range of text you want to play.  (2) 


2.
Click on the right mouse 
(MB2 or 3) button.
DECtalk speaks the selected text.
Changing the speaking rate
Sample applet dialog as DECtalk Software is speaking a file (1)
1.
Use the mouse to position the pointer on the rate slider bar. Press the left mouse (MB1) and drag the slider to the left and wait for the speaking voice change to occur. Then drag the slider to the right (5)
The speed at which DECtalk Software speaks the file changes. It increases if you drag to the right and decreases if you drag to the left. The rate in words per minute is displayed to the right of the slider bar. Changes in the speaking rate occur only on a clause boundary after all the previously queued audio has played.
DECtalk Sample applet dialog. (1)
2.
You can also insert DECtalk Software rate commands in the text. (6)
When the text is played, DECtalk changes the rate according to the commands.
Overview of the User Dictionary Build Tool
The User Dictionary Build Tool creates a loadable dictionary file (.dic) from a list of words and their corresponding pronunciations. The dictionary is loaded with a call to the TextToSpeechLoadUserDictionary API call or from the File menu in the Speak program applet.
Use the Translate command to create phonemic translations of words or phrases.
Figure 2-5 Components of the User Dictionary Build Tool

Legend



(1)
Edit Window 
In the edit window, enter word-pronunciation pairs that are not predefined or not pronounced as desired in the DECtalk Software user dictionary.   A word-pronunciation pair is a word, followed by its phonemic spelling enclosed in square brackets.
(2)
File pull-down menu 
Open... A pop-up dialog box that opens up a dictionary definition file (*.tab). 
Close   Closes the dictionary definition file.  If the entries in the edit window have been modified, it pops a dialog box asking if you wish to save changes.
Compile Dictionary   Compiles the current file to a .dic file with the same name. 
Save... A pop-up dialog box that saves the file and calls the compiler to create a dictionary file (*.dic). 
Save as... A pop-up dialog box that lets the user rename the file. This also calls the compiler to create a dictionary file (*.dic). 
Exit   Exits the program, and if the entries in the edit window have been modified, it pops a dialog box asking if you wish to save changes.


(3)
Edit pull-down menu 
Undo    Undo the previous command. 
Cut       Cut the selected region. 
Copy    Copy the selected region. 
Paste    Paste the selected region. 
Delete   Delete the selected region. 
Select All    Select all of the word-pronunciation pairs from the edit window. 
Find... A pop-up dialog box that prompts you to search for selected text.


(4)
Translate menu
Translates selected text into phonemic spelling.


(5)
Language pull-down menu
Lists the DECtalk languages.  Uninstalled languages are grayed out.


(6)
Help pull-down menu 
Selects the online help.


(7)
Pronounce Word button
When clicked, the selected text in the edit window is spoken.  If a word-pronunciation pair is selected, the phonemic pronunciation is used.  If only the word is selected, the currently stored pronunciation is used.
(8)
Previous button
When clicked, the previous word-pronunciation pair in the list is spoken.
(9)
Next button
When clicked, the next word-pronunciation pair in the list is spoken.
Building a User Dictionary
Building a user dictionary is a two-step process. First you create a .tab source file with the User Dictionary Build Tool to define the pronunciation of special words you want to place in the dictionary. 
Figure 2-6 Building a User Dictionary


Table 2-5 Building a User Dictionary
Task/Location

Action
Result
Creating or modifying dictionary entries
DECtalk Software   (1) program group 
1.
Double click on the User Dictionary icon. 
The DECtalk Software Dictionary Builder dialog is displayed. (2)
File pull-down menu (3)
2.
Select Open to open an existing dictionary definition (.tab) file.  
You can also create a new dictionary definition file by entering words directly.
The Open a File dialog box is displayed (not shown).  The file you select is displayed in the edit window.
Edit window
3.
Enter words that are not predefined or pronounced as desired in the DECtalk user dictionary.  DECtalk needs to know both the word and the phonemic spelling you want to associate with it.  
If you know the phonemic spelling, enter it using the following format:
word	[phonemic spelling] 
If you do not know the phonemic spelling, enter the word as it sounds, rather than as it is spelled. 

4.
Select the word and click Translate.  (4) 
For example, the Yugoslavian name Jovicic sounds like
Yoeveecheech
The User Dictionary Build Tool converts what you entered into a phonemic spelling.
The User Dictionary Build Tool converts the name to:
[yx' owv iychiych]

5.
To hear how DECtalk interprets the phonemic spelling, select it, and click Pronounce Word.  (5).
DECtalk speaks the word.

6.
Besides pronunciation, you can also define word usage.
For example, to define the word soda to be equivalent to pop; define water to be pronounced with a New England accent; and take into account the dialectic regional preferences so that the word sub is called a hero, you would use the following pronunciation pairs:
Soda 	[p ' aap]
water 	[w ' aotrr]
subs 	[hx' iyr ow]
Refer to the DECtalk Software Reference Guide or online help (the Reference Tables) for a complete list of phonemic, stress, and syntactic symbols. Both of these sources provide more information on modifying and enhancing pronunciation.
After you have created the .tab source file, you compile it to produce a .dic file. This file is loaded into a DECtalk Software session through the Speak applet or an API call.
Figure 2-7 Saving and Compiling the Dictionary

Table 2-6 Saving and Compiling the Dictionary
Task/Location

Action
Result
Saving and compiling a new dictionary
File pull-down menu (1)
1.
Display the file menu.
If you have not yet given your file a name, choose one of the following
Compile Dictionary  (2)
Save  (3)
Save As...  (4) 
The Save dialog box is displayed in all three cases.  (5)
Save as dialog box
2.
Navigate to the location where you want to save the dictionary session and enter a file name.  (6)
A success message (7) is displayed, indicating that both the text file (in .tab format) and a dictionary file (in .dic format) have been saved.
Saving and compiling an existing dictionary
File pull-down menu (1)
1.
Choose Open from the File menu to open an existing file.
The Open a File dialog box is displayed (not shown).  The dictionary file (.tab file type) you choose is displayed in the text-collection area.

2.
Edit the file as described in Table 2-5.

File pull-down menu (1)
3.
To save the changes you have made to the .tab file without compiling the dictionary,  pull down the File menu (1) and click Save (3).
The changes you have made are saved.
File pull-down menu (1)
4.
To save your changes and compile the dictionary, pull down the File menu (1) and click Compile Dictionary.  (2) 
A success message (7) is displayed and indicates that both the text file (in .tab format) and a dictionary file (in .dic format) have been saved.
Using the DECtalk Software Speak Applet
The Speak program applet demonstrates the DECtalk Software voice set. Each picture * displayed in the Speak dialog represents one of the nine built-in voices. You can select a specific voice by clicking the picture. DECtalk Software then uses the selected voice to speak the contents of a text file displayed in the edit window or from a file you drag and drop from the Windows File Manager into the edit window of the Speak dialog. 
* Note that the faces are cartoon characters when using VGA 16-color mode.
Figure 2-8 Using the DECtalk Software Speak Applet

Table 2-7 Using the DECtalk Speak Application
Task/Location

Action
Result
Editing a text file and playing selected segments
DECtalk program group  (1)
1.
Double-click on the Speak icon.
The Speak applet dialog  (2) displays.
File pull-down menu  (3)
2.
Choose open (4) to choose a text file, or enter text in the edit window.
The Open A File dialog box displays (not shown).  The file you choose is displayed in the edit window
Speak applet dialog (2)
3.
Select the range of text you want to edit or play. (5)


4.
Use the Cut, Paste, and Insert keys or corresponding commands from the Edit menu to manipulate the selected text. For example, cut and paste a single sentence for DECtalk Software to speak.


5.
Click the face of the voice you want to speak. (6)

Edit menu 
6.
Use the (MB2 or 3) right mouse button to speak a selected region or press the Play, Pause, and Stop buttons (7) to play the whole file. 
The edited file is spoken.
Changing the speaking rate
Speak applet dialog while DECtalk Software is speaking a file
1.
Use the mouse to position the pointer on the rate slider button. (8)  Press MB1 and drag the slider to the left and wait for the speaking rate to slow. Then move the slider to the right to increase the rate.
The rate in words per minute displays to the right of the slider bar. Rate changes occur only at a clause boundary and only after all previously queued audio has played.
Loading a User Dictionary
File pull-down menu (3)
1.
Select Load User Dictionary. (9)  Note that the current User Dictionary is defined in the dectalk.ini file and is loaded if available.
The Load Dictionary dialog box (not shown here)  is displayed.

2.
Select the User Dictionary you want to load, and press Enter or click on OK.
That dictionary is loaded and remains in effect until you change the dictionary or end the session.
Saving as a .WAV file
File pull-down menu (3)
1.
Pull down the File menu, select Convert to Wave File. (10)   Select the desired format. (11)   Select a file name for the audio file. 
The Convert to Wave File dialog box is displayed (not shown here).  The text file is saved to the selected file as a standard window .wav file.
Figure 2-9 Highlighting Spoken Text

Task/Location

Action
Result
Highlighting Spoken Text
Speak applet dialog , Edit pull-down menu  (1) 
1.
Click Highlighting. ( 2 )
The Highlighting option is checked.
Speak applet controls.
2.
Click the Start button.  (3 )
As DECtalk speaks the text, each word is highlighted.  (4 )

Running DECtalk Software from Other Applications
You can run DECtalk Software by way of the Text-To-Speech DDE server from any application that supports Dynamic Data Exchange (DDE).  When run from such applications, you can have DECtalk speak any selected text associated with the application.  For example, DECtalk can be "plugged into" Microsoft Word and then used as a proofing tool to read entire files or selected sections from those files.
The following section is an example of how to set up and then run DECtalk Software from within a Microsoft Word document. The steps include:
1)Creating a Word macro and associating it with a file or document template (for Word 6.0)
2)Associating the macro with a button, menu selection, or hot key
3)Launching the DECtalk TTS Server and speaking the text
4)Speaking the text from within the document

Step 1 - Creating a Word Macro and Associating it with a File or Document Template (for Word 7.0)
The first step in running DECtalk Software from a Microsoft Word document is creating the Word macro that links Word and DECtalk through DDE. You only have to create this macro once and associate it with a button, hot key, or menu command. If you make the macro part of a permanent .dot (template) file, DECtalk Software always is available when you edit a document associated with that template.
Figure 2-10 Creating a Word Macro

Table 2-8 Creating a Word Macro
Task/Location

Action
Result
Word dialog
1.
Select Macro from the Tools Menu.  (1)
The Macro dialog box is displayed. (2)

Macro dialog box (2)
2.
Enter the name of the macro you are going to create. (3)

Macro dialog box (2)
3.
Click the Create button. (4)
The Macro creation window is displayed.(5)
Macro creation window (5)
4.
Insert the following macro: (Note: you can open the word.txt  file located in the \DECTALK\ directory, copy it, and paste it into the Word macro.)
Sub MAIN
If AppIsRunning("TTSsrv") = 0 Then
        Shell "TTSSRV.EXE", 0
        rightNow = Now()
        diffTime = 0
        Print "Starting DECtalk Server"
        WaitCursor 1
        While diffTime < 0.00003
            diffTime = Now() - rightNow
        Wend
        WaitCursor 0
        Print " "
      If AppIsRunning("TTSsrv") = 0 Then
      MsgBox("Cannot find TTSSRV.EXE in the path", "Speak", 0)
      Goto FINIS
      End If
End If
      channel = DDEInitiate("TTSserver", "Speak")
      If channel = 0 Then
      MsgBox("Unable to connect to TTSSRV.EXE", "Speak", 0)
      Goto FINIS
  Else
    DDEPoke channel, "Speak", Selection$()
    DDETerminate channel
FINIS:
End Sub
File pull-down menu. 
5.
On the File menu, click Close  (6). Click Yes  (7) when you are asked if you want to keep changes to the macro.
The macro is created.
Step 2 - Associating the Macro with a Toolbar Button
After you create a macro to run DECtalk from within a Microsoft Word document (step 1), you can associate the macro with a button on a toolbar.  You can also associate the macro with a menu selection from one of the pull-down menus or with a power-key combination from the keyboard. This section illustrates how to link the macro with a button on a toolbar. 
Figure 2-11 Associating the Macro with a Toolbar Button

Table 2-9 Associating the Macro with a Toolbar Button
Task/Location

Action
Result
Word dialog 
Tools menu 
1.
Select Customize. 
The Customize dialog box is displayed.  (1)
Customize dialog box.
2.
Select the Toolbars tab and click on Macros  (2).


3.
Locate the macro you created and click the name.  (3)


4.
Place the cursor (arrow) on the macro name, press and hold MB1 and drag the cursor to the toolbar in which you want the DECtalk macro placed.(4)

Word toolbar you select.
5.
An outlined box appears where Word will place the new button. (4)
The Custom Button box is displayed. (5)
Custom button dialog box (5)
6.
Click the button you want to associate with the DECtalk macro.  (6)
The button is outlined.

7.
Click Assign.  (7)
The new button now appears in the gray outlined box in the toolbar.
Step 3 - Launching and Configuring the DECtalk Software Text-to-Speech Server 
After you associate the DECtalk macro with a button (step 2), you must have the TTS (text-to-speech) server running before DECtalk can speak selected sections of text from an application. This section outlines how to start the TTS server and configure the TTS server for speaker selection, User Dictionary selection, and speaking rate. 
The TTS server is launched by the Word macro and is displayed as a small window. You can control the speaking voice and speaking rate from the window pull-down menu.
Applications can access the Text-To-Speech DDE server using the service name "TTSserver". The service topic names are "Speak", "LoadDictionary", and "UnloadDictionary". Each of these topics requires a string that is either text to be spoken (for topic "Speak") or a dictionary file string.
Figure 2-12 Launching and Configuring the DECtalk Server

Table 2-10 Launching and Configuring the DECtalk TTS Server
Task/Location

Action
Result
Microsoft Word editing session
1.
Click the TTS Server icon you created when you associated your Word macro with a toolbar button.  (See Table 2-9 Associating the Macro with a Toolbar Button

The TTS Server dialog is displayed. (2)
TTS Server dialog  (2)
2.
Pull down the Window menu (3)
 and select Configure... (4)
The Change Settings dialog box is displayed. (5)
Change Settings dialog box (5)
3.
Click the desired speaking voice and speaking rate.  (6)


4.
Click on the Test button (7) to preview your selections.


5.
Adjust the settings until you produce the desired result.


6.
Click on OK.  (8)
The selected settings remain in effect as the default settings until they are changed.  
Note: in-line commands in selected text played through the TTS server will override the defaults.
Step 4 - Speaking Text in a Microsoft Word .doc File with the DECtalk TTS Server
After Word launches the TTS server macro and you configure it for the desired speaking voice, speaking rate, and with a user dictionary file (step 3), you can have DECtalk speak selected sections of text from an opened file. 
Figure 2-13 Speaking Text in a Microsoft Word .doc File with the DECtalk Software TTS Server

Table 2-11 Speaking Text in a Microsoft Word .doc file with the DECtalk TTS Server
Task/Location

Action
Result
Microsoft Word dialog  with file opened  (1)  and the TTS Server macro button visible (2)
1.
Select a range of text for DECtalk to speak. (3)


2.
Click the TTS Server button (2)
DECtalk speaks the selected text and displays the TTS Server dialog.  (4)
TTS Server dialog (4)
3.
Click the Pause or Stop button if you want to pause or stop DECtalk as it is speaking the text. 
Note: When you pause the server, all queued text remains queued up even though you deselect it in the Word document. When you stop the server, all queued text is flushed from the DECtalk system.


If the server is not accessible, an error is returned.(5)
Using the Say Command-Line Applet 
The DECtalk Say command-line applet lets you run DECtalk from the Windows command line. Say provides many of the standard DECtalk input and output options available in the Speak and Sample applets and the DECtalk API. 
Command syntax:	SAY [options] [text]

Help Options
-h or -?
Output this file to the console. This option cancels any others on the command line.
Output Options
-w outFile
Convert text to specified .WAV file instead of speaking to the sound device.
-l[t] outFile
Turn on text logging, which logs all input text to a file. This text includes any pre- and post- commands as well as commands sent to DECtalk by the Say program itself. 
Because this is the default logging mode, the 't' immediately following the '-l' is optional.
-ls outFile
Turn on syllable logging, which logs each syllable to a file.
-lp outFile
Turn on phoneme logging, which converts the input text to phonemes. This is useful if you want to get DECtalk to sing. You convert the text to phonemes and then insert the tone commands into the phoneme file.
If no output options are specified, Say sends its output to the installed sound device, usually a sound card. Only one output option can be specified; if you specify more than one, the last one on the command line is used
Input Options
-pre preText
Text to be passed to DECtalk before the normal input. The prefix text is "forced" out before the input text is read.
-post postText
Text to be passed to DECtalk after the normal input. 
This is useful for passing terminating commands to DECtalk that normally are not part of the input. If the postfix text has spaces, it must be enclosed in quotes. An example is "[:phoneme off]" or "The End".
The "normal" input is "forced" out before the postfix text is read.
text
Text appearing on the command line is spoken. The text to be spoken can come either from the standard input or from the command line.
Anything on the command line that is not an option is interpreted as text, as will anything following it on the command line. In other words, text to be spoken must appear on the command line after all options.
If the *first* word in the text has a dash (-) or slash (/) as its first character, you must precede it with another dash or slash. For example, to tell DECtalk to say the number -123, you would type the command
SAY --123
This is necessary to avoid having SAY interpret the number as a command line option. If you embed DECtalk commands into your text, you must enclose them in quotes if they contain spaces.
This is because SAY treats each space-delimited command-line argument as a separate "word", while DECtalk commands must be processed as single "words" by the SAY program.
If no text is specified, SAY takes its input from the standard input. For example, you could have SAY speak a directory listing in Betty's voice by typing
DIR | SAY -pre "[:nb]"
or you could just type the command 
SAY
and then enter text at the console. In this case, SAY speaks each line after you press Enter, and exits after you press Ctrl/x. If you want SAY to take its input from a file, use file redirection as in the following example, which reads the file foo.txt  in Harry's voice:
SAY -pre "[:nh]" < FOO.TXT
Dictionary Options
-d userDict
Loads the specified User Dictionary before speaking. This dictionary is loaded in place of any default User Dictionary determined by DECtalk.



Chapter 3 -
Introduction to the DECtalk Software API

This chapter introduces the DECtalk Software DIGITAL Speech API (DAPI), also known as the DECtalk Software API and describes how to write application programs using the DECtalk Software API. This API is designed to be extensible for future text-to-speech growth while still being easy to use. The current DECtalk Software implementation supports multiple instances of DECtalk Software per processor.
The API calls give you a flexible method for manipulating the various parameters of DECtalk Software functionality from within your application. These calls perform a wide range of tasks associated with the text-to-speech system and are listed by functionality in Table 3-1.
Note
In addition to the DAPI, DECtalk Software supports the Microsoft Speech API (SAPI). DECtalk Software for Windows now supports most of SAPI. This allows DECtalk Software to work as an OLE server in any OLE application environment. The information about SAPI is available in the Microsoft Developer Network (MSDN) CD-ROM Level II, January 1996 edition under the Microsoft Software Development Kit (SDK). For more information or documentation on SAPI, contact Microsoft.

Table 3-1 Text-To-Speech Calls by Category
Calls
Purpose
Core API 

TextToSpeechStartup()IDH_TextToSpeechStartup  
Initializes and starts up text-to-speech system.
In Windows, the user defines the window handle to which post messages can be sent.
In DIGITAL UNIX, the user defines the callback routine.
The calling application can then receive index marks, memory buffers, or status information through the above operating system dependent mechanism.
TextToSpeechStartupEx()IDH_TextToSpeechStartup  
Initializes and starts up text-to-speech system. The user defines the callback routine that can be called when index marks, memory buffers, or status information needs to be sent to the calling application.
TextToSpeechSpeak()IDH_TextToSpeechSpeak  
Speaks text from a buffer.
TextToSpeechShutdown()IDH_TextToSpeechShutdown  
Shuts down text-to-speech system.
Audio Output Control 

TextToSpeechPause()
Pauses output.
TextToSpeechResume()
Resumes output.
TextToSpeechReset()
Text-to-speech system is purged and output stopped.
Blocking Synchronization 

TextToSpeechSync()IDH_TextToSpeechSync  
Synchronizes to the text stream.
Control and Status 

TextToSpeechSetSpeaker()IDH_TextToSpeechSetSpeaker 
Selects one of nine speaking voices.
TextToSpeechGetSpeaker()IDH_TextToSpeechGetSpeaker  
Returns the last speaking voice to have spoken.
TextToSpeechSetRate()IDH_TextToSpeechSetRate  
Sets the speaking rate of the text-to-speech system. 
TextToSpeechGetRate()IDH_TextToSpeechGetRate  
Returns the speaking rate of the text-to-speech system.
TextToSpeechSetLanguage()IDH_TextToSpeechSetLanguage  
Sets the language to be used. 
TextToSpeechGetLanguage()IDH_TextToSpeechGetLanguage  
Returns the language in use.
TextToSpeechGetStatus()IDH_TextToSpeechGetStatus  
Gets status of text-to-speech system.
TextToSpeechGetCaps()IDH_TextToSpeechGetCaps  
Retrieves the capabilities of the text-to-speech system.
Special Text-To-Speech Mode 

TextToSpeechOpenWaveOutFile()IDH_TextToSpeechOpenWaveOutFile  
Opens a file for output. TextToSpeechSpeak() writes audio data in wave format to this file.
TextToSpeechCloseWaveOutFile()IDH_TextToSpeechCloseWaveOutFil  
Closes the specified wave file and returns the text-to-speech system to its startup state.
TextToSpeechOpenLogFile()IDH_TextToSpeechOpenLog 
Opens a log file. TextToSpeechSpeak() writes text, phonemes, or syllables to this file.
TextToSpeechCloseLogFile()IDH_TextToSpeechCloseLog  
Closes the specified log file and returns the text-to-speech system to its startup state.
TextToSpeechOpenInMemory()IDH_TextToSpeechOpenInMemory  
Produces buffered speech samples in wave format whenever TextToSpeechSpeak() function is called. Calling application is notified when memory buffer is filled.
TextToSpeechCloseInMemory()IDH_TextToSpeechCloseInMemory  
Returns the text-to-speech system to its startup state.
TextToSpeechAddBuffer()IDH_TextToSpeechAddBuffer 
Adds a shared-memory buffer allocated by the calling application to the memory buffer list.
TextToSpeechReturnBuffer()IDH_TextToSpeechReturnBuffer  
Returns the current shared-memory buffer.
Loading and Unloading a User Dictionary 

TextToSpeechLoadUserDictionary()IDH_TextToSpeechLoadUserDiction  
Loads User Dictionary.
TextToSpeechUnloadUserDictionary()IDH_TextToSpeechUnloadUserDicti 
Unloads User Dictionary.

The Core API Calls
The core DECtalk Software API calls are: 
TextToSpeechStartup and TextToSpeechStartupEx, known as the startup functions, allocate system resources.
TextToSpeechStartup, which is operating system dependent, has different calling parameters. On UNIX, a callback routine may be defined; on Windows, a window handle can be passed to the TextToSpeechStartup call.
TextToSpeechStartupEx works the same on both the UNIX and Windows platforms and allows a callback routine to be passed.
TextToSpeechSpeak queues text to the system.
TextToSpeechShutdown returns all system resources allocated by the startup functions.
The simplest application might only use these functions.
TextToSpeechSpeak 
The TextToSpeechSpeak call is used to pass a null terminated string of characters to the text-to-speech system. The system queues all characters up to the null character. If the TTS_FORCE flag is not used in the call to this function, then the queued characters are seamlessly concatenated with previously queued characters. The TTS_FORCE flag is used to force a string of characters to be spoken even though the string might not complete a clause. For example: 
TextToSpeechSpeak( phTTS, "This will be spoken. ", TTS_NORMAL); 
This text is spoken immediately by the system because it is terminated by a period and a space. These last two characters are one way to create a clause boundary. 
TextToSpeechSpeak( phTTS, "This will be spok", TTS_NORMAL );
This produces output only after the following line of code executes to complete the phrase. 
TextToSpeechSpeak( phTTS, "en. ", TTS_NORMAL );
Finally, a nonphrase string can be forced to be spoken by using the TTS_FORCE flag. 
TextToSpeechSpeak( phTTS, "This will be spok", TTS_FORCE );
Note that the word spoken is not pronounced correctly in this case even if the final characters, en are queued immediately afterward. 
The TTS_FORCE flag causes the previous line to be spoken before taking any subsequently queued characters into account. 
Important Text-Queuing Information
It is important that all sentences are separated with a space, new line, or line feed character. To make sure of this, it is recommended that a space character is routinely included after the final punctuation in a sentence. An example of what happens without this is shown below:
TextToSpeechSpeak( phTTS, "They are tired.", TTS_NORMAL );
TextToSpeechSpeak( phTTS, "I am Cold.", TTS_NORMAL );
Because there is no space, the text-to-speech system processes the following string:
"They are tired.I am Cold."
 The string, tired.I, will be pronounced incorrectly because the system treats it as one item instead of two words.
Clause-Based Synthesis
DECtalk Software processes all text on a clause basis. A clause is defined as a group of words terminated by a period, question mark, exclamation point, question mark, semicolon, or a colon and followed by white space. If you send DECtalk Software a string of text with NO terminator, it goes into an infinite loop waiting for a clause terminator. The Sync in-line command can be used to complete a clause without using a terminator.
Callback Routines and Window Procedures
After TextToSpeechSpeak  is called, the text-to-speech system can notify the calling application in one of two ways. On DIGITAL UNIX, the information can be sent back through the callback routine defined in the startup function. On Windows, the information is passed back through window messages or callback routines, depending on which startup function was called. See the DECtalk Software Reference Guide for more information on startup functions. 
Callback routines should not call TextToSpeech…() calls.  If callback routines call TextToSpeech…() calls, an application crash may occur in the application calling DECtalk Software.
Both the window procedures and the callback routines have a message type and the WPARAM and the LPARM parameters. There are three message types defined: one for error and status messages, one for index marks, and one to return memory buffers when using the TextToSpeechOpenInMemory call. Based on the message type, the WPARAM and the LPARAM parameters contain specific information.
Error Messages
The message type for error and status messages is defined as
For Callback Routine:
   uiID_Error_Message  = TTS_MSG_STATUS;

For Window Messages:
   uiID_Error_Message = 
	RegisterWindowMessage("DECtalkErrorMessage"); 

One of the error codes listed below, defined in ttsapi.h, is contained in the WPARAM parameter. The LPARAM parameter contains a value of type MMRESULT. The values can be found in the ttsapi.h file.
Parameter
#define ERROR_IN_AUDIO_WRITE
#define ERROR_OPENING_WAVE_OUTPUT_FILE
#define ERROR_GETTING_DEVICE_CAPABILITIES
#define ERROR_READING_DICTIONARY
#define ERROR_WRITING_FILE
#define ERROR_ALLOCATING_INDEX_MARK_MEMORY
#define ERROR_OPENING_WAVE_FILE
#define ERROR_BAD_WAVE_FILE_FORMAT
#define ERROR_UNSUPPORTED_WAVE_FILE_FORMAT
#define ERROR_UNSUPPORTED_WAVE_AUDIO_FORMAT
#define ERROR_READING_WAVE_FILE
#define TTS_AUDIO_START
#define TTS_AUDIO_STOP

Index Mark Messages
The message type for index marks is defined as
For Callback Routine:
   uiID_Index_Message  = TTS_MSG_INDEX_MARK;

For Window Messages:
   uiID_Index_Message = 
	RegisterWindowMessage("DECtalkIndexMessage"); 

The LPARAM parameter contains the index mark value. Note that the index mark information can also be returned in the Buffer Message. This happens when the text-to-speech system is in the speech-to-memory mode, due to the TextToSpeechOpenInMemory call. See the Special Text-To-Speech Modes section for more information.
Buffer Messages
The message type for buffered speech samples is defined as:
For Callback Routines:
   uiID_Buffer_Message  = TTS_MSG_BUFFER;
For Window Messages:
   uiID_Buffer_Message = 
	RegisterWindowMessage("DECtalkBufferMessage");
A pointer to the returned memory buffer is contained in the LPARAM parameter. Additional information about index marks and phonemes may also be returned here. See the Return of Memory Buffer section for additional details on what information gets returned. 
Callback Routine Example
VOID main()
{
	LPTTS_HANDLE_TAG  phTTS;
	TextToSpeechStartupEx(&phTTS, WAVE_MAPPER,REPORT_OPEN_ERROR, Callback, 0);
}
VOID Callback(LONG lParam1, LONG lParam2, DWORD dwCallbackParameter, UINT uiMsg)
{
	if (uiMsg == TTS_MSG_STATUS)
	{
		// lParam1 contains error code
		// lParam2 contains value of MMRESULT
	}
	else if (uiMsg == TTS_MSG_INDEX_MARK)
	{
		// lParam2 contains index mark
	}
	else if (uiMsg == TTS_MSG_BUFFER)
	{
		// lParam2 contains Pointer to buffer
	}
} 

Window Procedure Example 
static UINT uiID_Error_Message = 0;
static UNIT uiID_Buffer_Message = 0;
static UNIT uiID_Index_Message = 0;

// Window Procedure
VOID MyWndProc(LONG lParam1, LONG lParam2, DWORD dwCallbackParameter, UINT uiMsg)
{
	if (uiMsg == uiID_Error_Message)
	{
		// lParam1 contains error code
		// lParam2 contains value of MMRESULT
	}
	else if (uiMsg == uiID_Index_Message)
	{
		// lParam2 contains index mark
	}
	else if (uiMsg == uiID_Buffer_Message)
	{
		// lParam2 contains Pointer to buffer
	}
} 

VOID main()
{
	LPTTS_HANDLE_TAG  phTTS;
	TextToSpeechStartupEx(&phTTS, WAVE_MAPPER, REPORT_OPEN_ERROR, MyWndProc, 0);

	// Registering messages to report DECtalk asynchronous events
	uiID_Error_Message = RegisterWindowMessage("DECtalkErrorMessage");
	
	// Callback message is registered indicating index marks
	uiID_Index_Message = RegisterWindowMessage("DECtalkIndexMessage");
	
	// Callback message is registered indicating DECtalk has filled up an audio buffer
	uiID_Buffer_Message = RegisterWindowMessage("DECtalkBufferMessage");
}







Audio Output Control Calls
The audio output control calls pause the audio output, resume output after pausing, and reset the text-to-speech system. An application can control speech output using TextToSpeechPause, TextToSpeechResume, and the TextToSpeechReset. A reset discards all queued text and stops and discards all queued audio. If the application has called the TextToSpeechOpenInMemory call to store speech samples in memory, a reset causes all buffers to be returned to the application.
Blocking Synchronization Call
The TextToSpeechSync call is provided to block until all text previously queued by the TextToSpeechSpeak call is spoken. After the blocking synchronization function is called, there is no way to abort until all text is processed. This could take hours if there is a great deal of text queued. Non-blocking synchronization can be provided using the Index Mark in-line command.
Control and Status Calls
The control and status calls described in Table 3-2 provide additional information for the text-to-speech system.
Table 3-2 API Control and Status Calls
Call
Description
TextToSpeechSetSpeaker() 
Sets the speaker's voice which becomes active at the next clause boundary. 
TextToSpeechGetSpeaker() 
Returns the value of the last speaker to have spoken.
TextToSpeechSetRate() 
Sets the speaking rate, which becomes active at the next clause boundary. 
TextToSpeechGetRate() 
Gets the speaking rate.
TextToSpeechSetLanguage() 
Sets the text-to-speech system language. Refer to the ttsapi.h file for a list of valid languages, e.g. TTS_AMERICAN_ENGLISH.
TextToSpeechGetLanguage() 
Returns the current text-to-speech system language.
TextToSpeechGetStatus() 
Returns various text-to-speech system parameters, such as the number of characters in the text pipe, the ID of the wave output device, and a Boolean value that indicates whether the text-to-speech system is currently speaking or silent.
TextToSpeechGetCaps() 
Returns the capabilities of the text-to-speech system, which includes the version number of the system, the number of speakers, the maximum and minimum speaking rate, and the supported languages. 
Special Text-To-Speech Modes
After the startup function is called by an application, it then can call TextToSpeechSpeak to speak text. This converts text to speech and sends the speech sample to an audio device depending on the setting of the dwFlags field in the startup routine. 
The DECtalk Software API also provides alternatives for the speech samples by allowing the user to select one of the special text-to-speech modes. The special text-to-speech mode calls allow the speech samples to be written to a Wave file; converted to text, phonemes, or syllables and stored in a log file; or saved in memory buffers to be passed back to the calling application. Each mode-switch call has a corresponding call to return the text-to-speech system to the startup state. These calls are listed below.
Table 3-3 Special Text-To-Speech Modes
Open Function
 Mode
 Close Function
TextToSpeechOpenWaveOutFile()
wave-file
TextToSpeechCloseWaveOutFile()
TextToSpeechOpenLogFile()
log-file
TextToSpeechCloseLogFile()
TextToSpeechOpenInMemory()
speech-to-memory
TextToSpeechCloseInMemory()
The text-to-speech system must be in the startup state before calling any of the Open functions listed in Table 3-3. The corresponding Close calls return the system to the startup state.
Wave-File Mode
After calling the startup function, an application can call TextToSpeechOpenWaveOutFile. This call blocks until all previously queued text is processed. After the call returns, all text subsequently queued by the TextToSpeechSpeak call is converted to speech samples and written into a wave file. The TextToSpeechCloseWaveOutFile call blocks until the speech from all previously queued text is written to the file.
Log-File Mode
After calling the startup function, an application can call the TextToSpeechOpenLogFile. This call blocks until all previously queued text is processed. After the call returns, all text subsequently queued by the startup function is written to a log file as text, phonemes, or syllables. The phonemes and syllables are written using the arpabet phoneme alphabet. The TextToSpeechCloseLogFile call terminates phoneme logging and blocks until the speech from all previously queued text is processed.
Speech-To-Memory Mode
After calling the startup function, an application can call TextToSpeechOpenInMemory. This call blocks until all previously queued text is processed. After the call returns, all text subsequently queued by the TextToSpeechSpeak call is converted to speech and stored in the memory buffers supplied by the TextToSpeechAddBuffer call. The TextToSpeechCloseInMemory call blocks until the speech from all previously queued text is processed.
When a memory buffer is completed, the buffer is returned to the calling application. See the Callback Routines and Window Procedures section for more information about passing data back to the calling application.
Initialization of Memory Buffers
A memory buffer is a TTS_BUFFER_T structure. This structure and the elements of its lpData, lpPhonemeArray, and lpIndexArray members must be allocated. (Note that these last two pointers can be optionally set to NULL if they are not used by the application.) 
The lpData element points to a byte array. The dwMaximumBufferLength must be set to the length of this array. 
If the lpPhonemeArray element is set to NULL, then no phonemes are returned. Otherwise, the lpPhonemeArray element must point to an application-allocated array of structures of type TTS_PHONEME_T. The length of this array must be copied into the dwMaximumNumberOfPhonemeChanges element. 
If the lpIndexArray element is set to NULL, then no index marks are returned. Otherwise, the lpIndexArray element must point to an application-allocated array of structures of type TTS_INDEX_T. The length of this array must be copied into the dwMaximumNumberOfIndexChanges element.
TTS_BUFFER_T Structure (ttsapi.h)
This structure is allocated by the calling application and passed to the text-to-speech system through the TextToSpeechAddBuffer call.
typedef struct TTS_BUFFER_TAG 
{ 
   LPSTR lpData;
   LPTTS_PHONEME_T  lpPhonemeArray;
   LPTTS_INDEX_T  lpIndexArray;
   DWORD dwMaximumBufferLength;
   DWORD dwMaximumNumberOfPhonemeChanges;
   DWORD dwMaximumNumberOfIndexMarks;
   DWORD dwBufferLength;
   DWORD dwNumberOfPhonemeChanges;
   DWORD dwNumberOfIndexMarks;
   DWORD dwReserved; 
} TTS_BUFFER_T;

typedef TTS_BUFFER_T * LPTTS_BUFFER_T;
TTS_PHONEME_T Structure (ttsapi.h)
This structure is used to store phoneme, stress, and syntactic codes of the speech sample. Refer to the Phonemic Symbols and the Stress and Syntactic Symbols sections in the DECtalk Software Reference Guide for a detailed list of these symbols.
typedef struct TTS_PHONEME_TAG 
{ 
   // Phoneme, Stress or Syntactic symbols
   DWORD dwPhoneme; 

   // Indicates which sample in the memory buffer
   // corresponds to the phoneme symbol
   DWORD dwPhonemeSampleNumber; 

   // Duration of phoneme symbol in milliseconds
   DWORD dwPhonemeDuration

   DWORD dwReserved;
} TTS_PHONEME_T;
typedef TTS_PHONEME_T * LPTTS_PHONEME_T;
TTS_INDEX_T Structure (ttsapi.h)
This structure is used to store index marks defined by the Index Mark in-line command. Refer to the Index Mark in-line command in the DECtalk Software Reference Guide for information on the syntax and uses of Index Marks.
typedef struct TTS_INDEX_TAG 
{ 
   // Index Mark value
   DWORD dwIndexValue;

   // Indicates which sample in the memory buffer
   // corresponds to the index mark value
   DWORD dwIndexSampleNumber;

   DWORD dwReserved;
} TTS_INDEX_T; 
typedef TTS_INDEX_T * LPTTS_INDEX_T;
TTS_CAPS_T Structure (ttsapi.h)
This structure is used by the TextToSpeechGetCaps call to store language and proper name support, sample rate, minimum and maximum speaking rate, number of predefined speaking voices, character-set supported, and version number.
typedef struct TTS_CAPS_TAG
  {  
     DWORD dwNumberOfLanguages;
     LPLANGUAGE_PARAMS_T  lpLanguageParamsArray;
     DWORD dwSampleRate;
     DWORD dwMinimumSpeakingRate;
     DWORD dwMaximumSpeakingRate;
     DWORD dwNumberOfPredefinedSpeakers;
     DWORD dwCharacterSet;
     DWORD Version;
  } TTS_CAPS_T;
  typedef TTS_CAPS_T * LPTTS_CAPS_T;
The *lpLanguageParamsArray element is a pointer to an array of structures of type LANGUAGE_PARAMS_T. The "dwNumberOfLanguages" element contains the number of elements in this array. The dwLanguage element of each structure in this array equals one of the supported languages. Currently only the following value will be returned in the dwLanguage element.
TTS_AMERICAN_ENGLISH 
The dwLanguageAttributes element of each structure can contain the following constants defined in include file ttsapi.h:
PROPER_NAME_PRONUNCIATION 
Return of Memory Buffers
When the memory buffer is completed, the memory buffer is returned to the calling application. A memory buffer is considered completed when any one of the following occur:
The memory buffer, which is pointed to by the lpData field, is filled.
The phoneme array is filled. Refer to the American English Phoneme Codes in the DECtalk Software Reference Guide for more information on the phoneme codes.
The index mark array is filled. Refer to the Index Mark for Speech Status section in the DECtalk Software Reference Guide for more information on the index marks.
A TTS_FORCE is used in the call to TextToSpeechSpeak.
The application must not modify any buffer passed to the text-to-speech system by the TextToSpeechAddBuffer call until the buffer is returned from the text-to-speech system to the calling application. The application then owns the buffer. If no buffers are available, the system blocks. If the application is processing relatively long passages of text, it is recommended that the application queues several buffers and then requeues each buffer after finishing with it so that the system is not idle.
A call to TextToSpeechReset returns all buffers to the application. The TextToSpeechReturnBuffer call forces the return of the current memory buffer, whether it is filled or not. This call might not be required by most applications. It is included so an application can obtain the last buffer without forcing that buffer to be sent with the TTS_FORCE command in the TextToSpeechSpeak call.
When the memory buffer, a TTS_BUFFER_T structure, is returned to the calling application, it contains the following return values:
Parameter
Value
dwBufferLength
Number of bytes of audio samples.
lpData
Pointer to the audio sample data.
dwNumberOfPhonemeChanges
Number of phoneme changes.
lpPhonemeArray
Pointer to the phoneme information.
dwNumberOfIndexMarks
Number of index marks. 
lpIndexArray
Pointer to the index mark information.

The index and phoneme arrays each contain a time stamp in the form of a sample number. This sample number is initialized at zero at startup and after each call to TextToSpeechReset. The phoneme array also contains the current phoneme duration in frames. Each frame is approximately 6.4 milliseconds.

Dictionary Calls (UNIX only)
The DECtalk Software comes with a main dictionary, which is a compiled list of words and their associated phonemic interpretation. This main dictionary is loaded during the startup function. In addition to a main dictionary, users can create their own user dictionaries and access them using the TextToSpeechLoadUserDictionary and TextToSpeechUnloadUserDictionary calls.
Creating a User Dictionary
DECtalk Software comes with two dictionary applets. Both help the user to create their own user dictionary, which can be loaded at startup time or while the text-to-speech system is active.
Application
Location
Comments
userdict
/usr/ucb/userdict
Compiles a user dictionary from a file containing both the word and its phonemic pronunciation.
windict
/usr/ucb/windict
Application that has a graphical user interface and can: 
Pronounce words
Translate words into their phonemic symbols
Compile a user dictionary from a list of words and their phonemic symbols

Loading the Main Dictionary 
The startup function loads the DECtalk Software main pronunciation dictionary. 
 /usr/lib/dtk/dectalk.dic
If the dictionary file cannot be found or is loaded improperly, then the startup function returns an error.
Loading the User Dictionary 
The startup function attempts to load the DECtalk Software user pronunciation dictionary from the user's home directory. 
$HOME/user.dic
If the dictionary file is found but can not be loaded, then the startup function returns an error.
After the startup function has completed successfully, the user can load and unload user dictionaries using the TextToSpeechLoadUserDictionary and TextToSpeechUnloadUserDictionary calls.
Dictionary Calls (Windows only)
The DECtalk Software comes with a main dictionary, which is a compiled list of words and their associated phonemic interpretation. This main dictionary is loaded during the startup function call. In addition to a main dictionary, users can create their own user dictionaries and access them using the TextToSpeechLoadUserDictionary and TextToSpeechUnloadUserDictionary calls.
Creating a User Dictionary
DECtalk Software comes with the following files, which help the user to create their own user dictionary, which can be loaded at startup time or while the text-to-speech system is active.
File Name
Location
Comments
windic.exe
\Program Files\DECtalk
Application that has a graphical user interface and can: 
Pronounce words
Translate words into their phonemic symbols
Compile a user dictionary from a list of words and their phonemic symbols
user.tab
\Program Files\DECtalk
Source file used by windic.exe to create the user dictionary.

Loading the Main Dictionary
The TextToSpeechStartup call attempts to find the entry for the DECtalk Software main pronunciation dictionary in the registry at:
	REGISTRY KEY:  
	HKEY_LOCAL_MACHINE 	\SOFTWARE\DigitalEquipmentCorporation\DECtalk\vers\language_code
	Value: MainDict
and is set to value: 
	[user selected dir]\system\dectalk.dic
Replace vers using the format x.xx in the path designation with the current version number for the DECtalk Software, such as 4.50.
Replace language_code with the designation for the appropriate language, such as US for United States English, GR for German, LA for Latin American Spanish, or UK for United Kingdom English. 
If the MainDict entry cannot be found, then the TextToSpeechStartup call defaults to looking in the application's default directory for DECTALK.DIC to be loaded as the main pronunciation dictionary. 
If the main pronunciation dictionary fails to be loaded, then the TextToSpeechStartup call returns a value of MMSYSERR_ERROR.
Loading the User Dictionary
The TextToSpeechStartup call attempts to find the entry for the DECtalk Software user pronunciation dictionary in the registry at:
REGISTRY KEY:  
HKEY_CURRENT_USER \Software\DigitalEquipmentCorporation\DECtalk\vers\language_code
Value: UserDict
and is set to value: 
[user selected dir]\user.dic
Replace vers using the format x.xx in the path designation with the current version number for the DECtalk Software, such as 4.50.
Replace language_code with the designation for the appropriate language, such as US for United States English, GR for German, LA for Latin American Spanish, or UK for United Kingdom English. 
If the UserDict entry cannot be found, then the TextToSpeechStartup call defaults to looking in the application default directory for user.dic to be loaded as the user pronunciation dictionary. 
If the user pronunciation dictionary fails to be loaded, then the TextToSpeechStartup call returns a value of MMSYSERR_ERROR.
Sample Programs (UNIX only)
Some applets are included with DECtalk Software. These sample applications are included to demonstrate the use of DECtalk Software APIs. These sources can be used as templates for other applications that you might want to develop. 
Some of the applets demonstrate the DECtalk Software API extension to the multimedia API specified in the Multimedia Services for DIGITAL UNIX product. These applets are the ones that play back speech samples to an audio device. These applets are built using the libttsmme.so shared library.
Other applets demonstrate the DECtalk Software API that does not include the multimedia extensions. These applets are those that do not require any audio devices. These applets can be built using the libtts.so shared library.
Sources to these programs can be found in: 
/usr/examples/dtk/dtsamples 
The samples and a brief description are listed below. 
Applet
Description
xmsay
Demonstrates the use of DECtalk Software APIs in the Motif windows environment. 
say
This is an example of converting text into speech samples that are sent to an audio device.
dtmemory
This is an example of converting text into speech samples stored in memory buffers.
aclock
Announces the time at specified intervals.

Building Sample Programs
Sample programs can be created from the sources provided in /usr/examples/dtk/dtsamples. This section describes the procedure for building the sample programs. Before proceeding make sure that the DECtalk Software development kit has been installed. See the DECtalk™ Software Installation Guide for more information on different components of DECtalk Software. 
1.Create a local directory that you want to build the sample programs in. 
2.Copy all the files in /usr/examples/dtk/dtsamples into the directory that you just created. 
3.Generate a Makefile from the Imakefile by typing:
usr/bin/X11/xmkmf
4.Compile and link the sample application programs by typing the following while still in the directory that you just created: 
make all 
5.After the make program completes successfully, the sample programs are ready to run.
In addition to the sample programs you will also find some demo text files in your directory. These files demonstrate some of the DECtalk Software capabilities. 
Header Files 
DECtalk Software provides header files that contain all the public data-structure definitions that the DECtalk Software API references. They are ttsapi.h, dtmmedefs.h, and LL_xx_PH.H, where xx is the language abbreviation for each of the supported languages. When DECtalk Software is installed, these files are in /usr/include/dtk. 
ttsapi.h contains definitions of constants used in the DECtalk Software API calls, data structures that define the buffers that DECtalk Software returns, and the API function prototype definitions. 
dtmmedefs.h contains the basic data structure definitions used by DECtalk Software. It also contains definitions of error codes and audio formats. This file enables you to compile, link, and run certain DECtalk Software programs even if Multimedia Services for DIGITAL UNIX is not installed. Specifically, if you are writing an application program that does not use the audio drivers but want to use DECtalk Software to produce synthesized speech buffers using the TextToSpeechOpenInMemory call, then using dtmmedefs.h circumvents the requirement for Multimedia Services for DIGITAL UNIX. 
Header files for the phoneme codes are, as follows:
L_US_PH.H
English (United States)
L_GR_PH.H
German
L_LA_PH.H
Latin American Spanish
L_UK_PH.H
English (United Kingdom)


Shareable Libraries 
DECtalk Software APIs are available to programmers in two shareable libraries.
libtts.so contains device independent DECtalk Software routines. 
libttsmme.so contains the DECtalk Software library that requires Multimedia Services for DIGITAL UNIX. 
As in the case of the header files, if you want to use DECtalk Software to write an application that produces buffers of synthesized speech, then the program is linked with the libtts shared library. If, on the other hand, you want to use the Multimedia Services for DIGITAl UNIX to communicate with the audio subsystem then the application has to be linked with the libttsmme shared library. 
Sample Programs (Windows only)
Sample programs include:
dtsample
This is an example of a basic Windowed editor with integrated text to speech.
say
This is an example of a command-line program using DECtalk Software.
dtmemory
This is an example of synthesis into memory buffers.
ttstst
This is a sample program to demonstrate the Microsoft speech API interfaces supported by the DECtalk Software speech engine.


The sample programs are furnished as examples of simple Windows applications that can be built using the DECtalk Software API. The source code for the sample programs are placed in the root directory, \DECTALK\SAMPLE\, during the installation. These programs include the API definition file ttsapi.h and are linked with dectalk.lib. 
Using the Software Development Kit (the Win32 SDK must be installed), bring up a Windows console window.
Set your default directory to the \DECTALK\SAMPLE\DTSAMPLE directory.
Enter nmake
This procedure produces the dtsample.exe executable file. This file can be executed at the Windows console window or the File Manager. 
The dtsample program demonstrates most of the DECtalk Software API calls. Any application can call any of the API calls by including the ttsapi header file (ttsapi.h) and linking with the DECtalk Software library (dectalk.lib) as long as the associated dll (dectalk.dll) is present. The dectalk.dll must be installed and the dictionary dectalk.dic must be in the dictionary path in the registry or in the local directory.


Chapter 4 -
How to do Multi-Language Programming
Multi-language programming using DECtalk Software requires loading a DECtalk language, selecting a loaded language for a program thread, starting a TTS instance, closing the program thread, and closing that language. Swapping a language requires shutting down and closing the thread and the language selector. You can load as many languages as you want during the execution of your program as well as select two or more languages concurrently. The following steps summarize the methodology to start, select, and close a single language. 
Note
You must start and select a language before using DECtalk Software to speak.
The basic elements of multi-language programming are presented in the sections as follows:
Starting a Language
Selecting a Language
Closing a Language
Multi-Language Programming Example
Starting a Language
To start a DECtalk languageError! Reference source not found., use the TextToSpeechStartLang call to pass the call the two-letter name of the language you want to load.  After the language is loaded, you receive a handle to that language.  If the language is already loaded, you get the previously loaded handle to that language as the return value.  The same handle is used for all instances of a language per run.  On failure, you receive a handle with the TTS_LANG_ERROR bit set as defined in TTSFEAT.H.
Example:
TextToSpeechStartLang ("uk")
 Selecting a Language
Before a call can be made to any of the standard DAPI functions, and after you have the handle to a language, you must select the language.  This is accomplished through the TextToSpeechSelectLang call.  You must select the language before each call to any DAPI function that does not take in a valid LPTTS_HANDLE_T handle. The first parameter to TextToSpeechSelectLang must be NULL. The following parameter is the handle retrieved from TextToSpeechStartLang.  The return value from TextToSpeechSelectLang is a Boolean with TRUE to signify success and FALSE to signify failure.
Example:
TextToSpeechSelectLang (NULL,UKhandle)
Closing a Language
After you close your program threads, use the TextToSpeechCloseLang call to close the language.  This call takes in the two-character language name of the language to release and attempts to release the language and its associated files. If other threads are still using the language, the TextToSpeechCloseLang call reduces the instance counter by one for that language.  The file is free when all language hooks are freed.
Example:
TextToSpeechCloseLang ("uk")
Example
This example shows DECtalk ML allocating English (us), creating a thread, destroying the thread, and finally closing the language.
void sample(void) {
	unsigned long int UShandle;
	MMRESULT result;
	LPTTS_HANDLE_T phTTS;

	UShandle = TextToSpeechStartLang("us");
	if (UShandle & TTS_LANG_ERROR) {
		printf("Error loading US English\n");
		exit(1);
	}
	if (TextToSpeechSelectLang(NULL, UShandle) == FALSE) {
		printf("Error selecting language\n");
		TextToSpeechCloseLang("us");
		exit(1);
	}
	result = TextToSpeechStartup(hWnd, &phTTS, WAVE_MAPPER,
REPORT_OPEN_ERROR);
	if (result != MMSYSERR_NOERROR) {
		printf("Unable to start DECtalk Speech Engine\n");
		TextToSpeechCloseLang("us");
		exit(1);
	}
	TextToSpeechShutdown(phTTS);
	TextToSpeechCloseLang("us");
	printf("Example completed successfully!\n");
	return;
}


Glossary
allophone
A positional or free variant of a phoneme.
applet
A small application that normally performs a very specific function and can be used with other larger applications.
arpabet
A special phonetic alphabet used to write phonemes and syllables.  
clause boundary
The natural boundary between two or more clauses in a sentence that helps the listener easily separate the sentence into its component parts. Commas, periods, exclamation points, question marks, semi-colons, and colons are symbols used to indicate clause boundaries.
clause mode
The normal mode in which DECtalk Software speaks text a phrase, clause, or sentence at a time. In clause mode, speaking starts when DECtalk Software is sent a clause terminator (period, comma, exclamation point, question mark, semi-colon, or colon) followed by a space. 
clause terminator
A symbol used to begin and terminate a clause boundary. Symbols can be periods, commas, exclamation points, question marks, semi-colon, or colon. Each of these symbols must be followed by a space.
comma pause
The pause DECtalk Software takes in speaking that is equivalent to inserting a comma in a sentence. Comma pause can be increased and decreased with the Comma Pause in-line command.
.DIC file
The loadable dictionary file created by the User Dictionary Build Tool from a .tab source file.
emphatic stress
The emphasis placed on a syllable of a word to give it more meaning.
falling intonation 
A decrease in voice pitch.
flush
Process by which the Text-To-Speech system discards data in the system.
heuristic
A method or rule used to decide among several courses of action. Often called a "rule of thumb." In the case of DECtalk Software, pronunciation heuristics govern the manner in which DECtalk Software pronounces words.
homograph
Pairs of words that have the same spelling but which are pronounced differently, depending on which syllable is accented.  For example, the pronunciation of permit as a noun and the pronunciation of permit as a verb.
index marker (flag)
A marker placed in the text stream to synchronize an external event. An index marker is inserted with the Index Mark command.
intonation
The manner in which a voice imparts extra meaning to speech by adjusting sounds' durations and voice pitch. For example, the emphasis and meaning of the sentence, Bill, put in the edits. can be changed by putting stronger emphasis on the name, Bill.  Bill! Put in the edits!
letter mode
The state in which DECtalk Software speaks each letter as it is queued. In word and letter mode, DECtalk Software does not need to wait for a clause terminator to begin speaking. This command interacts with the rate selection command so that you can set both rate selection and letter mode for optimal output.
log file
A file that can contain text, phonemes, or syllables. The phonemes and syllables are written using the arpabet phoneme alphabet.
log-file mode
Log-file mode indicates that the speech samples are to be written as text, phonemes, or syllables into a log file rather than sent to an audio device. The TextToSpeechOpenLogFile() call enters the text-to-speech system into a log-file mode. The TextToSpeechCloseLogFile() call returns the text-to-speech system to the startup state.
morpheme
The minimum syntactic unit of a language that has an important role in determining pronunciations. For example, spell has only one morpheme, while misspelling is made up of three: mis, spell, and ing. 
period pause
The pause DECtalk Software inserts when it finds a period that marks the end of the sentence. This pause imitates humans taking a breath.  This pause is approximately half a second.
phoneme
Smallest unit of speech that distinguishes one word from another. Phonemes are divided into vowel and consonant phonemes. DECtalk Software interprets text brackets as phonemes only after the phoneme arpabet command is used.
phoneme arpabet command
A command that causes all text within brackets to be treated as phonemic text.
phoneme string
Two or more phonemes together used to pronounce a special word or group of words.
phonemicize
To encode words as strings of phonemes.
phonemic mode
A mode DECtalk Software uses for speaking phoneme strings.
phonemic transcription
A word written the way it is pronounced is said to be in phonemic transcription or simply in phonemics. When DECtalk Software says a word or phrase not as you intended, you might need to use phonemic transcription to get the desired pronunciation.  For example,  [r'ehd] is the phonemic transcription of the word read.
phrase boundary 
A clause boundary formed by terminating punctuation (comma, period, exclamation point, question mark, semi-colon, colon) followed by a space.
pitch control symbols	
Symbols used to override built-in DECtalk Software pitch control. Symbols include pitch rise [/], pitch fall [\], and pitch rise and fall [/\].
primary stress
Most content words of English (nouns, verbs, adjectives, and adverbs) contain one primary stressed syllable. The primary stress symbol in DECtalk Software is the apostrophe [ ' ].
proper name
First names, last names, street names, company names, and place names are all examples of proper names.
secondary stress
A symbol used to indicate a degree of stress that is between primary and unstressed (no stress). The secondary stress symbol is the grave accent [`]. 
silence phonemes
Silences of specified durations inserted into text files in the same manner as you would insert a phoneme.
speech-to-memory mode
Speech-to-memory mode indicates that the speech samples are to be written into memory buffers rather than sent to an audio device. The TextToSpeechAddBuffer call supplies the text-to-speech system with the memory buffers that it needs. The TextToSpeechOpenInMemory call enters the text-to-speech system into a speech-to-memory mode. The TextToSpeechCloseInMemory call returns the text-to-speech system to the startup state.
startup function
Startup function refers to either the TextToSpeechStartup call or the TextToSpeechStartupEx call.
startup state
Startup state indicates that TextToSpeechStartup or TextToSpeechStartupEx has been successfully called and the text-to-speech system is not in one of the three special modes; wave-file, log-file, or speech-to-memory mode. While in startup state, speech samples are sent to an audio device or ignored, depending on whether the DO_NOT_USE_AUDIO_DEVICE flag is set in the dwDeviceOptions parameter of the startup function. If the text-to-speech system is in one of its special modes, the speech samples are handled accordingly.
syntactic function words
A set of words that are either unstressed or have secondary stress. They include prepositions, conjunctions, determiners, auxiliary verbs, pronouns, question mark, and clause introducers. DECtalk Software uses stress and syntactic symbols to control aspects of rhythm, stress, and intonation patterns. These symbols include punctuation marks such as commas, periods, question marks, and exclamation points.
.TAB file
The source file used to build a user dictionary.	
user dictionary	
The dictionary that you define so DECtalk Software can load and use with an application to control the pronunciation of specific words processed by the application.
user dictionary builder	
A program applet included with DECtalk Software to build and compile user dictionaries.
voice-control command
A DECtalk Software command inserted into text strings and used to control basic and special Text-To-Speech calls, such as speaking voice and speaking rate.
Wave file
A Microsoft standard file format for storing waveform audio data. Wave files have a .WAV file extension.
wave form output
The digitized reproduction of a sound wave form. DECtalk Software produces waveform output from the Speak program applet and the API, both of which allow you to save an ASCII text file to .WAV file format. 
wave-file mode
Wave-file mode indicates that the speech samples are to be written to a wave file rather than sent to an audio device. The TextToSpeechOpenWaveOutFile call enters the text-to-speech system into a wave-file mode. The TextToSpeechCloseWaveOutFile call returns the text-to-speech system to the startup state.
word boundary 
A white space character (space or tab) in the text that indicates a boundary between words. DECtalk Software uses word boundary symbols to select the word-beginning or word-ending allophone of a phoneme.
word mode
A text-processing mode where DECtalk Software speaks one word at a time. A blank space or equivalent after a character or string of characters causes that string to be spoken in word mode.


Index

.
.dic file, 2-10, 2-14
.dot (template) file, 2-20
.tab source file, 2-12, 2-14
A
API
function set, 1-6
introduction, 1-6
application program, 2-1
application programmer's interface, 1-6
arpabet phoneme alphabet, 3-13
ASCII text, 1-2
audio output control functions, 3-2
B
blocking synchronization function, 3-2, 3-11
buffer, 3-8
buffered speech, 3-8
built-in voices, 2-16
button on a toolbar, 2-23
C
callback routines, 3-6
change a speaking voice, 2-6
change the output rate, 2-9
change the speaking rate, 2-17
clause, 3-5
clause buffering, 1-2
clause terminator, 3-5
close a DECtalk language, 4-2
command strings, 1-2
command-line applet, 2-29
compiling an existing dictionary, 2-15
configure the TTS server, 2-25
configuring
Text-to-Speech (TTS) server, 2-25
control and status functions, 3-2
core API functions, 3-2
create a macro, 2-23
creating Dictionary Entries, 2-13
D
DAPI, 1-6
DAPI function, 4-2
data buffers, 1-6
data-structure definitions, 3-23
DDE. See Dynamic Data Exchange
DECtalk
features and functions, 1-2
how are the components used?, 1-9
how it works, 1-11
overview, 1-2
DECtalk language. See language
DECtalk Software API (DAPI), 1-6, 3-1
DECtalk Software components, 1-3
DECtalk Software voice set, 2-16
DECtalk TTS Server, 2-19
definitions, data-structure, 3-23
dictionaries, 1-7
dictionary applets, 3-18
dictionary file (.dic), 2-10
dictionary file string, 2-25
Dictionary options, 2-30
DIGITAL Speech API. See DECtalk Software API (DAPI)
drag and drop, 2-3
dwFlags field, 3-12
dwLanguageAttributes element, 3-15
Dynamic Data Exchange
and DECtalk, 2-19
Dynamic Data Exchange (DDE), 2-19
E
edit a text file, 2-17
edit text, 2-8
edit the text, 2-9
error and status messages, 3-7
error codes, 3-7
F
functions
audio output control, 3-2
blocking synchronization, 3-2, 3-11
control and status, 3-2
core API, 3-2
loading and unloading a User Dictionary, 3-3
special Text-to-Speech mode, 3-3
H
header files, 3-23
Help options, 2-29
highlighting spoken text, 2-18
how to link the macro, 2-23
I
index and phoneme arrays, 3-17
Index Mark in-line command, 3-11
index marks, 3-8
in-line command
examples of, 2-4
Index Mark, 3-11
syntax rules, 2-4
in-line commands, 1-6
Input options, 2-29
internal (built-in) dictionary, 1-7
intonation, 1-7
L
language
close, 4-2
load, 4-2
name, 4-2
select, 4-2
start, 4-2
languages, 3-23
launching
Text-to-Speech (TTS) server, 2-25
link the macro, 2-23
load a user dictionary, 2-17
loadable dictionary file (.dic), 2-10
loading a User Dictionary function, 3-3
log file, 3-13
LPARAM parameter, 3-7, 3-8
lpData element, 3-13
lpIndexArray element, 3-13
lpLanguageParamsArray element, 3-15
lpPhonemeArray element, 3-13
M
macro, 2-27
macro to run DECtalk with MS Word
associating with toolbar, 2-23
main dictionary, 3-18, 3-19
memory buffer, 3-8
menu selection, 2-23
messages, 3-7
Microsoft Speech Application Programmer's Interface (SAPI), 1-6
Microsoft Word document, 2-19, 2-20
modifying Dictionary Entries, 2-13
multi-language programming, 4-1
N
name, language, 4-2
O
options
Dictionary, 2-30
Help, 2-29
Input, 2-29
Output, 2-29
Output options, 2-29
P
phoneme alphabet, 3-13
Phoneme command
proper use of brackets with, 2-5
phoneme logging, 3-13
phonemic interpretation, 3-18
phonemic translations, 2-10
play selected segments, 2-17
play selected text, 2-9
power-key combination, 2-23
program applet
Sample, 1-3, 2-1
Speak, 1-5, 2-1, 2-16
User Dictionary Build Tool, 2-1
program control, 2-1
programming aids, 1-6
programming, multi-language, 4-1
pronunciation, 2-12
pronunciation dictionaries, 1-7
pull-down menu, 2-6
punctuation, 3-5
R
returned memory buffer, 3-8
rhythmic naturalness, 1-2
S
Sample program applet, 1-3, 2-1
starting from program group, 2-2
sample user-dictionary file, 1-8
SAPI, 1-6
save as a WAVE file, 2-17
saving an existing dictionary, 2-15
Say command-line applet, 2-29
select a DECtalk language, 4-2
service name, TTSserver, 2-25
service topic names, 2-25
singing, 1-7
single characters, 1-2
Speak program applet, 1-5, 2-1, 2-16
speaker selection, 2-25
speaking a file, 2-3
speaking rate, 1-6, 2-17, 2-25
speaking voice, 1-6, 2-25
special effects, 1-7
special Text-to-Speech mode functions, 3-3
special words, 2-12
speech synthesis, 1-2
start a DECtalk language, 4-2
start the program applet, 2-2
start the TTS server, 2-25
startup routine, 3-12
status functions, 3-2
status messages, 3-7
stress, 1-7
supported languages, 3-23
Sync in-line command, 3-5
syntax
for in-line commands, 2-4
syntax rules, 1-7
T
template, 2-20
text file, 2-17
inserting commands into, 2-4
Text-to-Speech server
configuring, 2-25
for use with applications supporting DDE, 2-19
TextToSpeechLoadUserDictionary() function, 2-10
TextToSpeechSpeak, 3-6
toolbar, 2-23
associating Word macro with, 2-23
Translate command, 2-10
TTS server, 2-25, 2-27. See Text to Speech server
how to configure, 2-25
how to start, 2-25
TTS Server, 2-19
TTS server macro, 2-27
TTS service name, 2-25
ttsapi.h file, 3-7
U
unloading a User Dictionary function, 3-3
user dictionary, 2-12, 2-17
user dictionary build tool, 1-6, 1-8
User Dictionary Build Tool, 2-10, 2-12
User Dictionary Build Tool program applet, 2-1
User dictionary selection, 2-25
user-defined dictionary, 1-7
using DECtalk Software in-line commands, 2-7
using the Voice menu, 2-7
V
voice control, 2-1
Voice pull-down menu, 2-6
voice set, 2-16
voice-control commands, 1-6, 1-7
Voice-Control commands, 1-6
voices, 1-2, 2-16
W
WAVE file, 2-17
window messages, 3-6
Word document, 2-19, 2-20
Word macro, 2-20, 2-25
Word macro to run DECtalk
associating with toolbar, 2-23
creating, 2-20
WPARAM parameter, 3-7


v


vi

v


iii

x


xi

1-12


1-3

2-30


2-29


3-24


3-25


4-2


4-3


Glossary - 6


Glossary - 5


Index -4


Index -3


