Speech Synthesis Manager

Overview

The Speech Synthesis Manager, formerly called the Speech Manager, is the part of the Mac OS that provides a standardized method for Mac apps 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. For example, 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.

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 these 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.

Gestalt Constants

You can check for version and feature availability information by using the Speech Synthesis Manager selectors defined in the Gestalt Manager. For more information see Inside macOS: Gestalt Manager Reference.

Topics

Changing Speech Attributes

SetSpeechInfo

Changes a setting of a particular speech channel.

Deprecated
SetSpeechProperty

Sets the value of the specified speech-channel property.

SetSpeechPitch

Sets the speech pitch on a designated speech channel.

SetSpeechRate

Sets the speech rate of a designated speech channel.

Converting Text To Phonemes

TextToPhonemes

Converts a buffer of textual data into phonemic data.

Deprecated
CopyPhonemesFromText

Converts the specified text string into its equivalent phonemic representation.

Installing a Pronunciation Dictionary

UseDictionary

Installs the designated dictionary into a speech channel.

Deprecated
UseSpeechDictionary

Registers a speech dictionary with a speech channel.

Managing Speech Channels

DisposeSpeechChannel

Disposes of an existing speech channel.

NewSpeechChannel

Creates a new speech channel.

Obtaining Information About Speech and Speech Channels

CopySpeechProperty

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

GetSpeechInfo

Gets information about a designated speech channel.

Deprecated
GetSpeechPitch

Gets a speech channel’s current speech pitch.

GetSpeechRate

Gets a speech channel’s current speech rate.

SpeechBusy

Determines whether any channels of speech are currently synthesizing speech.

SpeechBusySystemWide

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

SpeechManagerVersion

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

Getting Information About Voices

CountVoices

Determines how many voices are available.

GetIndVoice

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

GetVoiceDescription

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

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.

MakeVoiceSpec

Sets the fields of a voice specification structure.

Starting, Stopping, and Pausing Speech

ContinueSpeech

Resumes speech paused by the PauseSpeechAt function.

PauseSpeechAt

Pauses speech on a speech channel.

SpeakBuffer

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

Deprecated
SpeakString

Begins speaking a text string.

Deprecated
SpeakCFString

Begins speaking a string represented as a CFString object.

SpeakText

Begins speaking a buffer of text.

Deprecated
StopSpeech

Terminates speech immediately on the specified channel.

StopSpeechAt

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

Registering and Unregistering Synthesizers and Voices

SpeechSynthesisRegisterModuleURL

Registers and makes available a speech synthesizer or voice.

SpeechSynthesisUnregisterModuleURL

Unregisters a registered speech synthesizer or voice.

Creating, Invoking, and Disposing Universal Procedure Pointers

DisposeSpeechDoneUPP

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

Deprecated
DisposeSpeechErrorUPP

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

Deprecated
DisposeSpeechPhonemeUPP

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

Deprecated
DisposeSpeechSyncUPP

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

Deprecated
DisposeSpeechTextDoneUPP

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

Deprecated
DisposeSpeechWordUPP

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

Deprecated
InvokeSpeechDoneUPP

Invokes your speech-done callback function.

Deprecated
InvokeSpeechErrorUPP

Invokes your error callback function.

Deprecated
InvokeSpeechPhonemeUPP

Invokes your phoneme callback function.

Deprecated
InvokeSpeechSyncUPP

Invokes your synchronization callback function.

Deprecated
InvokeSpeechTextDoneUPP

Invokes your text-done callback function.

Deprecated
InvokeSpeechWordUPP

Invokes your word callback function.

Deprecated
NewSpeechDoneUPP

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

Deprecated
NewSpeechErrorUPP

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

Deprecated
NewSpeechPhonemeUPP

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

Deprecated
NewSpeechSyncUPP

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

Deprecated
NewSpeechTextDoneUPP

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

Deprecated
NewSpeechWordUPP

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

Deprecated

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.

SpeechErrorProcPtr

Defines a pointer to an error callback function that handles syntax errors within commands embedded in a text buffer being processed by the Speech Synthesis Manager.

SpeechErrorCFProcPtr

Defines a pointer to an error callback function that handles syntax errors within commands embedded in a CFString object being processed by the Speech Synthesis Manager.

