Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Speech Synthesis Manager Reference

Framework
ApplicationServices/ApplicationServices.h
Declared in
SpeechSynthesis.h

Overview

The Speech Synthesis Manager, formerly called the Speech Manager, is the part of the Mac OS that provides a standardized method for Macintosh applications to generate synthesized speech. For example, you may want your application to incorporate the capability to speak its dialog box messages to the user. A word-processing application might use the Speech Synthesis Manager to implement a command that speaks a selected section of a document to the user. Because sound samples can take up large amounts of room on disk, using text in place of sampled sound is extremely efficient, and so a multimedia application might use the Speech Synthesis Manager to provide a narration of a QuickTime movie instead of including sampled-sound data on a movie track.

Mac OS X v10.5 introduces native support for performing speech synthesis tasks using Core Foundation-based objects, such as speaking text represented as CFString objects and managing speech channel properties using a CFDictionary-based property dictionary. You should begin using the new, Core Foundation-based programming interfaces as soon as it’s convenient, because future synthesizers will accept Core Foundation strings and data structures directly through the speech synthesis framework. In the meantime, existing buffer-based clients and synthesizers will continue to work as before, with strings and other data structures getting automatically converted as necessary.

Functions by Task

Changing Speech Attributes

Converting Text To Phonemes

Installing a Pronunciation Dictionary

Managing Speech Channels

Obtaining Information About Speech and Speech Channels

Getting Information About Voices

Starting, Stopping, and Pausing Speech

Creating, Invoking, and Disposing Universal Procedure Pointers

Functions

ContinueSpeech

Resumes speech paused by the PauseSpeechAt function.

OSErr ContinueSpeech (
   SpeechChannel chan
);

Parameters
chan

The paused speech channel on which speech is to be resumed.

Return Value

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

Discussion

At any time after the PauseSpeechAt function is called, the ContinueSpeech function can be called to continue speaking from the beginning of the word in which speech paused. Calling ContinueSpeech on a channel that is not currently in a paused state has no effect on the speech channel or on future calls to the PauseSpeechAt function. If you call ContinueSpeech on a channel before a pause is effective, ContinueSpeech cancels the pause.

If the PauseSpeechAt function stopped speech in the middle of a word, the Speech Synthesis Manager will start speaking that word from the beginning when you call ContinueSpeech.

Availability
Declared In
SpeechSynthesis.h

CopyPhonemesFromText

Converts the specified text string into its equivalent phonemic representation.

OSErr CopyPhonemesFromText (
   SpeechChannel chan,
   CFStringRef text,
   CFStringRef * phonemes
);

Parameters
chan

A speech channel whose associated synthesizer and properties are to be used in the conversion process.

text

The text from which to extract phonemic data.

phonemes

On return, a CFString object that contains the extracted phonemic data. The caller is responsible for releasing this object.

Return Value

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

Discussion

The CopyPhonemesFromText function is the Core Foundation-based equivalent of the TextToPhonemes function.

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 data the CopyPhonemesFromText function stores in the phonemes parameter corresponds precisely to the phonemes that would be spoken had the input text been sent to SpeakCFString instead. All current property settings for the speech channel specified by chan are applied to the converted speech. No callbacks are generated while the CopyPhonemesFromText function is generating its output.

Availability
Declared In
SpeechSynthesis.h

CopySpeechProperty

Gets the value associated with the specified property of a speech channel.

OSErr CopySpeechProperty (
   SpeechChannel chan,
   CFStringRef property,
   CFTypeRef * object
);

Parameters
chan

The speech channel with which the specified property is associated.

property

A speech-channel property about which information is being requested. See “Speech-Channel Properties” for information on the properties you can specify.

object

On return, a pointer to a Core Foundation object that holds the value of the specified property. The type of the object depends on the specific property passed in. For some properties, the value of object can be NULL. When the returned object is a CFDictionary object, you can use CFDictionary functions, such as CFDictionaryGetValue, to retrieve the values associated with the keys that are associated with the specified property.

Return Value

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

