SpVoice Speak method (SAPI 5.3)

Microsoft Speech API 5.3

Object: SpVoice

Speak Method

The Speak method initiates the speaking of a text string, a text file, an XML file, or a wave file by the voice.

The Speak method can be called synchronously or asynchronously. When called synchronously, the method does not return until the text has been spoken; when called asynchronously, it returns immediately, and the voice speaks as a background process.

When synchronous speech is used in an application, the application's execution is blocked while the voice speaks, and the user is effectively locked out. This may be acceptable for simple applications, or those with no graphical user interface (GUI), but when sophisticated user interaction is intended, asynchronous speaking will generally be more appropriate.

The WaitUntilDone and SpeakCompleteEvent methods can be used to block an application's forward progress while allowing user interaction with the mouse or keyboard.

  
    SpVoice.Speak(
     Text As String,
     [Flags As SpeechVoiceSpeakFlags = SVSFDefault]
) As Long

Parameters

• Text
  The text to be spoken, or if the SVSFIsFilename flag is included in the Flags parameter, the path of the file to be spoken.
• Flags
  [Optional] Flags. Default value is SVSFDefault.

Return Value

A Long variable containing the stream number. When a voice enqueues more than one stream by speaking asynchronously, the stream number is necessary to associate events with the appropriate stream.

Remarks

The Speak method inserts a stream into the text-to-speech (TTS) engine's queue, and returns a stream number, assigned by the engine. This distinguishes the stream from other streams in the queue. This number is a temporary identifier which functions like an index into the TTS queue. The first stream spoken into an empty queue will always have a stream number of 1.

A voice object can enqueue numerous streams, and each of these streams can generate events. SpVoice events always return the stream number as a parameter. If an application saves the stream numbers of the streams it enqueues, events can be associated with the proper stream.

Example

The following code snippet demonstrates the Speak method with several commonly used flag settings.

  Const cstrTextName = "c:\Speech Voice Speak.txt"

Dim V As SpeechLib.SpVoice
Set V = New SpVoice

'Build a simple text file for demonstration purposes
Open cstrTextName For Output As #1
Print #1, "The name of this file is " & cstrTextName
Close #1

'Speak literal text
V.Speak "This is some text", SVSFDefault

'Speak the text of the test file
V.Speak cstrTextName, SVSFIsFilename + SVSFlagsAsync

'Speak with/without punctuation
V.Speak "one, two, three!", SVSFlagsAsync
V.Speak "one, two, three!", SVSFNLPSpeakPunc + SVSFlagsAsync

'Speak text with/without XML tags
V.Speak "text with XML", SVSFIsXML + SVSFlagsAsync
V.Speak "text with XML", SVSFIsNotXML + SVSFlagsAsync

V.WaitUntilDone 10000