Speech Synthesis Manager Reference

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.

Functions by Task

Changing Speech Attributes

• SetSpeechProperty
• SetSpeechPitch
• SetSpeechRate
• SetSpeechInfo Deprecated in OS X v10.8

Converting Text To Phonemes

• CopyPhonemesFromText
• TextToPhonemes Deprecated in OS X v10.8

Installing a Pronunciation Dictionary

• UseSpeechDictionary
• UseDictionary Deprecated in OS X v10.8

Managing Speech Channels

• DisposeSpeechChannel
• NewSpeechChannel

Obtaining Information About Speech and Speech Channels

• CopySpeechProperty
• GetSpeechPitch
• GetSpeechRate
• SpeechBusy
• SpeechBusySystemWide
• SpeechManagerVersion
• GetSpeechInfo Deprecated in OS X v10.8

Getting Information About Voices

• CountVoices
• GetIndVoice
• GetVoiceDescription
• GetVoiceInfo
• MakeVoiceSpec

Starting, Stopping, and Pausing Speech

• ContinueSpeech
• PauseSpeechAt
• SpeakCFString
• StopSpeech
• StopSpeechAt
• SpeakBuffer Deprecated in OS X v10.8
• SpeakString Deprecated in OS X v10.8
• SpeakText Deprecated in OS X v10.8

Registering and Unregistering Synthesizers and Voices

• SpeechSynthesisRegisterModuleURL
• SpeechSynthesisUnregisterModuleURL

Creating, Invoking, and Disposing Universal Procedure Pointers

• DisposeSpeechDoneUPP Deprecated in OS X v10.8
• DisposeSpeechErrorUPP Deprecated in OS X v10.8
• DisposeSpeechPhonemeUPP Deprecated in OS X v10.8
• DisposeSpeechSyncUPP Deprecated in OS X v10.8
• DisposeSpeechTextDoneUPP Deprecated in OS X v10.8
• DisposeSpeechWordUPP Deprecated in OS X v10.8
• InvokeSpeechDoneUPP Deprecated in OS X v10.8
• InvokeSpeechErrorUPP Deprecated in OS X v10.8
• InvokeSpeechPhonemeUPP Deprecated in OS X v10.8
• InvokeSpeechSyncUPP Deprecated in OS X v10.8
• InvokeSpeechTextDoneUPP Deprecated in OS X v10.8
• InvokeSpeechWordUPP Deprecated in OS X v10.8
• NewSpeechDoneUPP Deprecated in OS X v10.8
• NewSpeechErrorUPP Deprecated in OS X v10.8
• NewSpeechPhonemeUPP Deprecated in OS X v10.8
• NewSpeechSyncUPP Deprecated in OS X v10.8
• NewSpeechTextDoneUPP Deprecated in OS X v10.8
• NewSpeechWordUPP Deprecated in OS X v10.8

Functions

ContinueSpeech

Resumes speech paused by the PauseSpeechAt function.

OSErr ContinueSpeech (
   SpeechChannel chan
);

CopyPhonemesFromText

Converts the specified text string into its equivalent phonemic representation.

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

CopySpeechProperty

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

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

CountVoices

Determines how many voices are available.

OSErr CountVoices (
   SInt16 *numVoices
);

DisposeSpeechChannel

Disposes of an existing speech channel.

OSErr DisposeSpeechChannel (
   SpeechChannel chan
);

GetIndVoice

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

OSErr GetIndVoice (
   SInt16 index,
   VoiceSpec *voice
);

GetSpeechPitch

Gets a speech channel’s current speech pitch.

OSErr GetSpeechPitch (
   SpeechChannel chan,
   Fixed *pitch
);

GetSpeechRate

Gets a speech channel’s current speech rate.

OSErr GetSpeechRate (
   SpeechChannel chan,
   Fixed *rate
);

GetVoiceDescription

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

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

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
);

MakeVoiceSpec

Sets the fields of a voice specification structure.

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

NewSpeechChannel

Creates a new speech channel.

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

PauseSpeechAt

Pauses speech on a speech channel.

OSErr PauseSpeechAt (
   SpeechChannel chan,
   SInt32 whereToPause
);

SetSpeechPitch

Sets the speech pitch on a designated speech channel.

OSErr SetSpeechPitch (
   SpeechChannel chan,
   Fixed pitch
);

SetSpeechProperty

Sets the value of the specified speech-channel property.

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

SetSpeechRate

Sets the speech rate of a designated speech channel.

OSErr SetSpeechRate (
   SpeechChannel chan,
   Fixed rate
);

SpeakCFString

Begins speaking a string represented as a CFString object.

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

SpeechBusy

Determines whether any channels of speech are currently synthesizing speech.

SInt16 SpeechBusy (
   void
);

SpeechBusySystemWide

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

SInt16 SpeechBusySystemWide (
   void
);

SpeechManagerVersion

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

NumVersion SpeechManagerVersion (
   void
);

SpeechSynthesisRegisterModuleURL

Registers and makes available a speech synthesizer or voice.

OSErr SpeechSynthesisRegisterModuleURL (
   CFURLRef url
);

SpeechSynthesisUnregisterModuleURL

Unregisters a registered speech synthesizer or voice.

OSErr SpeechSynthesisUnregisterModuleURL (
   url
);

StopSpeech

Terminates speech immediately on the specified channel.

OSErr StopSpeech (
   SpeechChannel chan
);

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
);

UseSpeechDictionary

Registers a speech dictionary with a speech channel.

OSErr UseSpeechDictionary (
   SpeechChannel chan,
   CFDictionaryRef speechDictionary
);

<?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>

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
);

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.

typedef void (*SpeechErrorCFProcPtr) (
   SpeechChannel chan,
   SRefCon refCon,
   CFErrorRef theError
);

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

void MySpeechErrorCFProc (
   SpeechChannel chan,
   long refCon,
   CFErrorRef theError
);

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.

typedef void (*SpeechErrorProcPtr) (
   SpeechChannel chan,
   SRefCon refCon,
   OSErr theError,
   long bytePos
);

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

void MySpeechErrorProc (
   SpeechChannel chan,
   long refCon,
   OSErr theError,
   long bytePos
);

SpeechPhonemeProcPtr

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

typedef void (*SpeechPhonemeProcPtr)
(
   SpeechChannel chan,
   SRefCon refCon,
   short phonemeOpcode
);

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

void MySpeechPhonemeProc (
   SpeechChannel chan,
   long refCon,
   short phonemeOpcode
);

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.

typedef void (*SpeechSyncProcPtr) (
   SpeechChannel chan,
   SRefCon refCon,
   OSType syncMessage
);

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

void MySpeechSyncProc (
   SpeechChannel chan,
   long refCon,
   OSType syncMessage
);

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.

