---

NSSpeechRecognizer Class Reference

Overview

The NSSpeechRecognizer class is the Cocoa interface to Speech Recognition on Mac OS X. Speech Recognition is architected as a “command and control” voice recognition system. It uses a finite state grammar and listens for phrases in that grammar. When it recognizes a phrase, it notifies the client process. This architecture is different from that used to support dictation.

Through an NSSpeechRecognizer instance, Cocoa applications can use the speech recognition engine built into Mac OS X to recognize spoken commands. With speech recognition, users can accomplish complex, multi-step tasks with one spoken command—for example, “schedule a meeting with Adam and John tomorrow at ten o’clock.”

The NSSpeechRecognizer class has methods that let you specify which spoken words should be recognized as commands (setCommands:) and to start and stop listening (startListening and stopListening). When the Speech Recognition facility recognizes one of the designated commands, NSSpeechRecognizer invokes the delegation method speechRecognizer:didRecognizeCommand:, allowing the delegate to perform the command.

Speech Recognition is just one of the Mac OS X speech technologies. The Speech Synthesis technology allows applications to “pronounce” written text in U.S. English; the NSSpeechSynthesizer class is the Cocoa interface to this technology. These 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. By incorporating speech into your application, you can provide a concurrent mode of interaction for your users: In Mac OS X, your software can accept input and provide output without requiring users to change their working context.

Tasks

Creating Speech Recognizers

• – init

Configuring Speech Recognizers

• – commands
• – setCommands:
• – displayedCommandsTitle
• – setDisplayedCommandsTitle:
• – listensInForegroundOnly
• – setListensInForegroundOnly:
• – blocksOtherRecognizers
• – setBlocksOtherRecognizers:
• – delegate
• – setDelegate:

Listening

• – startListening
• – stopListening

Recognizing Commands

• – speechRecognizer:didRecognizeCommand:  delegate method

Instance Methods

blocksOtherRecognizers

Returns whether the receiver should block all other recognizers (that is, other applications attempting to understand spoken commands) when listening.

- (BOOL)blocksOtherRecognizers

Availability

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

See Also

• – setBlocksOtherRecognizers:

Declared In

NSSpeechRecognizer.h

commands

Returns an array of strings defining the commands for which the receiver should listen.

- (NSArray *)commands

Availability

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

See Also

• – setCommands:

Declared In

NSSpeechRecognizer.h

delegate

Returns the receiver’s delegate.

- (id)delegate

Availability

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

See Also

• – setDelegate:

Declared In

NSSpeechRecognizer.h

displayedCommandsTitle

Returns the title of the commands section or nil if there is no title.

- (NSString *)displayedCommandsTitle

Discussion

Commands are displayed in the Speech Commands window indented under a section with this title.

Availability

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

See Also

• – setDisplayedCommandsTitle:

Declared In

NSSpeechRecognizer.h

init

Initializes and returns an instance of the NSSpeechRecognizer class.

- (id)init

Discussion

Returns nil if initialization did not succeed.

Availability

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

Declared In

NSSpeechRecognizer.h

listensInForegroundOnly

Returns whether the receiver should only enable its commands when the receiver’s application is the frontmost one.

- (BOOL)listensInForegroundOnly

Availability

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

See Also

• – setListensInForegroundOnly:

Declared In

NSSpeechRecognizer.h

setBlocksOtherRecognizers:

Sets whether the receiver’s commands should be the only enabled commands on the system.

- (void)setBlocksOtherRecognizers:(BOOL)flag

Discussion

If flag is YES, all other speech recognition commands on the system are disabled until the receiver object is released, listening is stopped, or this method is called again with flag as NO. Because this option effectively takes over the computer at the expense of other applications using speech recognition, you should use it only in circumstances that warrant it, such as when listening for a response important to overall system operation or when an application is running in full-screen mode (such as games and presentation software). The default is NO.

Availability

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

See Also

• – blocksOtherRecognizers

Declared In

NSSpeechRecognizer.h

setCommands:

Sets the list of commands for which the receiver should listen to commands.

- (void)setCommands:(NSArray *)commands

Discussion

If the receiver is already listening, the current command list is updated and listening continues. commands should be an array of NSString objects. The commands must be in U.S. English.

Availability

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

See Also

• – commands

Declared In

NSSpeechRecognizer.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id)anObject

Availability

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

See Also

• – delegate

Declared In

NSSpeechRecognizer.h

setDisplayedCommandsTitle:

Sets whether the speech-recognition commands should be displayed indented under a section title in the Speech Commands window, and if so, sets the title string to display.

- (void)setDisplayedCommandsTitle:(NSString *)title

Discussion

When title is a non-empty string, the receiver’s commands are displayed under a section with title. If title is nil or an empty string, the commands are displayed at the top level of the Speech Commands window. This default is not to display the commands under a section title.

Availability

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

See Also

• – displayedCommandsTitle

Declared In

NSSpeechRecognizer.h

setListensInForegroundOnly:

Sets whether the receiver should only enable its commands when the receiver’s application is the frontmost one.

- (void)setListensInForegroundOnly:(BOOL)flag

Discussion

If flag is YES, the receiver’s commands are only recognized when the receiver’s application is the frontmost application—normally the application displaying the menu bar. If flag is NO, the commands are recognized regardless of the visibility of applications, including agent applications (agent applications, which have the LSUIElement property set, do not appear in the Dock or Force Quit window). The default is YES.

Availability

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

See Also

• – listensInForegroundOnly

Declared In

NSSpeechRecognizer.h

startListening

Tells the speech recognition engine to begin listening for commands.

- (void)startListening

Discussion

When a command is recognized the message speechRecognizer:didRecognizeCommand: is sent to the delegate.

Availability

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

See Also

• – stopListening

Declared In

NSSpeechRecognizer.h

stopListening

Tells the speech recognition engine to suspend listening for commands.

- (void)stopListening

Availability

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

See Also

• – startListening

Declared In

NSSpeechRecognizer.h

Delegate Methods

speechRecognizer:didRecognizeCommand:

Invoked when the recognition engine has recognized the application command command.

- (void)speechRecognizer:(NSSpeechRecognizer *)sender didRecognizeCommand:(id)command

Discussion

command is one of the strings from the array passed to setCommands:. The delegate typically evaluates which command was recognized and performs the related action.

Availability

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

Declared In

NSSpeechRecognizer.h

---