Speech Recognition Manager Reference

Overview

The Speech Recognition Manager provides speech recognition support in applications.

Functions by Task

Opening and Closing Recognition Systems

• SRCloseRecognitionSystem
• SROpenRecognitionSystem

Creating and Manipulating Recognizers

• SRCancelRecognition
• SRContinueRecognition
• SRGetLanguageModel
• SRIdle
• SRNewRecognizer
• SRSetLanguageModel
• SRStartListening
• SRStopListening

Managing Speech Objects

• SRGetProperty
• SRGetReference
• SRReleaseObject
• SRSetProperty

Traversing Speech Objects

• SRCountItems
• SRGetIndexedItem
• SRRemoveIndexedItem
• SRSetIndexedItem

Creating Language Objects

• SRNewLanguageModel
• SRNewPath
• SRNewPhrase
• SRNewWord

Manipulating Language Objects

• SRAddLanguageObject
• SRAddText
• SRChangeLanguageObject
• SREmptyLanguageObject
• SRNewLanguageObjectFromHandle
• SRNewLanguageObjectFromDataFile
• SRPutLanguageObjectIntoHandle
• SRPutLanguageObjectIntoDataFile
• SRRemoveLanguageObject

Using the System Feedback Window

• SRDrawRecognizedText
• SRDrawText
• SRProcessBegin
• SRProcessEnd
• SRSpeakAndDrawText
• SRSpeakText
• SRSpeechBusy
• SRStopSpeech

Creating, Invoking and Disposing UPPs

• NewSRCallBackUPP
• DisposeSRCallBackUPP
• InvokeSRCallBackUPP

Functions

DisposeSRCallBackUPP

Disposes of a universal procedure pointer (UPP) to a speech recognition callback function.

void DisposeSRCallBackUPP (
   SRCallBackUPP userUPP
);

InvokeSRCallBackUPP

Invokes your speech recognition callback function.

void InvokeSRCallBackUPP (
   SRCallBackStruct *param,
   SRCallBackUPP userUPP
);

NewSRCallBackUPP

Creates a new universal procedure pointer (UPP) to a speech recognition callback function.

SRCallBackUPP NewSRCallBackUPP (
   SRCallBackProcPtr userRoutine
);

SRAddLanguageObject

Adds a language object to some other language object.

OSErr SRAddLanguageObject (
   SRLanguageObject base,
   SRLanguageObject addon
);

SRAddText

Adds text to the contents of a language object.

OSErr SRAddText (
   SRLanguageObject base,
   const void *text,
   SInt32 textLength,
   SRefCon refCon
);

SRCancelRecognition

Cancels the attempt to recognize the current utterance.

OSErr SRCancelRecognition (
   SRRecognizer recognizer
);

SRChangeLanguageObject

Changes the contents of a language object.

OSErr SRChangeLanguageObject (
   SRLanguageObject languageObject,
   const void *text,
   SInt32 textLength
);

SRCloseRecognitionSystem

Closes a recognition system when your application is finished using it (for example, just before your application quits).

OSErr SRCloseRecognitionSystem (
   SRRecognitionSystem system
);

SRContinueRecognition

Causes a recognizer to continue recognizing speech.

OSErr SRContinueRecognition (
   SRRecognizer recognizer
);

SRCountItems

Determines the number of subitems in a container object.

OSErr SRCountItems (
   SRSpeechObject container,
   long *count
);

SRDrawRecognizedText

Draws recognized text in the feedback window.

OSErr SRDrawRecognizedText (
   SRRecognizer recognizer,
   const void *dispText,
   SInt32 dispLength
);

SRDrawText

Draws output text in the feedback window.

OSErr SRDrawText (
   SRRecognizer recognizer,
   const void *dispText,
   SInt32 dispLength
);

SREmptyLanguageObject

Empties the contents of a language object.

OSErr SREmptyLanguageObject (
   SRLanguageObject languageObject
);

SRGetIndexedItem

Gets a subitem in a container object.

OSErr SRGetIndexedItem (
   SRSpeechObject container,
   SRSpeechObject *item,
   long index
);

SRGetLanguageModel

Gets a recognizer’s active language model.

OSErr SRGetLanguageModel (
   SRRecognizer recognizer,
   SRLanguageModel *languageModel
);

SRGetProperty

Gets the current value of a property of a speech object.