typedef void (*SpeechTextDoneProcPtr)
(
   SpeechChannel chan,
   SRefCon refCon,
   void ** nextBuf,
   unsigned long * byteLen,
   long * controlFlags
);

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

void MySpeechTextDoneProc (
   SpeechChannel chan,
   long refCon,
   void ** nextBuf,
   unsigned long * byteLen,
   long * controlFlags
);

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.

typedef void (*SpeechWordCFProcPtr) (
   SpeechChannel chan,
   SRefCon refCon,
   CFStringRef aString,
   CFRange wordRange
);

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

void MySpeechWordCFProc (
   SpeechChannel chan,
   SRefCon refCon,
   CFStringRef aString,
   CFRange wordRange
);

SpeechWordProcPtr

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

typedef void (*SpeechWordProcPtr) (
   SpeechChannel chan,
   SRefCon refCon,
   unsigned long wordPos,
   unsigned short wordLen
);

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

void MySpeechWordProc (
   SpeechChannel chan,
   long refCon,
   unsigned long wordPos,
   unsigned short wordLen
);

Data Types

DelimiterInfo

Defines a delimiter information structure.

struct DelimiterInfo {
   Byte startDelimiter[2];
   Byte endDelimiter[2];
};
typedef struct DelimiterInfo DelimiterInfo;

Fields

startDelimiter

The start delimiter for an embedded command. By default, the start delimiter is “[[”.

endDelimiter

The end delimiter for an embedded command. By default, the end delimiter is “]]”.

PhonemeDescriptor

Defines a phoneme descriptor structure.

struct PhonemeDescriptor {
   SInt16 phonemeCount;
   PhonemeInfo thePhonemes[1];
};
typedef struct PhonemeDescriptor PhonemeDescriptor;

Fields

phonemeCount

The number of phonemes that the current synthesizer defines. Typically, this will correspond to the number of phonemes in the language supported by the synthesizer.

thePhonemes

An array of phoneme information structures.

PhonemeInfo

Defines a structure that stores information about a phoneme.

struct PhonemeInfo {
   SInt16 opcode;
   Str15 phStr;
   Str31 exampleStr;
   SInt16 hiliteStart;
   SInt16 hiliteEnd;
};
typedef struct PhonemeInfo PhonemeInfo;

Fields

opcode

The opcode for the phoneme.

phStr

The string used to represent the phoneme. The string does not necessarily have a phonetic connection to the phoneme, but might simply be an abstract textual representation of it.

exampleStr

An example word that illustrates use of the phoneme.

hiliteStart

The number of characters in the example word that precede the portion of that word representing the phoneme.

hiliteEnd

The number of characters between the beginning of the example word and the end of the portion of that word representing the phoneme.

SpeechChannelRecord

Represents a speech channel.

struct SpeechChannelRecord {
   long data[1];
};
typedef struct SpeechChannelRecord SpeechChannelRecord;

SpeechChannel

Defines a pointer to a speech channel record.

typedef SpeechChannelRecord * SpeechChannel;

SpeechDoneUPP

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

typedef SpeechDoneProcPtr SpeechDoneUPP;

SpeechErrorInfo

Defines a speech error information structure.

struct SpeechErrorInfo {
   SInt16 count;
   OSErr oldest;
   long oldPos;
   OSErr newest;
   long newPos;
};
typedef struct SpeechErrorInfo SpeechErrorInfo;

Fields

count

The number of errors that have occurred in processing the current text buffer since the last call to the GetSpeechInfo function with the soErrors selector. Of these errors, you can find information about only the first and last error that occurred.

oldest

The error code of the first error that occurred after the previous call to the GetSpeechInfo function with the soErrors selector.

oldPos

The character position within the text buffer being processed of the first error that occurred after the previous call to the GetSpeechInfo function with the soErrors selector.

newest

The error code of the most recent error.

newPos

The character position within the text buffer being processed of the most recent error.

SpeechErrorUPP

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

typedef SpeechErrorProcPtr SpeechErrorUPP;

SpeechPhonemeUPP

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

typedef SpeechPhonemeProcPtr SpeechPhonemeUPP;

SpeechStatusInfo

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

struct SpeechStatusInfo {
   Boolean outputBusy;
   Boolean outputPaused;
   long inputBytesLeft;
   SInt16 phonemeCode;
};
typedef struct SpeechStatusInfo SpeechStatusInfo;

Fields

outputBusy

Whether the speech channel is currently producing speech. A speech channel is considered to be producing speech even at some times when no audio data is being produced through the Macintosh speaker. This occurs, for example, when the Speech Synthesis Manager is processing an input buffer but has not yet initiated speech or when speech output is paused.

outputPaused

Whether speech output in the speech channel has been paused by a call to the PauseSpeechAt function.

inputBytesLeft

The number of input bytes of the text that the speech channel must still process. When inputBytesLeft is 0, the buffer of input text passed to one of the SpeakText or SpeakBuffer functions may be disposed of. When you call the SpeakString function, the Speech Synthesis Manager stores a duplicate of the string to be spoken in an internal buffer; thus, you may delete the original string immediately after calling SpeakString.

phonemeCode

The opcode for the phoneme that the speech channel is currently processing.

SpeechSyncUPP

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

typedef SpeechSyncProcPtr SpeechSyncUPP;

SpeechTextDoneUPP

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

typedef SpeechTextDoneProcPtr SpeechTextDoneUPP;

SpeechVersionInfo

Defines a speech version information structure.

struct SpeechVersionInfo {
   OSType synthType;
   OSType synthSubType;
   OSType synthManufacturer;
   SInt32 synthFlags;
   NumVersion synthVersion;
};
typedef struct SpeechVersionInfo SpeechVersionInfo;

Fields

synthType

The general type of the synthesizer. For the current version of the Speech Synthesis Manager, this field always contains the value kTextToSpeechSynthType, indicating that the synthesizer converts text into speech.

synthSubType

The specific type of the synthesizer. Currently, no specific types of synthesizer are defined. If you define a new type of synthesizer, you should register the four-character code for your type with Developer Technical Support.

synthManufacturer

A unique identification of a synthesizer engine. If you develop synthesizers, then you should register a different four-character code for each synthesizer you develop with Developer Technical Support. The creatorID field of the voice specification structure and the synthCreator field of a speech extension data structure should each be set to the value stored in this field for the desired synthesizer.

synthFlags

A set of flags indicating which synthesizer features are activated. Specific constants define the bits in this field whose meanings are defined for all synthesizers.

synthVersion

The version number of the synthesizer.

SpeechWordUPP

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

typedef SpeechWordProcPtr SpeechWordUPP;

SpeechXtndData

Defines a speech extension data structure.

struct SpeechXtndData {
   OSType synthCreator;
   Byte synthData[2];
};
typedef struct SpeechXtndData SpeechXtndData;

Fields

synthCreator

