Inside Macintosh: Sound /

Chapter 1 - Introduction to Sound on the Macintosh / Using Sound on Macintosh Computers

Generating Speech From a String

It is easy to have the Speech Manager generate speech from a string stored as a variable of type Str255. The SpeakString 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 because SpeakString copies the string you pass it into an internal buffer, you are free to release the memory you allocated for the string as soon as SpeakString 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;

The MySpeakStringResource 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 the GetIndString procedure, which loads the string from the resource file into memory. MySpeakStringResource then calls the SpeakString 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 use SpeakString in conjunction with the SpeechBusy function, which returns the number of active speech channels, including the speech channel created by the SpeakString function.

Listing 1-9 illustrates how you can use SpeechBusy and SpeakString 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;

The MySpeakStringResourceSync procedure defined in Listing 1-9 uses the MySpeakStringResource procedure defined in Listing 1-8 to speak a string. However, before calling MySpeakStringResource, MySpeakStringResourceSync calls the SpeechBusy function to determine how many speech channels are active. After the speech has begun, the MySpeakStringResourceSync function does not return until the number of speech channels active again falls to this level.

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.

You can use the SpeakString function to stop speech being generated by a prior call to SpeakString. 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 the SpeakString function (or if you are programming in C, pass NULL).

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.