Mac Developer Library

Developer

AppKit Framework Reference NSSpeechRecognizer Class Reference

Options
Deployment Target:

On This Page
Language:

NSSpeechRecognizer

The NSSpeechRecognizer class is the Cocoa interface to Speech Recognition on OS X. This class provides a “command and control” style of voice recognition system, where the command phrases must be defined prior to listening, in contrast to a dictation system where the recognized text is unconstrained.

Through an NSSpeechRecognizer instance, Cocoa applications can use the speech recognition engine built into OS X to recognize spoken commands. With speech recognition, users can accomplish complex tasks with spoken commands—for example, “Move pawn B2 to B4” and “Take back move.”

The NSSpeechRecognizer class has a property that lets you specify which spoken words should be recognized as commands (commands) and methods that let you 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 OS X speech technologies. The Speech Synthesis technology allows applications to “pronounce” written text in U.S. English and over 25 other languages, with a number of different voices and dialects for each language (NSSpeechSynthesizer is the Cocoa interface to this technology). Both speech 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 OS X, your software can accept input and provide output without requiring users to change their working context.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.3 and later.
  • Initializes and returns an instance of the NSSpeechRecognizer class.

    Declaration

    Swift

    init()

    Objective-C

    - (instancetype)init

    Discussion

    Returns nil if initialization did not succeed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • commands commands Property

    An array of strings defining the commands for which the speech recognizer object should listen.

    Declaration

    Swift

    var commands: [AnyObject]?

    Objective-C

    @property(copy) NSArray *commands

    Discussion

    Setting this property when the speech recognizer is already listening means that the current command list is updated and listening continues. The items in the array should be NSString objects. The command strings must match the current locale of the recognizer, which is selected in the Dictation pane of Accessibility system preferences.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • The title of the commands section in the Speech Commands window or nil if there is no title.

    Declaration

    Swift

    var displayedCommandsTitle: String?

    Objective-C

    @property(copy) NSString *displayedCommandsTitle

    Discussion

    When this property is a non-empty string, commands are displayed in the Speech Commands window indented under a section with this 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the speech recognizer object should only enable its commands when its application is the frontmost one.

    Declaration

    Swift

    var listensInForegroundOnly: Bool

    Objective-C

    @property BOOL listensInForegroundOnly

    Discussion

    When the value of this property is YEStrue, the speech recognizer’s commands are only recognized when the speech recognizer’s application is the frontmost application—typically the application displaying the menu bar. If the value of the property is NOfalse, the commands are recognized regardless of the visibility of the application, including agent applications (agent applications, which have the LSUIElement property set, do not appear in the Dock or Force Quit window). The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • A Boolean value that indicates whether the speech recognizer object should block all other recognizers (that is, other applications attempting to understand spoken commands) when listening.

    Declaration

    Swift

    var blocksOtherRecognizers: Bool

    Objective-C

    @property BOOL blocksOtherRecognizers

    Discussion

    When the value of this property is YEStrue, all other speech recognition commands on the system are disabled until the speech recognizer is released, listening is stopped, or the property is set to NOfalse. Setting this property to YEStrue effectively takes over the computer at the expense of other applications using speech recognition, so 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 value of this property is NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • delegate delegate Property

    The delegate for the speech recognizer object.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSSpeechRecognizerDelegate?

    Objective-C

    @property(assign) id< NSSpeechRecognizerDelegate > delegate

    Discussion

    The delegate must conform to the NSSpeechRecognizerDelegate Protocol protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Tells the speech recognition engine to begin listening for commands.

    Declaration

    Swift

    func startListening()

    Objective-C

    - (void)startListening

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Tells the speech recognition engine to suspend listening for commands.

    Declaration

    Swift

    func stopListening()

    Objective-C

    - (void)stopListening

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.