The synthesizer’s creator ID, identical to the value stored in the synthManufacturer field of a speech version information structure. You should set this field to the appropriate value before calling GetSpeechInfo or SetSpeechInfo.

synthData

Synthesizer-specific data. The size and format of the data in this field may vary.

VoiceDescription

Defines a voice description structure.

struct VoiceDescription {
   SInt32 length;
   VoiceSpec voice;
   SInt32 version;
   Str63 name;
   Str255 comment;
   SInt16 gender;
   SInt16 age;
   SInt16 script;
   SInt16 language;
   SInt16 region;
   SInt32 reserved[4];
};
typedef struct VoiceDescription VoiceDescription;

Fields

length

The size of the voice description structure, in bytes.

voice

A voice specification structure that uniquely identifies the voice.

version

The version number of the voice.

name

The name of the voice, preceded by a length byte. Names must be 63 characters or less.

comment

Additional text information about the voice. Some synthesizers use this field to store a phrase that can be spoken.

gender

The gender of the individual represented by the voice. See “Gender Constants.”

age

The approximate age in years of the individual represented by the voice.

script

In OS X v10.4.7 and later, the encoding code of the text that the voice can process.

Note that this field contains a 16-bit value. You can use any of the 16-bit values described in External_String_Encodings or CFStringBuiltInEncodings. However, if you need to use a 32-bit value, such as kCFStringEncodingUTF8, you pass the value in the first array element of the reserved field, and you also need to specify -1 or kCFStringEncodingInvalidId in the script field.

language

A code that indicates the language of voice output.

region

A code that indicates the region represented by the voice.

reserved

Reserved. May be used to hold a 32-bit encoding value, if necessary (see the description of the script field for more information).

VoiceFileInfo

Defines a voice file information structure.

struct VoiceFileInfo {
   FSSpec fileSpec;
   SInt16 resID;
};
typedef struct VoiceFileInfo VoiceFileInfo;

Fields

fileSpec

A file system specification structure that contains the volume, directory, and name of the file containing the voice. Generally, files containing a single voice are of type kTextToSpeechVoiceFileType, and files containing multiple voices are of type kTextToSpeechVoiceBundleType.

resID

The resource ID of the voice in the file. Voices are stored in resources of type kTextToSpeechVoiceType.

VoiceSpec

Defines a voice specification structure.

struct VoiceSpec {
   OSType creator;
   OSType id;
};
typedef struct VoiceSpec VoiceSpec;
   typedef VoiceSpec * VoiceSpecPtr;

Fields

creator

The synthesizer that is required to use the voice. This is equivalent to the value contained in the synthManufacturer field of a speech version information structure and that contained in the synthCreator field of a speech extension data structure. The set of OSType values specified entirely by space characters and lowercase letters is reserved.

id

The voice ID of the voice for the synthesizer. Every voice on a synthesizer has a unique ID.

Constants

Control Flags Constants

Flags that indicate which synthesizer features are active.

enum {
   kNoEndingProsody = 1,
   kNoSpeechInterrupt = 2,
   kPreflightThenPause = 4
};

Constants

kNoEndingProsody

Disables prosody at end of sentences. 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.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kNoSpeechInterrupt

Does not interrupt current speech. 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. 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. One way of achieving continuous speech without using callback functions is to continually call SpeakBuffer with the kNoSpeechInterrupt flag bit set until the function returns noErr. The function will then execute as soon as the first text buffer has been processed.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kPreflightThenPause

Computes speech without generating.The kPreflightThenPause 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 might be detrimental to certain applications, a mechanism exists to allow the synthesizer to perform any necessary computations at noncritical times. Once the computations have been completed, the speech is able to start instantly. When the kPreflightThenPause 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 ContinueSpeech function to begin speaking.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Gender Constants

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

enum {
   kNeuter = 0,
   kMale = 1,
   kFemale = 2
};

Constants

kNeuter

Neuter voice.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kMale

Male voice.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kFemale

Female voice.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Audio Unit Constants

Constants that identify values in a speech synthesis audio unit.

enum {
   kAudioUnitSubType_SpeechSynthesis = 'ttsp',
   kAudioUnitProperty_Voice      = 3330,
   kAudioUnitProperty_SpeechChannel = 3331
};

Constants

kAudioUnitSubType_SpeechSynthesis

The speech synthesis component subtype used in the creation of a speech synthesis audio unit. (The component type is kAudioUnitType_Generator.)

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kAudioUnitProperty_Voice

The voice property in the speech synthesis audio unit.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kAudioUnitProperty_SpeechChannel

The speech channel property in the speech synthesis audio unit.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Stop Speech Locations

Locations that indicate where speech should be paused or stopped.

enum {
   kImmediate = 0,
   kEndOfWord = 1,
   kEndOfSentence = 2
};

Constants

kImmediate

Speech should be paused or stopped immediately.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kEndOfWord

Speech should be paused or stopped at the end of the word.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kEndOfSentence

Speech should be paused or stopped at the end of the sentence.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Speech Synthesis Manager Operating System Types

The OSType definitions used by the Speech Synthesis Manager.

enum {
   kTextToSpeechSynthType = 'ttsc',
   kTextToSpeechVoiceType = 'ttvd',
   kTextToSpeechVoiceFileType = 'ttvf',
   kTextToSpeechVoiceBundleType = 'ttvb'
};

Constants

kTextToSpeechSynthType

The type of a synthesizer component.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kTextToSpeechVoiceType

The type of a voice resource.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kTextToSpeechVoiceFileType

The type of a voice file. Typically. files containing a single voice are of type kTextToSpeechVoiceFileType.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

kTextToSpeechVoiceBundleType

The type of a voice bundle file. Typically, files containing multiple voices are of type kTextToSpeechVoiceBundleType.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Speech-Channel Modes

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

enum {
   modeText = 'TEXT',
   modePhonemes = 'PHON',
   modeNormal = 'NORM',
   modeLiteral = 'LTRL'
};

Constants

modeText

Used with soInputMode to indicate that the speech channel is in text-processing mode.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

modePhonemes

Used with soInputMode to indicate that the speech channel is in phoneme-processing mode. When in phoneme-processing mode, a text buffer is interpreted to be a series of characters representing various phonemes and prosodic controls.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

modeNormal

When the speech channel is in text-processing mode, indicates that the synthesizer should process characters as expected and assemble digits into numbers. Use this value with soCharacterMode and soNumberMode.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

modeLiteral

When the speech channel is in text-processing mode, indicates that characters and digits are spoken literally (for example, “cat” is spoken as “C-A-T” and “12” is spoken as "one, two"). Use this value with soCharacterMode and soNumberMode.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Speech-Channel Modes for Core Foundation-based Functions

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