Discussion

The CopySpeechProperty function is the Core Foundation-based equivalent of the GetSpeechInfo function.

Availability
Declared In
SpeechSynthesis.h

CountVoices

Determines how many voices are available.

OSErr CountVoices (
   SInt16 *numVoices
);

Parameters
numVoices

On exit, a pointer to the number of voices that the application can use.

Return Value

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

Discussion

The CountVoices function returns, in the numVoices parameter, the number of voices available. The application can then use this information to call the GetIndVoice function to obtain voice specification structures for one or more of the voices.

Each time CountVoices is called, the Speech Synthesis Manager searches for new voices.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechChannel

Disposes of an existing speech channel.

OSErr DisposeSpeechChannel (
   SpeechChannel chan
);

Parameters
chan

The speech channel to dispose of.

Return Value

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

Discussion

The DisposeSpeechChannel function disposes of the speech channel specified in the chan parameter and releases all memory the channel occupies. If the speech channel specified is producing speech, then the DisposeSpeechChannel function immediately stops speech before disposing of the channel. If you have defined a text-done callback function or a speech-done callback function, the function will not be called before the channel is disposed of.

The Speech Synthesis Manager releases any speech channels that have not been explicitly disposed of by an application when the application quits. In general, however, your application should dispose of any speech channels it has created whenever it receives a suspend event. This ensures that other applications can take full advantage of Speech Synthesis Manager and Sound Manager capabilities.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechDoneUPP

Disposes of a universal procedure pointer (UPP) to a speech-done callback function.

