Inside Macintosh: Sound /

Chapter 4 - Speech Manager / Speech Manager Reference

Speech Manager Routines / Starting, Stopping, and Pausing Speech

SpeakBuffer

You can use the SpeakBuffer function to have the Speech Manager speak a buffer of text, using certain flags to control speech behavior.

FUNCTION SpeakBuffer (chan: SpeechChannel; textBuf: Ptr; 
                        textBytes: LongInt; 
                        controlFlags: LongInt): OSErr;

chan

The speech channel through which speech is to be spoken.

textBuf

A pointer to the first byte of text to spoken.

textBytes

The number of bytes of text to spoken.

controlFlags

Control flags to customize speech behavior.

DESCRIPTION

The SpeakBuffer function behaves identically to the SpeakText function, but allows control of several speech parameters by setting values of the controlFlags parameter. The controlFlags parameter relies on the following constants, which may be applied additively:

CONST
   kNoEndingProsody        = 1;  {disable prosody at end of sentences}
   kNoSpeechInterrupt      = 2;  {do not interrupt current speech}
   kPreflightThenPause     = 4;  {compute speech without generating}

Each constant specifies a flag bit of the controlFlags parameter, so by passing the constants additively you can enable multiple capabilities of SpeakBuffer. If you pass 0 in the controlFlags parameter, SpeakBuffer works just like SpeakText. By passing kNoEndingProsody + kNoSpeechInterrupt in the controlFlags parameter, SpeakBuffer works like SpeakText except that the kNoEndingProsody and kNoSpeechInterrupt features have been selected. Future versions of the Speech Manager may define additional constants.

The kNoEndingProsody flag bit is used to control whether or not the speech synthesizer automatically applies ending prosody, the speech tone and cadence that normally occur at the end of a statement. Under normal circumstances (for example, when the flag bit is not set), ending prosody is applied to the speech when the end of the textBuf data is reached. This default behavior can be disabled by setting the kNoEndingProsody flag bit.

Some synthesizers do not speak until the kNoEndingProsody flag bit is reset, or they encounter a period in the text, or textBuf is full.

The kNoSpeechInterrupt flag bit is used to control the behavior of SpeakBuffer when called on a speech channel that is still busy. When the flag bit is not set, SpeakBuffer behaves similarly to SpeakString and SpeakText. Any speech currently being produced on the specified speech channel is immediately interrupted, and then the new text buffer is spoken. When the kNoSpeechInterrupt flag bit is set, however, a request to speak on a channel that is still busy processing a prior text buffer will result in an error. The new buffer is ignored and the error synthNotReady is returned. If the prior text buffer has been fully processed, the new buffer is spoken normally. One way of achieving continuous speech without using callback procedures is to continually call SpeakBuffer with the kNoSpeechInterrupt flag bit set until the function returns noErr. The function will then execute as soon as the first text buffer has been processed.

The kPreflightThenPause flag bit is used to minimize the latency experienced when the speech synthesizer is attempting to speak. Ordinarily, whenever a call to SpeakString, SpeakText, or SpeakBuffer is made, the speech synthesizer must perform a certain amount of initial processing before speech output is heard. This startup latency can vary from a few milliseconds to several seconds depending upon which speech synthesizer is being used. Recognizing that larger startup delays might be detrimental to certain applications, a mechanism exists to allow the synthesizer to perform any necessary computations at noncritical times. Once the computations have been completed, the speech is able to start instantly. When the kPreflightThenPause flag bit is set, the speech synthesizer will process the input text as necessary to the point where it is ready to begin producing speech output. At this point, the synthesizer will enter a paused state and return to the caller. When the application is ready to produce speech, it should call the ContinueSpeech function to begin speaking.

When the controlFlags parameter is set to 0, SpeakBuffer behaves identically to SpeakText.

SPECIAL CONSIDERATIONS

Because the SpeakBuffer function might move memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the SpeakBuffer function are

Trap macro	Selector
_SoundDispatch	$0828000C

RESULT CODES

noErr	0	No error
synthNotReady	-242	Speech channel is still busy speaking
invalidComponentID	-3000	Speech channel is uninitialized or bad