This chapter is an alphabetical listing of DECtalk Software API functions. They include:
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.
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.
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.
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.
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
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()
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()
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()
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.
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()
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()
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.
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:
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()
Syntax
Parameters
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:
Comments
The STATUS_SPEAKING status identifier has no meaning if the application
is sending speech to a wave file or sending speech to memory.
Syntax
Parameters
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:
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()
Syntax
Parameters
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:
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()
Syntax
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.
Continued from previous page
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()
Syntax
Parameters
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:
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
Syntax
MMRESULT TextToSpeechPause (LPTTS_HANDLE_T phTTS)
Parameters
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 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:
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()
Syntax
Parameters
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:
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()
Syntax
MMRESULT TextToSpeechResume (LPTTS_HANDLE_T
phTTS)
Parameters
Return Value
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
Syntax
Parameters
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:
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()
Syntax
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:
Comments
Currently, American English is the only supported language.
See Also
TextToSpeechGetLanguage()
Syntax
Parameters
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:
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()
Syntax
Parameters
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:
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()
Syntax
MMRESULT TextToSpeechShutdown (LPTTS_HANDLE_T phTTS)
Parameters
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:
Comments
See Also
TextToSpeechStartup()
Syntax
Parameters
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:
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:
See Also
About TextToSpeechSpeak()
Syntax
Parameters
VOID (*DtCallbackRoutine)()
A value of NULL should be passed in if no user-specificed parameters are
desired.
LONG dwCallbackParameter
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:
Comments
The default parameters are:
See Also
TextToSpeechShutdown()
If the dictionary file cannot be found in this fashion then the
TextToSpeechStartup() function returns a value of MMSYSERR_ERROR.
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
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
This function returns the state of one or more text-to-speech system
parameters.
TextToSpeechGetStatus
MMRESULT TextToSpeechGetStatus (LPTTS_HANDLE_T phTTS,
DWORD dwIdentifier[ ],
DWORD dwStatus[ ],
DWORD dwNumberOfStatusValues)
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.
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.
This function loads a user-defined pronunciation dictionary into the
text-to-speech system.
TextToSpeechLoadUserDictionary
MMRESULT TextToSpeechLoadUserDictionary (LPTTS_HANDLE_T phTTS,
LPSTR pszFileName)
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.
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.
Automatic Loading of a User Dictionary
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.
TextToSpeechOpenInMemory
MMRESULT TextToSpeechOpenInMemory (LPTTS_HANDLE_T phTTS, DWORD dwFormat)
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
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.
TextToSpeechCloseInMemory()
TextToSpeechReturnBuffer()
Special text-to-speech Modes
Storing Speech Samples in Memory
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.
TextToSpeechOpenLogFile
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
Constants Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALPARAM An invalid parameter was passed.
Continued on next 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.
Creating a Log File
Special text-to-speech Modes
This function opens the named file for speech output as a wave file.
TextToSpeechOpenWaveOutFile
MMRESULT TextToSpeechOpenWaveOutFile (LPTTS_HANDLE_T phTTS,
LPSTR pszFileName,
DWORD dwFormat)
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
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.
Creating a Wave File
Special text-to-speech Modes
This function pauses text-to-speech audio output.
TextToSpeechPause
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 specified device handle is
invalid. The system is not speaking
or the text-to-speech handle is
invalid.
Audio Output Control Functions
This function flushes all previously queued text from the text-to-speech system
and stops any audio output.
TextToSpeechReset
MMRESULT TextToSpeechReset (LPTTS_HANDLE_T phTTS, BOOL bReset)
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:
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.
TextToSpeechShutdown()
Audio Output Control Functions
This function resumes text-to-speech output after it has been paused by calling
the TextToSpeechPause() function.
TextToSpeechResume
LPTTS_HANDLE_T phTTS Specifies a text-to-speech handle
identifying the opened text-to-speech
device.
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:
Audio Output Control Functions
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.
TextToSpeechReturnBuffer
MMRESULT TextToSpeechReturnBuffer (LPTTS_HANDLE_T phTTS,
LPTTS_BUFFER_TppTTSbuffer)
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.
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.
TextToSpeechShutdown()
This function selects a language for the text-to-speech system to use as the
default language.
TextToSpeechSetLanguage
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
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALPARAM An invalid parameter was passed.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
This function sets the text-to-speech speaking rate.
TextToSpeechSetRate
MMRESULT TextToSpeechSetRate (LPTTS_HANDLE_T phTTS, DWORD dwRate)
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.
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALPARAM An invalid parameter was passed.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
This function sets the voice of the speaker the text-to-speech system will
use.
TextToSpeechSetSpeaker
MMRESULT TextToSpeechSetSpeaker (LPTTS_HANDLE_T phTTS, SPEAKER_T Speaker)
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
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALPARAM An invalid parameter was passed.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
This function shuts down the text-to-speech system and frees all system
resources used by the text-to-speech system.
TextToSpeechShutdown
LPTTS_HANDLE_T phTTS Specifies a text-to-speech handle
identifying the opened text-to-speech
device.
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
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.
This function queues a null-terminated string to the text-to-speech system.
TextToSpeechSpeak
MMRESULT TextToSpeechSpeak (LPTTS_HANDLE_T phTTS,
LPSTR pszTextString, DWORD dwFlags)
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.
Constant Description
MMSYSERR_NOERROR Normal successful completion.
MMSYSERR _NOMEM Unable to allocate memory.
MMSYSERR_INVALHANDLE The text-to-speech handle was invalid.
[: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.
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.
TextToSpeechStartup
MMRESULT TextToSpeechStartup (HWND hWnd, LPTTS_HANDLE_T *phTTS,
UINT uiDeviceNumber, DWORD dwDeviceOptions
VOID (*DTCallbackRoutine) (),
long dwDTCallbackParameter
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.
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.
This is a pointer to a user-specified
parameter. It is used to pass parameters into the callback routine.
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.
Language: American English.
Speaking rate: 180 words per
minute. Speaker: Paul.
The TextToSpeechStartup() function loads the DECtalk main pronunciation
dictionary, dectalk.dic, from the directory specified in the directory at
/usr/lib/dtk/.
Loading of the Main Pronunciation Dictionary
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()
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.
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()