CFStringRef kSpeechModeText = CFSTR("TEXT");
CFStringRef kSpeechModePhoneme = CFSTR("PHON");
CFStringRef kSpeechModeNormal = CFSTR("NORM");
CFStringRef kSpeechModeLiteral = CFSTR("LTRL");

Constants

kSpeechModeText

Used with kSpeechInputModeProperty to indicate that the speech channel is in text-processing mode.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechModePhoneme

Used with kSpeechInputModeProperty to indicate that the speech channel is in phoneme-processing mode. When in phoneme-processing mode, a text buffer is interpreted to be a series of characters representing various phonemes and prosodic controls.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechModeNormal

When the speech channel is in text-processing mode, indicates that the synthesizer should process characters as expected and assemble digits into numbers. Use this value with kSpeechCharacterModeProperty and kSpeechNumberModeProperty.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechModeLiteral

When the speech channel is in text-processing mode, indicates that characters and digits are spoken literally (for example, “cat” is spoken as “C-A-T” and “12” is spoken as "one, two"). Use this value with kSpeechCharacterModeProperty and kSpeechNumberModeProperty.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Voice Information Selectors

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

enum {
   soVoiceDescription = 'info',
   soVoiceFile = 'fref'
};

Constants

soVoiceDescription

Get basic voice information.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soVoiceFile

Get voice file reference information.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

Speech-Channel Information Constants

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

enum {
   soStatus = 'stat',
   soErrors = 'erro',
   soInputMode = 'inpt',
   soCharacterMode = 'char',
   soNumberMode = 'nmbr',
   soRate = 'rate',
   soPitchBase = 'pbas',
   soPitchMod = 'pmod',
   soVolume = 'volm',
   soSynthType = 'vers',
   soRecentSync = 'sync',
   soPhonemeSymbols = 'phsy',
   soCurrentVoice = 'cvox',
   soCommandDelimiter = 'dlim',
   soReset = 'rset',
   soCurrentA5 = 'myA5',
   soRefCon = 'refc',
   soTextDoneCallBack = 'tdcb',
   soSpeechDoneCallBack = 'sdcb',
   soSyncCallBack = 'sycb',
   soErrorCallBack = 'ercb',
   soPhonemeCallBack = 'phcb',
   soWordCallBack = 'wdcb',
   soSynthExtension = 'xtnd',
   soSoundOutput = 'sndo',
   soOutputToFileWithCFURL = 'opaf',
   soOutputToExtAudioFile = 'opax',
   soPhonemeOptions = 'popt',
   soOutputToAudioDevice = 'opad'
};

Constants

soStatus

Get a speech status information structure for the speech channel. The speechInfo parameter is a pointer to a speech status information structure, described in SpeechStatusInfo.

This selector works with the GetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soErrors

Get saved error information for the speech channel and clear its 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 Synthesis Manager functions are not reported here. If your application defines an error callback function, the callback should use the soErrors selector to obtain error information. The speechInfo parameter is a pointer to a speech error information structure, described in SpeechErrorInfo.

This selector works with the GetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soInputMode

Get or set the speech channel’s current text-processing mode. The returned value specifies whether the channel is currently in text input mode or phoneme input mode. The speechInfo parameter is a pointer to a variable of type OSType, which specifies a text-processing mode. The constants modeText and modePhonemes specify the available text-processing modes.

The modeText constant indicates that the speech channel is in text-processing mode. The modePhonemes constant indicates that the speech channel is in phoneme-processing mode. When in phoneme-processing mode, a text buffer is interpreted to be a series of characters representing various phonemes and prosodic controls. Some synthesizers might support additional input-processing modes and define constants for these modes.

When in text-processing mode, you can also specify how characters and numbers should be processed, using soCharacterMode and soNumberMode.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soCharacterMode

Get or set the speech channel’s character-processing mode. Two constants are currently defined for the processing mode, modeNormal and modeLiteral. When the character-processing mode is modeNormal, input characters are spoken as you would expect to hear them. When the mode is modeLiteral, each character is spoken literally, so that the word “cat” would be spoken “C–A–T”. The speechInfo parameter points to a variable of type OSType, which is the character-processing mode.

This selector works with the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soNumberMode

Get or set the speech channel’s current number-processing mode. Two OSType constants are currently defined, modeNormal and modeLiteral. When the number-processing mode is modeNormal, the synthesizer assembles digits into numbers (so that “12” is spoken as “twelve”). When the mode is modeLiteral, each digit is spoken literally (so that “12” is spoken as “one, two”). The speechInfo parameter is a pointer to a variable of type OSType, which specifies the number-processing mode.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soRate

Get or set a speech channel’s speech rate. The speechInfo parameter is a pointer to a variable of type Fixed. The possible range of speech rates is from 0.000 to 65535.65535. The range of supported rates is not predefined by the Speech Synthesis Manager; each speech synthesizer provides its own range of speech rates. Average human speech occurs at a rate of 180 to 220 words per minute.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soPitchBase

Get or set the speech channel’s baseline speech pitch. This selector is intended for use by the Speech Synthesis Manager; ordinarily, an application uses the GetSpeechPitch and SetSpeechPitch functions. The speechInfo parameter is a pointer to a variable of type Fixed.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Note: The change in speech pitch may not be noticeable until the next sentence or paragraph is spoken.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soPitchMod

Get or set a speech channel’s pitch modulation. The speechInfo parameter is a pointer to a variable of type Fixed. Pitch modulation is also expressed as a fixed-point value in the range of 0.000 to 127.000. These values correspond to MIDI note values, where 60.000 is equal to middle C on a piano scale. The most useful speech pitches fall in the range of 40.000 to 55.000. A pitch modulation value of 0.000 corresponds to a monotone in which all speech is generated at the frequency corresponding to the speech pitch. Given a speech pitch value of 46.000, a pitch modulation of 2.000 would mean that the widest possible range of pitches corresponding to the actual frequency of generated text would be 44.000 to 48.000.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Note: The change in pitch modulation may not be noticeable until the next sentence or paragraph is spoken.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soVolume

Get or set the speech volume for a speech channel. The speechInfo parameter is a pointer to a variable of type Fixed. 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.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soSynthType

Get a speech version information structure for the speech synthesizer being used on the specified speech channel. The speechInfo parameter is a pointer to a speech version information structure, described in SpeechVersionInfo.

This selector works with the GetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soRecentSync

Get the message code for the most recently encountered synchronization command. If no synchronization command has been encountered, 0 is returned. The speechInfo parameter is a pointer to a variable of type OSType.

This selector works with the GetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soPhonemeSymbols

Get a list of phoneme symbols and example words defined for the speech channel’s synthesizer. Your application might use this information to show the user what symbols to use when entering phonemic text directly. The speechInfo parameter is a pointer to a variable of type Handle that, on exit from the GetSpeechInfo function, is a handle to a phoneme descriptor structure, described in PhonemeDescriptor.

