Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

NSSpeechSynthesizer Class Reference

Overview

The NSSpeechSynthesizer class is the Cocoa interface to Speech Synthesis on Mac OS X. Instances of this class are called speech synthesizers.

Speech Synthesis, also called text-to-speech (TTS), parses text and converts it into audible speech. It offers a concurrent feedback mode that can be used in concert with or in place of traditional visual and aural notifications. For example, your application can use an NSSpeechSynthesizer object to “pronounce” the text of important alert dialogs. Synthesized speech has several advantages. It can provide urgent information to users without forcing them to shift attention from their current task. And because speech doesn’t rely on visual elements for meaning, it is a crucial technology for users with vision or attention disabilities.

In addition, synthesized speech can help save system resources. 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 an NSSpeechSynthesizer object to provide a narration of a QuickTime movie instead of including sampled-sound data on a movie track.

When you create an NSSpeechSynthesizer instance using the default initializer (init), the class uses the default voice selected in System Preferences > Speech. Alternatively, you can select a specific voice for an NSSpeechSynthesizer instance by initializing it with initWithVoice:. To begin synthesis, send either startSpeakingString: or startSpeakingString:toURL: to the instance. The former generates speech through the system’s default sound output device; the latter saves the generated speech to a file. If you wish to be notified when the current speech concludes, set a delegate object using setDelegate: and implement the delegate method speechSynthesizer:didFinishSpeaking:.

Speech Synthesis is just one of the Mac OS X speech technologies. The Speech Recognizer technology allows applications to “listen to” text spoken in U.S. English; the NSSpeechRecognizer class is the Cocoa interface to this technology. Both technologies provide benefits for all users, and are particularly useful to those users who have difficulties seeing the screen or using the mouse and keyboard.

Table 1 lists the attributes of instances of this class. The list following the table describes each attribute.

• UsesFeedbackWindow

  The speech feedback window (Figure 1) displays the text recognized from the user’s speech and the text from which an NSSpeechSynthesizer object synthesizes speech. Using the feedback window makes spoken exchange more natural and helps the user understand the synthesized speech.

  Figure 1  Speech feedback window

  

  For example, your application may use an NSSpeechRecognizer object to listen for the command “Play some music.” When it recognizes this command, your application might then respond by speaking “Which artist?” using a speech synthesizer.

  When UsesFeedbackWindow is YES, the speech synthesizer uses the feedback window if its visible, which the user specifies in System Preferences > Speech.

• CurrentVoice

  The identifier of the voice the receiver uses to speak synthesized text.

Tasks

Creating Speech Synthesizers

• – initWithVoice:

Configuring Speech Synthesizers

• – usesFeedbackWindow
• – setUsesFeedbackWindow:
• – voice
• – setVoice:
• – rate
• – setRate:
• – volume
• – setVolume:
• – addSpeechDictionary:
• – objectForProperty:error:
• – setObject:forProperty:error:
• – delegate
• – setDelegate:

Getting Speech Synthesizer Information

• + availableVoices
• + attributesForVoice:
• + defaultVoice

Getting Speech State

• + isAnyApplicationSpeaking

Synthesizing Speech

• – isSpeaking
• – startSpeakingString:
• – startSpeakingString:toURL:
• – speechSynthesizer:willSpeakWord:ofString:  delegate method
• – speechSynthesizer:willSpeakPhoneme:  delegate method
• – pauseSpeakingAtBoundary:
• – continueSpeaking
• – stopSpeaking
• – stopSpeakingAtBoundary:
• – speechSynthesizer:didEncounterErrorAtIndex:ofString:message:  delegate method
• – speechSynthesizer:didEncounterSyncMessage:  delegate method
• – speechSynthesizer:didFinishSpeaking:  delegate method

Getting Phonemes

• – phonemesFromText:

Class Methods

attributesForVoice:

Provides the attribute dictionary of a voice.

+ (NSDictionary *)attributesForVoice:(NSString *)voiceIdentifier

Parameters

voiceIdentifier

Identifier of the voice whose attributes you want to obtain.

Return Value

Attribute dictionary of the voice identified by voiceIdentifier.