SpeechPhonemeProcPtr

Defines a pointer to a phoneme callback function that is called by the Speech Synthesis Manager before it pronounces a phoneme.

SpeechSyncProcPtr

Defines a pointer to a synchronization callback function that is called when the Speech Synthesis Manager encounters a synchronization command embedded in a text buffer.

SpeechTextDoneProcPtr

Defines a pointer to a text-done callback function that is called when the Speech Synthesis Manager has finished processing a buffer of text.

SpeechWordProcPtr

Defines a pointer to a word callback function that is called by the Speech Synthesis Manager before it pronounces a word.

SpeechWordCFProcPtr

Defines a pointer to a Core Foundation-based word callback function that is called by the Speech Synthesis Manager before it pronounces a word.

Data Types

DelimiterInfo

Defines a delimiter information structure.

PhonemeDescriptor

Defines a phoneme descriptor structure.

PhonemeInfo

Defines a structure that stores information about a phoneme.

SpeechChannelRecord

Represents a speech channel.

SpeechChannel

Defines a pointer to a speech channel record.

SpeechDoneUPP

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

SpeechErrorInfo

Defines a speech error information structure.

SpeechErrorUPP

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

SpeechPhonemeUPP

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

SpeechStatusInfo

Defines a a speech status information structure, which stores information about the status of a speech channel.

SpeechSyncUPP

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

SpeechTextDoneUPP

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

SpeechVersionInfo

Defines a speech version information structure.

SpeechWordUPP

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

SpeechXtndData

Defines a speech extension data structure.

VoiceDescription

Defines a voice description structure.

VoiceFileInfo

Defines a voice file information structure.

VoiceSpec

Defines a voice specification structure.

Constants

Control Flags Constants

Flags that indicate which synthesizer features are active.

Gender Constants

Constants that indicate the gender of the individual represented by a voice.

Audio Unit Constants

Constants that identify values in a speech synthesis audio unit.

Stop Speech Locations

Locations that indicate where speech should be paused or stopped.

Speech Synthesis Manager Operating System Types

The OSType definitions used by the Speech Synthesis Manager.

Speech-Channel Modes

The available text-processing and number-processing modes for a speech channel.

Speech-Channel Modes for Core Foundation-based Functions

The available text-processing and number-processing modes for a speech channel.

Voice Information Selectors

The types of voice data that can be requested by the GetVoiceInfo function.

Speech-Channel Information Constants

Selectors that can be passed to the GetSpeechInfo or SetSpeechInfo functions.

Phoneme Generation Options

Flags that specify options for the generation of phonetic output.

Speech-Channel Properties

Properties used with CopySpeechProperty or SetSpeechProperty to get or set the characteristics of a speech channel.

Synthesizer Option Keys

Keys used to specify synthesizer options.

Speech Status Keys

Keys used with the kSpeechStatusProperty property to specify the status of the speech channel.

Speech Error Keys

Keys used with the kSpeechErrorsProperty property to describe errors encountered during speech processing and production.

Speech Synthesizer Information Keys

Keys used with the kSpeechSynthesizerInfoProperty property to get information about the synthesizer.

Phoneme Symbols Keys

Keys used with the kSpeechPhonemeSymbolsProperty property to provide information about the phoneme being processed.

Current Voice Keys

Keys used with the kSpeechCurrentVoiceProperty property to specify information about the current voice.

Command Delimiter Keys

Keys used with the kSpeechCommandDelimiterProperty property to specify information about the command delimiter strings.

Speech Dictionary Keys

Keys used in a speech dictionary to override the synthesizer’s default pronunciation of a word.

Error Callback User-Information String

Specifies information about the text being synthesized when an error occurs.

Result Codes

The most common result codes returned by Speech Synthesis Manager are listed below.

noSynthFound

Could not find the specified speech synthesizer

synthOpenFailed

Could not open another speech synthesizer channel

synthNotReady

Speech synthesizer is still busy speaking

bufTooSmall

Output buffer is too small to hold result

voiceNotFound

Voice resource not found

incompatibleVoice

Specified voice cannot be used with synthesizer

badDictFormat

Pronunciation dictionary format error

badInputText

Raw phoneme text contains invalid characters