Deprecated Speech Synthesis Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.8

DisposeSpeechDoneUPP

Disposes of a universal procedure pointer (UPP) to a speech-done callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechDoneUPP (
   SpeechDoneUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

DisposeSpeechErrorUPP

Disposes of a universal procedure pointer (UPP) to an error callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechErrorUPP (
   SpeechErrorUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

DisposeSpeechPhonemeUPP

Disposes of a universal procedure pointer (UPP) to a phoneme callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechPhonemeUPP (
   SpeechPhonemeUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

DisposeSpeechSyncUPP

Disposes of a universal procedure pointer (UPP) to a synchronization callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechSyncUPP (
   SpeechSyncUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

DisposeSpeechTextDoneUPP

Disposes of a universal procedure pointer (UPP) to a text-done callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechTextDoneUPP (
   SpeechTextDoneUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

DisposeSpeechWordUPP

Disposes of a universal procedure pointer (UPP) to a word callback function. (Deprecated in OS X v10.8.)

void DisposeSpeechWordUPP (
   SpeechWordUPP userUPP
);
Parameters
userUPP

The UPP to dispose of.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

GetSpeechInfo

Gets information about a designated speech channel. (Deprecated in OS X v10.8.)

OSErr GetSpeechInfo (
   SpeechChannel chan,
   OSType selector,
   void *speechInfo
);
Parameters
chan

The speech channel about which information is being requested.

selector

A speech information selector that indicates the type of information being requested.

For a complete list of speech information selectors, see “Speech-Channel Information Constants.” This list indicates how your application should set the speechInfo parameter for each selector.

speechInfo

A pointer whose meaning depends on the speech information selector specified in the selector parameter.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

The GetSpeechInfo function returns, in the data structure pointed to by the speechInfo parameter, the type of information requested by the selector parameter as it applies to the speech channel specified in the chan parameter.

The format of the data structure specified by the speechInfo parameter depends on the selector you choose. For example, a selector might require that your application allocate a block of memory of a certain size and pass a pointer to that block. Another selector might require that speechInfo be set to the address of a handle variable. In this case, the GetSpeechInfo function would allocate a relocatable block of memory and change the handle variable specified to reference the block.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
SpeechSynthesis.h

InvokeSpeechDoneUPP

Invokes your speech-done callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechDoneUPP (
   SpeechChannel chan,
   SRefCon refCon,
   SpeechDoneUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechDoneUPP function, because the system calls your speech-done callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

InvokeSpeechErrorUPP

Invokes your error callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechErrorUPP (
   SpeechChannel chan,
   SRefCon refCon,
   OSErr theError,
   long bytePos,
   SpeechErrorUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechErrorUPP function, because the system calls your error callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

InvokeSpeechPhonemeUPP

Invokes your phoneme callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechPhonemeUPP (
   SpeechChannel chan,
   SRefCon refCon,
   SInt16 phonemeOpcode,
   SpeechPhonemeUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechPhonemeUPP function, because the system calls your phoneme callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

InvokeSpeechSyncUPP

Invokes your synchronization callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechSyncUPP (
   SpeechChannel chan,
   SRefCon refCon,
   OSType syncMessage,
   SpeechSyncUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechSyncUPP function, because the system calls your synchronization callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

InvokeSpeechTextDoneUPP

Invokes your text-done callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechTextDoneUPP (
   SpeechChannel chan,
   SRefCon refCon,
   const void **nextBuf,
   unsigned long *byteLen,
   SInt32 *controlFlags,
   SpeechTextDoneUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechTextDoneUPP function, because the system calls your text-done callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

InvokeSpeechWordUPP

Invokes your word callback function. (Deprecated in OS X v10.8.)

void InvokeSpeechWordUPP (
   SpeechChannel chan,
   SRefCon refCon,
   unsigned long wordPos,
   UInt16 wordLen,
   SpeechWordUPP userUPP
);
Discussion

You should not need to call the InvokeSpeechWordUPP function, because the system calls your word callback function for you.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechDoneUPP

Creates a new universal procedure pointer (UPP) to a speech-done callback function. (Deprecated in OS X v10.8.)

SpeechDoneUPP NewSpeechDoneUPP (
   SpeechDoneProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your speech-done callback function.

Return Value

A UPP to the speech-done callback function. See the description of the SpeechDoneUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechErrorUPP

Creates a new universal procedure pointer to an error callback function. (Deprecated in OS X v10.8.)

SpeechErrorUPP NewSpeechErrorUPP (
   SpeechErrorProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your error callback function.

Return Value

A UPP to the error callback function. See the description of the SpeechErrorUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechPhonemeUPP

Disposes of a universal procedure pointer (UPP) to a phoneme callback function. (Deprecated in OS X v10.8.)

SpeechPhonemeUPP NewSpeechPhonemeUPP (
   SpeechPhonemeProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your phoneme callback function.

Return Value

A UPP to the phoneme callback function. See the description of the SpeechPhonemeUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechSyncUPP

Creates a new universal procedure pointer (UPP) to a synchronization callback function. (Deprecated in OS X v10.8.)

SpeechSyncUPP NewSpeechSyncUPP (
   SpeechSyncProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your synchronization callback function.

Return Value

A UPP to the synchronization callback function. See the description of the SpeechSyncUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechTextDoneUPP

Creates a new universal procedure pointer (UPP) to a text-done callback function. (Deprecated in OS X v10.8.)

SpeechTextDoneUPP NewSpeechTextDoneUPP (
   SpeechTextDoneProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your text-done callback function.

Return Value

A UPP to the text-done callback function. See the description of the SpeechTextDoneUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

NewSpeechWordUPP

Creates a new universal procedure pointer (UPP) to a word callback function. (Deprecated in OS X v10.8.)

SpeechWordUPP NewSpeechWordUPP (
   SpeechWordProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your word callback function.

Return Value

A UPP to the word callback function. See the description of the SpeechWordUPP data type.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

SetSpeechInfo

Changes a setting of a particular speech channel. (Deprecated in OS X v10.8.)

OSErr SetSpeechInfo (
   SpeechChannel chan,
   OSType selector,
   const void *speechInfo
);
Parameters
chan

The speech channel for which your application wishes to change a setting.

selector

A speech information selector that indicates the type of information being changed.

For a complete list of speech information selectors, see “Speech-Channel Information Constants.” This list indicates how your application should set the speechInfo parameter for each selector.

speechInfo

A pointer whose meaning depends on the speech information selector specified in the selector parameter.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

The SetSpeechInfo function changes the type of setting indicated by the selector parameter in the speech channel specified by the chan parameter, based on the data your application provides via the speechInfo parameter.

The format of the data structure specified by the speechInfo parameter depends on the selector you choose. Ordinarily, a selector requires that speechInfo be a pointer to a data structure that specifies a new setting for the speech channel.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
SpeechSynthesis.h

SpeakBuffer

Speaks a buffer of text, using certain flags to control speech behavior. (Deprecated in OS X v10.8.)

OSErr SpeakBuffer (
   SpeechChannel chan,
   const void *textBuf,
   unsigned long textBytes,
   SInt32 controlFlags
);
Parameters
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.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

The SpeakBuffer function behaves identically to the SpeakText function, but allows control of several speech parameters by setting values of the controlFlags parameter. The controlFlags parameter relies on specific constants, which may be applied additively. See “Control Flags Constants.”

Each constant specifies a flag bit of the controlFlags parameter, so by passing the constants additively you can enable multiple capabilities of SpeakBuffer. If you pass 0 in the controlFlags parameter, SpeakBuffer works just like SpeakText. By passing kNoEndingProsody + kNoSpeechInterrupt in the controlFlags parameter, SpeakBuffer works like SpeakText except that the kNoEndingProsody and kNoSpeechInterrupt features have been selected. Future versions of the Speech Synthesis Manager may define additional constants.

When the controlFlags parameter is set to 0, SpeakBuffer behaves identically to SpeakText.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

SpeakString

Begins speaking a text string. (Deprecated in OS X v10.8.)

OSErr SpeakString (
   ConstStr255Param textToBeSpoken
);
Parameters
textToBeSpoken

The string to be spoken.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

The SpeakString function attempts to speak the Pascal-style text string contained in the string textToBeSpoken. Speech is produced asynchronously using the default system voice. When an application calls this function, the Speech Synthesis Manager makes a copy of the passed string and creates any structures required to speak it. As soon as speaking has begun, control is returned to the application. The synthesized speech is generated asynchronously to the application so that normal processing can continue while the text is being spoken. No further interaction with the Speech Synthesis Manager is required at this point, and the application is free to release the memory that the original string occupied.

If SpeakString is called while a prior string is still being spoken, the sound currently being synthesized is interrupted immediately. Conversion of the new text into speech is then begun. If you pass a zero-length string (or, in C, a null pointer) to SpeakString, the Speech Synthesis Manager stops any speech previously being synthesized by SpeakString without generating additional speech. If your application uses SpeakString, it is often a good idea to stop any speech in progress whenever your application receives a suspend event. Calling SpeakString with a zero-length string has no effect on speech channels other than the one managed internally by the Speech Synthesis Manager for the SpeakString function.)

The text passed to the SpeakString function may contain embedded speech commands.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
SpeechSynthesis.h

SpeakText

Begins speaking a buffer of text. (Deprecated in OS X v10.8.)

OSErr SpeakText (
   SpeechChannel chan,
   const void *textBuf,
   unsigned long textBytes
);
Parameters
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.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

Like SpeakString, the SpeakText function also generates speech, but through a speech channel through which you can exert control over the generated speech.

The SpeakText function converts the text stream specified by the textBuf and textBytes parameters into speech using the voice and control settings for the speech channel chan, which should be created with the NewSpeechChannel function. The speech is generated asynchronously. This means that control is returned to your application before the speech has finished (and probably even before it has begun). The maximum length of the text buffer that can be spoken is limited only by the available RAM.

If SpeakText is called while the channel is currently busy speaking the contents of a prior text buffer, it immediately stops speaking from the prior buffer and begins speaking from the new text buffer as soon as possible. If you pass a zero-length string (or, in C, a null pointer) to SpeakText, the Speech Synthesis Manager stops all speech currently being synthesized by the speech channel specified in the chan parameter without generating additional speech.

The text buffer must be locked in memory and must not move while the Speech Synthesis Manager processes it. This buffer is read at interrupt time, and moving it could cause a system crash. If your application defines a text-done callback function, then it can move the text buffer or dispose of it once the callback function is executed.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
SpeechSynthesis.h

TextToPhonemes

Converts a buffer of textual data into phonemic data. (Deprecated in OS X v10.8.)

OSErr TextToPhonemes (
   SpeechChannel chan,
   const void *textBuf,
   unsigned long textBytes,
   Handle phonemeBuf,
   long *phonemeBytes
);
Parameters
chan

A speech channel whose associated synthesizer and voice are to be used for the conversion process.

textBuf

A pointer to a buffer of text to be converted.

textBytes

The number of bytes of text to be converted.

phonemeBuf

A handle to a buffer to be used to store the phonemic data. The TextToPhonemes function may resize the relocatable block referenced by this handle.

phonemeBytes

On return, a pointer to the number of bytes of phonemic data written to the handle.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

Converting textual data into phonemic data is particularly useful during application development, when you might wish to adjust phrases that your application generates to produce smoother speech. 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.

The TextToPhonemes function converts the textBytes bytes of textual data pointed to by the textBuf parameter to phonemic data, which it writes into the relocatable block specified by the phonemeBuf parameter. If necessary, TextToPhonemes resizes this relocatable block. The TextToPhonemes function sets the phonemeBytes parameter to the number of bytes of phonemic data actually written.

If the textual data is contained in a relocatable block, a handle to that block must be locked before the TextToPhonemes function is called.

The data returned by TextToPhonemes corresponds precisely to the phonemes that would be spoken had the input text been sent to SpeakText instead. All current mode settings for the speech channel specified by chan are applied to the converted speech. No callbacks are generated while the TextToPhonemes function is generating its output.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
SpeechSynthesis.h

UseDictionary

Installs the designated dictionary into a speech channel. (Deprecated in OS X v10.8.)

OSErr UseDictionary (
   SpeechChannel chan,
   Handle dictionary
);
Parameters
chan

The speech channel into which a dictionary is to be installed.

dictionary

A handle to the dictionary data. This is often a handle to a resource of type 'dict'.

Return Value

A result code. See “Speech Synthesis Manager Result Codes.”

Discussion

The UseDictionary function attempts to install the dictionary data referenced by the dictionary parameter into the speech channel referenced by the chan parameter. The synthesizer will use whatever elements of the dictionary resource it considers useful to the speech conversion process. Some speech synthesizers might ignore certain types of dictionary entries.

After the UseDictionary function returns, your application is free to release any storage allocated for the dictionary handle. The search order for application-provided dictionaries is last-in, first-searched.

All details of how an application-provided dictionary is represented within the speech synthesizer are dependent on the specific synthesizer implementation and are private to the synthesizer.

Pronunciation dictionaries allow your application to override the default Speech Synthesis Manager pronunciations of individual words, such as names with unusual spellings.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Related Sample Code
Declared In
SpeechSynthesis.h