This selector works with the GetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soCurrentVoice

Set the current voice on the current speech channel to the specified voice. The speechInfo parameter is a pointer to a voice specification structure. Your application should create the structure by calling MakeVoiceSpec. SetSpeechInfo will return an incompatibleVoice error if the specified voice is incompatible with the speech synthesizer associated with the speech channel. If you have a speech channel open using a voice from a particular synthesizer and you try to switch to a voice that works with a different synthesizer, you receive an incompatibleVoice error. You need to create a new channel to use with the new voice.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soCommandDelimiter

Set the embedded speech command delimiter characters to be used for the speech channel. By default the opening delimiter is “[[” and the closing delimiter is “]]”. Your application might need to change these delimiters temporarily if those character sequences occur naturally in a text buffer that is to be spoken. Your application can also disable embedded command processing by passing empty delimiters (using two NUL ASCII characters). The speechInfo parameter is a pointer to a delimiter information structure, described in DelimiterInfo.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soReset

Set a speech channel back to its default state. For example, speech pitch and speech rate are set to default values. The speechInfo parameter should be set to NULL.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soCurrentA5

Set the value that the Speech Synthesis Manager assigns to the A5 register before invoking any application-defined callback functions for the speech channel. The A5 register must be set correctly if the callback functions are to be able to access application global variables. The speechInfo parameter should be set to the pointer contained in the A5 register at a time when the application is not executing interrupt code or to NULL if your application wishes to clear a value previously set with the soCurrentA5 selector.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soRefCon

Set a speech channel’s reference constant value. The reference constant value is passed to application-defined callback functions and might contain any value convenient for the application. The speechInfo parameter is a long integer containing the reference constant value. In contrast with other selectors, this selector does not require that the speechInfo parameter’s value be a pointer value. Typically, however, an application does use this selector to pass a pointer or handle value to callback functions.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soTextDoneCallBack

Set the callback function to be called when the Speech Synthesis Manager has finished processing speech being generated on the speech channel. The speechInfo parameter is a pointer to an application-defined text-done callback function, whose syntax is described in SpeechTextDoneProcPtr. Passing NULL in speechInfo disables the text-done callback function.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soSpeechDoneCallBack

Set the callback function to be called when the Speech Synthesis Manager has finished generating speech on the speech channel. The speechInfo parameter is a pointer to an application-defined speech-done callback function, whose syntax is described in SpeechDoneProcPtr. Passing NULL in speechInfo disables the speech-done callback function.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soSyncCallBack

Set the callback function to be called when the Speech Synthesis Manager encounters a synchronization command within an embedded speech command in text being processed on the speech channel. The speechInfo parameter is a pointer to an application-defined synchronization callback function, whose syntax is described in SpeechSyncProcPtr. Passing NULL in speechInfo disables the synchronization callback function.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soErrorCallBack

Set the callback function to be called when an error is encountered during the processing of an embedded command. The callback function might also be called if other conditions (such as insufficient memory) arise during the speech conversion process. When a Speech Synthesis Manager function returns an error directly, the error callback function is not called. The callback function is passed information about the most recent error; it can determine information about the oldest pending error by using the speech information selector soErrors. The speechInfo parameter is a pointer to an application-defined error callback function. Passing NULL in speechInfo disables the error callback function, SpeechErrorProcPtr.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soPhonemeCallBack

Set the callback function to be called every time the Speech Synthesis Manager is about to generate a phoneme on the speech channel. The speechInfo parameter is a pointer to an application-defined phoneme callback function, whose syntax is described in SpeechPhonemeProcPtr. Passing NULL in speechInfo disables the phoneme callback function.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soWordCallBack

Set the callback function to be called every time the Speech Synthesis Manager is about to generate a word on the speech channel. The speechInfo parameter is a pointer to an application-defined word callback function, whose syntax is described in SpeechWordProcPtr. Passing NULL in speechInfo disables the word callback function.

This selector works with the SetSpeechInfo function.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soSynthExtension

Get or set synthesizer-specific information or settings. The speechInfo parameter is a pointer to a speech extension data structure, described in SpeechXtndData. Your application should set the synthCreator field of this structure before calling GetSpeechInfo or SetSpeechInfo. Ordinarily, your application must pass additional information to the synthesizer in the synthData field.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soSoundOutput

Get or set the speech channel’s current output channel. (Deprecated. Use soOutputToFileWithCFURL instead.)

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.0 and later.

Declared in SpeechSynthesis.h.

soOutputToFileWithCFURL

Pass a CFURLRef in the speechInfo parameter to write to this file, or NULL to generate sound.

This selector works with the SetSpeechInfo function.

Available in OS X v10.3 and later.

Declared in SpeechSynthesis.h.

soOutputToExtAudioFile

Pass an ExtAudioFileRef in the speechInfo parameter to write to this file, or NULL to generate sound.

Note that the Speech Synthesis Manager may alter the kExtAudioFileProperty_ClientDataFormat and kExtAudioFileProperty_ClientChannelLayout properties of the extended audio file object. The caller is responsible for closing the extended audio file object after the Speech Synthesis Manager is finished with it.

This selector works with the SetSpeechInfo function.

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

soPhonemeOptions

Get or set options for the generation of phonetic output. See “Phoneme Generation Options” for a complete list of options.

The speechInfo parameter is a pointer to a long value that represents the phoneme generation value.

This selector works with both the GetSpeechInfo and SetSpeechInfo functions.

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

soOutputToAudioDevice

Pass a pointer to an AudioDeviceID in the speechInfo parameter to play to this file, or 0 to play through the default audio output device.

This selector works with the SetSpeechInfo function.

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

Phoneme Generation Options

Flags that specify options for the generation of phonetic output.

enum {
   kSpeechGenerateTune = 1,
   kSpeechRelativePitch = 2,
   kSpeechRelativeDuration = 4,
   kSpeechShowSyllables = 8
};

Constants

kSpeechGenerateTune

Generate phonemes that produce a detailed tune, specified by pitch and duration information.

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

kSpeechRelativePitch

Specify the pitch in the tune, relative to the pitch baseline of the voice (this makes it easier to reuse the tune with a different voice).

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

kSpeechRelativeDuration

Specify the duration in the tune, relative to the current speech rate (this makes it easier to reuse the tune at a different rate).

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

kSpeechShowSyllables

Show all syllable marks in the phonetic output or tune.

Available in OS X v10.6 and later.

Declared in SpeechSynthesis.h.

Speech-Channel Properties

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