Discussion

The keys and values of voice attribute dictionaries are described in “Constants.”

Availability

• Available in Mac OS X v10.3 and later.

Declared In

availableVoices

Provides the identifiers of the voices available on the system.

+ (NSArray *)availableVoices

Return Value

Array of strings representing the identifiers of each voice available on the system.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + attributesForVoice:
• – setVoice:

Declared In

defaultVoice

Provides the identifier of the default voice.

+ (NSString *)defaultVoice

Return Value

Identifier of the default voice.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

isAnyApplicationSpeaking

Indicates whether any other application is currently speaking through the sound output device.

+ (BOOL)isAnyApplicationSpeaking

Return Value

YES when another application is producing speech through the sound output device, NO otherwise.

Discussion

You usually invoke this method to prevent your application from speaking over speech being generated by another application or system component.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Instance Methods

addSpeechDictionary:

Registers the given speech dictionary with the receiver.

- (void)addSpeechDictionary:(NSDictionary *)speechDictionary

Parameters

speechDictionary

Speech dictionary to add to the receiver’s dictionaries.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

continueSpeaking

Resumes synthesis.

- (void)continueSpeaking

Discussion

If systhesis is paused, it’s resumed.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – pauseSpeakingAtBoundary:

Declared In

delegate

Returns the receiver’s delegate.

- (id)delegate

Return Value

The receiver’s delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setDelegate:

Declared In

initWithVoice:

Initializes the receiver with a voice.

- (id)initWithVoice:(NSString *)voiceIdentifier

Parameters

voiceIdentifier

Identifier of the voice to set as the current voice. When nil, the default voice is used. Passing in a specific voice means the initial speaking rate is determined by the synthesizer’s default speaking rate; passing nil means the speaking rate is automatically set to the rate the user specifies in Speech preferences.

Return Value

Initialized speech synthesizer or nil when the voice identified by voiceIdentifier is not available or when there’s an allocation error.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• + availableVoices

Declared In

isSpeaking

Indicates whether the receiver is currently generating synthesized speech.

- (BOOL)isSpeaking

Return Value

YES when the receiver is generating synthesized speech, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – startSpeakingString:
• – startSpeakingString:toURL:
• – stopSpeaking

Declared In

objectForProperty:error:

Provides the value of a receiver’s property.

- (id)objectForProperty:(NSString *)speechProperty error:(NSError **)out_error

Parameters

speechProperty

Property to get.

out_error

On output, error that ocured while obtaining the value of speechProperty.

Return Value

The value of speechProperty.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setObject:forProperty:error:

Declared In

pauseSpeakingAtBoundary:

Pauses synthesis in progress at a given boundary.

- (void)pauseSpeakingAtBoundary:(NSSpeechBoundary)boundary

Parameters

boundary

Boundary at which to pause speech..

Discussion

If the receiver is currently generating speech, synthesis is paused at boundary.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – continueSpeaking

Declared In

phonemesFromText:

Provides the phoneme symbols generated by the given text.

- (NSString *)phonemesFromText:(NSString *)text

Parameters

text

Text from which to generate phonemes.

Return Value

Phonemes generated from text.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

rate

Provides the receiver’s speaking rate.

- (float)rate

Return Value

Speaking rate (words per minute).

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setRate:

Declared In

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)delegate

Parameters

delegate

Object to be the receiver’s delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – delegate

Declared In

setObject:forProperty:error:

Specifies the value of a receiver’s property.

- (BOOL)setObject:(id)object forProperty:(NSString *) speechProperty error:(NSError **)out_error

Parameters

speechProperty

Property to set.

out_error

On output, error that ocurred while setting speechProperty.

Return Value

YES when the speechProperty was set. NO when there was an error, specified in out_error.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – objectForProperty:error:

Declared In

setRate:

Specifies the receivers speaking rate.

- (void)setRate:(float)rate

Parameters

rate

Words to speak per minute.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – rate

Declared In

setUsesFeedbackWindow:

Specifies whether the receiver uses the speech feedback window.

- (void)setUsesFeedbackWindow:(BOOL)useFeedbackWindow

Parameters