OSErr SRGetProperty (
   SRSpeechObject srObject,
   OSType selector,
   void *property,
   Size *propertyLen
);

SRGetReference

Obtains an extra reference to a speech object.

OSErr SRGetReference (
   SRSpeechObject srObject,
   SRSpeechObject *newObjectRef
);

SRIdle

Grants processing time to the Speech Recognition Manager if your application does not call WaitNextEvent frequently.

OSErr SRIdle (
   void
);

SRNewLanguageModel

Creates a new language model.

OSErr SRNewLanguageModel (
   SRRecognitionSystem system,
   SRLanguageModel *model,
   const void *name,
   SInt32 nameLength
);

SRNewLanguageObjectFromDataFile

Reads a language object from a data file.

OSErr SRNewLanguageObjectFromDataFile (
   SRRecognitionSystem system,
   SRLanguageObject *languageObject,
   short fRefNum
);

SRNewLanguageObjectFromHandle

Creates a language object from the handle previously created by the SRPutLanguageObjectIntoHandle function.

OSErr SRNewLanguageObjectFromHandle (
   SRRecognitionSystem system,
   SRLanguageObject *languageObject,
   Handle lObjHandle
);

SRNewPath

Creates a new path.

OSErr SRNewPath (
   SRRecognitionSystem system,
   SRPath *path
);

SRNewPhrase

Creates a new phrase.

OSErr SRNewPhrase (
   SRRecognitionSystem system,
   SRPhrase *phrase,
   const void *text,
   SInt32 textLength
);

SRNewRecognizer

Creates a new recognizer.

OSErr SRNewRecognizer (
   SRRecognitionSystem system,
   SRRecognizer *recognizer,
   OSType sourceID
);

SRNewWord

Creates a new word.

OSErr SRNewWord (
   SRRecognitionSystem system,
   SRWord *word,
   const void *text,
   SInt32 textLength
);

SROpenRecognitionSystem

Opens a recognition system.

OSErr SROpenRecognitionSystem (
   SRRecognitionSystem *system,
   OSType systemID
);

SRProcessBegin

Indicates that a recognition result is being processed.

OSErr SRProcessBegin (
   SRRecognizer recognizer,
   Boolean failed
);

SRProcessEnd

Indicates that a recognition result is done being processed.

OSErr SRProcessEnd (
   SRRecognizer recognizer,
   Boolean failed
);

SRPutLanguageObjectIntoDataFile

Puts a language object (and any embedded language objects it contains) into a data file.

OSErr SRPutLanguageObjectIntoDataFile (
   SRLanguageObject languageObject,
   short fRefNum
);

SRPutLanguageObjectIntoHandle

Puts a language object (and any embedded languages objects it contains) into a handle.

OSErr SRPutLanguageObjectIntoHandle (
   SRLanguageObject languageObject,
   Handle lobjHandle
);

SRReleaseObject

Releases a speech object.

OSErr SRReleaseObject (
   SRSpeechObject srObject
);

SRRemoveIndexedItem

Removes a subitem from a container object.

OSErr SRRemoveIndexedItem (
   SRSpeechObject container,
   long index
);

SRRemoveLanguageObject

Removes a language object from another language object that contains it.

OSErr SRRemoveLanguageObject (
   SRLanguageObject base,
   SRLanguageObject toRemove
);

SRSetIndexedItem

Replaces a subitem in a container object with some other object.

OSErr SRSetIndexedItem (
   SRSpeechObject container,
   SRSpeechObject item,
   long index
);

SRSetLanguageModel

Sets a recognizer’s active language model.

OSErr SRSetLanguageModel (
   SRRecognizer recognizer,
   SRLanguageModel languageModel
);

SRSetProperty

Sets the value of a property of a speech object.

OSErr SRSetProperty (
   SRSpeechObject srObject,
   OSType selector,
   const void *property,
   Size propertyLen
);

SRSpeakAndDrawText

Draws output text in the feedback window and causes the feedback character in the feedback window to speak that text.

OSErr SRSpeakAndDrawText (
   SRRecognizer recognizer,
   const void *text,
   SInt32 textLength
);

SRSpeakText

Causes the feedback character in the feedback window to speak a text string.

OSErr SRSpeakText (
   SRRecognizer recognizer,
   const void *speakText,
   SInt32 speakLength
);

SRSpeechBusy

Determines if the feedback character in a feedback window is currently speaking.