CFStringRef kSpeechStatusProperty = CFSTR("stat");
CFStringRef kSpeechErrorsProperty = CFSTR("erro");
CFStringRef kSpeechInputModeProperty = CFSTR("inpt");
CFStringRef kSpeechCharacterModeProperty = CFSTR("char");
CFStringRef kSpeechNumberModeProperty = CFSTR("nmbr");
CFStringRef kSpeechRateProperty = CFSTR("rate");
CFStringRef kSpeechPitchBaseProperty = CFSTR("pbas");
CFStringRef kSpeechPitchModProperty = CFSTR("pmod");
CFStringRef kSpeechVolumeProperty = CFSTR("volm");
CFStringRef kSpeechSynthesizerInfoProperty = CFSTR("vers");
CFNumberRef kSpeechRecentSyncProperty = CFSTR("sync");
CFStringRef kSpeechPhonemeSymbolsProperty = CFSTR("phsy");
CFStringRef kSpeechCurrentVoiceProperty = CFSTR("cvox");
CFStringRef kSpeechCommandDelimiterProperty = CFSTR("dlim");
CFStringRef kSpeechResetProperty = CFSTR("rset");
CFStringRef kSpeechOutputToFileURLProperty = CFSTR("opaf");
CFStringRef kSpeechOutputToExtAudioFileProperty = CFSTR("opax");
CFStringRef kSpeechRefConProperty = CFSTR("refc");
CFStringRef kSpeechTextDoneCallBack = CFSTR("tdcb");
CFStringRef kSpeechSpeechDoneCallBack = CFSTR("sdcb");
CFStringRef kSpeechSyncCallBack = CFSTR("sycb");
CFStringRef kSpeechPhonemeCallBack = CFSTR("phcb");
CFStringRef kSpeechErrorCFCallBack = CFSTR("eccb");
CFStringRef kSpeechWordCFCallBack = CFSTR("wccb");
CFStringRef kSpeechPhonemeOptionsProperty = CFSTR("popt");
CFStringRef kSpeechOutputToAudioDeviceProperty = CRSTR("opad");

Constants

kSpeechStatusProperty

Get speech-status information for the speech channel.

The value associated with this property is a CFDictionary object that contains speech-status information for the speech channel. See “Speech Status Keys” for a description of the keys present in the dictionary.

This property works with the CopySpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechErrorsProperty

Get speech-error information for the speech channel.

The value associated with this property is a CFDictionary object that contains speech-error information. See “Speech Error Keys” for a description of the keys present in the dictionary.

This property lets you get information about various run-time errors that occur during speaking, such as the detection of badly formed embedded commands. Errors returned directly by the Speech Synthesis Manager are not reported here. If your application defines an error callback function, the function can use this property to get error information.

This property works with the CopySpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechInputModeProperty

Get or set the speech channel’s current text-processing mode.

The value associated with this property is a CFString object that specifies whether the channel is currently in text input mode or phoneme input mode. The constants kSpeechModeText and kSpeechModePhoneme (defined in “Speech-Channel Modes for Core Foundation-based Functions”) are the possible values of this string.

When in phoneme-processing mode, a text string is interpreted to be a series of characters representing various phonemes and prosodic controls. Some synthesizers might support additional input-processing modes and define constants for these modes.

When in text-processing mode, you can also specify how characters and numbers should be processed using the kSpeechCharacterModeProperty and kSpeechNumberModeProperty.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechCharacterModeProperty

Get or set the speech channel’s current character-processing mode.

The value associated with this property is a CFString object that specifies whether the speech channel is currently in normal or literal character-processing mode. The constants kSpeechModeNormal and kSpeechModeLiteral (defined in “Speech-Channel Modes for Core Foundation-based Functions”) are the possible values of this string.

When the character-processing mode is kSpeechModeNormal, input characters are spoken as you would expect to hear them. When the mode is kSpeechModeLiteral, each character is spoken literally, so that the word “cat” is spoken “C–A–T”.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechNumberModeProperty

Get or set the speech channel’s current number-processing mode.

The value associated with this property is a CFString object that specifies whether the speech channel is currently in normal or literal number-processing mode. The constants kSpeechModeNormal and kSpeechModeLiteral (defined in “Speech-Channel Modes for Core Foundation-based Functions”) are the possible values of this string.

When the number-processing mode is kSpeechModeNormal, the synthesizer assembles digits into numbers (so that “12” is spoken as “twelve”). When the mode is kSpeechModeLiteral, each digit is spoken literally (so that “12” is spoken as “one, two”).

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechRateProperty

Get or set a speech channel’s speech rate.

The value associated with this property is a CFNumber object that specifies the speech channel’s speaking rate.

The range of supported rates is not predefined by the Speech Synthesis Manager; each speech synthesizer provides its own range of speech rates. Average human speech occurs at a rate of 180 to 220 words per minute.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPitchBaseProperty

Get or set the speech channel’s baseline speech pitch.

The value associated with this property is a CFNumber object that specifies the speech channel’s baseline speech pitch.

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.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Note: The change in speech pitch may not be noticeable until the next sentence or paragraph is spoken.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPitchModProperty

Get or set a speech channel’s pitch modulation.

The value associated with this property is a CFNumber object that specifies the speech channel’s pitch modulation.

Pitch modulation is also expressed as a floating-point value in the range of 0.000 to 127.000. These values correspond to MIDI note values, where 60.000 is equal to middle C on a piano scale. The most useful speech pitches fall in the range of 40.000 to 55.000. A pitch modulation value of 0.000 corresponds to a monotone in which all speech is generated at the frequency corresponding to the speech pitch. Given a speech pitch value of 46.000, a pitch modulation of 2.000 would mean that the widest possible range of pitches corresponding to the actual frequency of generated text would be 44.000 to 48.000.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Note: The change in pitch modulation may not be noticeable until the next sentence or paragraph is spoken.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechVolumeProperty

Get or set the speech volume for a speech channel.

The value associated with this property is a CFNumber object that specifies the speech channel’s speech volume.

Volumes are expressed in floating-point values 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.

This property works with the CopySpeechProperty and SetSpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechSynthesizerInfoProperty

Get information about the speech synthesizer being used on the specified speech channel.

The value associated with this property is a CFDictionary object that contains information about the speech synthesizer being used on the specified speech channel. See “Speech Synthesizer Information Keys” for a description of the keys present in the dictionary.

This property works with the CopySpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechRecentSyncProperty

Get the message code for the most recently encountered synchronization command.

The value associated with this property is a CFNumber object that specifies the most recently encountered synchronization command. This property works with the CopySpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPhonemeSymbolsProperty

Get a list of phoneme symbols and example words defined for the speech channel’s synthesizer.

The value associated with this property is a CFDictionary object that contains the phoneme symbols and example words defined for the current synthesizer. Your application might use this information to show the user what symbols to use when entering phonemic text directly. See “Phoneme Symbols Keys” for a description of the keys present in the dictionary.

This property works with the CopySpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechCurrentVoiceProperty

Set the current voice on the current speech channel to the specified voice.