useFeedbackWindow

YES to make the receiver use the speech feedback window if it’s visible when the user begins speaking. NO not to use the feedback window.

Discussion

See the class description for details on the UsesFeedbackWindow attribute.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – usesFeedbackWindow

Declared In

setVoice:

Sets the receiver’s current voice.

- (BOOL)setVoice:(NSString *)voiceIdentifier

Parameters

voiceIdentifier

Identifier of the voice to set at the receiver’s current voice. When nil, the receiver sets the default voice as its current voice.

Return Value

YES when the receiver is not currently synthesizing speech and the current voice is set successfully, NO otherwise.

Discussion

See the class description for details on the CurrentVoice attribute.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – voice
• + defaultVoice

Declared In

setVolume:

Specifies the receiver’s speaking volume.

- (void)setVolume:(float)volume

Parameters

volume

Sound level to use for speech.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – volume

Declared In

startSpeakingString:

Begins speaking synthesized text through the system’s default sound output device.

- (BOOL)startSpeakingString:(NSString *)text

Parameters

text

Text to synthesize. When nil or empty, no synthesis occurs.

Return Value

YES when synthesis starts successfully, NO otherwise.

Discussion

If the receiver is currently speaking synthesized speech when startSpeakingString: is called, that process is stopped before text is spoken.

When synthesis of text finishes normally or is stopped, the message speechSynthesizer:didFinishSpeaking: is sent to the delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – isSpeaking
• – startSpeakingString:toURL:
• – stopSpeaking

Declared In

startSpeakingString:toURL:

Begins synthesizing text into a sound (AIFF) file.

- (BOOL)startSpeakingString:(NSString *)text toURL:(NSURL *)url

Parameters

text

Text to synthesize. When nil or empty, no synthesis is started.

url

Filesystem location of the output sound file.

Return Value

YES when synthesis starts successfully, NO otherwise.

Discussion

When synthesis of text finishes normally or is stopped, the message speechSynthesizer:didFinishSpeaking: is sent to the delegate.

One example of how you might use this method is in an email program that automatically converts new messages into sound files that can be stored on an iPod for later listening.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – isSpeaking
• – startSpeakingString:
• – stopSpeaking

Declared In

stopSpeaking

Stops synthesis in progress.

- (void)stopSpeaking

Discussion

If the receiver is currently generating speech, synthesis is halted, and the message speechSynthesizer:didFinishSpeaking: is sent to the delegate.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – isSpeaking
• – startSpeakingString:
• – startSpeakingString:toURL:

Declared In

stopSpeakingAtBoundary:

Stops synthesis in progress at a given boundary.

- (void)stopSpeakingAtBoundary:(NSSpeechBoundary)boundary

Parameters

boundary

Boundary at which to stop speech.

Discussion

If the receiver is currently generating speech, synthesis is halted at boundary, and the message speechSynthesizer:didFinishSpeaking: is sent to the delegate.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

usesFeedbackWindow

Indicates whether the receiver uses the speech feedback window.

- (BOOL)usesFeedbackWindow

Return Value

YES when the receiver uses the speech feedback window, NO otherwise.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setUsesFeedbackWindow:

Declared In

voice

Returns the identifier of the receiver’s current voice.

- (NSString *)voice

Return Value

Identifier of the receiver’s current voice.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setVoice:

Declared In

volume

Provides the receiver’s speaking volume.

- (float)volume

Return Value

Speaking volume: From 0.0 (minimum) to 1.0 (maximum).

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setVolume:

Declared In

Delegate Methods

speechSynthesizer:didEncounterErrorAtIndex:ofString:message:

Sent to the delegate when a speech synthesizer encounters an error in text being synthesized.

- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender didEncounterErrorAtIndex:(NSUInteger)characterIndex ofString:(NSString *)text message:(NSString *)errorMessage

Parameters

sender

Speech synthesizer informing its delegate of an error.

characterIndex

Location in text where the reciver encountered the error.

text

Text the receiver was synthesizing when the error ocurred.

errorMessage

Error message.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

speechSynthesizer:didEncounterSyncMessage:

