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.
Generating Speech From a String
It is easy to have the Speech Manager generate speech from a string stored as a variable of typeStr255
. TheSpeakString
function takes one parameter, the string to be spoken.SpeakString
automatically allocates a speech channel, uses that channel to produce speech, and then disposes of the speech channel when speaking is complete. Speech generation is asynchronous, but becauseSpeakString
copies the string you pass it into an internal buffer, you are free to release the memory you allocated for the string as soon asSpeakString
returns.Listing 1-8 show how you can use the
SpeakString
function to convert a string stored in a resource of type'STR#'
into speech.Listing 1-8 Using
SpeakString
to generate speech from a string
PROCEDURE MySpeakStringResource (myStrListID: Integer; myIndex: Integer); VAR myString: Str255; {the string to speak} myErr: OSErr; BEGIN GetIndString(myString, myStrListID, myIndex); {load the string} myErr := SpeakString(myString); {start speaking} IF myErr <> noErr THEN DoError(myErr); END;TheMySpeakStringResource
procedure defined in Listing 1-8 takes as parameters the resource ID of the'STR#'
resource containing the string and the index of the string within that resource.MySpeakStringResource
passes these values to theGetIndString
procedure, which loads the string from the resource file into memory.MySpeakStringResource
then calls theSpeakString
function to convert the string into speech; if an error occurs, it calls an application-defined error-handling procedure.The speech that the
SpeakString
function generates is asynchronous; that is, control returns to your application before the function finishes speaking the string. If you would like to generate speech synchronously, you can useSpeakString
in conjunction with theSpeechBusy
function, which returns the number of active speech channels, including the speech channel created by theSpeakString
function.Listing 1-9 illustrates how you can use
SpeechBusy
andSpeakString
to generate speech synchronously.Listing 1-9 Generating speech synchronously
PROCEDURE MySpeakStringResourceSync (myStrListID: Integer; myIndex: Integer); VAR activeChannels: Integer; {number of active speech channels} BEGIN activeChannels := SpeechBusy; {find number of active channels} MySpeakStringResource(myStrListID, myIndex); {speak the string} {Wait until channel is no longer processing speech.} REPEAT UNTIL SpeechBusy = activeChannels; END;TheMySpeakStringResourceSync
procedure defined in Listing 1-9 uses theMySpeakStringResource
procedure defined in Listing 1-8 to speak a string. However, before callingMySpeakStringResource
,MySpeakStringResourceSync
calls theSpeechBusy
function to determine how many speech channels are active. After the speech has begun, theMySpeakStringResourceSync
function does not return until the number of speech channels active again falls to this level.
You can use the
- Note
- Ordinarily, you should play speech asynchronously, to allow the user to perform other activities while speech is being generated. You might play speech synchronously if other activities performed by your application should not occur while speech is being generated.
SpeakString
function to stop speech being generated by a prior call toSpeakString
. You might do this, for example, if the user switches to another application or closes a document associated with speech being generated. To stop speech, simply pass a zero-length string to theSpeakString
function (or if you are programming in C, passNULL
).Listing 1-10 shows how your application can stop speech generated by a call to the
SpeakString
function.Listing 1-10 Stopping speech generated by
SpeakString
PROCEDURE MyStopSpeech; VAR myString: Str255; {an empty string} myErr: OSErr; BEGIN myString[0] := Char(0); {set length of string to 0} myErr := SpeakString(myString); {stop previous speech} IF myErr <> noErr THEN DoError(myErr); END;The MyStopSpeech procedure defined in Listing 1-10 sets the length byte of a string to 0 before calling the SpeakString function. To execute this code in some development systems, you need to ensure that range checking is disabled. Consult your development system's documentation for details on enabling and disabling range checking.