Boolean SRSpeechBusy (
   SRRecognizer recognizer
);

SRStartListening

Starts a recognizer listening and reporting results to your application.

OSErr SRStartListening (
   SRRecognizer recognizer
);

SRStopListening

Stops a recognizer listening and reporting results to your application.

OSErr SRStopListening (
   SRRecognizer recognizer
);

SRStopSpeech

Terminates speech by the feedback character in a feedback window.

OSErr SRStopSpeech (
   SRRecognizer recognizer
);

Callbacks

SRCallBackProcPtr

Defines a pointer to a speech recognition callback function which is called whenever the recognizer encounters one of the events specified in its kSRNotificationParam property.

typedef void (*SRCallBackProcPtr) (
   SRCallBackStruct * param
);

If you name your function MySRCallBackProc, you would declare it like this:

void MySRCallBackProc (
   SRCallBackStruct * param
);

Data Types

SRCallBackParam

Defines a speech recognition callback parameter structure.

struct SRCallBackParam {
   SRCallBackUPP callBack;
   long refCon;
};
typedef struct SRCallBackParam SRCallBackParam;

Fields

callBack

A UPP for a speech recognition callback function. You can use the function NewSRCallBackUPP to create this UPP.

refCon

An application-defined reference constant. This value is passed to your callback routine in the refcon field of a speech recognition callback structure. You can pass any 4-byte value you wish.

SRCallBackStruct

Defines a structure sent to your speech recognition callback function.

struct SRCallBackStruct {
   long what;
   long message;
   SRRecognizer instance;
   OSErr status;
   short flags;
   long refCon;
};
typedef struct SRCallBackStruct SRCallBackStruct;

Fields

what

A notification flag that indicates the kind of event that caused this notification to be issued. This field contains either kSRNotifyRecognitionBeginning or kSRNotifyRecognitionDone. See “Notification Flags” for complete details on the available notification flags.

message

If the value of the status field is noErr and the value of the what field is kSRNotifyRecognitionDone, this field contains a reference to a recognition result. Your callback routine can inspect the properties of this recognition result to determine what the user said.

Note that your callback routine must release this reference (by calling SRReleaseObject) when it is finished using it. If the value of the status field is not noErr, the value of this field is undefined.

instance

A reference to the recognizer that issued this notification. You should not call SRReleaseObject on this recognizer reference in response to a recognition notification.

status

An error code indicating the status of the recognition. If the value of this field is noErr, the message field contains a reference to a recognition result. If the value of this field is kSRRecognitionDone and the value of the what field is kSRNotifyRecognitionDone, the recognizer finished without error but nothing belonging to that recognizer was recognized; in this case, the message field does not contain a reference to a recognition result. If the value of this field is any other value, some other error occurred.

flags

Reserved for use by Apple Computer, Inc.

refCon

An application-defined reference constant. The value in this field is the value you passed in the refcon field of a callback function parameter structure (of type SRCallBackParam).

SRCallBackUPP

Defines a universal procedure pointer (UPP) to a speech recognition callback function.

typedef SRCallBackProcPtr SRCallBackUPP;

SRLanguageModel

Represents a language model.

typedef SRLanguageObject SRLanguageModel;

SRLanguageObject

Represents a language object.

typedef SRSpeechObject SRLanguageObject;

SRPath

Represents a language object identifying a path.

typedef SRLanguageObject SRPath;

SRPhrase

Represents a language object identifying a phrase.

typedef SRLanguageObject SRPhrase;

SRRecognitionResult

Represents a recognition result which contains information about a recognized utterance.

typedef SRSpeechSource SRRecognitionResult;

SRRecognitionSystem

Represents a speech object identifying a recognition system.

typedef SRSpeechObject SRRecognitionSystem;

SRRecognizer

Represents a speech object identifying a speech recognizer.

typedef SRSpeechObject SRRecognizer;

SRRejectionLevel

typedef  SRRejectionLevel;

SRSpeechObject

Defines a reference to a speech object.

typedef struct OpaqueSRSpeechObject * SRSpeechObject;

SRSpeechSource

Represents a speech object identifying a speech source.

typedef SRSpeechObject SRSpeechSource;

SRSpeedSetting

typedef  SRSpeedSetting;

SRWord

Represents a language object identifying a word.

typedef SRLanguageObject SRWord;

Constants

Feedback and Listening Modes

Identify the feedback and listening modes of the recognition system.