Sent to the delegate when a speech synthesizer encounters a synchronization error.

- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender didEncounterSyncMessage:(NSString *)errorMessage

Parameters

sender

Speech synthesizer informing its delegate of an error.

errorMessage

Error message.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

speechSynthesizer:didFinishSpeaking:

Sent when an NSSpeechSynthesizer object finishes speaking through the sound output device.

- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender didFinishSpeaking:(BOOL)success

Parameters

sender

An NSSpeechSynthesizer object that has stopped speaking into the sound output device.

success

YES when speaking completed normally, NO if speaking is stopped prematurely for any reason.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – startSpeakingString:
• – stopSpeaking

Declared In

speechSynthesizer:willSpeakPhoneme:

Sent just before a synthesized phoneme is spoken through the sound output device.

- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender willSpeakPhoneme:(short)phonemeOpcode

Parameters

sender

An NSSpeechSynthesizer object that’s synthesizing text into speech.

phonemeOpcode

Phoneme that sender is about to speak into the sound output device.

Discussion

One use of this method might be to animate a mouth on screen to match the generated speech.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – startSpeakingString:

Declared In

speechSynthesizer:willSpeakWord:ofString:

Sent just before a synthesized word is spoken through the sound output device.

- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender willSpeakWord:(NSRange)wordToSpeak ofString:(NSString *)text

Parameters

sender

An NSSpeechSynthesizer object that’s synthesizing text into speech.

wordToSpeak

Word that sender is about to speak into the sound output device.

text

Text that is being synthesized by sender.

Discussion

One use of this method might be to visually highlight the word being spoken.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – startSpeakingString:

Declared In

Constants

Voice Attributes

The following voice attributes are defined by the NSSpeechSynthesizer class for the dictionary returned by attributesForVoice: (the values are all NSString objects).

NSString *NSVoiceIdentifier;
NSString *NSVoiceName;
NSString *NSVoiceAge;
NSString *NSVoiceGender;
NSString *NSVoiceDemoText;
NSString *NSVoiceLanguage;
NSString *NSVoiceLocaleIdentifier;
NSString *NSVoiceSupportedCharacters;
NSString *NSVoiceIndividuallySpokenCharacters;

Constants

NSVoiceIdentifier

A unique string identifying the voice. The identifiers of the system voices are listed in Listing 1.

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceName

The name of the voice suitable for display.

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceAge

The perceived age (in years) of the voice.

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceGender

The perceived gender of the voice. May be either NSVoiceGenderNeuter, NSVoiceGenderFemale, or NSVoiceGenderMale.

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceDemoText

A demonstration string to speak.

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceLanguage

The language of the voice (currently US English only).

Deprecated:

Available in Mac OS X v10.3 and later.

Deprecated in Mac OS X v10.5.

Declared in NSSpeechSynthesizer.h.

NSVoiceLocaleIdentifier

Available in Mac OS X v10.5 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceSupportedCharacters

Available in Mac OS X v10.5 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceIndividuallySpokenCharacters

Available in Mac OS X v10.5 and later.

Declared in NSSpeechSynthesizer.h.

Discussion

Listing 1 lists the identifiers of the system voices (defined in /System/Library/Speech/Voices):

Listing 1  Identifiers of the Mac OS X system voices

com.apple.speech.synthesis.voice.Agnes

com.apple.speech.synthesis.voice.Albert

com.apple.speech.synthesis.voice.BadNews

com.apple.speech.synthesis.voice.Bahh

com.apple.speech.synthesis.voice.Bells

com.apple.speech.synthesis.voice.Boing

com.apple.speech.synthesis.voice.Bruce

com.apple.speech.synthesis.voice.Bubbles

com.apple.speech.synthesis.voice.Cellos

com.apple.speech.synthesis.voice.Deranged

com.apple.speech.synthesis.voice.Fred

com.apple.speech.synthesis.voice.GoodNews

com.apple.speech.synthesis.voice.Hysterical

com.apple.speech.synthesis.voice.Junior

com.apple.speech.synthesis.voice.Kathy

com.apple.speech.synthesis.voice.Organ

