Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.3 and later. |
Companion guide | |
Declared in | NSSpeechSynthesizer.h |
Related sample code |
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.
Instance attribute | Default value | Accessors |
---|---|---|
|
| |
| Identifier of the default voice |
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.
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.
– usesFeedbackWindow
– setUsesFeedbackWindow:
– voice
– setVoice:
– rate
– setRate:
– volume
– setVolume:
– addSpeechDictionary:
– objectForProperty:error:
– setObject:forProperty:error:
– delegate
– setDelegate:
– 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
Provides the attribute dictionary of a voice.
+ (NSDictionary *)attributesForVoice:(NSString *)voiceIdentifier
Identifier of the voice whose attributes you want to obtain.
Attribute dictionary of the voice identified by voiceIdentifier.
The keys and values of voice attribute dictionaries are described in “Constants.”
NSSpeechSynthesizer.h
Provides the identifiers of the voices available on the system.
+ (NSArray *)availableVoices
Array of strings representing the identifiers of each voice available on the system.
NSSpeechSynthesizer.h
Provides the identifier of the default voice.
+ (NSString *)defaultVoice
Identifier of the default voice.
NSSpeechSynthesizer.h
Indicates whether any other application is currently speaking through the sound output device.
+ (BOOL)isAnyApplicationSpeaking
YES
when another application is producing speech through the sound output device, NO
otherwise.
You usually invoke this method to prevent your application from speaking over speech being generated by another application or system component.
NSSpeechSynthesizer.h
Registers the given speech dictionary with the receiver.
- (void)addSpeechDictionary:(NSDictionary *)speechDictionary
Speech dictionary to add to the receiver’s dictionaries.
NSSpeechSynthesizer.h
Resumes synthesis.
- (void)continueSpeaking
If systhesis is paused, it’s resumed.
NSSpeechSynthesizer.h
Returns the receiver’s delegate.
- (id)delegate
The receiver’s delegate.
NSSpeechSynthesizer.h
Initializes the receiver with a voice.
- (id)initWithVoice:(NSString *)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.
Initialized speech synthesizer or nil
when the voice identified by voiceIdentifier is not available or when there’s an allocation error.
NSSpeechSynthesizer.h
Indicates whether the receiver is currently generating synthesized speech.
- (BOOL)isSpeaking
YES
when the receiver is generating synthesized speech, NO
otherwise.
NSSpeechSynthesizer.h
Provides the value of a receiver’s property.
- (id)objectForProperty:(NSString *)speechProperty error:(NSError **)out_error
Property to get.
On output, error that ocured while obtaining the value of speechProperty.
The value of speechProperty.
NSSpeechSynthesizer.h
Pauses synthesis in progress at a given boundary.
- (void)pauseSpeakingAtBoundary:(NSSpeechBoundary)boundary
Boundary at which to pause speech..
If the receiver is currently generating speech, synthesis is paused at boundary.
NSSpeechSynthesizer.h
Provides the phoneme symbols generated by the given text.
- (NSString *)phonemesFromText:(NSString *)text
Text from which to generate phonemes.
Phonemes generated from text.
NSSpeechSynthesizer.h
Provides the receiver’s speaking rate.
- (float)rate
Speaking rate (words per minute).
NSSpeechSynthesizer.h
Sets the receiver’s delegate.
- (void)setDelegate:(id)delegate
Object to be the receiver’s delegate.
NSSpeechSynthesizer.h
Specifies the value of a receiver’s property.
- (BOOL)setObject:(id)object forProperty:(NSString *) speechProperty error:(NSError **)out_error
Property to set.
On output, error that ocurred while setting speechProperty.
YES
when the speechProperty was set. NO
when there was an error, specified in out_error.
NSSpeechSynthesizer.h
Specifies the receivers speaking rate.
- (void)setRate:(float)rate
Words to speak per minute.
NSSpeechSynthesizer.h
Specifies whether the receiver uses the speech feedback window.
- (void)setUsesFeedbackWindow:(BOOL)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.
See the class description for details on the UsesFeedbackWindow
attribute.
Important: The delegate does not receive speechSynthesizer:willSpeakWord:ofString:
and speechSynthesizer:willSpeakPhoneme:
messages when speaking occurs through the feedback window.
NSSpeechSynthesizer.h
Sets the receiver’s current voice.
- (BOOL)setVoice:(NSString *)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.
YES
when the receiver is not currently synthesizing speech and the current voice is set successfully, NO
otherwise.
See the class description for details on the CurrentVoice
attribute.
NSSpeechSynthesizer.h
Specifies the receiver’s speaking volume.
- (void)setVolume:(float)volume
Sound level to use for speech.
NSSpeechSynthesizer.h
Begins speaking synthesized text through the system’s default sound output device.
- (BOOL)startSpeakingString:(NSString *)text
Text to synthesize. When nil
or empty, no synthesis occurs.
YES
when synthesis starts successfully, NO
otherwise.
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.
NSSpeechSynthesizer.h
Begins synthesizing text into a sound (AIFF) file.
- (BOOL)startSpeakingString:(NSString *)text toURL:(NSURL *)url
Text to synthesize. When nil
or empty, no synthesis is started.
Filesystem location of the output sound file.
YES
when synthesis starts successfully, NO
otherwise.
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.
Note: The delegate does not receive speechSynthesizer:willSpeakWord:ofString:
and speechSynthesizer:willSpeakPhoneme:
messages when text is being synthesized to a file.
NSSpeechSynthesizer.h
Stops synthesis in progress.
- (void)stopSpeaking
If the receiver is currently generating speech, synthesis is halted, and the message speechSynthesizer:didFinishSpeaking:
is sent to the delegate.
NSSpeechSynthesizer.h
Stops synthesis in progress at a given boundary.
- (void)stopSpeakingAtBoundary:(NSSpeechBoundary)boundary
Boundary at which to stop speech.
If the receiver is currently generating speech, synthesis is halted at boundary, and the message speechSynthesizer:didFinishSpeaking:
is sent to the delegate.
NSSpeechSynthesizer.h
Indicates whether the receiver uses the speech feedback window.
- (BOOL)usesFeedbackWindow
YES
when the receiver uses the speech feedback window, NO
otherwise.
NSSpeechSynthesizer.h
Returns the identifier of the receiver’s current voice.
- (NSString *)voice
Identifier of the receiver’s current voice.
NSSpeechSynthesizer.h
Provides the receiver’s speaking volume.
- (float)volume
Speaking volume: From 0.0
(minimum) to 1.0
(maximum).
NSSpeechSynthesizer.h
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
Speech synthesizer informing its delegate of an error.
Location in text where the reciver encountered the error.
Text the receiver was synthesizing when the error ocurred.
Error message.
NSSpeechSynthesizer.h
Sent to the delegate when a speech synthesizer encounters a synchronization error.
- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender didEncounterSyncMessage:(NSString *)errorMessage
Speech synthesizer informing its delegate of an error.
Error message.
NSSpeechSynthesizer.h
Sent when an NSSpeechSynthesizer
object finishes speaking through the sound output device.
- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender didFinishSpeaking:(BOOL)success
An NSSpeechSynthesizer
object that has stopped speaking into the sound output device.
YES
when speaking completed normally, NO
if speaking is stopped prematurely for any reason.
NSSpeechSynthesizer.h
Sent just before a synthesized phoneme is spoken through the sound output device.
- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender willSpeakPhoneme:(short)phonemeOpcode
An NSSpeechSynthesizer
object that’s synthesizing text into speech.
Phoneme that sender is about to speak into the sound output device.
One use of this method might be to animate a mouth on screen to match the generated speech.
Important: The delegate is not sent this message when the NSSpeechSynthesizer
object is synthesizing speech to a file (startSpeakingString:toURL:
).
NSSpeechSynthesizer.h
Sent just before a synthesized word is spoken through the sound output device.
- (void)speechSynthesizer:(NSSpeechSynthesizer *)sender willSpeakWord:(NSRange)wordToSpeak ofString:(NSString *)text
An NSSpeechSynthesizer
object that’s synthesizing text into speech.
Word that sender is about to speak into the sound output device.
Text that is being synthesized by sender.
One use of this method might be to visually highlight the word being spoken.
Important: The delegate is not sent this message when the NSSpeechSynthesizer
object is synthesizing speech to a file (startSpeakingString:toURL:
).
NSSpeechSynthesizer.h
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;
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
.
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 |
NSSpeechSynthesizer.h
The NSSpeechSynthesizer
class defines the following voice gender attributes, which are the allowable values of the NSVoiceGender
key:
NSString *NSVoiceGenderNeuter; NSString *NSVoiceGenderMale; NSString *NSVoiceGenderFemale;
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
.
NSSpeechSynthesizer.h
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
NSSpeechSynthesizer.h
These constants identify input modes (used with NSSpeechInputModeProperty
).
NSString *NSSpeechModeText NSString *NSSpeechModePhoneme
NSSpeechSynthesizer.h
These constants identify speech types (used with NSSpeechInputModeProperty
and NSSpeechNumberModeProperty
).
NSString *NSSpeechModeNormal NSString *NSSpeechModeLiteral
NSSpeechSynthesizer.h
These constants identify speech status (used with NSSpeechStatusProperty
).
NSString *NSSpeechStatusOutputBusy NSString *NSSpeechStatusOutputPaused NSString *NSSpeechStatusNumberOfCharactersLeft NSString *NSSpeechStatusPhonemeCode
NSSpeechSynthesizer.h
These constants identify errors that may occur during speech synthesis (used with NSSpeechErrorProperty
).
NSString *NSSpeechErrorCount NSString *NSSpeechErrorOldestCode NSString *NSSpeechErrorOldestCharacterOffset NSString *NSSpeechErrorNewestCode NSString *NSSpeechErrorNewestCharacterOffset
NSSpeechSynthesizer.h
These constants identify synthesizer properties (used with NSSpeechSynthesizerInfoProperty
).
NSString *NSSpeechSynthesizerInfoIdentifier NSString *NSSpeechSynthesizerInfoVersion
NSSpeechSynthesizer.h
These constants identify speech-command delimiters in synthesized text (used with NSSpeechCommandDelimiterProperty
).
NSString *NSSpeechCommandPrefix NSString *NSSpeechCommandSuffix
NSSpeechSynthesizer.h
These constants identify speech-dictionary properties (use with -addSpeechDictionary).
NSString *NSSpeechDictionaryLanguage NSString *NSSpeechDictionaryModificationDate NSString *NSSpeechDictionaryPronunciations NSString *NSSpeechDictionaryAbreviations NSString *NSSpeechDictionaryEntrySpelling NSString *NSSpeechDictionaryEntryPhonemes
NSSpeechSynthesizer.h
These constants are used in stopping and pausing speech.
enum { NSSpeechImmediateBoundary = 0, NSSpeechWordBoundary, NSSpeechSentenceBoundary }; typedef NSUInteger NSSpeechBoundary;
NSSpeechSynthesizer.h
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)