enum {
   kSRNoFeedbackNoListenModes = 0,
   kSRHasFeedbackHasListenModes = 1,
   kSRNoFeedbackHasListenModes = 2
};

Constants

kSRNoFeedbackNoListenModes

If the feedback and listening modes value of a recognition system is set to kSRNoFeedbackNoListenModes, the next created recognizer has no feedback window and does not use the listening modes selected by the user in the Speech control panel. (For example, push-to-talk is a listening mode.)

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRHasFeedbackHasListenModes

If the feedback and listening modes value of a recognition system is set to kSRHasFeedbackHasListenModes, the next created recognizer opens a feedback window that uses the listening modes selected by the user in the Speech control panel.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRNoFeedbackHasListenModes

If the feedback and listening modes value of a recognition system is set to kSRNoFeedbackHasListenModes, the next created recognizer has no feedback window but does use the listening modes selected by the user in the Speech control panel.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Apple Event Selectors

Define selectors that you can use to handle recognition notifications in your Apple event handler.

enum {
   kAESpeechDone = 'srsd',
   kAESpeechDetected = 'srbd'
};
enum {
   kAESpeechSuite = 'sprc'
};
enum {
   keySRRecognizer = 'krec',
   keySRSpeechResult = 'kspr',
   keySRSpeechStatus = 'ksst'
};
enum {
   typeSRRecognizer = 'trec',
   typeSRSpeechResult = 'tspr'
};

Constants

kAESpeechDone

The message ID for a speech-done event.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kAESpeechDetected

The message ID for a speech-detected event.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kAESpeechSuite

The Apple event suite for speech recognition events.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

keySRRecognizer

The ID for the recognizer parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

keySRSpeechResult

The ID for the recognition result parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

keySRSpeechStatus

The ID for the speech status parameter, which is of type typeSInt16.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

typeSRRecognizer

The type for the recognizer parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

typeSRSpeechResult

The type for the recognition result parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Default Rejection Level

Represents a default rejection level.

enum {
   kSRDefaultRejectionLevel = 50
};

Constants

kSRDefaultRejectionLevel

The default rejection level.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Language Object Properties

Define property selectors for language objects.

enum {
   kSRSpelling = 'spel',
   kSRLMObjType = 'lmtp',
   kSRRefCon = 'refc',
   kSROptional = 'optl',
   kSREnabled = 'enbl',
   kSRRepeatable = 'rptb',
   kSRRejectable = 'rjbl',
   kSRRejectionLevel = 'rjct'
};

Constants

kSRSpelling

The spelling of a language object. The value of this property is a variable-length string of characters. For an object of type SRWord, the value is the spelled word. For an object of type SRPhrase, the value is the concatenation of the spellings of each word in the phrase, separated by a language-dependent separation character (for example, by a space character). For an object of type SRPath, the value is the concatenation of the spellings of each word and language model name in the path. For an object of type SRLanguageModel, the value is the name of the language model. For any object, the string value does not include either a length byte (as in Pascal strings) or a null terminating character (as in C strings).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRLMObjType

The type of a language object. The value of this property is a four-character constant of type OSType; see the section “Language Object Types” for the values that are defined for this property. You cannot set a property of this type.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRRefCon

The reference constant. The value of this property is a 4-byte value specified by your application. By default, the value of a reference constant property is zero (0).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSROptional

The optional flag. The value of this property is a Boolean value that indicates whether speaking the words, phrases, paths, and language models represented by the object is optional (TRUE) or required (FALSE). A user is not required to utter optional words, phrases, or language models. By default, the value of an object’s optional flag is FALSE.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSREnabled

The enabled flag. The value of this property is a Boolean value that indicates whether the object is enabled (TRUE) or disabled (FALSE). Disabled objects are ignored during speech recognition. By default, the value of an object’s enabled flag is TRUE.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRRepeatable

The repeatable flag. The value of this property is a Boolean value that indicates whether the object is repeatable (TRUE) or not (FALSE). A user can utter a repeatable object more than once. By default, the value of an object’s repeatable flag is FALSE.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRRejectable

The rejectable flag. The value of this property is a Boolean value that indicates whether the object is rejectable (TRUE) or not (FALSE). An object is rejectable if a recognition system can return the rejected word instead of that object. (The rejected word is the value of the kSRRejectedWord property of the recognition system.) By default, the value of an object’s rejectable flag is FALSE. However, if an entire utterance is rejected, you can still get the rejected word. See “Recognition Result Properties.”

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRRejectionLevel

The rejection level. The value of this property is a 2-byte unsigned integer of type SRRejectionLevel between 0 and 100, inclusive, that determines how likely a recognizer is to reject a language object whose kSRRejectable property is TRUE. If an object’s rejection level is close to 0, the recognizer is less likely to reject utterances (and hence more likely to return a result with phrases from the current language model, whether or not the user actually said something in that language model) if an object’s rejection level is close to 100, the recognizer is more likely to reject utterances. You can set an object’s rejection flag to TRUE and its rejection level to some appropriate value to reduce the likelihood that a recognizer will mistakenly recognize a random user utterance as part of the active language model. By default, the value of an object’s rejection level is 50.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Language Object Types

Identify the four subclasses of the SRLanguageObject class.

enum {
   kSRLanguageModelType = 'lmob',
   kSRPathType = 'path',
   kSRPhraseType = 'phra',
   kSRWordType = 'word'
};

Constants

kSRLanguageModelType

A language model (that is, an object of type SRLanguageModel).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRPathType

A path (that is, an object of type SRPath).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRPhraseType

A phrase (that is, an object of type SRPhrase).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRWordType

A word (that is, an object of type SRWord).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Listen Key Modes

Identify listen key modes.

enum {
   kSRUseToggleListen = 0,
   kSRUsePushToTalk = 1
};

Constants

kSRUseToggleListen

The recognizer interprets presses on the listen key as a toggle to turn listening on or off.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRUsePushToTalk

The recognizer listens only when the listen key is held down.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Notification Flags

Identify the recognizer events that may be sent to an application.

enum {
   kSRNotifyRecognitionBeginning = 1L << 0,
   kSRNotifyRecognitionDone = 1L << 1
};

Constants

kSRNotifyRecognitionBeginning

If this bit is set, your application will be notified when the user starts speaking and recognition is ready to begin. When your application gets this notification, it must call either SRContinueRecognition or SRCancelRecognition in order for recognition either to continue or be canceled. If you do not call one of these functions, the recognizer will simply wait until you do (and hence appear to have quit working). Note that calling SRCancelRecognition cancels a recognition only for the application that requested it, not for all applications.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRNotifyRecognitionDone

If this bit is set, your application will be notified when recognition is finished and the result (if any) of that recognition is available.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Recognition Result Properties

Identify property selectors for recognition results.

enum {
   kSRTEXTFormat = 'TEXT',
   kSRPhraseFormat = 'lmph',
   kSRPathFormat = 'lmpt',
   kSRLanguageModelFormat = 'lmfm'
};

Constants

kSRTEXTFormat

The text format. The value of this property is a variable-length string of characters that is the text of the recognized utterance. If the utterance was rejected, this text is the spelling of the rejected word. The string value does not include either a length byte (as in Pascal strings) or a null terminating character (as in C strings).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRPhraseFormat

The phrase format. The value of this property is a phrase that contains one word (of type SRWord) for each word in the recognized utterance. If the utterance was rejected, this path or phrase contains one object, the rejected word. The reference constant value of the phrase is always 0, but each word in the phrase retains its own reference constant property value.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRPathFormat

The path format. The value of this property is a path that contains a sequence of words (of type SRWord) and phrases (of type SRPhrase) representing the text of the recognized utterance. If the utterance was rejected, this path or phrase contains one object, the rejected word. The reference constant value of the path is always 0, but each word or phrase in the path retains its own reference constant property value.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRLanguageModelFormat

The language model format. The value of this property is a language model that contains a copy of each word, phrase, path, and language model used in the recognized utterance. If the utterance was rejected, the value of this property is the rejected word (that is, the kSRRejectedWord property of the recognition system). The name and reference constant of this language model are the same as the name and reference constant of the active language model, and each subitem in the language model retains its own reference constant property value.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Recognition System IDs

Defines a recognition system ID.

enum {
   kSRDefaultRecognitionSystemID = 0
};

Constants

kSRDefaultRecognitionSystemID

The default speech recognition system.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Recognition System Properties

Define property selectors for recognition systems.

enum {
   kSRFeedbackAndListeningModes = 'fbwn',
   kSRRejectedWord = 'rejq',
   kSRCleanupOnClientExit = 'clup'
};