The value associated with this property is a CFDictionary object that contains the phoneme symbols and example words defined for the current synthesizer. Your application might use this information to show the user what symbols to use when entering phonemic text directly. See “Phoneme Symbols Keys” for the keys you can use to specify values in this dictionary.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechCommandDelimiterProperty

Set the embedded speech command delimiter characters to be used for the speech channel.

By default, the opening delimiter is “[[” and the closing delimiter is “]]”. Your application might need to change these delimiters temporarily if those character sequences occur naturally in a text buffer that is to be spoken. Your application can also disable embedded command processing by passing empty delimiters (as empty strings). The value associated with this property is a CFDictionary object that contains the delimiter information. See “Command Delimiter Keys” for the keys you can use to specify values in this dictionary.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechResetProperty

Set a speech channel back to its default state.

You can use this function to, for example, set speech pitch and speech rate to default values. There is no value associated with this property; to reset the channel to its default state, set the string to NULL.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechOutputToFileURLProperty

Set the speech output destination to a file or to the computer’s speakers.

The value associated with this property is a CFURL object. To write the speech output to a file, use the file’s CFURLRef; to generate the sound through the computer’s speakers, use NULL.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechOutputToExtAudioFileProperty

Set the speech output destination to an extended audio file or to the computer’s speakers.

The value associated with this property is a CFNumber object whose value is an ExtAudioFileRef. To write the speech output to an extended audio file, use the file’s ExtAudioFileRef; to generate sound through the computer’s speakers, use NULL.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechRefConProperty

Set a speech channel’s reference constant value.

The reference constant value is passed to application-defined callback functions and might contain any value convenient for the application. The value associated with this property is a CFNumber object that contains an integer value. For example, an application might set the value of the CFNumber object to an address in memory that contains a reference to an object or a pointer to a function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechTextDoneCallBack

Set the callback function to be called when the Speech Synthesis Manager has finished processing speech being generated on the speech channel.

The value associated with this property is a CFNumber object whose value is a pointer to an application-defined text-done callback function, whose syntax is described in SpeechTextDoneProcPtr. Passing a CFNumber object that contains the value NULL disables the text-done callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechSpeechDoneCallBack

Set the callback function to be called when the Speech Synthesis Manager has finished generating speech on the speech channel.

The value associated with this property is CFNumber object whose value is a pointer to an application-defined speech-done callback function, whose syntax is described in SpeechDoneProcPtr. Passing NULL for the value of this property disables the speech-done callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechSyncCallBack

Set the callback function to be called when the Speech Synthesis Manager encounters a synchronization command within an embedded speech command in text being processed on the speech channel.

The value associated with this property is CFNumber object whose value is a pointer to an application-defined synchronization callback function, whose syntax is described in SpeechSyncProcPtr. Passing a CFNumber object that contains the value NULL for the value of this property disables the synchronization callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPhonemeCallBack

Set the callback function to be called every time the Speech Synthesis Manager is about to generate a phoneme on the speech channel.

The value associated with this property is CFNumber object whose value is a pointer to an application-defined phoneme callback function, whose syntax is described in SpeechPhonemeProcPtr. Passing a CFNumber object that contains the value NULL for the value of this property disables the phoneme callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechErrorCFCallBack

Set the callback function to be called when an error is encountered during the processing of an embedded command.

When a Speech Synthesis Manager function returns an error directly, the error callback function is not called. The callback function is passed information about the most recent error; it can determine information about the oldest pending error by using the speech information property kSpeechErrorsProperty. The value associated with this property is CFNumber object whose value is a pointer to an application-defined error callback function, whose syntax is described in SpeechErrorCFProcPtr. Passing a CFNumber object that contains the value NULL for the value of this property disables the error callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechWordCFCallBack

Set the callback function to be called every time the Speech Synthesis Manager is about to generate a word on the speech channel.

The value associated with this property is CFNumber object whose value is a pointer to an application-defined word callback function, whose syntax is described in SpeechWordCFProcPtr. Passing a CFNumber object that contains the value NULL for the value of this property disables the word callback function.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPhonemeOptionsProperty

Get or set the options for the generation of phonetic output.

The value associated with this property is a pointer to an CFNumber object containing the flags (options) you would pass to soPhonemeOptions. (See “Phoneme Generation Options” for a complete list of options.)

This property works with the SetSpeechProperty and the CopySpeechProperty functions.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechOutputToAudioDeviceProperty

Set the speech output destination to an audio device file or to the computer’s speakers.

The value associated with this property is a CFNumber object that contains an AudioDeviceID. To play the speech output to an audio device, use the AudioDeviceID that represents the device; to generate sound through the computer’s speakers, use 0.

This property works with the SetSpeechProperty function.

Declared in SpeechSynthesis.h.

Available in OS X v10.6 and later.

Synthesizer Option Keys

Keys used to specify synthesizer options.

CFStringRef kSpeechNoEndingProsody = CFSTR("NoEndingProsody");
CFStringRef kSpeechNoSpeechInterrupt = CFSTR("NoSpeechInterrupt");
CFStringRef kSpeechPreflightThenPause = CFSTR("PreflightThenPause");

Constants

kSpeechNoEndingProsody

Disable prosody at the end of sentences.

The kSpeechNoEndingProsody key is used to indicate whether the speech synthesizer should automatically apply ending prosody, which is the speech tone and cadence that normally occur at the end of a sentence. When the key is not specified (or if it is specified with the value kCFBooleanFalse), ending prosody is applied to the speech at the end of aString. This behavior can be disabled by specifying the kSpeechNoEndingProsody key, with the value kCFBooleanTrue, in the options dictionary.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechNoSpeechInterrupt

Do not interrupt current speech.

The kSpeechNoSpeechInterrupt key is used to control the behavior of SpeakCFString when it is called on a speech channel that is busy. When kSpeechNoSpeechInterrupt is not specified in the options dictionary (or if it is specified with the value kCFBooleanFalse), SpeakCFString immediately interrupts the speech currently being produced on the specified speech channel and the new aString text is spoken. When kSpeechNoSpeechInterrupt is specified with the value kCFBooleanTrue, the request to speak on a speech channel that is already busy causes the new aString text to be ignored and the synthNotReady error to be returned.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPreflightThenPause

Compute speech without generating it.

The kSpeechPreflightThenPause key is used to minimize the latency experienced when the speech synthesizer is attempting to speak. To achieve this, specify the kSpeechPreflightThenPause key, with the value kCFBooleanTrue, in the options dictionary. This causes the speech synthesizer to process the input text as necessary to the point where it is ready to begin producing speech output. At this point, the synthesizer enters a paused state and returns to the caller. When the application is ready to produce speech, it should call ContinueSpeech to begin speaking.

If you do not specify the kSpeechPreflightThenPause key (or you specify it with the value kCFBooleanFalse), SpeakCFString starts speaking the input text after processing it.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

