Important: Inside Macintosh: Sound is deprecated as of Mac OS X v10.5. For new audio development in Mac OS X, use Core Audio. See the Audio page in the ADC Reference Library.
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
TheSpeakBuffer
function behaves identically to theSpeakText
function, but allows control of several speech parameters by setting values of thecontrolFlags
parameter. ThecontrolFlags
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 thecontrolFlags
parameter, so by passing the constants additively you can enable multiple capabilities ofSpeakBuffer
. If you pass 0 in thecontrolFlags
parameter,SpeakBuffer
works just likeSpeakText
. By passingkNoEndingProsody + kNoSpeechInterrupt
in thecontrolFlags
parameter,SpeakBuffer
works likeSpeakText
except that thekNoEndingProsody
andkNoSpeechInterrupt
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 thetextBuf
data is reached. This default behavior can be disabled by setting thekNoEndingProsody
flag bit.Some synthesizers do not speak until the
kNoEndingProsody
flag bit is reset, or they encounter a period in the text, ortextBuf
is full.The
kNoSpeechInterrupt
flag bit is used to control the behavior ofSpeakBuffer
when called on a speech channel that is still busy. When the flag bit is not set,SpeakBuffer
behaves similarly toSpeakString
andSpeakText
. Any speech currently being produced on the specified speech channel is immediately interrupted, and then the new text buffer is spoken. When thekNoSpeechInterrupt
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 errorsynthNotReady
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 callSpeakBuffer
with thekNoSpeechInterrupt
flag bit set until the function returnsnoErr
. 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 toSpeakString
,SpeakText
, orSpeakBuffer
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 thekPreflightThenPause
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 theContinueSpeech
function to begin speaking.When the
controlFlags
parameter is set to 0,SpeakBuffer
behaves identically toSpeakText
.SPECIAL CONSIDERATIONS
Because theSpeakBuffer
function might move memory, you should not call it at interrupt time.ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for theSpeakBuffer
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