#### Preface Chapter 1 Chapter 2 Chapter 3 Chapter 4 Chapter 5

#

Chapter 5:
DECtalk Software API Function Calls

This chapter is an alphabetical listing of DECtalk Software API functions. They include:

- Control and Status Fuctions
- Text-to-Speech Modes
- Text-to-Speech Functions: Alphabetical Listing
- Function Listed by Category
- TextToSpeechAddBuffer
- TextToSpeechCloseInMemory
- TextToSpeechCloseLogFile
- TextToSpeechCloseWaveOutFile
- TextToSpeechGetCaps
- TextToSpeechGetLanguage
- TextToSpeechGetRate
- TextToSpeechGetSpeaker
- TextToSpeechGetStatus
- TextToSpeechLoadUserDictionary
- TextToSpeechOpenInMemory
- TextToSpeechOpenLogFile
- TextToSpeechOpenWaveOutFile
- TextToSpeechPause
- TextToSpeechReset
- TextToSpeechResume
- TextToSpeechReturnBuffer
- TextToSpeechSetLanguage
- TextToSpeechSetRate
- TextToSpeechSetSpeaker
- TextToSpeechShutdown
- TextToSpeechSpeak
- TextToSpeechStartup
- Loading of the Main Pronunciation Dictionary
- Loading of the User Dictionary
- TextToSpeechSync
- TextToSpeechUnloadUserDictionary

      Conventions used in API functions

      bold          Bold text is used to indicate function
                    names, data structures, and field names.

      italics       Italic text is used to indicate function
                    arguments and to emphasize important
                    information.

  ## Control and Status Fuctions

  The functions described in the following table provide additional control and status information for the text-to-speech system.

      Function                  Descriptions
      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. This
                                value cannot be the value
                                previously set by the
                                TextToSpeechSetSpeaker()
                                function.
      TextToSpeechSetRate()     Sets the speaking rate, which
                                becomes active at the next
                                clause boundary.
      TextToSpeechGetRate()     Gets the speaking rate (the
                                current rate setting is
                                returned even if it has not
                                been activated).
      TextToSpeechSetLanguage() Sets the text-to-speech
                                system language. (Currently,
                                this must be 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 system is 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.

  ## Text-to-Speech Modes

  After the TextToSpeechStartup() function is called by an application, it can then call the TextToSpeechSpeak() function to speak text. The application can also use the text-to-speech API to select different modes. These modes allow for writing wave files; writing a log file, which can contain text, phonemes, or syllables; or writing the audio (speech) samples to memory. Each mode-switch function has a corresponding function to return the text-to-speech system to the startup state. These functions are listed below.

      Open                        Close
      TextToSpeechOpenWaveOutFile TextToSpeechCloseWaveOutFile()

      TextToSpeechOpenLogFile()   TextToSpeechCloseLogFile()
      TextToSpeechOpenInMemory()  TextToSpeechCloseInMemory()

  The text-to-speech system must be in the startup state before calling any of the Open functions listed above. The corresponding Close functions return the system to the startup state.

  ## Text-to-Speech Functions: Alphabetical Listing

  TextToSpeechAddBuffer()
  TextToSpeechCloseInMemory()
  TextToSpeechCloseLog File()
  TextToSpeechCloseWaveOutFile()
  TextToSpeechGetCaps()
  TextToSpeechGetLanguage()
  TextToSpeechGetRate()
  TextToSpeechGetSpeaker()
  TextToSpeechGetStatus()
  TextToSpeechLoadUserDictionary()
  TextToSpeechOpenInMemory()
  TextToSpeechOpenLogFile()
  TextToSpeechOpenWaveOutFile()
  TextToSpeechPause()
  TextToSpeechReset()
  TextToSpeechResume()
  TextToSpeechReturnBuffer()
  TextToSpeechSetLanguage()
  TextToSpeechSetRate()
  TextToSpeechSetSpeaker()
  TextToSpeechShutdown()
  TextToSpeechSpeak()
  TextToSpeechStartup()
  TextToSpeechSync()
  TextToSpeechUnloadUserDictionary()

  ## Function Listed by Category

      Function                                Purpose
      Core API Functions
                      TextToSpeechStartup()  Initializes and
                                             starts up
                                             text-to-speech
                                             system.
                        TextToSpeechSpeak()  Speaks text
                                             from a buffer.
                     TextToSpeechShutdown()  Shuts down
                                             text-to-speech
                                             system.

      Audio Output Control Functions
                        TextToSpeechPause()  Pauses output.
                       TextToSpeechResume()  Resumes output.
                        TextToSpeechReset()  text-to-speech
                                             System is
                                             purged and
                                             output stopped.
      Blocking Synchronization Function
                         TextToSpeechSync()  Synchronizes to
                                             the text stream.
       Control and Status Functions
                   TextToSpeechSetSpeaker()  Selects one of
                                             nine speaking
                                             voices.
                   TextToSpeechGetSpeaker()  Returns the
                                             last speaking
                                             voice to have
                                             spoken.
                      TextToSpeechSetRate()  Sets the
                                             speaking rate
                                             of the
                                             text-to-speech
                                             system.
                      TextToSpeechGetRate()  Gets the
                                             speaking rate
                                             of the
                                             text-to-speech
                                             system.
                  TextToSpeechSetLanguage()  Sets the
                                             language to be
                                             used.
                  TextToSpeechGetLanguage()  Returns the
                                             language in use.
                    TextToSpeechGetStatus()  Gets status of
                                             text-to-speech
                                             System.
      	TextToSpeechOpenWaveOutFile()  Opens a file for
      				       output. Text-To
             		                       SpeechSpeak writes
             		                       audio data in wave
             		                       format to this file.
             TextToSpeechCloseWaveOutFile()  Closes the specified
                                             wave file.
                  TextToSpeechOpenLogFile()  Opens a log File.
                TextToSpeechCloseLog File()  Closes a log File.
                 TextToSpeechOpenInMemory()  Produces buffered
                                             speech samples in
                                             shared memory.
                TextToSpeechCloseInMemory()  Returns the
                                             text-to-speech system
                                             to its normal state.
                    TextToSpeechAddBuffer()  Adds a shared-memory
                                             buffer to the memory
                                             buffer list.
                 TextToSpeechReturnBuffer()  Returns the current
                                             shared-memory buffer.
                      TextToSpeechGetCaps()  Retrieves the capabilities of
                                             the text-to-speech system.
      Special Text-To-Speech Modes
       Loading and Unloading a User Dictionary
           TextToSpeechLoadUserDictionary()  Loads user dictionary.
         TextToSpeechUnloadUserDictionary()  Unloads user dictionary.

  ## TextToSpeechAddBuffer

  This function adds a buffer to the memory list the application uses in the speech-to-memory mode.

  Syntax

      MMRESULT TextToSpeechAddBuffer    (LPTTS_HANDLE_T phTTS,
                                         LPTTS_BUFFER_T pTTSbuffer)

  Parameters

      LPTTS_HANDLE_T phTTS        A pointer to a structure of
                                  type TTS_HANDLE_T.
      LPTTS_BUFFER_T pTTSbuffer   A pointer to a structure of
                                  type TTS_BUFFER_T.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

               Constant           Description
      MMSYSERR_NOERROR            Normal successful completion.
      MMSYSERR_INVALPARAM         Invalid parameter.
      MMSYSERR_ERROR              Output to memory not enabled or unable to create
                                  a system object.
      MMSYSERR_INVALHANDLE        The text-to-speech handle was invalid.

  Comments

  The application must have previously called the TextToSpeechOpenInMemory() function before calling this function. The buffer is passed using the structure TTS_BUFFER_T . The user must allocate the structure and the memory buffer. The text-to-speech system returns the buffer to the application when the buffer is full.

  The structure of type TTS_BUFFER is returned to the application in a message to the window procedure that corresponds to the window handle passed to the TextToSpeechStartup() function. A pointer to the structure of the type TTS_BUFFER_T is in the LPARAM field of the message. The message ID value is obtained with the following call:

  `uiID_Buffer_Message = RegisterWindowMessage("DECtalkBufferMessage");`

  See the topic, Storing Speech Samples in Memory

  See Also

  TextToSpeechOpenInMemory()
  TextToSpeechReturnBuffer()
  Storing Speech Samples in Memory
  Asynchronous Messages

  ## TextToSpeechCloseInMemory

  This function terminates the text-to-speech system's speech-to-memory capability and returns the text-to-speech system to its startup state. If audio is enabled at startup, then speech samples are routed to the audio device.

  Syntax

      MMRESULT TextToSpeechCloseInMemory  (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS        A pointer to a text-to-speech handle.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                    Description
      MMSYSERR_NOERROR            Normal successful completion.
      MMSYSERR_ERROR              Output to memory not enabled or unable to create
                                  a system object.
      MMSYSERR_INVALHANDLE        The text-to-speech handle was invalid.

  Comments

  The TextToSpeechOpenInMemory() function must be called before calling this function.

  See Also

  TextToSpeechOpenInMemory()

  ## TextToSpeechCloseLogFile

  This function closes a log file opened by the TextToSpeechOpenLogFile() function.

  Syntax

      MMRESULT TextToSpeechCloseLogFile   (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS          A pointer to a text-to-speech handle.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants.

      Constants                     Description
      MMSYSERR_NOERROR              Normal successful
                                    completion.
      MMSYSERR_ERROR                Failure to wait for
                                    pending speech,  unable to
                                    close the output file, or
                                    no output file is open.
      MMSYSERR_INVALHANDLE          The text-to-speech handle
                                    was invalid.

  Comments

  This function, when called, closes any open log file, even if it was opened with the Log [:log] voice-control command. The application must have previously called the TextToSpeechOpenLogFile() function before calling this function.

  See Also

  TextToSpeechOpenLogFile()

  ## TextToSpeechCloseWaveOutFile

  This function closes a wave file opened by the TextToSpeechOpenWaveOutFile() function.

  Syntax

      MMRESULT TextToSpeechCloseWaveOutFile (LPTTS_HANDLE_T phTTS)

  Parameters

       LPTTS_HANDLE_T phTTS       Specifies a text-to-speech handle identifying the
                                  opened text-to-speech device.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                    Description
      MMSYSERR_NOERROR            Normal successful
                                  completion.
      MMSYSERR_ERROR              Failure to wait for pending
                                  speech. Unable to update
                                  wave file header. Unable to
                                  close the wave file.
      MMSYSERR_INVALHANDLE        The text-to-speech handle
                                  was invalid.

  Comments

  The application must have previously called the TextToSpeechOpenWaveOutFile() function before calling this function.

  See Also

  TextToSpeechOpenWaveOutFile()

  ## TextToSpeechGetCaps

  This function provides the capabilities of the text-to-speech system by filling in a structure of type TTS_CAPS_T. The caller must have space allocated for this structure before calling this function.

  Syntax

      MMRESULT TextToSpeechGetCaps   (LPTTS_CAPS_T lpTTScaps)

  Parameters

      LPTTS_CAPS_T lpTTScaps      A pointer to a structure of type TTS_CAPS_T.
      			    This structure returns the capabilities of the
                                  text-to-speech system.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                    Description
      MMSYSERR_NOERROR            Normal successful completion.
      MMSYSERR_INVALHANDLE        The text-to-speech handle
                                  was invalid.
      MMSYSERR_ERROR              The pointer to the
                                  TTS_CAPS_T  structure was
                                  invalid.

  Comments

  Information returned in the TTS_CAPS_T structure includes languages and proper-name pronunciation support, sample rate, minimum and maximum speaking rate, number of predefined speaking voices, character-set supported, and version number.

  ## TextToSpeechGetLanguage

  This function returns the current language.

  Syntax

      MMRESULT TextToSpeechGetLanguage  (LPTTS_HANDLE_T phTTS,
                                         LANGUAGE_T pLanguage)

  Parameters

      LPTTS_HANDLE_T phTTS        Specifies a text-to-speech handle identifying the
                                  opened text-to-speech device.
      LANGUAGE_T * pLanguage      Specifies a language from the following list:

      Constant                    Description
      TTS_AMERICAN_ENGLISH        Specifies American English.
                                  Currently, American English
                                  is the only supported
                                  language (defined in include
                                  file ttsapi.h).

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                    Description
      MMSYSERR_NOERROR            Normal successful completion.
      MMSYSERR_INVALHANDLE        The text-to-speech handle
                                  was invalid.

  See Also

  TextToSpeechSetLanguage()

  ## TextToSpeechGetRate

  This function returns the current setting of the speaking rate.

  Syntax

      MMRESULT TextToSpeechGetRate   (LPTTS_HANDLE_T phTTS,LPDWORD pdwRate)

  Parameters

      LPTTS_HANDLE_T phTTS           Specifies a text-to-speech handle and
                                     identifies the opened text-to-speech device.
      LPDWORD pdwRate                A pointer to a DWORD that is used to
                                     return the speaking rate. Valid values
                                     range from 75 to 600 words per minute.

  Return Value

      Constant                       Description
      MMSYSERR_NOERROR               Normal successful completion.
      MMSYSERR_INVALHANDLE           The text-to-speech handle was invalid.

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

  Comments

  The current setting of the speaking rate is returned even if the speaking rate change has not occurred. (The speaking-rate change occurs on clause boundaries.)

  See Also

  TextToSpeechSetRate()

  ## TextToSpeechGetSpeaker

  This function returns the value of the identifier for the last voice that has spoken.

  Syntax

      MMRESULT TextToSpeechGetSpeaker   (LPTTS_HANDLE_T phTTS,
                                         LPSPEAKER_T lpSpeaker)

  Parameters

      LPTTS_HANDLE_T phTTS 		Specifies a text-to-speech Handle identifying
      	                        the opened text-to-speech device.
      LPSPEAKER_T lpSpeaker           A pointer to a DWORD that returns a speaker
                                      value from the following list. These symbols
                                      are defined in include file ttsapi.h.

      Speaker                                 Description
      PAUL                                    Default (male) voice
      HARRY                                   Full male voice
      FRANK                                   Aged male voice
      DENNIS                                  Male voice
      BETTY                                   Full female voice
      URSULA                                  Aged female voice
      WENDY                                   Whispering female voice
      RITA                                    Female voice
      KIT                                     Child's voice

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  Note that even after a call to the TextToSpeechSetSpeaker() function, this function returns the value for the previous speaking voice until the new voice actually speaks.

  See Also

  TextToSpeechSetSpeaker()

  ## TextToSpeechGetStatus

  This function returns the state of one or more text-to-speech system parameters.

  Syntax

      MMRESULT TextToSpeechGetStatus          (LPTTS_HANDLE_T phTTS,
      					 DWORD dwIdentifier[ ],
      					 DWORD dwStatus[ ],
                                               DWORD dwNumberOfStatusValues)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.
      DWORD dwIdentifier[ ]                   An array of values of type DWORD that
                                              contains identifiers specifying the
                                              status values to return in array
                                              dwStatus[ ]. These values can be one
                                              of the following constants defined in
                                              include file ttsapi.h:

      Constant                                Description
      INPUT_CHARACTER_COUNT                   Returns a count of characters in the
                                              text-to-speech system is currently
                                              processing.
      STATUS_SPEAKING                         The status value is TRUE if audio
                                              samples are playing and FALSE if no
                                              audio sample is playing.
      WAVE_OUT_DEVICE_ID                      The current wave output device ID is
                                              returned.
      DWORD dwStatus[ ]                       An array of type DWORD that contains
                                              the status values corresponding to
                                              each of the identifiers in array
                                              dwIdentifier[].
      DWORD dwNumberOfStatusValues            A DWORD that contains the number of
                                              entries to return.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed.
      MMSYSERR_ERROR                          Error obtaining status values.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was
                                              invalid.

  Comments

  The STATUS_SPEAKING status identifier has no meaning if the application is sending speech to a wave file or sending speech to memory.

  ## TextToSpeechLoadUserDictionary

  This function loads a user-defined pronunciation dictionary into the text-to-speech system.

  Syntax

      MMRESULT TextToSpeechLoadUserDictionary (LPTTS_HANDLE_T phTTS,
      					 LPSTR pszFileName)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech Handle
                                              identifying the opened text-to-speech
                                              device.
      LPSTR pszFileName                       A pointer to a NULL terminated string
                                              that specifies the name of the user
                                              dictionary file to be loaded.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.
      MMSYSERR_NOMEM                          Unable to allocate memory for
                                              dictionary.
      MMSYSERR_INVALPARAM                     Dictionary file not found. (Invalid
                                              dictionary file name.)
      MMSYSERR_ERROR                          Illegal dictionary format or a
                                              dictionary is already loaded.

  Comments

  This function loads a dictionary created by the User Dictionary Build Tool applet. The text-to-speech system loads a default user dictionary at startup if it finds a file named user.dic in the default directory or in the directory specified in the directory. Any previously loaded user dictionary must be unloaded before loading a new user dictionary.

  See Also

  TextToSpeechUnloadUserDictionary()
  Automatic Loading of a User Dictionary

  ## TextToSpeechOpenInMemory

  The TextToSpeechOpenInMemory() function allows speech to be stored in memory buffers supplied by the application. These buffers are passed to the text-to-speech system using the TextToSpeechAddBuffer() function.

  Syntax

      MMRESULT TextToSpeechOpenInMemory       (LPTTS_HANDLE_T phTTS, DWORD dwFormat)

  Parameters

      LPTTS_HANDLE_T phTTS                    A pointer to a text-to-speech handle.
      DWORD dwFormat                          An identifier that determines the
                                              audio sample format. It is one of the
                                              following constants defined in the
                                              include files mmsystem.h and
                                              ttsapi.h.

      Constant                                Description
      WAVE_FORMAT_11M08                       Mono, 8-bit 11.025 kHz sample rate
      WAVE_FORMAT_11M16                       Mono, 16-bit 11.025 kHz sample rate
      WAVE_FORMAT_08M08                       Mono, 8-bit -law, 8 kHz sample rate

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed. (An
                                              illegal output format value.)
      MMSYSERR_NOMEM                          Unable to allocate memory.
      Constant                                Description
      MMSYSERR_ERROR                          Illegal output state.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comment

  The buffer is passed using the structure TTS_BUFFER_T. The user must allocate the structure and the memory buffer. The text-to-speech system returns the buffer to the application when the buffer is full. The TextToSpeechStartup() function must be called to start the text-to-speech system before calling this function.

  The buffer is sent in a message to the window procedure that corresponds to the window handle passed to the function TextToSpeechStartup(). A pointer to the structure of the type TTS_BUFFER_T is in the LPARAM field of the message. The message ID value can be obtained by the following call:

  `uiID_Buffer_Message = RegisterWindowMessage("DECtalkBufferMessage");`

  ``See the section, Storing Speech Samples in Memory , at the beginning of this Appendix for more information. The TextToSpeechStartup() function must be called to start the text-to-speech system before calling this function.

  See Also

  TextToSpeechAddBuffer()
  TextToSpeechCloseInMemory()
  TextToSpeechReturnBuffer()
  Special text-to-speech Modes
  Storing Speech Samples in Memory

  ## TextToSpeechOpenLogFile

  This function creates a file that contains text, phonemes, or syllables. The phonemes and syllables are written using the arpabet alphabet. After calling this function, all subsequent calls to the TextToSpeechSpeak() function cause the log data to be written to a specified file until the TextToSpeechCloseLogFile() function is called.

  Syntax

      MRESULT TextToSpeechOpenLogFile         (LPTTS_HANDLE_T phTTS,
      					 LPSTR pszFileName, DWORD dwFlags)

  Parameters

      LPTTS_HANDLE_T phTTS                    A pointer to a text-to-speech handle.
      char pszFileName                        A pointer to a NULL terminated string
                                              that specifies the name of the log
                                              file to be opened.
      DWORD dwFlags                           Specifies the type of output. It can
                                              contain one or more of the following
                                              constants:
      Constants                               Description
      LOG_TEXT                                Log text
      LOG_PHONEMES                            Log phonemes
      LOG_SYLLABLES                           Log syllable structure

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants.

      Constants                               Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed.

  Continued on next page

  Continued from previous page

      MMSYSERR_NOMEM                          Unable to allocate memory.
      MMSYSERR_ALLOCATED                      A phoneme file is already open.
      MMSYSERR_ERROR                          Unable to open the output file.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  If more than one of the flags are passed, then the logged output is mixed in an unpredictable fashion. If there is already a log file open, this function returns an error. The voice-control Log command [:Log] has no effect when a log file is already open. The TextToSpeechStartup() function must be called to start the text-to-speech system before calling this function.

  See Also

  TextToSpeechCloseLogFile()
  Creating a Log File
  Special text-to-speech Modes

  ## TextToSpeechOpenWaveOutFile

  This function opens the named file for speech output as a wave file.

  Syntax

      MMRESULT TextToSpeechOpenWaveOutFile    (LPTTS_HANDLE_T phTTS,
      					 LPSTR pszFileName,
      					 DWORD dwFormat)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle and
                                              identifies the opened text-to-speech
                                              device.
      PSZFileName FileName                    Specifies a pointer to a file name.
      DWORD dwFormat                          Determines the audio sample format.
                                              It can be one of the following
                                              constants that are defined in include
                                              files mmsystem.h and ttsapi.h:

      Constant                                Description
      WAVE_FORMAT_11M08                        Mono 8-bit, 11.025 kHz sample rate
      WAVE_FORMAT_11M16                        Mono 16-bit, 11.025 kHz sample rate
      WAVE_FORMAT_08M08                       Mono 8-bit, -law 8 kHz sample rate

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was
                                              passed.
      Illegal wave output format
      MMSYSERR_NOMEM                          Memory allocation error.
      MMSYSERR_ALLOCATED                      A wave file is already open.
      MMSYSERR_ERROR                          Unable to open the wave file. Unable
                                              to write to the wave file.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  If an application calls the TextToSpeechOpenWaveOutFile() function, all subsequent calls to the TextToSpeechSpeak() function write the audio to a wave file until the TextToSpeechCloseWaveOutFile() function is called. The TextToSpeechStartup() function must be called to start the text-to-speech system before calling this function.

  See Also

  TextToSpeechOpenWaveOutFile
  Creating a Wave File
  Special text-to-speech Modes

  ## TextToSpeechPause

  This function pauses text-to-speech audio output.

  Syntax

  MMRESULT TextToSpeechPause (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The specified device handle is
                                              invalid. The system is not speaking
                                              or the text-to-speech handle is
                                              invalid.

  Comments

  This function only affects the audio output and will have no effect when writing log files, wave files, or when using the speech-to-memory capability of the text-to-speech system.

  The text-to-speech system will remain paused until one of the following functions is called:

- TextToSpeechResume()

- TextToSpeechSync()

- TextToSpeechOpenInMemory()

- TextToSpeechOpenLogFile()

  TextToSpeechOpenWaveOutFile()

  If the wave output (audio) device is being shared (i.e. OWN_AUDIO_DEVICE was NOT specified when the TextToSpeechStartup() function started the text-to-speech system.) by the text-to-speech system, and the TextToSpeechPause() function is called while the system is speaking, the wave output device is not released until one of the functions listed above is called and the system finishes speaking or the TextToSpeechReset() function is called. Note that the TextToSpeechReset() function will NOT resume audio output if text-to-speech system has been paused by the TextToSpeechPause() function.

  See Also

  TextToSpeechResume()
  Audio Output Control Functions

  ## TextToSpeechReset

  This function flushes all previously queued text from the text-to-speech system and stops any audio output.

  Syntax

      MMRESULT TextToSpeechReset         (LPTTS_HANDLE_T phTTS, BOOL bReset)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.
      BOOL bReset                             bReset returns one of the following
                                              Boolean values:

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

       Constant                               Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_NOMEM                          Unable to allocate memory.
      MMSYSERR_ERROR                          Unable to flush the system.
      Value                                   Description
      FALSE                                   Preserves the current mode of the
                                              text-to-speech system.
      TRUE                                    The text-to-speech system is returned
                                              to the startup state and any open
                                              text-to-speech files are closed. The
                                              one exception is that this function
                                              will NOT resume the text-to-speech
                                              system if it has been paused by the
                                              TextToSpeechPause() function.
       MMSYSERR_INVALHANDLE                   The text-to-speech handle was invalid.

  Comments

  The file is closed if the application has called the TextToSpeechOpenWaveOutFile() function or the TextToSpeechOpenLogFile() function and if bReset has a value of TRUE. Then, the TextToSpeechReset() function flushes all previously queued text and stops all audio output. If the TextToSpeechOpenInMemory() function has enabled outputting the speech samples to memory, then all queued TTS_BUFFER_T structures are returned to the application by a message that is sent to the application's window procedure. See the TextToSpeechOpenInMemory() function for more information.

  See Also

  TextToSpeechStartup()
  TextToSpeechShutdown()
  Audio Output Control Functions

  ## TextToSpeechResume

  This function resumes text-to-speech output after it has been paused by calling the TextToSpeechPause() function.

  Syntax

  MMRESULT TextToSpeechResume (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.

  Return Value

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The system was not paused, or the
                                              text-to-speech handle was invalid.

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

  Comments

  This function only affects the audio output and has no effect when writing log files, wave files, or when using the speech-to-memory capability of the text-to-speech system.

  See Also

  TextToSpeechPause
  Audio Output Control Functions

  ## TextToSpeechReturnBuffer

  This function returns the current buffer when an application is using the text-to-speech system's speech-to-memory capability. The buffer can be empty or partially full when it is returned. The dwBufferLength element of the TTS_BUFFER_T structure contains the number of samples in the buffer. If no buffer is available, then a NULL pointer is returned in ppTTSBuffer.

  Syntax

      MMRESULT TextToSpeechReturnBuffer       (LPTTS_HANDLE_T phTTS,
      					 LPTTS_BUFFER_TppTTSbuffer)

  Parameters

      LPTTS_HANDLE_T phTTS                    A pointer to a structure of type
                                              TTS_HANDLE_T.
      LPTTS_BUFFER_T *ppTTSbuffer             The address of a pointer to a
                                              structure of type TTS_BUFFER_T.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     Invalid parameter.
      MMSYSERR_ERROR                          Output to memory not enabled or
                                              unable to create a system object.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  Most applications do not require this function because buffers are automatically returned when filled or when a TTS_FORCE flag is passed in the TextToSpeechSpeak() function. The TextToSpeechReturnBuffer() function is provided so an application can return a buffer before it is filled and, therefore, obtain more speech samples immediately.

  See Also

  TextToSpeechStartup()
  TextToSpeechShutdown()

  ## TextToSpeechSetLanguage

  This function selects a language for the text-to-speech system to use as the default language.

  Syntax

      MMRESULT TextToSpeechSetLanguage        (LPTTS_HANDLE_T phTTS,
      				         LANGUAGE_T Language)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.
      LANGUAGE_T Language                     Specifies a language. It must be one
                                              of languages listed below. (Currently
                                              there is only one supported language.)
      Constant                                Description
      TTS_AMERICAN_ENGLISH                    Specifies American English. This
                                              symbol is defined in include file
                                              ttsapi.h

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  Currently, American English is the only supported language. See Also

  TextToSpeechGetLanguage()

  ## TextToSpeechSetRate

  This function sets the text-to-speech speaking rate.

  Syntax

      MMRESULT TextToSpeechSetRate            (LPTTS_HANDLE_T phTTS, DWORD dwRate)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.
      DWORD dwRate                            Sets the speaking rate. Valid values
                                              range from 75 to 600 words per
                                              minute.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  The speaking rate change is not effective until the next phrase boundary. All the queued audio encountered before the phrase boundary is unaffected.

  See Also

  TextToSpeechGetRate()

  ## TextToSpeechSetSpeaker

  This function sets the voice of the speaker the text-to-speech system will use.

  Syntax

      MMRESULT TextToSpeechSetSpeaker  (LPTTS_HANDLE_T phTTS, SPEAKER_T Speaker)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device
      SPEAKER_T  Speaker                      Selects a speaker from the following
                                              list. These values are defined in
                                              include file ttsapi.h.

      Speaker                                 Description
      PAUL                                    Default (male) voice
      HARRY                                   Full male voice
      FRANK                                   Aged male voice
      DENNIS                                  Male voice
      BETTY                                   Full female voice
      URSULA                                  Aged female voice
      WENDY                                   Whispering female voice
      RITA                                    Female voice
      KIT                                     Child's voice

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALPARAM                     An invalid parameter was passed.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  The change in speaking voice is not effective until the next phrase boundary. All queued audio encountered before the phrase boundary is unaffected.

  See Also

  TextToSpeechGetSpeaker()

  ## TextToSpeechShutdown

  This function shuts down the text-to-speech system and frees all system resources used by the text-to-speech system.

  Syntax

  MMRESULT TextToSpeechShutdown (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  This function is called when you close an application. Any user-defined dictionaries, which were previously loaded, are automatically unloaded. All previously queued text is discarded and the text-to-speech system will immediately stop speaking.

  See Also

  TextToSpeechStartup()

  ## TextToSpeechSpeak

  This function queues a null-terminated string to the text-to-speech system.

  Syntax

      MMRESULT TextToSpeechSpeak              (LPTTS_HANDLE_T phTTS,
                                               LPSTR pszTextString, DWORD dwFlags)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.
      LPSTR pszTextString                     Specifies a pointer to a null
                                              terminated string of characters to be
                                              queued
      DWORD dwFlags                           Specifies whether the text is to be
                                              pushed through the text-to-speech
                                              system even if it does NOT end on a
                                              clause boundary. It can be set to one
                                              of the following constants defined in
                                              include file ttsapi.h:

      Constant                                Description
      TTS_NORMAL                              Insert characters in the
                                              text-to-speech queue.
      TTS_FORCE                               Insert characters in the text-to-speech
      					queue and force all text to be output
      					even if the text stream does NOT end
      					on a clause boundary.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR _NOMEM                         Unable to allocate memory.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  The speaker, speaking rate, and volume can also be changed in the text string by inserting voice-control commands as shown in the following example:

  `
  [:name paul] I am Paul. [:nb] I am Betty. [:volume set 50] The volume has been set to 50% of the maximum level. [:ra 120] I am speaking at 120 words per minute.`

  See Also

  About TextToSpeechSpeak()

  ## TextToSpeechStartup

  This function initializes the text-to-speech system and returns a value of type MMRESULT. This value is zero if initialization was successful. A single process can run only one instance of DECtalk.

  Syntax

      MMRESULT TextToSpeechStartup  (HWND hWnd, LPTTS_HANDLE_T *phTTS,
                                    UINT uiDeviceNumber, DWORD dwDeviceOptions
                                    VOID (*DTCallbackRoutine) (),
      			      long dwDTCallbackParameter

  Parameters

      HWND hWnd                               A handle to the parent window. This
                                              can be NULL.
      LPTTS_HANDLE_T *phTTS                   A pointer to a pointer to a structure
                                              of type TTS_HANDLE_T.
      UINT uiDeviceNumber                     Specifies a device number of the wave
                                              output device. A value of WAVE_MAPPER
                                              can be used to select the first
                                              available device.
      DWORD dwDeviceOptions                   Specifies how the wave output device
                                              is managed. It can be a combination
                                              of the following constants defined in
                                              include file ttsapi.h:

      Constants                               Description
      OWN_AUDIO_DEVICE                        The wave output device is opened. No
                                              other process can allocate the wave
                                              output device until the
                                              TextToSpeechShutdown() function is
                                              called.
                                              If OWN_AUDIO_DEVICE is NOT specified,
                                              the wave output device is opened
                                              after audio is queued by the
                                              TextToSpeechSpeak() function. The
                                              wave output device is released when
                                              the text-to-speech system has
                                              completed speaking.
      DO_NOT_USE_AUDIO_DEVICE                 The text-to-speech system can only be
                                              used to write wave files, write
                                              speech samples to memory, or to write
                                              log files. No error is returned if a
                                              wave output device is not present.
      OUTPUT_TO_MME_DEVICE                    This flag need not be specified
                                              anymore, it is still available for
                                              compatiblity with previous versions
                                              of DECtalk Software.

  VOID (*DtCallbackRoutine)()
  This parameter is used to specify a callback routine. The callback routine is used by DECtalk Sofware to inform the application when the buffer is full (if DECtalk Software in-memory calls are used) or when the TexToSpeechSpeak () function encounters an index mark.

  A value of NULL should be passed in if no user-specificed parameters are desired.

  LONG dwCallbackParameter
  This is a pointer to a user-specified parameter. It is used to pass parameters into the callback routine.

  A value of NULL should be passed in if no user-specified parameters are desired.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constant                                Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_NODRIVER                       No wave output device present.
      MMSYSERR_NOMEM                          Memory allocation error.
      MMSYSERR_ERROR                          DECtalk dictionary not found.
      MMSYSERR_baddevice_id                   Device ID out of range.

  Comments

  The default parameters are:

      Language: American English.

      Speaking rate: 180 words per
      minute. Speaker: Paul.

  See Also

  TextToSpeechShutdown()

  ## Loading of the Main Pronunciation Dictionary

  The TextToSpeechStartup() function loads the DECtalk main pronunciation dictionary, dectalk.dic, from the directory specified in the directory at /usr/lib/dtk/.

  If the dictionary file cannot be found in this fashion then the TextToSpeechStartup() function returns a value of MMSYSERR_ERROR.

  ## Loading of the User Dictionary

  The TextToSpeechStartup() function attempts to load a user specified pronunciation dictionary from the user's login home directory. When started, DECtalk Software loads the default user dictionary called user.dic if it is available.

  If the dictionary file cannot be found in this fashion then the TextToSpeechStartup() function attempts to load the user dictionary from the applications default directory. If this second attempt fails then a user dictionary is not loaded.

  See Also

  TextToSpeechLoadUserDictionary()
  TextToSpeechUnloadUserDictionary()

  ## TextToSpeechSync

  This function blocks until all previously queued text has been processed. This function automatically resumes audio output if the text-to-speech system has been paused by the TextToSpeechPause() function.

  Syntax

  MMRESULT TextToSpeechSync (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T ph TTS                   Specifies a text-to-speech handle
                                              identifying the opened text-to-speech
                                              device.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constants                               Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_ERROR                          Unable to complete queued text.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  This function automatically resumes audio output if the text-to-speech system is in a paused state by a previously issued TextToSpeechPause() function.

  ## TextToSpeechUnloadUserDictionary

  This function unloads a user dictionary. You must unload any previously loaded dictionary before you can load a new one. That is, only one user dictionary can be loaded at a time.

  Syntax

      MMRESULT TextToSpeechUnloadUserDictionary (LPTTS_HANDLE_T phTTS)

  Parameters

      LPTTS_HANDLE_T phTTS                    Specifies a text-to-speech Handle
                                              identifying the opened text-to-speech
                                              device.

  Return Value

  This function returns a value of type MMRESULT. The value is zero if the function is successful. The return value is one of the following constants:

      Constants                               Description
      MMSYSERR_NOERROR                        Normal successful completion.
      MMSYSERR_INVALHANDLE                    The text-to-speech handle was invalid.

  Comments

  A user dictionary is created using the User Dictionary Build tool. See Creating a user dictionary.

  See Also

  TextToSpeechLoadUserDictionary()