com.apple.speech.synthesis.voice.Princess

com.apple.speech.synthesis.voice.Ralph

com.apple.speech.synthesis.voice.Trinoids

com.apple.speech.synthesis.voice.Vicki

com.apple.speech.synthesis.voice.Victoria

com.apple.speech.synthesis.voice.Whisper

com.apple.speech.synthesis.voice.Zarvox

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Voice Genders

The NSSpeechSynthesizer class defines the following voice gender attributes, which are the allowable values of the NSVoiceGender key:

NSString *NSVoiceGenderNeuter;
NSString *NSVoiceGenderMale;
NSString *NSVoiceGenderFemale;

Constants

NSVoiceGenderNeuter

A neutral voice (neither male nor female)

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceGenderMale

A male voice

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

NSVoiceGenderFemale

A female voice

Available in Mac OS X v10.3 and later.

Declared in NSSpeechSynthesizer.h.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

Speech Synthesizer Property Keys

These constants identify synthesizer properties.

NSString *NSSpeechStatusProperty
NSString *NSSpeechErrorsProperty
NSString *NSSpeechInputModeProperty
NSString *NSSpeechCharacterModeProperty
NSString *NSSpeechNumberModeProperty
NSString *NSSpeechRateProperty
NSString *NSSpeechPitchBaseProperty
NSString *NSSpeechPitchModProperty
NSString *NSSpeechVolumeProperty
NSString *NSSpeechSynthesizerInfoProperty
NSString *NSSpeechRecentSyncProperty
NSString *NSSpeechPhonemeSymbolsProperty
NSString *NSSpeechCurrentVoiceProperty
NSString *NSSpeechCommandDelimiterProperty
NSString *NSSpeechResetProperty
NSString *NSSpeechOutputToFileURLProperty

Declared In

Input Modes

These constants identify input modes (used with NSSpeechInputModeProperty).

NSString *NSSpeechModeText
NSString *NSSpeechModePhoneme

Declared In

Speech Type

These constants identify speech types (used with NSSpeechInputModeProperty and NSSpeechNumberModeProperty).

NSString *NSSpeechModeNormal
NSString *NSSpeechModeLiteral

Declared In

Speech Status

These constants identify speech status (used with NSSpeechStatusProperty).

NSString *NSSpeechStatusOutputBusy
NSString *NSSpeechStatusOutputPaused
NSString *NSSpeechStatusNumberOfCharactersLeft
NSString *NSSpeechStatusPhonemeCode

Declared In

Synthesis Error

These constants identify errors that may occur during speech synthesis (used with NSSpeechErrorProperty).

NSString *NSSpeechErrorCount
NSString *NSSpeechErrorOldestCode
NSString *NSSpeechErrorOldestCharacterOffset
NSString *NSSpeechErrorNewestCode
NSString *NSSpeechErrorNewestCharacterOffset

Declared In

Synthesizer Information

These constants identify synthesizer properties (used with NSSpeechSynthesizerInfoProperty).

NSString *NSSpeechSynthesizerInfoIdentifier
NSString *NSSpeechSynthesizerInfoVersion

Declared In

Speech Command Delimiter

These constants identify speech-command delimiters in synthesized text (used with NSSpeechCommandDelimiterProperty).

NSString *NSSpeechCommandPrefix
NSString *NSSpeechCommandSuffix

Declared In

Dictionary Properties

These constants identify speech-dictionary properties (use with -addSpeechDictionary).

NSString *NSSpeechDictionaryLanguage
NSString *NSSpeechDictionaryModificationDate
NSString *NSSpeechDictionaryPronunciations
NSString *NSSpeechDictionaryAbreviations
NSString *NSSpeechDictionaryEntrySpelling
NSString *NSSpeechDictionaryEntryPhonemes

Declared In

NSSpeechBoundary

These constants are used in stopping and pausing speech.

enum {
   NSSpeechImmediateBoundary =  0,
   NSSpeechWordBoundary,
   NSSpeechSentenceBoundary
};
typedef NSUInteger NSSpeechBoundary;

Availability

• Available in Mac OS X v10.5 and later.

Declared In

Next Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice