Speak

(VoiceTalk Module)

Description:	Executes on the speech thread to speak the supplied text through a specified SAPI text-to-speech stream.
Returns:	Nothing
Usage:	Script Only.
Function Groups:	Speech and Sound
Related to:	Configure | GetDevices | GetVoices | Reset | ShowLexicon | VoiceTalk
Format:	VoiceTalkStream\Speak(Text [, Flags])
Parameters:

VoiceTalkStream

Required. A speech stream returned from VoiceTalk that you wish to speak the given phrase.

Text

Required. Any text expression that will be spoken on a specified stream.

Flags

An optional parameter to specify speaking flags to the stream. All text will be spoken asynchronously (i.e. the function will not wait for the speech to complete speaking). Flags can be used to specify other parsing of the text. The values for Flags can be any combination of the following: Flags Meaning 0 Use default settings (speak asynchronously) 1 Speak asynchronously. 2 Purge speaking queue before speaking text. This cancels all pending and current speech, and then immediately begins speaking the new text. 4 Regard the Text parameter as a filename, and speak the contents of that file. 8 Parse text for XML markup. 16 Do not parse text for XML markup. 32 Any XML state changes in the text will persist across any future VoiceTalk\Speak calls. 64 Punctuation characters should be spoken (i.e. "Hello, there." would be spoken as "Hello comma there period"). (As indicated above, an Invalid value, or a value of "0" or "1" for the Flags parameter will have the same result.)

Comments:

This function returns the error code resulting from issuing the command to the speech engine, or zero if no error was encountered. This function will execute and immediately return, sending the text to the speech engine to be spoken asynchronously. Asynchronous speech will not block the calling thread. You can determine when a section of text has completed speaking by inserting bookmarks into the text that can then be watched for in the VoiceTalk BookmarkNum parameter. Multiple VoiceTalk\Speak statements can be issued on SAPI text-to-speech streams without blocking. The text will be queued up and will be spoken in the order it is submitted. The text speech queue will be terminated immediately if the SAPI text-to-speech stream is closed. If speaking simultaneously on several streams, all to the same output device, the thread that is currently speaking will continue to do so until all its queued text has been spoken, even if the other thread issues VoiceTalk\Speak calls during this time. The text string spoken can optionally contain embedded "control tags" that affect the way that the text is spoken. These control tags are in the form of embedded XML. For example, <EMPH> and </EMPH> emphasizes the words between the tags, and <BOOKMARK MARK="32"/> sets the SAPI text-to-speech stream current bookmark number to 32. In order for embedded XML to be parsed, either the text stream must be enabled to process XML (by passing a value for Flags that includes the value 8), or the text string itself must begin with an angle bracket (<). For a complete list of embedded control tags, please refer to the Microsoft SAPI 5.1 speech documentation.

Example:

sHandle = \VoiceTalk();
If Valid(sHandle) && ZButton(10, 40, 110, 10, "Talk", 1);
[
  sHandle\Speak("<P>Mary had a <EMPH>little</EMPH> lamb</P>");
]

This will speak the supplied text with emphasis on the word "little".

sHandle = \VoiceTalk();
If Valid(sHandle) && Value < 0 Warning;
[
  sHandle\Speak("The value has fallen below zero", 1+2 {synchronous & purge});
]

This will immediately stop any current speech, begin speaking the warning to the user, and continue on right away to the state Warning.