void DisposeSpeechDoneUPP (
   SpeechDoneUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechErrorUPP

Disposes of a universal procedure pointer (UPP) to an error callback function.

void DisposeSpeechErrorUPP (
   SpeechErrorUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechPhonemeUPP

Disposes of a universal procedure pointer (UPP) to a phoneme callback function.

void DisposeSpeechPhonemeUPP (
   SpeechPhonemeUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechSyncUPP

Disposes of a universal procedure pointer (UPP) to a synchronization callback function.

void DisposeSpeechSyncUPP (
   SpeechSyncUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechTextDoneUPP

Disposes of a universal procedure pointer (UPP) to a text-done callback function. 

void DisposeSpeechTextDoneUPP (
   SpeechTextDoneUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

DisposeSpeechWordUPP

Disposes of a universal procedure pointer (UPP) to a word callback function.

void DisposeSpeechWordUPP (
   SpeechWordUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
SpeechSynthesis.h

GetIndVoice

Gets a voice specification structure for a voice by passing an index to the GetIndVoice function.

OSErr GetIndVoice (
   SInt16 index,
   VoiceSpec *voice
);

Parameters
index

The index of the voice for which to obtain a voice specification structure. This number must range from 1 to the total number of voices, as returned by the CountVoices function.

voice

A pointer to the voice specification structure whose fields are to be filled in.

Return Value

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

Discussion

The GetIndVoice function returns, in the voice specification structure pointed to by the voice parameter, a specification of the voice whose index is provided in the index parameter. Your application should make no assumptions about the order in which voices are indexed.

Your application should not add, remove, or modify a voice and then call the GetIndVoice function with an index value other than 1. To allow the Speech Synthesis Manager to update its information about voices, your application should always either call the CountVoices function or call the GetIndVoice function with an index value of 1 after adding, removing, or modifying a voice or after a time at which the user might have done so.

If you specify an index value beyond the number of available voices, the GetIndVoice function returns a voiceNotFound error.

Availability
Declared In
SpeechSynthesis.h

GetSpeechInfo

Gets information about a designated speech channel.

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
Declared In
SpeechSynthesis.h

GetSpeechPitch

Gets a speech channel’s current speech pitch.

OSErr GetSpeechPitch (
   SpeechChannel chan,
   Fixed *pitch
);

Parameters
chan

The speech channel whose pitch you wish to determine.

pitch

On return, a pointer to the current pitch of the voice in the speech channel, expressed as a fixed-point frequency value.

Return Value

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

Discussion

Typical voice frequencies 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 approximate pitch values in the ranges of 30.000 to 40.000 and 55.000 to 65.000, respectively.

Availability
Declared In
SpeechSynthesis.h

GetSpeechRate

Gets a speech channel’s current speech rate.

OSErr GetSpeechRate (
   SpeechChannel chan,
   Fixed *rate
);

Parameters
chan

The speech channel whose rate you wish to determine.

rate

On return, a pointer to the speech channel’s speech rate in words per minute, expressed as an integer value.

Return Value

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

Availability
Declared In
SpeechSynthesis.h

GetVoiceDescription

Gets a description of a voice by using the GetVoiceDescription function.

OSErr GetVoiceDescription (
   const VoiceSpec *voice,
   VoiceDescription *info,
   long infoLength
);

Parameters
voice

A pointer to the voice specification structure identifying the voice to be described, or NULL to obtain a description of the system default voice.

info

A pointer to a voice description structure. If this parameter is NULL, the function does not fill in the fields of the voice description structure; instead, it simply determines whether the voice parameter specifies an available voice and, if not, returns a voiceNotFound error.

infoLength

The length, in bytes, of the voice description structure. In the current version of the Speech Synthesis Manager, the voice description structure contains 362 bytes. However, you should always use the SizeOf function to determine the length of this structure.

Return Value

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

Discussion

The GetVoiceDescription function fills out the voice description structure pointed to by the info parameter with the correct information for the voice specified by the voice parameter. It fills in the length field of the voice description structure with the number of bytes actually copied. This value will always be less than or equal to the value that your application passes in infoLength before calling GetVoiceDescription. This scheme allows applications targeted for the current version of the Speech Synthesis Manager to work on future versions that might have longer voice description structures; it also allows you to write code for future versions of the Speech Synthesis Manager that will also run on computers that support only the current version.

If the voice specification structure does not identify an available voice, GetVoiceDescription returns a voiceNotFound error.

Availability
Declared In
SpeechSynthesis.h

GetVoiceInfo

Gets the same information about a voice that the GetVoiceDescription function provides, or to determine in which file and resource a voice is stored. 

OSErr GetVoiceInfo (
   const VoiceSpec *voice,
   OSType selector,
   void *voiceInfo
);

Parameters
voice

A pointer to the voice specification structure identifying the voice about which your application requires information, or NULL to obtain information on the system default voice.

selector

A specification of the type of data being requested. For current versions of the Speech Synthesis Manager, you should set this field either to soVoiceDescription, if you would like to use the GetVoiceInfo function to mimic the GetVoiceDescription function, or to soVoiceFile, if you would like to obtain information about the location of a voice on disk.

voiceInfo

A pointer to the appropriate data structure. If the selector is soVoiceDescription, then voiceInfo should be a pointer to a voice description structure, and the length field of the structure should be set to the length of the voice description structure. If the selector is soVoiceFile, then voiceInfo should be a pointer to a voice file information structure.

Return Value

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

Discussion

This function is intended primarily for use by synthesizers, but an application can call it too.

The GetVoiceInfo function accepts a selector in the selector parameter that determines the type of information you wish to obtain about the voice specified in the voice parameter. The function then fills the fields of the data structure appropriate to the selector you specify in the voiceInfo parameter.

If the voice specification is invalid, GetVoiceInfo returns a voiceNotFound error. If there is not enough memory to load the voice into memory to obtain information about it, GetVoiceInfo returns the result code memFullErr.

Availability
Declared In
SpeechSynthesis.h

InvokeSpeechDoneUPP

Invokes your speech-done callback function.

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
Declared In
SpeechSynthesis.h

InvokeSpeechErrorUPP

Invokes your error callback function.

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
Declared In
SpeechSynthesis.h

InvokeSpeechPhonemeUPP

Invokes your phoneme callback function.

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
Declared In
SpeechSynthesis.h

InvokeSpeechSyncUPP

Invokes your synchronization callback function.

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
Declared In
SpeechSynthesis.h

InvokeSpeechTextDoneUPP

Invokes your text-done callback function.

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
Declared In
SpeechSynthesis.h

InvokeSpeechWordUPP

Invokes your word callback function.

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
Declared In
SpeechSynthesis.h

MakeVoiceSpec

Sets the fields of a voice specification structure. 

OSErr MakeVoiceSpec (
   OSType creator,
   OSType id,
   VoiceSpec *voice
);

Parameters
creator

The ID of the synthesizer that your application requires.

id

The ID of the voice on the synthesizer specified by the creator parameter.

voice

A pointer to the voice specification structure whose fields are to be filled in.

Return Value

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

Discussion

A voice specification structure is a unique voice ID used by the Speech Synthesis Manager. Most voice management functions expect to be passed a pointer to a voice specification structure. When you already know the creator and ID for a voice, you should use the MakeVoiceSpec function to create such a structure rather than filling in the fields of one directly. On exit, the voice specification structure pointed to by the voice parameter contains the appropriate values. You should never set the fields of such a structure directly.

Availability
Declared In
SpeechSynthesis.h

NewSpeechChannel

Creates a new speech channel.

OSErr NewSpeechChannel (
   VoiceSpec *voice,
   SpeechChannel *chan
);

Parameters
voice

A pointer to the voice specification structure corresponding to the voice to be used for the new speech channel. Pass NULL to create a speech channel using the system default voice.

chan

On return, a pointer to a valid speech channel.

Return Value

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

Discussion

The NewSpeechChannel function allocates memory for a speech channel structure and sets the speech channel variable pointed to by the chan parameter to point to this speech channel structure. The Speech Synthesis Manager automatically locates and opens a connection to the proper synthesizer for the voice specified by the voice parameter.

There is no predefined limit to the number of speech channels an application can create. However, system constraints on available RAM, processor loading, and number of available sound channels limit the number of speech channels actually possible.

Your application should not attempt to manipulate the data pointed to by a variable of type SpeechChannel. The internal format that the Speech Synthesis Manager uses for speech channel data is not documented and may change in future versions of system software.

Availability
Declared In
SpeechSynthesis.h

NewSpeechDoneUPP

Creates a new universal procedure pointer (UPP) to a speech-done callback function.

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
Declared In
SpeechSynthesis.h

NewSpeechErrorUPP

Creates a new universal procedure pointer to an error callback function.

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
Declared In
SpeechSynthesis.h

NewSpeechPhonemeUPP

Disposes of a universal procedure pointer (UPP) to a phoneme callback function.

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
Declared In
SpeechSynthesis.h

NewSpeechSyncUPP

Creates a new universal procedure pointer (UPP) to a synchronization callback function.

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
Declared In
SpeechSynthesis.h

NewSpeechTextDoneUPP

Creates a new universal procedure pointer (UPP) to a text-done callback function.

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
Declared In
SpeechSynthesis.h

NewSpeechWordUPP

Creates a new universal procedure pointer (UPP) to a word callback function.

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
Declared In
SpeechSynthesis.h

PauseSpeechAt

Pauses speech on a speech channel.

OSErr PauseSpeechAt (
   SpeechChannel chan,
   SInt32 whereToPause
);

Parameters
chan

The speech channel on which speech is to be paused.

whereToPause

A constant indicating when speech processing should be paused. Pass the constant kImmediate to pause immediately, even in the middle of a word. Pass kEndOfWord or kEndOfSentence to pause speech at the end of the current word or sentence, respectively.

Return Value

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

Discussion

The PauseSpeechAt function makes speech production pause at a specified point in the text. PauseSpeechAt returns immediately, although speech output will continue until the specified point.

You can determine whether your application has paused speech output on a speech channel by obtaining a speech status information structure through the GetSpeechInfo function. While a speech channel is paused, the speech status information structure indicates that outputBusy and outputPaused are both TRUE.

If the end of the input text buffer is reached before the specified pause point, speech output pauses at the end of the buffer.

The PauseSpeechAt function differs from the StopSpeech and StopSpeechAt functions in that a subsequent call to ContinueSpeech, described next, causes the contents of the current text buffer to continue being spoken.

If you plan to continue speech synthesis from a paused speech channel, the text buffer being processed must remain available at all times and must not move while the channel is in a paused state.

Availability
Declared In
SpeechSynthesis.h

SetSpeechInfo

Changes a setting of a particular speech channel.

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
Declared In
SpeechSynthesis.h

SetSpeechPitch

Sets the speech pitch on a designated speech channel.

OSErr SetSpeechPitch (
   SpeechChannel chan,
   Fixed pitch
);

Parameters
chan

The speech channel whose pitch you wish to set.

pitch

The new pitch for the speech channel, expressed as a fixed-point frequency value.

Return Value

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

Discussion

The SetSpeechPitch function changes the current speech pitch on the speech channel specified by the chan parameter to the pitch specified by the pitch parameter. Typical voice frequencies 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 approximate pitch values in the ranges of 30.000 to 40.000 and 55.000 to 65.000, respectively. Although fixed-point values allow you to specify a wide range of pitches, not all synthesizers will support the full range of pitches. If your application specifies a pitch that a synthesizer cannot handle, it may adjust the pitch to fit within an acceptable range.

Availability
Declared In
SpeechSynthesis.h

SetSpeechProperty

Sets the value of the specified speech-channel property.

OSErr SetSpeechProperty (
   SpeechChannel chan,
   CFStringRef property,
   CFTypeRef object
);

Parameters
chan

The speech channel whose property to set.

property

The speech-channel property to set to the specified value.

object

The value to which the specified speech-channel property should be set. For some properties, this value can be NULL.

Return Value

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

Discussion

The SetSpeechProperty function is the Core Foundation-based equivalent of the SetSpeechInfo function.

See “Speech-Channel Properties” for information on the properties you can specify.

Availability
Declared In
SpeechSynthesis.h

SetSpeechRate

Sets the speech rate of a designated speech channel.

OSErr SetSpeechRate (
   SpeechChannel chan,
   Fixed rate
);

Parameters
chan

The speech channel whose rate you wish to set.

rate

The new speech rate in words per minute, expressed as an integer value.

Return Value

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

Discussion

The SetSpeechRate function adjusts the speech rate on the speech channel specified by the chan parameter to the rate specified by the rate parameter. As a general rule, speaking rates range from around 150 words per minute to around 220 words per minute. It is important to keep in mind, however, 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.

Note: the new speech rate should be expressed as an integer (not a fixed point decimal number as the data type implies).

Availability
Declared In
SpeechSynthesis.h

SpeakBuffer

Speaks a buffer of text, using certain flags to control speech behavior.

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
Declared In
SpeechSynthesis.h

SpeakCFString

Begins speaking a string represented as a CFString object.

OSErr SpeakCFString (
   SpeechChannel chan,
   CFStringRef aString,
   CFDictionaryRef options
);

Parameters
chan

The speech channel through which speech is to be spoken.

aString

The string to be spoken, represented as a CFString object.

options

An optional dictionary of key-value pairs used to customize speech behavior. See “Synthesizer Option Keys” for the available keys.

Return Value

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

Discussion

The SpeakCFString function is the Core Foundation-based equivalent of the SpeakBuffer function.

The SpeakCFString function converts the text string specified in aString into speech, using the voice and control settings in effect for the speech channel specified in chan. (Before you use SpeakCFString, therefore, be sure you’ve created a speech channel with the NewSpeechChannel function.) The SpeakCFString function generates speech asynchronously, which means that control is returned to your application before speech has finished, perhaps even before the speech is first audible.

If SpeakCFString is called while the speech channel is currently speaking the contents of another text string, the speech stops immediately and the new text string is spoken as soon as possible.

Availability
Declared In
SpeechSynthesis.h

SpeakString

Begins speaking a text string.

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
Declared In
SpeechSynthesis.h

SpeakText

Begins speaking a buffer of text.

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
Declared In
SpeechSynthesis.h

SpeechBusy

Determines whether any channels of speech are currently synthesizing speech.

SInt16 SpeechBusy (
   void
);

Return Value

The number of speech channels that are currently synthesizing speech in the application. This is useful when you want to ensure that an earlier speech request has been completed before having the system speak again. Paused speech channels are counted among those that are synthesizing speech.

The speech channel that the Speech Synthesis Manager allocates internally in response to calls to the SpeakString function is counted in the number returned by SpeechBusy. Thus, if you use just SpeakString to initiate speech, SpeechBusy always returns 1 as long as speech is being produced. When SpeechBusy returns 0, all speech has finished.

Availability
Declared In
SpeechSynthesis.h

SpeechBusySystemWide

Determines if any speech is currently being synthesized in your application or elsewhere on the computer.

SInt16 SpeechBusySystemWide (
   void
);

Return Value

The total number of speech channels currently synthesizing speech on the computer, whether they were initiated by your application or process’s code or by some other process executing concurrently. Paused speech channels are counted among those channels that are synthesizing speech.

Discussion

This function is useful when you want to ensure that no speech is currently being produced anywhere on the Macintosh computer before initiating speech. Although the Speech Synthesis Manager allows different applications to produce speech simultaneously, this can be confusing to the user. As a result, it is often a good idea for your application to check that no other process is producing speech before producing speech itself. If the difference between the values returned by SpeechBusySystemWide and the SpeechBusy function is 0, no other process is producing speech.

Availability
Declared In
SpeechSynthesis.h

SpeechManagerVersion

Determines the current version of the Speech Synthesis Manager installed in the system.

NumVersion SpeechManagerVersion (
   void
);

Return Value

The version of the Speech Synthesis Manager installed in the system, in the format of the first 4 bytes of a 'vers' resource.

Discussion

Use this call to determine whether your program can access features of the Speech Synthesis Manager that are included in some Speech Synthesis Manager releases but not in earlier ones.

Availability
Declared In
SpeechSynthesis.h

StopSpeech

Terminates speech immediately on the specified channel.

OSErr StopSpeech (
   SpeechChannel chan
);

Parameters
chan

The speech channel on which speech is to be stopped.

Return Value

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

Discussion

The StopSpeech function immediately terminates speech on the channel specified by the chan parameter. After returning from StopSpeech, your application can safely release any text buffer that the speech synthesizer has been using. You can call StopSpeech for an already idle channel without ill effect.

You can also stop speech by passing a zero-length string (or, in C, a null pointer) to one of the SpeakString, SpeakText, or SpeakBuffer functions. Doing this stops speech only in the specified speech channel (or, in the case of SpeakString, in the speech channel managed internally by the Speech Synthesis Manager).

Before calling the StopSpeech function, you can use the SpeechBusy function, which is described in SpeechBusy, to determine if a synthesizer is still speaking. If you are working with multiple speech channels, you can use the status selector with the function GetSpeechInfo which is described in GetSpeechInfo, to determine if a specific channel is still speaking.

Availability
Declared In
SpeechSynthesis.h

StopSpeechAt

Terminates speech delivery on a specified channel either immediately or at the end of the current word or sentence.

OSErr StopSpeechAt (
   SpeechChannel chan,
   SInt32 whereToStop
);

Parameters
chan

The speech channel on which speech is to be stopped.

whereToStop

A constant indicating when speech processing should stop. Pass the constant kImmediate to stop immediately, even in the middle of a word. Pass kEndOfWord or kEndOfSentence to stop speech at the end of the current word or sentence, respectively.

Return Value

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

Discussion

The StopSpeechAt function halts the production of speech on the channel specified by chan at a specified point in the text. This function returns immediately, although speech output continues until the specified point has been reached.

If you call the StopSpeechAt function before the Speech Synthesis Manager finishes processing input text, then the function might return before some input text has yet to be spoken. Thus, before disposing of the text buffer, your application should wait until its text-done callback function has been called (if one has been defined), or until it can determine (by, for example obtaining a speech status information structure) that the Speech Synthesis Manager is no longer processing input text.

If the end of the input text buffer is reached before the specified stopping point, the speech synthesizer stops at the end of the buffer without generating an error.

Availability
Declared In
SpeechSynthesis.h

TextToPhonemes

Converts a buffer of textual data into phonemic data.

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
Declared In
SpeechSynthesis.h

UseDictionary

Installs the designated dictionary into a speech channel.

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
Declared In
SpeechSynthesis.h

UseSpeechDictionary

Registers a speech dictionary with a speech channel.

OSErr UseSpeechDictionary (
   SpeechChannel chan,
   CFDictionaryRef speechDictionary
);

Parameters
chan

The speech channel with which the specified speech dictionary is to be registered.

speechDictionary

A speech dictionary to be registered with the specified speech channel, represented as a CFDictionary object. See “Speech Dictionary Keys” for the keys you can use in the dictionary.

Return Value

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

Discussion

The UseSpeechDictionary function is the Core Foundation-based equivalent of the UseDictionary function.

The UseSpeechDictionary function registers the CFDictionary object referenced by the speechDictionary parameter with the speech channel referenced by the chan parameter. Speech dictionaries allow your application to override a synthesizer's default pronunciations of individual words, such as names with unusual spellings. A synthesizer will use whatever elements of the dictionary it considers useful in the speech conversion process. Some speech synthesizers might ignore certain types of dictionary entries.

Multiple dictionaries can be registered with a synthesizer. If the same word appears in multiple dictionaries, the synthesizer will use the one from the dictionary with the most recent date.

Note that because a speech dictionary is a CFDictionary object, it can be loaded from an XML-based property list file. An example of such a file is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>LocaleIdentifier</key>
    <string>en_US</string>
    <key>ModificationDate</key>
    <string>2006-12-21 11:59:25 -0800</string>
    <key>Pronunciations</key>
    <array>
        <dict>
            <key>Phonemes</key>
            <string>_hEY_yUW</string>
            <key>Spelling</key>
            <string>Hello</string>
        </dict>
    </array>
    <key>Abbreviations</key>
    <array>
        <dict>
            <key>Phonemes</key>
            <string>_OW_sAEkz</string>
            <key>Spelling</key>
            <string>OSAX</string>
        </dict>
    </array>
</dict>
</plist>

After the UseSpeechDictionary function returns, your application is free to release the CFDictionary object referenced by the speechDictionary parameter.

Availability
Declared In
SpeechSynthesis.h

Callbacks

SpeechDoneProcPtr

Defines a pointer to a speech-done callback function which is called when the Speech Synthesis Manager finishes speaking a buffer of text.

typedef void (*SpeechDoneProcPtr) (
   SpeechChannel chan,
   SRefCon refCon
);

If you name your function MySpeechDoneProc, you would declare it like this:

void MySpeechDoneProc (
   SpeechChannel chan,
   long refCon
);

Parameters
chan

The speech channel that has finished processing input text.

refCon

The reference constant associated with the speech channel.

Discussion

If a speech-done callback function is installed in a speech channel, then the Speech Synthesis Manager calls this function when it finishes speaking a buffer of text.

You can specify a speech-done callback function by passing the soSpeechDoneCallBack selector to the SetSpeechInfo function.

You might use a speech-done callback function if you need to update some visual indicator that shows what text is currently being spoken. For example, suppose your application passes text buffers to the Speech Synthesis Manager one paragraph at a time. Your speech-done callback function might set a global flag variable to indicate to the application that the Speech Synthesis Manager has finished speaking a paragraph. When a function called by your application’s main event loop checks the global flag variable and determines that it has been set, the function might ensure that the next paragraph of text is visible.

You might use a speech-done callback function to set a flag variable that alerts the application that it should pass a new buffer of text to the Speech Synthesis Manager. If you do so, however, there might be a noticeable pause as the Speech Synthesis Manager switches from processing one text buffer t