SpVoice Interface (SAPI 5.3)

Microsoft Speech API 5.3

SpVoice

The SpVoice object brings the text-to-speech (TTS) engine capabilities to applications using SAPI automation. An application can create numerous SpVoice objects, each independent of and capable of interacting with the others. An SpVoice object, usually referred to simply as a voice, is created with default property settings so that it is ready to speak immediately.

Voice Characteristics and UI Support

The fundamental characteristics of the voice are the Voice property, which can be thought of as the person of the voice, the Rate property, and the Volume property. "Microsoft Mary" and "Microsoft Mike" are examples of Voices. Use the GetVoices method to determine what other voices are available to the voice object.

These properties can be modified with a User Interface (UI). The IsUISupported method determines if a specific UI is supported. Use the DisplayUI method to display a supported UI. The TTS tab of Speech properties in Control Panel, which enables users to modify the characteristics of the default system voice, is an example of a voice UI.

Speaking and Queueing

The Speak method places a text stream in the TTS engine's input queue and returns a stream number. It can be called synchronously or asynchronously. When called synchronously, the Speak 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.

Asynchronous speaking can place numerous text streams into the input queue. These streams are also referred to as speech requests. The stream number returned by an asynchronous Speak call is the stream's index in the voice queue. The WaitUntilDone method blocks execution until the voice finishes speaking, enabling an application to speak a text stream asynchronously and determine when it finishes. The hidden SpeakCompleteEvent method is similar to WaitUntilDone, except that it returns an event handle for the background speaking process, and does not block application execution.

The SpeakStream method operates like the Speak method, except that it speaks sound files instead of text.

Voice Output

An SpVoice object is created with its audio output set to the system default audio output. Use the GetAudioOutputs method to determine what other outputs are available to the voice, and use the AudioOutput property to set its audio output to one of them.

Use the AudioOutputStream property with other Speech automation objects to store audio output in memory (see SpMemoryStream) or in files (see SpFileStream).

Voice Events

As a voice speaks text, it can generate events when it detects certain conditions in the input stream. These events are contained in the SpeechVoiceEvents enumeration. Examples of these events are completion of phonemes, words, or sentences, as well as changes of voice or the presence of bookmarks. The range of conditions which can be reported by SpeechVoiceEvents is wide enough that most applications will use only a few of them. To prevent the TTS engine from generating events that will be ignored by the application, use the EventInterests property to specify the events of interest. Only these events will be raised.

The point in the input text stream at which a potential event has been completed is referred to as an event boundary. At each event boundary, the event type is compared with the current EventInterests. If the event type is of interest, an event of that type is raised. Voice events return the input stream number in order to associate them with the appropriate stream.

Voice Priorities and Alerts

Application error handling has traditionally interrupted a UI with message boxes or alert boxes describing error states. Because a TTS application might operate with no graphical UI at all, it is able to implement error handling with a TTS voice. This voice is referred to as an alert, because its purpose is identical to that of an alert box or message box. To create an alert voice, create a new SpVoice object and set its Priority property appropriately. The alert voice should also use a different Voice property from the normal voice, so that users can easily distinguish the two.

When a speaking voice detects a pending alert, it continues speaking until it arrives at a specific application-defined stopping point, such as a sentence or a word. This stopping point is called the alert boundary because it is an event boundary at which alerts can be processed. When the alert has finished speaking, the interrupted voice resumes. Get and set the alert boundary with the AlertBoundary property.

Status and Control

The Status method may return an ISpeechVoiceStatus object, which contains several types of information about the state of the voice. Some ISpeechVoiceStatus properties are equivalent to parameters returned by voice events; it may be advantageous for some applications to get these elements by calling Status occasionally, rather than by receiving events constantly.

Voice status and voice events are closely associated with the status of the audio output device. A voice speaking to a file stream produces no audio output, generates no events, and has no audio output status. As a result, the ISpeechVoiceStatus data returned by that voice will always show it to be inactive.

A speaking voice can be paused at the next alert boundary with the Pause method. A paused voice can be resumed with the Resume method. The Skip method causes the voice to skip forward or backward in the input stream.

Automation Interface Elements

The SpVoice automation object has the following elements: