Inside Macintosh: Sound /

Chapter 4 - Speech Manager / Using the Speech Manager

Creating, Using, and Disposing of a Speech Channel

To take advantage of most of the Speech Manager's capabilities, you must pass a speech channel to Speech Manager functions. You use the NewSpeechChannel function to create a speech channel. After you are done using a speech channel, you must dispose of it by using the DisposeSpeechChannel function. Listing 4-2 shows how to create a speech channel, start speaking text with the SpeakText function, stop speaking text with the StopSpeech function, and then dispose of the speech channel when the speaking is finished.

Listing 4-2 Speaking text with a speech channel

FUNCTION MyUseSpeechChannel: OSErr;
VAR
   myErr:   OSErr;
   myErr2:  OSErr;
   myStr:   Str255;                                      {text to be spoken}
BEGIN
   myStr := 'Hold the mouse button down to stop speech.';
   myErr := NewSpeechChannel(NIL, gChannel);             {create the channel}
   IF (myErr = noErr) THEN
   BEGIN                                                 {speak the string}
      myErr := SpeakText(gChannel, @myStr[1], Length(myStr));
      WHILE (SpeechBusy <> 0) DO                {wait until speaking is done}
      BEGIN    
         IF (Button) THEN
         myErr := StopSpeech(gChannel);         {stop speech at mouse down}
      END;  
      IF (gChannel <> NIL) THEN
         myErr2 := DisposeSpeechChannel(gChannel);{get rid of channel}
   END;
   IF (myErr = noErr) THEN 
      MyUseSpeechChannel := myErr2
   ELSE
      MyUseSpeechChannel := myErr;
END;

The MyUseSpeechChannel function defined in Listing 4-2 creates a default speech channel using the default system voice. You pass NIL in the first parameter to use the system default voice. You must also pass a global variable to NewSpeechChannel in which is returned a valid speech channel. Once the channel exists, then you can use the SpeakText function to generate speech. To generate synthesized speech, you pass in the channel allocated by NewSpeechChannel in the first parameter, and then you pass a pointer to the text that you want to speak as well as the length of the text that you want the Speech Manager to attempt to speak. That is, you can pass a pointer to a buffer of text that is 500 bytes long, but specify that only the first 10 bytes get spoken. Then MyUseSpeechChannel uses the SpeechBusy function in a WHILE loop to allow the text to be completely spoken before disposing of the channel.

When the designated action to stop the speaking occurs, which in this example is the user pressing the mouse button, MyUseSpeechChannel halts speech production. In this case, the StopSpeech function stops the speech immediately (as soon as the synthesizer can). You need to pass StopSpeech the variable that identifies the channel on which the speech is currently being synthesized. If you want to have more control over when the speech is stopped, you can use the StopSpeechAt function, which allows you to stop speech immediately, at the end of a word, or at the end of a sentence. See the description of the StopSpeechAt function on page 4-60 for more information.

Once you are done using the speech channel that was created with NewSpeechChannel, you must dispose of it. The MyUseSpeechChannel function calls DisposeSpeechChannel with the global variable that identifies the channel currently in use.