Constants

kSRFeedbackAndListeningModes

The feedback and listening modes of the recognition system. The value of this property is an integer that determines some of the features of a recognizer subsequently created by your application. See “Feedback and Listening Modes” for a description of the values possible here.

The default value for version 1.5 is kSRNoFeedbackNoListenModes, but most applications should set this to kSRHasFeedbackHasListenModes.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRRejectedWord

The rejected word of the recognition system. The value of this property is a value of type SRWord that will be returned in a recognition result object when a recognizer encounters an unrecognizable utterance. For example, if an utterance is rejected, the kSRLMObjType property of the rejection result is the rejected word. By default, a recognition system’s rejected word is spelled “???” and has a reference constant of 0.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRCleanupOnClientExit

The cleanup mode of the recognition system. Applications should never set this property. If, however, you do not have a process ID (as issued by the Process Manager), you should set this property to FALSE so that speech objects you allocate will not be associated with any other process. By default, the value of a recognition system’s cleanup mode is TRUE.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Recognizer Listen Key Properties

Define listen key property selectors for recognizers.

enum {
   kSRListenKeyMode = 'lkmd',
   kSRListenKeyCombo = 'lkey',
   kSRListenKeyName = 'lnam',
   kSRKeyWord = 'kwrd',
   kSRKeyExpected = 'kexp'
};

Constants

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 “Listen Key Modes” 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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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. 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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Recognizer Properties

Define property selectors for recognizers.

enum {
   kSRNotificationParam = 'noti',
   kSRCallBackParam = 'call',
   kSRSearchStatusParam = 'stat',
   kSRAutoFinishingParam = 'afin',
   kSRForegroundOnly = 'fgon',
   kSRBlockBackground = 'blbg',
   kSRBlockModally = 'blmd',
   kSRWantsResultTextDrawn = 'txfb',
   kSRWantsAutoFBGestures = 'dfbr',
   kSRSoundInVolume = 'volu',
   kSRReadAudioFSSpec = 'aurd',
   kSRCancelOnSoundOut = 'caso',
   kSRSpeedVsAccuracyParam = 'sped'
};

Constants

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” for the bit masks that are defined for this property. By default, the value of a recognizer’s notification property is kSRNotifyRecognitionDone.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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” for the bit masks that are defined for this property. This property is read-only; you cannot set a property of this type.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRAutoFinishingParam

The auto-finishing parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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 is not the foreground application in addition, the feedback window is hidden if you are 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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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 is busy performing the task. By default, the value of a recognizer’s automatic feedback gestures flag is TRUE.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

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.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRSpeedVsAccuracyParam

The speed vs accuracy parameter.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Search Status Flags

Indicate the status of a recognizer search.

enum {
   kSRIdleRecognizer = 1L << 0,
   kSRSearchInProgress = 1L << 1,
   kSRSearchWaitForAllClients = 1L << 2,
   kSRMustCancelSearch = 1L << 3,
   kSRPendingSearch = 1L << 4
};

Constants

kSRIdleRecognizer

If this bit is set, the search engine is not active and the user is able to make a new utterance.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRSearchInProgress

If this bit is set, a search is currently in progress.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRSearchWaitForAllClients

If this bit is set, a search is not currently in progress, but will begin as soon as every recognizer using the speech source used by this recognizer has called SRContinueRecognition to indicate that the search should begin.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRMustCancelSearch

If this bit is set, a search is about to be canceled (for example, because the recognizer determined a sound to be non-speech).

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRPendingSearch

If this bit is set, a search is about to begin.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Speech Source Constants

Identify Speech Recognition Manager-supported speech sources.

enum {
   kSRDefaultSpeechSource = 0,
   kSRLiveDesktopSpeechSource = 'dklv',
   kSRCanned22kHzSpeechSource = 'ca22'
};

Constants

kSRDefaultSpeechSource

The default speech source.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRLiveDesktopSpeechSource

Live desktop sound input.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

kSRCanned22kHzSpeechSource

AIFF file based 16 bit, 22.050 KHz sound input.

Available in OS X v10.0 and later.

Declared in SpeechRecognition.h.

Result Codes

The most common result codes returned by Speech Recognition Manager are listed below.

Gestalt Constants

You can check for version and feature availability information by using the Speech Recognition Manager selectors defined in the Gestalt Manager. For more information see Inside OS X: Gestalt Manager Reference.