Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Speech Recognition Manager /

Chapter 1 - Speech Recognition Manager / Speech Recognition Manager Reference

Recognizer Properties
Every recognizer has a set of properties that you can inspect and change by calling the SRGetProperty and SRSetProperty routines. You specify a property by passing a property selector to those functions. The Speech Recognition Manager defines these property selectors for recognizers:
enum {
   kSRNotificationParam                = 'noti',
   kSRCallBackParam                    = 'call',
   kSRSearchStatusParam                = 'stat',
   kSRForegroundOnly                   = 'fgon',
   kSRBlockBackground                  = 'blbg',
   kSRBlockModally                     = 'blmd',
   kSRWantsResultTextDrawn             = 'txfb',
   kSRWantsAutoFBGestures              = 'dfbr',
   kSRSoundInVolume                    = 'volu',
   kSRReadAudioFSSpec                  = 'aurd',
   kSRCancelOnSoundOut                 = 'caso',
   kSRListenKeyMode                    = 'lkmd',
   kSRListenKeyCombo                   = 'lkey',
   kSRListenKeyName                    = 'lnam',
   kSRKeyWord                          = 'kwrd',
   kSRKeyExpected                      = 'kexp'
};
Note
The listen key properties (that is, kSRListenKeyMode through kSRKeyExpected) are provided for use by applications that want to provide their own visual feedback. If your application uses the default feedback mechanisms, you do not need to access those properties.
Constant descriptions

kSRNotificationParam
The notification property. The value of this property is a 4-byte unsigned integer whose bits encode the kinds of events of which the recognizer will notify your application. See the section "Notification Flags" on page 1-45 for the bit masks that are defined for this property. By default, the value of a recognizer's notification property is kSRNotifyRecognitionDone.
kSRCallBackParam
The callback property. The value of this property is of type SRCallBackParam that determines whether recognition notifications are sent to your application via Apple events or via an application-defined callback routine. To specify a callback routine, set the value of this property to the address of a callback routine parameter structure. By default, the value of a recognizer's callback property is NULL, indicating that Apple events are to be used to report recognizer events.
kSRSearchStatusParam
The search status. The value of this property is a 4-byte unsigned integer whose bits indicate the current state of the recognizer. See the section "Search Status Flags" on page 1-44 for the bit masks that are defined for this property. This property is read-only; you cannot set a property of this type.
kSRForegroundOnly
The foreground-only flag. The value of this property is a Boolean value that indicates whether the recognizer is enabled only when your application is the foreground application (TRUE) or not (FALSE). By default, the value of a recognizer's foreground-only flag is TRUE.
kSRBlockBackground
The background-blocking flag. The value of this property is a Boolean value that indicates whether all recognizers owned by other applications are automatically disabled whenever your application is the foreground application (TRUE) or are not automatically disabled (FALSE). By default, the value of a recognizer's background-blocking flag is FALSE.
kSRBlockModally
The modal-blocking flag. The value of this property is a Boolean value that indicates whether the language model associated with this recognizer is the only active language model (TRUE) or not (FALSE). When this flag is TRUE, your application's recognizer blocks those of other applications even when it isn't the foreground application; in addition, the feedback window is hidden if you're not using it. Setting this property to TRUE prevents speech recognition from working for other applications, so you want to use this property only if your application is taking over the computer (like some games) or briefly attempting to constrain the language model severely. By default, the value of a recognizer's modal-blocking flag is FALSE.
kSRWantsResultTextDrawn
The text feedback flag. The value of this property is a Boolean value that indicates whether the results of a search are to be automatically displayed as text in the feedback window (TRUE) or not (FALSE). If you set the value of this property to FALSE, you should call SRDrawRecognizedText with a string representing what the user said. By default, the value of a recognizer's text feedback flag is TRUE.
kSRWantsAutoFBGestures
The automatic feedback gestures flag. The value of this property is a Boolean value that determines whether the feedback gestures are automatically drawn (TRUE) or not (FALSE). If you want more control over feedback behavior, you should set this property to FALSE; then call SRProcessBegin when you want to begin responding to a spoken request and SRProcessEnd when you are finished. During that time, the feedback character displays appropriate animated gestures to indicate that it's busy performing the task. By default, the value of a recognizer's automatic feedback gestures flag is TRUE.
kSRSoundInVolume
The sound input volume. The value of this property is a 2-byte unsigned integer between 0 and 100, inclusive, that indicates the current sound input volume. This property is read-only; you cannot set a property of this type.
kSRReadAudioFSSpec
The audio file property. You can use this property to perform speech recognition from an audio file. The value of this property is a pointer to a file system specification (a structure of type FSSpec). The file system specification indicates an AIFF file that contains raw audio data (16-bit audio data sampled at 22.050 kHz). After you create a new recognizer using the speech source ID kSRCanned22kHzSpeechSource, you must set this recognizer property to perform recognition from an audio file. Setting the audio source to a file also allows the Speech Recognition Manager to process sound data at system background time rather than at interrupt time or deferred task time.
kSRCancelOnSoundOut
The cancel during sound output flag. The value of this property is a Boolean value that indicates whether speech recognition is canceled whenever any sound is output by the computer during an utterance (TRUE) or whether speech recognition continues (FALSE). By default, the value of a recognizer's cancel during sound output flag is TRUE.
kSRListenKeyMode
The listen key mode. The value of this property is a 2-byte unsigned integer that indicates whether the listen key operates in push-to-talk or toggle-listening mode. See page 1-45 for a description of the available listen key modes. The value of a recognizer's listen key mode is whatever the user has selected in the Speech control panel. This property is read-only; you cannot set a property of this type.
kSRListenKeyCombo
The listen key combination property. The value of this property is a 2-byte unsigned integer that specifies the key combination the user must press for the listen key. The high-order byte of this value has the same format as the high-order byte of the modifiers field of an event record. The low-order byte of this value has the same format as the key code contained in the message field of an event record. (See Inside Macintosh: Macintosh Toolbox Essentials for complete information about event records.) The value of a recognizer's listen key combination property is whatever the user has selected in the Speech control panel. This property is read-only; you cannot set a property of this type.
kSRListenKeyName
The listen key name property. The value of this property is a string (of type Str63) that represents the listen key combination specified by the kSRListenKeyCombo property. The value of a recognizer's listen key name property is whatever the user has selected in the Speech control panel. This property is read-only; you cannot set a property of this type.
kSRKeyWord
The key word property. The value of this property is a string (of type Str255) that represents the key word that must precede utterances when the recognizer is in toggle-listen mode. The value of a recognizer's key word property is whatever the user has selected in the Speech control panel. This property is read-only; you cannot set a property of this type.
kSRKeyExpected
The key expected flag. The value of this property is a Boolean value that indicates whether the recognizer expects the user to hold down a key or to utter the key word in order to have the recognizer begin listening (TRUE) or not (FALSE). The value of a recognizer's key expected flag is a function of the user's Speech control panel selections. This property is TRUE whenever text is visible below the feedback character in the lower-left corner of the feedback window. This property is read-only.