CHAPTER 6
`
`Speech Manager
`
`Hz) on a conventional piano. Pitches are represented on a logarithmic scale. On this
`scale, a change of +12 units corresponds to doubling the frequency, while a change of
`-12 units corresponds to halving the frequency. For a further discussion of pitch values,
`see ”Getting Information About a Speech Channel,” later in this chapter.
`
`Typical Voice frequencies might range from around 90 Hertz for a low-pitched male
`voice to perhaps 300 Hertz for a high-pitched child's voice. These frequencies
`correspond to pitch values of 41.526 and 53.526, respectively.
`
`Changes in speech rate and pitch are effective immediately (as soon as the synthesizer
`can respond), even if they occur in the middle of a word.
`
`SetSpeechRate
`
`The SetSpeechRate routine sets the speaking rate on a designated speech channel.
`
`pascal OSErr SetSpeechRate (speechchannel chan, Fixed rate);
`
`chan
`
`rate
`
`Specific speech channel.
`
`Word output speaking rate.
`
`DESCRIPTION
`
`RESULT CODES
`
`The SetSpeechRate routine is used to adjust the speaking rate on a speech channel.
`The rate parameter is specified as a fixed-point, words-per-minute value. As a general
`rule of thumb, ”normal” speaking rates range from around 150 WPM to around
`180 WPM. It is important when working with speaking rates, however, to keep in
`mind that users will differ greatly in their ability to understand synthesized speech
`at a particular rate based upon their level of experience listening to the voice and their
`ability to anticipate the types of utterances they will encounter.
`
`noErr
`
`0
`
`No error
`
`invalidComponentID
`
`-3000
`
`Invalid Speechchannel parameter
`
`GetSpeechRate
`
`The GetSpeechRate routine returns the speech rate currently active on a designated
`speech channel.
`
`pascal OSErr GetSpeechRate (speechchannel chan, Fixed *rate);
`
`chan
`
`* rate
`
`Specific speech channel.
`
`Pointer to the current speaking rate.
`
`Using the Speech Manager
`
`Page 301 of 500
`
`277
`
`PUMA EXHIBIT 2005
`
`PART 7 OF 10
`
`Page 301 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`DESCRIPTION
`
`RESULT CODES
`
`The GetSpeechRate routine is used to find out the speaking rate currently active on a
`speech channel.
`
`noErr
`
`0
`
`No error
`
`invalidcomponent I D
`
`-3000
`
`Invalid Speechchanne l parameter
`
`SetSpeechPitch
`
`The SetSpeechPitch routine sets the speaking pitch on a designated speech channel.
`
`pascal OSErr SetSpeechPitch (speechchannel chan, Fixed pitch);
`
`chan
`
`pi t ch
`
`Specific speech channel.
`
`Frequency of voice.
`
`DESCRIPTION
`
`RESULT CODES
`
`Use the SetSpeechPitch routine to change the current speaking pitch on a
`speech channel.
`
`noErr
`
`0
`
`No error
`
`invalidComponentID
`
`-3000
`
`Invalid Speechchannel parameter
`
`GetSpeechPitch
`
`The GetSpeechPitch routine returns the current speaking pitch on a designated
`speech channel.
`
`pascal OSErr GetSpeechPitch (speechchannel chan, Fixed *pitch);
`
`Field descriptions
`
`Chan
`
`pi t ch
`
`Specific speech channel.
`
`Frequency of voice.
`
`DESCRIPTION
`
`The GetSpeechPitch routine is used to find out the speaking pitch currently active on
`a speech channel.
`
`Using the Speech Manager
`
`Page 302 of 500
`
`Page 302 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`RESUETCODES
`
`noErr
`
`invalidComponentID
`
`0
`-3000
`
`No error
`
`Invalid Speechcharmel parameter
`
`Putting It All Together
`
`The code fragment in Listing 6-4 illustrates many of the routines introduced in this
`section. The example steps through the list of available voices to find the first female
`voice. Then it creates a new speech channel and begins speaking. While the voice is
`speaking, the pitch of the voice is continually adjusted around the original pitch. If the
`mouse button is pressed while the voice is speaking, the code halts the speech and exits.
`This example uses the spe e chAva i l abl e and Getvo i ceGende r routines shown
`earlier in Listing 6-1 and Listing 6-3.
`
`Listing 6-4
`
`Putting it all together
`
`OSErr
`
`Str255
`
`Voicespec
`
`VoiceDescription
`Boolean
`
`short
`
`Speechchannel
`Fixed
`
`err;
`
`mystr
`voice;
`
`vd;
`
`"\pThe bat sat on my hat.";
`
`gotvoice
`voicecount,
`Chan;
`
`FALSE;
`
`gender,
`
`i;
`
`origPitch, newPitch;
`
`{
`&& SpeechAvailable())
`if (myStr[O]
`err
`CountVoices(&voiceCount);// count the avaiiable voices
`
`i = 1;
`
`while ((i <= voiceCount)
`
`&&
`
`((err=GetIndVoice(i+n, &voice))
`
`==noErr))
`
`GetIndVoice(i++,
`
`&voice))
`
`noErr;
`
`{ e
`
`rr
`
`err
`if ((err
`
`GetVoiceGender(&voice,
`&&
`noErr)
`
`(gender
`
`&gender);
`kFemale))
`
`{
`
`gotVoice
`break;
`
`TRUE;
`
`(gotvoice)
`
`{
`
`NewSpeechChannel(&voice, &chan);
`err
`if (err
`noErr)
`{
`
`GetSpeechPitch(chan,
`err
`noErr)
`if (err
`
`&origPitch); // cur pitch
`
`err
`
`SpeakText(chan, &myStr[l], myStr[O]);
`
`Using the Speech Manager
`
`Page 303 of 500
`
`Page 303 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`i = 0;
`
`if (err == noErr)
`
`{
`while (SpeechBusy() > O)
`CoolAnimationRoutine();
`
`newPitch =
`
`(i — 4) << 16;
`
`// fixed pitch offset
`
`newPitch += origPitch;
`
`i = (i + 1)
`
`to 7 repeatedly
`& 7;// steps from O
`newPitch);
`
`err = SetSpeechPitch(chan,
`if ((err != noErr)
`Button())
`||
`
`{
`
`err = StopSpeech(chan);
`break;
`
`}
`
`err = Disposespeechchannel(chan);
`
`} i
`
`f (err
`
`!= noErr)
`
`NotSoCoolAlertRoutine(err);
`
`Advanced Routines
`
`This section describes several advanced or rarely used Speech Manager routines. You can
`use them to improve the quality of your application's speech.
`
`Advanced Speech Controls
`
`The Stopspeech routine, described on page 276, provides a simple way to interrupt
`any speech output instantly. In some situations it is preferable to be able to stop speech
`production at the next natural boundary, such as the next Word or the end of the current
`sentence. StopSpeechAt provides that capability.
`
`Similarly, the PauseSpeechAt routine causes speech to pause at a specified point in the
`text being spoken; the Cont inue Speech routine resumes speech after it has paused.
`
`In addition to Speakstring and SpeakText, described earlier in this chapter, the
`Speech Manager provides a third, more general routine. SpeakBuf fer is the low-level
`speech routine upon which the other two are built. SpeakBuf fer provides greater
`control through the use of an additional flags parameter.
`
`The SpeechBusySystemWide routine tells you if any speech is currently being synthe-
`sized in your application or elsewhere on the computer.
`
`Using the Speech Manager
`
`Page 304 of 500
`
`Page 304 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`StopSpeechAt
`
`The StopSpeechAt routine halts speech at a specific point in the text being spoken.
`
`pascal OSErr StopSpeechAt
`
`(speechchannel chan,
`
`long whereToStop);
`
`enum {
`kImmediate
`
`kEndOfWord
`
`kEndOfSentence
`
`};
`
`0,
`
`1,
`2
`
`chan
`
`Specific speech channel.
`
`whereToStop
`
`Location in text at which speech is to stop.
`
`DESCRIPTION
`
`StopSpeechAt is used to halt the production of speech at a specified point in the text.
`The whereToStop argument should be set to one of the following constants:
`
`I The klmmediate constant stops speech output immediately.
`
`I The kEndO fWord constant lets speech continue until the current word has been
`spoken.
`
`The kEndOf Sentence constant lets speech continue until the end of the current
`sentence has been reached.
`
`This routine returns immediately, although speech output continues until the specified
`point has been reached.
`
`WARNING
`
`You must not release the memory associated with the current
`text buffer until the channel status indicates that the speech
`channel output is no longer busy. A
`
`If the end of the input text buffer is reached before the specified stopping point, the
`speech synthesizer will stop at this point. Once the stopping point has been reached, the
`application is free to release the text buffer. Calling StopSpeechAt with whereToStop
`equal to klmmediate is equivalent to calling Stopspeech, described on page 276.
`
`Contrast the StopSpeechAt routine with PauseSpeechAt, described next.
`
`RESUETCODES
`
`noErr
`
`invalidComponentID
`
`0
`-3000
`
`No error
`
`Invalid Speechchannel parameter
`
`Using the Speech Manager
`
`Page 305 of 500
`
`Page 305 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`PauseSpeechAt
`
`The PauseSpeechAt routine causes speech to pause at a specified point in the text
`being spoken.
`
`pascal OSErr PauseSpeechAt
`
`(speechchannel chan,
`
`long whereToPause);
`
`enum {
`klmmediate
`
`kEndOfWord
`
`kEndOfSentence
`
`0,
`
`1,
`2
`
`};
`
`chan
`
`Specific speech channel.
`
`whereToPause
`
`Location in text at which speech is to pause.
`
`DESCRIPTION
`
`Pausespeech makes speech production pause at a specified point in the text. The
`whereToPause parameter should be set to one of these constants:
`
`I The klmmediate constant stops speech output immediately.
`
`I The kEndO fWord constant lets speech continue until the current word has
`been spoken.
`
`I The k3ndOf Sentence constant lets speech continue until the end of the current
`sentence has been reached.
`
`When the specified point is reached, the speech channel enters the paused state, reflected
`in the channel's status. PauseSpeechAt returns immediately, although speech output
`will continue until the specified point.
`
`If the end of the input text buffer is reached before the specified pause point, speech
`output pauses at the end of the buffer.
`
`PauseSpeechAt differs from Stopspeech and StopSpeechAt in that a subsequent
`call to Continue Speech, described next, causes the contents of the current text buffer
`
`to continue being spoken.
`
`WARNING
`
`While in a paused state, the last text buffer must remain available at all
`times and must not move. While paused, the SpeechChannel status
`indkamsoutputBusy=trueandoutputPaused=true.A
`
`RESULT CODES
`
`noErr
`
`invalidComponentID
`
`0
`-3000
`
`No error
`
`Invalid Speechchannel parameter
`
`Using the Speech Manager
`
`Page 306 of 500
`
`Page 306 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Continuespeech
`
`The Continuespeech routine resumes speech after it has been halted by the
`PauseSpeechAt routine.
`
`pascal OSErr Continuespeech (speechchannel chan);
`
`chan
`
`Specific speech channel.
`
`DESCRIPTION
`
`RESULT CODES
`
`At any time after PauseSpeechAt is called, Continue Speech may be called to
`continue speaking from the point at which speech paused. Calling Continuespeech on
`a channel that is not currently in a pause state has no effect; calling it before a pause is
`effective cancels the pause.
`
`noErr
`
`0
`
`No error
`
`invalidComponentID
`
`—$Mm
`
`InvafidSpeechchannelpanunemr
`
`SpeakBuffer
`
`The SpeakBuf fer routine causes the contents of a text buffer to be spoken, using
`certain flags to control speech behavior.
`
`pascal OSErr SpeakBuffer
`
`(SpeechChannel chan, Ptr textBuf,
`
`long textBytes,
`
`long controlFlags);
`
`enum {
`
`kNoEndingProsody
`
`kNoSpeechInterrupt
`
`kPreflightThenPause
`
`1,
`
`2,
`
`4
`
`};
`
`chan
`textBuf
`
`Specific speech channel.
`Buffer of text.
`
`textBytes
`
`Length of textBuf.
`
`controlFlags
`
`Control flags to control speech behavior.
`
`DESCRIPTION
`
`When the controlFlags parameter is set to O, SpeakBuf fer behaves identically to
`SpeakText, described on page 275.
`
`Using the Speech Manager
`
`Page 307 of 500
`
`Page 307 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`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, described earlier
`in this chapter. 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.
`
`The kPref lightThenPause 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 may be
`detrimental to certain applications, a mechanism is provided to provide the synthesizer
`a chance to perform any necessary computations at noncritical times. Once the
`computations have been completed, the speech is able to start instantly. When the
`kPre f lightThenPause 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 Continue Speech routine to
`begin speaking.
`
`RESULT CODES
`
`noE r r
`
`0
`
`No error
`
`s ynthNo tRe ady
`invalidComponentID
`
`-242
`-3000
`
`Speech channel is still busy speaking
`Invalid Speechchannel parameter
`
`SpeechBusySystemWide
`
`You can use SpeechBusySystemWide to determine if any speech is currently being
`synthesized in your application or elsewhere on the computer.
`
`pascal short SpeechBusySystemWide (void);
`
`Using the Speech Manager
`
`Page 308 of 500
`
`Page 308 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`DESCRIPTION
`
`This routine is useful when you want to ensure that no speech is currently being
`produced anywhere on the Macintosh computer. SpeechBusySystemWide returns the
`total number of speech channels currently synthesizing speech on the computer, whether
`they were initiated by your code or by some other process executing concurrently.
`
`RESULT CODES
`
`None
`
`Converting Text Into Phonemes
`
`In some situations it is desirable to convert a text string into its equivalent phonemic
`representation. This may be useful during the content development process to fine-tune
`the pronunciation of particular words or phrases. By first converting the target phrase
`into phonemes, you can see what the synthesizer will try to speak. Then you need
`correct only the parts that would not have been spoken the way you want.
`
`TextToPhonemes
`
`The TextToPhonemes routine converts a designated text to phoneme codes.
`
`pascal OSErr TextToPhonemes
`
`(speechchannel chan, Ptr textBuf,
`
`long textBytes, Handle phonemeBuf,
`
`long *phonemeBytes);
`
`chan
`textBuf
`
`Specific speech channel.
`Buffer of text.
`
`textBytes
`
`Length of textBuf in bytes.
`
`phonemeBuf
`
`Buffer of phonemes.
`
`*phonemeBytes
`
`Pointer to length of phonemeBuf in bytes.
`
`DESCRIPTION
`
`It may be useful to convert your text into phonemes during application development in
`order to be able to reduce the amount of memory required to speak. If your application
`does not require the text-to-phoneme conversion portion of the speech synthesizer,
`significantly less RAM may be required to speak with some synthesizers. Additionally,
`you may be able to use a higher quality text-to-phoneme conversion process (even one
`that does not work in real time) to generate precise phonemic information. This data can
`then be used with any speech synthesizer to produce better speech.
`
`TextToPhonemes accepts a Valid Speechchannel parameter, a pointer to the
`characters to be converted into phonemes, the length of the input text buffer in bytes, an
`application-supplied handle into which the converted phonemes can be written, and a
`
`Using the Speech Manager
`
`Page 309 of 500
`
`Page 309 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`length parameter. On return, the phonemeBytes argument is set to the number of
`phoneme character bytes that were written into phonemeBuf. The data returned by
`TextToPhonemes will correspond precisely to the phonemes that would be spoken had
`the input text been sent to SpeakText instead. All current mode settings are applied to
`the converted speech. No callbacks are generated while the TeXtToPhor1emes routine is
`generating its output.
`
`RESUETCODES
`
`n oE r r
`
`0
`
`No error
`
`pa ramErr
`nilHandleErr
`s i Un kn own I n f o T yp e
`invalidComponentID
`
`-50
`-109
`-231
`-3000
`
`Parameter value is invalid
`Handle argument is nil
`Feature not implemented on synthesizer
`Invalid Speechchannel parameter
`
`Getting Information About a Speech Channel
`
`Several additional types of information have been made available for advanced users of
`the Speech Manager. This information provides more detailed status information for
`each channel. You can get this information by calling the Getspeechlnf o routine. This
`function accepts selectors that determine the type of information you want to get.
`
`Note
`
`Throughout this document, there are several references to parameter
`values specified with fixed-point integer values (pbas, pmod, rate, and
`volm). Unless otherwise stated, the full range of values of the Fixed
`data type is valid. However, it is left to the individual speech synthesizer
`implementation to determine whether or not to use the full resolution
`and range of the Fixed data type. In the event a specified parameter
`value lies outside the range supported by a particular synthesizer, the
`synthesizer will substitute the value closest to the specified value that
`does lie Within its performance specifications. 0
`
`Getspeechlnfo
`
`The Get Speechln f o routine returns information about a designated speech channel.
`
`pascal OSErr Getspeechlnfo (speechchannel chan, OSType selector,
`
`void *speechInfo);
`
`speech output status
`error status
`
`current text/phon mode
`current character mode
`
`current number mode
`
`enum {
`
`sostatus
`soErrors
`
`soInputMode
`soCharacterMode
`
`soNumberMode
`
`‘stat’,
`'erro',
`
`'inpt',
`‘char’,
`
`'nmbr',
`
`Using the Speech Manager
`
`Page 310 of 500
`
`Page 310 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`soRate
`
`soPitchBase
`
`soPitchMod
`
`sovolume
`
`soSynthType
`
`soRecentSync
`
`soPhonemeSymbols
`
`soSynthExtension
`};
`
`'rate',
`
`'pbas',
`
`'pmod',
`
`'volm',
`
`'vers',
`
`'sync',
`
`'phsy',
`
`'xtnd'
`
`'
`
`'
`
`current speaking rate
`
`current baseline pitch
`
`current pitch modulation
`
`current speaking volume
`
`speech synth version info
`
`most recent sync message info
`
`phoneme symbols & ex. words
`
`synthesizer—specific info
`
`Field descriptions
`
`chan
`
`Specific speech channel.
`
`s e 1 e ct or
`
`Used to specify data being requested.
`
`* spee ch I n f o
`
`Pointer to an information structure.
`
`DESCRIPTION
`
`The following list of selectors describes the Various types of information that can be
`obtained from the Speech Manager. The format of the information returned depends on
`which Value is used in the selector field, as follows:
`
`Note
`
`For future code compatibility, use the application programming
`interface (API) labels instead of literal selector values. 9
`
`Field descriptions
`
`stat
`
`Gets Various items of status information for the specified channel.
`Indicates whether any speech audio is being generated, Whether or
`not the channel has paused, how many bytes in the input text have
`yet to be processed, and the phoneme code for the phoneme that is
`currently being generated. If inputBytesLe f t is 0, the input
`buffer is no longer needed and can be disposed of. The API label for
`this selector is sostatus.
`
`typedef Speechstatuslnfo *speechInfo;
`
`typedef struct Speechstatuslnfo {
`
`Boolean
`
`outputBusy;
`
`// true = audio playing
`
`Boolean outputPaused;
`
`// true = channel paused
`
`long
`
`short
`
`inputBytesLeft;// bytes left to process
`
`phonemecode;
`
`// current phoneme code
`
`} Speechstatuslnfo;
`
`Gets saved error information and clears the error registers. This
`selector lets you poll for Various run-time errors that occur during
`speaking, such as the detection of badly formed embedded
`commands. Errors returned directly by Speech Manager routines
`are not reported here. The count field shows how many errors
`
`Using the Speech Manager
`
`Page 311 of 500
`
`Page 311 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`have occurred since the last check. If count is 0 or 1, then oldest
`and newest will be the same. Otherwise, oldest contains the
`error code for the oldest unread error and newest contains the
`error code for the most recent error. Both oldPos and newPos
`
`contain the character positions of their respective errors in the
`original input text buffer. The API label for this selector is
`soflrrors
`
`typedef SpeechErrorInfo *speechInfo;
`
`typedef struct SpeechErrorInfo {
`short
`count;
`// # of errs since last check
`
`OSErr
`
`long
`OSErr
`
`long
`
`oldest;
`
`// oldest unread error
`
`oldPos;
`newest;
`
`// char position of oldest err
`// most recent error
`
`newPos;
`
`// char position of newest err
`
`} SpeechErrorInfo;
`
`Gets the current Value of the text processing mode control. The
`returned Value specifies whether the specified speech channel is
`currently in text-input mode (TEXT) or phoneme-input mode
`(PHON). The API label for this selector is soInputMode.
`
`typedef OSType *speechInfo;
`
`// TEXT or PHON
`
`Gets the current value of the character processing mode control. The
`returned Value specifies whether the specified speech channel is
`currently processing input characters in normal mode (NORM) or in
`literal, letter-by-letter, mode (LTRL). The API label for this selector
`issoCharacterMode.
`
`typedef OSType *speechInfo;// NORM or LTRL
`
`Gets the current value of the number processing mode control. The
`returned value specifies whether the specified speech channel is
`currently processing input character digits in normal mode (NORM)
`or in literal, digit-by-digit, mode (LTRL). The API label for this
`selector is soNumberMode.
`
`typedef OSType *speechInfo;// NORM or LTRL
`
`Gets the current speaking rate in words per minute on the specified
`channel. Speaking rates are fixed-point Values. The API label for this
`selector is soRate.
`
`typedef Fixed *speechInfo;
`
`Using the Speech Manager
`
`Page 312 of 500
`
`Page 312 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Note
`
`Words per minute is a convenient, if difficult to define, way of
`representing speaking rate. Although there is no universally
`accepted definition of words per minute, it does communicate
`approximate information about speaking rates. Any specific rate
`may correspond to different rates on different synthesizers, but the
`two rates should be reasonably close. More importantly, doubling
`the rate on a particular synthesizer should halve the time needed to
`speak any particular utterance. 9
`
`Gets the current baseline pitch for the specified channel. The pitch
`value is a fixed—point integer that conforms to the following
`frequency relationship:
`
`Hertz = 440.0 * 2((BasePitch — 69)
`BasePitch of 1.0
`z
`9 Hertz
`
`/ 12)
`
`BasePitch of 39.5
`
`BasePitch of 45.8
`
`BasePitch of 50.4
`
`BasePitch of 100.0
`
`=
`
`=
`
`z
`
`=
`
`80 Hertz
`
`115 Hertz
`
`150 Hertz
`
`2637 Hertz
`
`BasePitch values are always positive numbers in the range from
`1.0 through 100.0. The API label for this selector is soPitchBase.
`
`typedef Fixed *speechInfo;
`
`Gets the current pitch modulation range for the speech channel.
`Modulation values range from 0.0 through 100.0. A value of 0.0
`corresponds to no modulation and means the channel will speak in
`a monotone. The API label for this selector is soPitchMod.
`
`Nonzero modulation values correspond to pitch and frequency
`deviations according to the following formula:
`
`Maximum pitch = BasePitch + PitchMod
`
`Minimum pitch = BasePitch - PitchMod
`Maximum Hertz = BaseHertz *
`2(+ ModVa;ue / 12)
`Modvalue / 12)
`2(-
`
`Minimum Hertz = BaseHertz
`Given:
`
`BasePitch of 46.0
`
`(= 115 Hertz),
`
`PitchMod of 2.0,
`Then:
`
`Maximum pitch = 48.0
`
`(=131 Hertz),
`
`Minimum pitch = 44.0
`
`(z104 Hertz)
`
`typedef Fixed *speechInfo;
`
`Using the Speech Manager
`
`Page 313 of 500
`
`Page 313 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Gets the current setting of the volume control on the specified
`channel. Volumes are expressed in fixed—point units ranging from
`0.0 through 1.0. A value of 0.0 corresponds to silence, and a value of
`1.0 corresponds to the maximum possible volume. Volume units lie
`on a scale that is linear with amplitude or voltage. A doubling of
`perceived loudness corresponds to a doubling of the volume. The
`API label for this selector is sovolume.
`
`typedef Fixed *speechInfo;
`
`Gets descriptive information for the type of speech synthesizer
`being used on the specified speech channel. The API label for this
`sehCKwissoSynthType
`
`typedef Speechversionlnfo *speechInfo;
`
`typedef struct Speechversionlnfo {
`
`OSType
`
`OSType
`
`synthType;
`
`// always 'ttsc'
`
`synthSubType;
`
`// synth flavor
`
`OSType
`
`synthManufacturer;// synth creator
`
`long
`
`synthFlags;
`
`// reserved
`
`Numversion synthversion;
`
`// synth version
`
`} Speechversionlnfo;
`
`Returns the sync message code for the most recently encountered
`embedded sync command at the audio output point. If no sync
`command has been encountered, 0 is returned. Refer to the section
`”Embedded Speech Commands,” later in this chapter, for infor1na-
`tion about sync commands. The API label for this selector is
`soRecentSynQ
`
`typedef OSType *speechInfo;
`
`Returns a list of phoneme symbols and example words defined for
`the current synthesizer. The input parameter is the address of a
`handle variable. On return, the PhonemeDescriptor parameter
`contains a handle to the array of phoneme definitions. Make sure to
`dispose of the handle when you are done using it. This information
`is normally used to indicate to the user the approximate sounds
`corresponding to various phonemes—an important feature in
`international speech. The API label for this selector is
`soPhonemeSymbols
`
`typedef PhonemeDescriptor ***speechInfo; // VAR
`Handle
`
`typedef struct Phonemelnfo {
`
`short opcode;
`
`// opcode for the phoneme
`
`Strl5 phStr;
`
`7/ corresponding char string
`
`Str3l examplestr;
`
`// word that shows use of
`
`// phoneme
`
`Using the Speech Manager
`
`Page 314 of 500
`
`Page 314 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`short hilitestart;
`
`// par: of example word
`
`short hiliteEnd;
`
`} Phonemelnfo;
`
`// to be hilighted as in
`// Tex:Edit selections
`
`typedef struct PhonemeDescriptor {
`
`// # of elements
`phonemecount;
`short
`Phonemelnfo thePhonemes[l]; // element list
`
`} PhonemeDescriptor;
`
`This call supports a general method for extending the functionality
`of the Speech Manager. It is used to get synthesizer-specific
`information. The format of the returned data is determined by the
`specific synthesizer queried. The speechlnf o argument should be
`a pointer to the proper data structure. If a particular
`synthcreator value is not recognized by the synthesizer, the
`command is ignored and the siUnknownInfoType code is
`returned. The API label for this selector is soSynthExtens ion.
`
`typedef SpeechXtndData *speechInfo;
`
`typedef struct SpeechXtndData {
`
`OSType
`
`synthcreator; // synth creator ID
`
`synthData[2]; // data TBD by synth
`Byte
`} SpeechXtndData;
`
`RESULTCODES
`
`noErr
`
`0
`
`No error
`
`s iUn known I n f oType
`invalidComponentID
`
`-231
`-3000
`
`Feature is not implemented on synthesizer
`Invalid Speechchannel parameter
`
`Advanced Control Routines
`
`The Speech Manager provides numerous control features for sophisticated developers.
`These controls enable you to set various speaking parameters programmatically and
`provide a rich set of callback routines that can be used to notify applications of various
`conditions within the speaking process. They are extended by many speech synthesizers.
`
`These controls are accessed with the Setspeechlnfo routine. All calls to this routine
`
`expect a speechchannel parameter, a selector to indicate the desired function, and a
`pointer to some data. The format of this data depends on the particular selector and is
`documented in the following routine description.
`
`Using the Speech Manager
`
`Page 315 of 500
`
`Page 315 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Setspeechlnfo
`
`TheSetspeechlnforoufineseminflunmfionforadeflgnamdspaxhchannd.
`
`pascal OSErr Setspeechlnfo (speechchannel chan, OSType selector,
`
`void *speechInfo);
`
`enum {
`
`// Sets the parameter:
`
`soInputMode
`soCharacterMode
`
`= 'inpt',
`‘char’,
`
`// current text/phon mode
`// current character mode
`
`soNumberMode
`
`'nmbr',
`
`// current number mode
`
`soRate
`
`soPitchBase
`
`soPitchMod
`
`sovolume
`
`soCurrentVoice
`soCommandDelimiter
`
`soReset
`
`soCurrentA5
`soRefCon
`
`‘rate’,
`
`'pbas',
`
`'pmod',
`
`'volm',
`
`'cvox',
`'dlim',
`
`// current speaking rate
`
`// current baseline pitch
`
`// current pitch modulation
`
`// current speaking volume
`
`// current speaking voice
`// command delimiters
`
`'rset',
`
`// re channel to default state
`
`'myA5',
`'refc',
`
`// app's A5 on callbacks
`// reference constant
`
`soTextDoneCallBack
`
`'tdcb',
`
`// text done callback proc
`
`soSpeechDoneCallBack
`
`'sdcb',
`
`// end—of—speech callback proc
`
`soSyncCal_Back
`
`'sycb',
`
`// sync command callback proc
`
`soErrorCa;lBack
`
`soPhonemeCallBack
`
`'ercb',
`
`'phcb',
`
`// error callback proc
`
`// phoneme callback proc
`
`soWordCallBack
`
`'wdcb',
`
`// word callback proc
`
`soSynthExtension
`
`'xtnd'
`
`// synthesizer—specific info
`
`chan
`
`Spedficspeednchannel
`
`selector
`
`Used to specify data being requested.
`
`* spee ch I n f o Pointer to an information structure.
`
`DESCRIPTION
`
`The following list of selectors outlines the controls available with the Speech
`Manager. The format of the information returned depends on which value is used
`in the selector field.
`
`UsmgtheSpeed1Manager
`
`Page 316 of 500
`
`Page 316 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Note
`
`The Speech Manager supports several callback features that can provide
`the sophisticated developer with a tight coupling to the speech synthesis
`process. However, these callbacks must be used carefully. Each is
`invoked from interrupt level. This means that you may not perform any
`operations that might cause memory to be allocated, purged, or moved.
`Although application global variables are also ordinarily not accessible
`at interrupt time, the soCurrentA5 myA5 selector described in the
`following text can be used to ask the Speech Manager to point register
`A5 at your application's global variables prior to each callback. This
`makes it fairly painless to access global variables from your callback
`handlers. If this information worries you, don't despair. Most
`information available through callbacks is also available through a
`Getspeechlnfo call. These calls are more friendly and do not come
`With the constraints imposed upon callback code. The only drawback
`is that if you do not poll the information you are interested in often
`enough, you may miss some of the changes in your speech channel's
`status. 0
`
`Field descriptions
`
`inpt
`
`Sets the current value of the text processing mode control. The
`passed value specifies whether the speech channel should be in
`text-input mode (TEXT) or phoneme-input mode (PHON). Input
`mode changes take effect as soon as possible; however, the precise
`latency is dependent upon the specific speech synthesizer. The API
`label for this selector is soInputMode.
`
`typedef OSType *speechInfo; // TEXT or PHON
`
`Sets the current value of the character processing mode control. The
`passed value specifies whether the speech channel should be in
`normal character processing mode (NORM) or literal, letter-by-letter,
`mode (LTRL). Character mode changes take effect as soon as
`possible; however, the precise latency is dependent upon the
`specific speech synthesizer. The API label for this selector is
`soCharacterMode.
`
`typedef OSType *speechInfo; // NORM or LTRL
`
`Sets the current value of the number processing mode control. The
`passed value specifies whether the specified speech channel should
`be in normal number processing mode (NORM) or in literal,
`digit-by-digit, mode (LTRL). The number mode changes take effect
`as soon as possible. However, the precise latency is dependent upon
`the specific speech synthesizer. The API label for this selector is
`soNumberMode.
`
`typedef OSType *speechInfo; // NORM or LTRL
`
`Using the Speech Manager
`
`Page 317 of 500
`
`Page 317 of 500
`
`

`
`CHAPTER 6
`
`Speech Manager
`
`Sets the speaking rate in words per minute on the specified channel.
`Speaking rates are fixed—point values. All values are valid; however,
`specific synthesizers will not necessarily be able to speak at all
`possible rates. The API label for this selector is soRate.
`
`typedef Fixed *speechInfo;
`
`Changes the current baseline pitch for the specified channel. The
`pitch value is a fixed—point integer that conforms to the following
`frequency relationship:
`
`Hertz = 440.0 * 2((BasePitch — 69)
`BasePitch of 1.0
`=
`9 Hertz
`
`/ 12)
`
`BasePitch of 39.5
`
`BasePitch of 45.8
`
`BasePitch of 50.4
`
`BasePitch of 100.0
`
`z
`
`=
`
`z
`
`=
`
`80 Hertz
`
`115 Hertz
`
`150 Hertz
`
`2637 Hertz
`
`BasePitch values are always positive numbers in the range from
`1.0 through 100.0.
`
`typedef Fixed *speechInfo;
`
`The API label for this selector is soPitchBase.
`
`Changes the current pitch modulation range