Speech Status Keys

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

CFStringRef kSpeechStatusOutputBusy = CFSTR("OutputBusy");
CFStringRef kSpeechStatusOutputPaused = CFSTR("OutputPaused");
CFStringRef kSpeechStatusNumberOfCharactersLeft = CFSTR("NumberOfCharactersLeft");
CFStringRef kSpeechStatusPhonemeCode = CFSTR("PhonemeCode");

Constants

kSpeechStatusOutputBusy

Indicates whether the speech channel is currently producing speech.

A speech channel is considered to be producing speech even at some times when no audio data is being produced through the computer’s speaker. This occurs, for example, when the Speech Synthesis Manager is processing input, but has not yet initiated speech or when speech output is paused.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechStatusOutputPaused

Indicates whether speech output in the speech channel has been paused by a call to the PauseSpeechAt function.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechStatusNumberOfCharactersLeft

The number of characters left in the input string of text.

When the value of this constant is zero, you can destroy the input string.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechStatusPhonemeCode

The opcode for the phoneme that the speech channel is currently processing.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Speech Error Keys

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

CFStringRef kSpeechErrorCount = CFSTR("Count");
CFStringRef kSpeechErrorOldest = CFSTR("OldestCode");
CFStringRef kSpeechErrorOldestCharacterOffset = CFSTR("OldestCharacterOffset");
CFStringRef kSpeechErrorNewest = CFSTR("NewestCode");
CFStringRef kSpeechErrorNewestCharacterOffset = CFSTR("NewestCharacterOffset");

Constants

kSpeechErrorCount

The number of errors that have occurred in processing the current text string, since the last call to the CopySpeechProperty function with the kSpeechErrorsProperty property.

Using the kSpeechErrorOldest keys and the kSpeechErrorNewest keys, you can get information about the oldest and most recent errors that occurred since the last call to CopySpeechProperty, but you cannot get information about any intervening errors.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechErrorOldest

The error code of the first error that occurred since the last call to the CopySpeechProperty function with the kSpeechErrorsProperty property.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechErrorOldestCharacterOffset

The position in the text string of the first error that occurred since the last call to the CopySpeechProperty function with the kSpeechErrorsProperty property.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechErrorNewest

The error code of the most recent error that occurred since the last call to the CopySpeechProperty function with the kSpeechErrorsProperty property.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechErrorNewestCharacterOffset

The position in the text string of the most recent error that occurred since the last call to the CopySpeechProperty function with the kSpeechErrorsProperty property.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Speech Synthesizer Information Keys

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

CFStringRef kSpeechSynthesizerInfoIdentifier = CFSTR("Identifier");
CFStringRef kSpeechSynthesizerInfoVersion = CFSTR("Version");
CFStringRef kSpeechSynthesizerInfoManufacturer = CFSTR("Manufacturer");

Constants

kSpeechSynthesizerInfoIdentifier

The identifier of the speech synthesizer.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechSynthesizerInfoVersion

The version of the speech synthesizer.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechSynthesizerInfoManufacturer

The identification of a synthesizer engine (see the synthManufacturer field in SpeechVersionInfo).

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Phoneme Symbols Keys

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

CFStringRef kSpeechPhonemeInfoOpcode = CFSTR("Opcode");
CFStringRef kSpeechPhonemeInfoSymbol = CFSTR("Symbol");
CFStringRef kSpeechPhonemeInfoExample = CFSTR("Example");
CFStringRef kSpeechPhonemeInfoHiliteStart = CFSTR("HiliteStart");
CFStringRef kSpeechPhonemeInfoHiliteEnd = CFSTR("HiliteEnd");

Constants

kSpeechPhonemeInfoOpcode

The opcode of the phoneme.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechPhonemeInfoSymbol

The symbol used to represent the phoneme.

The symbol does not necessarily have a phonetic connection to the phoneme, but might simply be an abstract textual representation of it.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechPhonemeInfoExample

An example word that illustrates the use of the phoneme.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechPhonemeInfoHiliteStart

The character offset into the example word that identifies the location of the beginning of the phoneme.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechPhonemeInfoHiliteEnd

The character offset into the example word that identifies the location of the end of the phoneme.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Current Voice Keys

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

CFStringRef kSpeechVoiceCreator = CFSTR("Creator");
CFStringRef kSpeechVoiceID = CFSTR("ID");

Constants

kSpeechVoiceCreator

The synthesizer that is required to use the voice.

Declared in SpeechSynthesis.h.

Available in OS X v10.5 and later.

kSpeechVoiceID

The voice ID of the voice for the synthesizer (every voice on a synthesizer has a unique ID).

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Command Delimiter Keys

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

CFStringRef kSpeechCommandPrefix = CFSTR("Prefix");
CFStringRef kSpeechCommandSuffix = CFSTR("Suffix");

Constants

kSpeechCommandPrefix

The command delimiter string that prefixes a command (by default, this is “[[”). The string should contain two or fewer characters, which, for best compatibility, should be ASCII characters.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechCommandSuffix

The command delimiter string that suffixes a command (by default, this is “]]”). The string should contain two or fewer characters, which, for best compatibility, should be ASCII characters.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Speech Dictionary Keys

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

CFStringRef kSpeechDictionaryLocaleIdentifier = CFSTR("LocaleIdentifier");
CFStringRef kSpeechDictionaryModificationDate = CFSTR("ModificationDate");
CFStringRef kSpeechDictionaryPronunciations = CFSTR("Pronunciations");
CFStringRef kSpeechDictionaryAbbreviations = CFSTR("Abbreviations");
CFStringRef kSpeechDictionaryEntrySpelling = CFSTR("Spelling");
CFStringRef kSpeechDictionaryEntryPhonemes = CFSTR("Phonemes");

Constants

kSpeechDictionaryLocaleIdentifier

The locale associated with the pronunciation.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechDictionaryModificationDate

The date the dictionary was last modified.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechDictionaryPronunciations

The set of custom pronunciations.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechDictionaryAbbreviations

The set of custom pronunciations for abbreviations.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechDictionaryEntrySpelling

The spelling of an entry.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechDictionaryEntryPhonemes

The phonemic representation of an entry.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Error Callback User-Information String

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

CFStringRef kSpeechErrorCallbackSpokenString = CFSTR("SpokenString");
CFStringRef kSpeechErrorCallbackCharacterOffset = CFSTR("CharacterOffset");

Constants

kSpeechErrorCallbackSpokenString

The text being synthesized when the error occurred.

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

kSpeechErrorCallbackCharacterOffset

The character index in the text being synthesized when the error occurred (the string representing the text is in kSpeechErrorCallbackSpokenString).

Available in OS X v10.5 and later.

Declared in SpeechSynthesis.h.

Result Codes

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

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 OS X: Gestalt Manager Reference.