Inside Macintosh: Speech Recognition Manager /

Chapter 1 - Speech Recognition Manager

Summary of the Speech Recognition Manager

C Summary

Constants

Gestalt Selectors and Response Values

enum {
   gestaltSpeechRecognitionVersion     = 'srtb',
   gestaltSpeechRecognitionAttr        = 'srta'
};
enum {
   gestaltDesktopSpeechRecognition     = 1L<<0,
   gestaltTelephoneSpeechRecognition   = 1L<<1
};

Recognition System IDs

enum {
   kSRDefaultRecognitionSystemID       = 0
};

Recognition System Properties

enum {
   kSRFeedbackAndListeningModes        = 'fbwn',
   kSRRejectedWord                     = 'rejq',
   kSRCleanupOnClientExit              = 'clup'
};
enum {
   kSRNoFeedbackNoListenModes          = 0,
   kSRHasFeedbackHasListenModes        = 1,
   kSRNoFeedbackHasListenModes         = 2
};

Speech Source IDs

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

Apple Event Selectors

/* Apple event message class */
enum {
   kAESpeechSuite                      = 'sprc'
};
/* Apple event message event IDs */
enum {
   kAESpeechDetected                   = 'srbd',
   kAESpeechDone                       = 'srsd'
};
/* Apple event parameter IDs */
enum {
   keySRRecognizer                     = 'krec',
   keySRSpeechResult                   = 'kspr',
   keySRSpeechStatus                   = 'ksst'
};
/* Apple event parameter types */
enum {
   typeSRRecognizer                    = 'trec',
   typeSRSpeechResult                  = 'tspr'
};

Recognizer Properties

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'
};

Search Status Flags

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

Notification Flags

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

Listen Key Modes

enum {
   kSRUseToggleListen                  = 0,
   kSRUsePushToTalk                    = 1
};

Recognition Result Properties

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

Language Object Properties

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

Language Object Types

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

Procedure Information

enum {
   uppSRCallBackProcInfo               = kPascalStackBased | 
         STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(SRCallBackStruct*)))
};

Default Rejection Level

enum {
   kSRDefaultRejectionLevel            = 50
};

Data Types

Speech Objects

typedef struct OpaqueSRSpeechObject    *SRSpeechObject;
typedef SRSpeechObject                 SRRecognitionSystem;
typedef SRSpeechObject                 SRRecognizer;
typedef SRSpeechObject                 SRSpeechSource;
typedef SRSpeechObject                 SRLanguageObject;
typedef SRSpeechSource                 SRRecognitionResult;

Language Objects

typedef SRLanguageObject               SRLanguageModel;
typedef SRLanguageObject               SRPath;
typedef SRLanguageObject               SRPhrase;
typedef SRLanguageObject               SRWord;

CallBack Structure

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

Callback Routine Type

#if GENERATINGCFM
typedef UniversalProcPtr      SRCallBackUPP;
#else
typedef SRCallBackProcPtr     SRCallBackUPP;
#endif

Callback Routine Parameter Structure

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

Other Types

typedef unsigned short        SRRejectionLevel;

Speech Recognition Manager Routines

Opening and Closing Recognition Systems

pascal OSErr SROpenRecognitionSystem (
SRRecognitionSystem *system, 
OSType systemID);
pascal OSErr SRCloseRecognitionSystem (
SRRecognitionSystem system);

Creating and Manipulating Recognizers

pascal OSErr SRNewRecognizer(SRRecognitionSystem system, 
SRRecognizer *recognizer, 
OSType sourceID);
pascal OSErr SRStartListening(SRRecognizer recognizer);
pascal OSErr SRStopListening(SRRecognizer recognizer);
pascal OSErr SRGetLanguageModel(SRRecognizer recognizer, 
SRLanguageModel *languageModel);
pascal OSErr SRSetLanguageModel(SRRecognizer recognizer, 
SRLanguageModel languageModel);
pascal OSErr SRContinueRecognition(SRRecognizer recognizer);
pascal OSErr SRCancelRecognition(SRRecognizer recognizer);
pascal OSErr SRIdle(void);

Managing Speech Objects

pascal OSErr SRGetProperty(SRSpeechObject srObject, 
OSType selector, 
void *property, 
Size *propertyLen);
pascal OSErr SRSetProperty(SRSpeechObject srObject, 
OSType selector, 
const void *property, 
Size propertyLen);
pascal OSErr SRGetReference(SRSpeechObject srObject, 
SRSpeechObject *newObjectRef);
pascal OSErr SRReleaseObject(SRSpeechObject srObject);

Traversing Speech Objects

pascal OSErr SRCountItems(SRSpeechObject container, long *count);
pascal OSErr SRGetIndexedItem(SRSpeechObject container, 
SRSpeechObject *item, 
long index);
pascal OSErr SRSetIndexedItem(SRSpeechObject container, 
SRSpeechObject item, 
long index);
pascal OSErr SRRemoveIndexedItem(SRSpeechObject container, long index);

Creating Language Objects

pascal OSErr SRNewWord(SRRecognitionSystem system, 
SRWord *word, 
const void *text, 
Size textLength);
pascal OSErr SRNewPhrase(SRRecognitionSystem system, 
SRPhrase *phrase, 
const void *text, 
Size textLength);
pascal OSErr SRNewPath(SRRecognitionSystem system, SRPath *path);
pascal OSErr SRNewLanguageModel(SRRecognitionSystem system, 
SRLanguageModel *model, 
const void *name, 
Size nameLength);

Manipulating Language Objects

pascal OSErr SRAddText(SRLanguageObject base, 
const void *text, 
Size textLength, 
long refCon);
pascal OSErr SRAddLanguageObject(SRLanguageObject base, SRLanguageObject addon);
pascal OSErr SREmptyLanguageObject(SRLanguageObject languageObject);
pascal OSErr SRChangeLanguageObject (
SRLanguageObject languageObject, 
const void *text, 
Size textLength);
pascal OSErr SRRemoveLanguageObject (
SRLanguageObject base, SRLanguageObject toRemove);
pascal OSErr SRPutLanguageObjectIntoHandle (
SRLanguageObject languageObject, Handle lobjHandle);
pascal OSErr SRPutLanguageObjectIntoDataFile (
SRLanguageObject languageObject, short fRefNum);
pascal OSErr SRNewLanguageObjectFromHandle (
SRRecognitionSystem system,
SRLanguageObject *languageObject, 
Handle lobjHandle);
pascal OSErr SRNewLanguageObjectFromDataFile (
SRRecognitionSystem system,
SRLanguageObject *languageObject, 
short fRefNum);

Using the System Feedback Window

pascal OSErr SRDrawText(SRRecognizer recognizer, 
const void *dispText, 
Size dispLength);
pascal OSErr SRDrawRecognizedText(SRRecognizer recognizer, 
const void *dispText, 
Size dispLength);
pascal OSErr SRSpeakText(SRRecognizer recognizer, 
const void *speakText, 
Size speakLength);
pascal OSErr SRSpeakAndDrawText(SRRecognizer recognizer, 
const void *text, 
Size textLength);
pascal OSErr SRProcessBegin(SRRecognizer recognizer, Boolean failed);
pascal OSErr SRProcessEnd(SRRecognizer recognizer, Boolean failed);
pascal OSErr SRStopSpeech(SRRecognizer recognizer);
pascal Boolean SRSpeechBusy(SRRecognizer recognizer);

Application-Defined Routines

Callback Routines

pascal void MySRCallBack(SRCallBackStruct *param);

Pascal Summary

Constants

Gestalt Selectors and Response Values

CONST
   gestaltSpeechRecognitionVersion     = 'srtb';
   gestaltSpeechRecognitionAttr        = 'srta';
   gestaltDesktopSpeechRecognition     = $00000001;
   gestaltTelephoneSpeechRecognition   = $00000002;

Recognition System IDs

   kSRDefaultRecognitionSystemID       = 0;

Recognition System Properties

   kSRFeedbackAndListeningModes        = 'fbwn';
   kSRRejectedWord                     = 'rejq';
   kSRCleanupOnClientExit              = 'clup';
   kSRNoFeedbackNoListenModes          = 0;
   kSRHasFeedbackHasListenModes        = 1;
   kSRNoFeedbackHasListenModes         = 2;

Speech Source IDs

   kSRDefaultSpeechSource              = 0;
   kSRLiveDesktopSpeechSource          = 'dklv';
   kSRCanned22kHzSpeechSource          = 'ca22';

Apple Event Selectors

   {Apple event message class}
   kAESpeechSuite                      = 'sprc';
   {Apple event message event IDs}
   kAESpeechDetected                   = 'srbd';
   kAESpeechDone                       = 'srsd';
   {Apple event parameter IDs}
   keySRRecognizer                     = 'krec';
   keySRSpeechResult                   = 'kspr';
   keySRSpeechStatus                   = 'ksst';
   {Apple event parameter types}
   typeSRRecognizer                    = 'trec';
   typeSRSpeechResult                  = 'tspr';

Recognizer Properties

   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';

Search Status Flags

   kSRIdleRecognizer                   = $00000001;
   kSRSearchInProgress                 = $00000002;
   kSRSearchWaitForAllClients          = $00000004;
   kSRMustCancelSearch                 = $00000008;
   kSRPendingSearch                    = $00000010;

Notification Flags

   kSRNotifyRecognitionBeginning       = $00000001;
   kSRNotifyRecognitionDone            = $00000002;

Recognition Result Properties

   kSRLanguageModelFormat              = 'lmfm';
   kSRPathFormat                       = 'lmpt';
   kSRPhraseFormat                     = 'lmph';
   kSRTEXTFormat                       = 'TEXT';

Language Object Properties

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

Language Object Types

   kSRLanguageModelType                = 'lmob';
   kSRPathType                         = 'path';
   kSRPhraseType                       = 'phra';
   kSRWordType                         = 'word';

Default Rejection Level

   kSRDefaultRejectionLevel            = 50;

Data Types

Speech Objects

TYPE
   SRSpeechObject    = ^LongInt;
   SRRecognitionSystem= SRSpeechObject;
   SRRecognizer      = SRSpeechObject;
   SRSpeechSource    = SRSpeechObject;
   SRLanguageObject  = SRSpeechObject;
   SRRecognitionResult= SRSpeechSource;

Language Objects

   SRLanguageModel   = SRLanguageObject;
   SRPath            = SRLanguageObject;
   SRPhrase          = SRLanguageObject;
   SRWord            = SRLanguageObject;

CallBack Structure

   SRCallBackStruct =
   RECORD
      what:                   LongInt;
      message:                LongInt;
      instance:               SRRecognizer;
      status:                 OSErr;
      flags:                  Integer;
      refcon:                 LongInt;
   END;
   SRCallBackStructPtr = ^SRCallBackStruct;
   SRCallBackStructHandle = ^SRCallBackStructPtr;

Callback Routine Type

   SRCallBackProcPtr = ProcPtr;
   SRCallBackUPP = SRCallBackProcPtr;

Callback Routine Parameter Structure

   SRCallBackParam = 
   RECORD
      callBack:               SRCallBackUPP;
      refcon:                 LongInt;
   END;
   SRCallBackParamPtr = ^SRCallBackParam;
   SRCallBackParamHandle = ^SRCallBackParamPtr;

Other Types

   SRRejectionLevel  = LongInt;

Speech Recognition Manager Routines

Opening and Closing Recognition Systems

FUNCTION SROpenRecognitionSystem(VAR system: SRRecognitionSystem; 
systemID: OSType): OSErr;
FUNCTION SRCloseRecognitionSystem(system: SRRecognitionSystem): OSErr;

Creating and Manipulating Recognizers

FUNCTION SRNewRecognizer(system: SRRecognitionSystem; 
VAR recognizer: SRRecognizer; 
sourceID: OSType): OSErr;
FUNCTION SRStartListening(recognizer: SRRecognizer): OSErr;
FUNCTION SRStopListening(recognizer: SRRecognizer): OSErr;
FUNCTION SRGetLanguageModel(recognizer: SRRecognizer; 
VAR languageModel: SRLanguageModel): OSErr;
FUNCTION SRSetLanguageModel(recognizer: SRRecognizer; 
languageModel: SRLanguageModel): OSErr;
FUNCTION SRContinueRecognition(recognizer: SRRecognizer): OSErr;
FUNCTION SRCancelRecognition(recognizer: SRRecognizer): OSErr;
FUNCTION SRIdle: OSErr;

Managing Speech Objects

FUNCTION SRGetProperty(srObject: SRSpeechObject; 
selector: OSType; 
property: UNIV Ptr; 
VAR propertyLen: Size): OSErr;
FUNCTION SRSetProperty(srObject: SRSpeechObject; 
selector: OSType; 
property: UNIV Ptr; 
propertyLen: Size): OSErr;
FUNCTION SRGetReference(srObject: SRSpeechObject; 
VAR newObjectRef: SRSpeechObject): OSErr;
FUNCTION SRReleaseObject(srObject: SRSpeechObject): OSErr;

Traversing Speech Objects

FUNCTION SRCountItems(container: SRSpeechObject; VAR count: LongInt): 
OSErr;
FUNCTION SRGetIndexedItem(container: SRSpeechObject; 
VAR item: SRSpeechObject; 
index: LongInt): OSErr;
FUNCTION SRSetIndexedItem(container: SRSpeechObject; 
item: SRSpeechObject; 
index: LongInt): OSErr;
FUNCTION SRRemoveIndexedItem(container: SRSpeechObject; index: LongInt): OSErr;

Creating Language Objects

FUNCTION SRNewWord(system: SRRecognitionSystem; 
VAR word: SRWord; 
text: UNIV Ptr; 
textLength: Size): OSErr;
FUNCTION SRNewPhrase(system: SRRecognitionSystem; 
VAR phrase: SRPhrase; 
text: UNIV Ptr; 
textLength: Size): OSErr;
FUNCTION SRNewPath(system: SRRecognitionSystem; VAR path: SRPath): 
OSErr;
FUNCTION SRNewLanguageModel(system: SRRecognitionSystem; 
VAR model: SRLanguageModel; 
name: UNIV Ptr; 
nameLength: Size): OSErr;

Manipulating Language Objects

FUNCTION SRAddText(base: SRLanguageObject; 
text: UNIV Ptr; 
textLength: Size; 
refCon: LongInt): OSErr;
FUNCTION SRAddLanguageObject(base: SRLanguageObject; addon: SRLanguageObject): 
OSErr;
FUNCTION SREmptyLanguageObject(languageObject: SRLanguageObject): OSErr;
FUNCTION SRChangeLanguageObject(languageObject: SRLanguageObject; 
text: UNIV Ptr; 
textLength: Size): OSErr;
FUNCTION SRRemoveLanguageObject(base: SRLanguageObject; 
toRemove: SRLanguageObject): OSErr;
FUNCTION SRPutLanguageObjectIntoHandle (
languageObject: SRLanguageObject; 
lobjHandle: Handle): OSErr;
FUNCTION SRPutLanguageObjectIntoDataFile (
languageObject: SRLanguageObject; 
fRefNum: Integer): OSErr;
FUNCTION SRNewLanguageObjectFromHandle (
system: SRRecognitionSystem;
VAR languageObject: SRLanguageObject; 
lobjHandle: Handle): OSErr;
FUNCTION SRNewLanguageObjectFromDataFile (
system: SRRecognitionSystem;
VAR languageObject: SRLanguageObject; 
fRefNum: Integer): OSErr;

Using the System Feedback Window

FUNCTION SRDrawText(recognizer: SRRecognizer; 
dispText: UNIV Ptr; 
dispLength; Size): OSErr;
FUNCTION SRDrawRecognizedText(recognizer: SRRecognizer; 
dispText: UNIV Ptr; 
dispLength; Size): OSErr;
FUNCTION SRSpeakText(recognizer: SRRecognizer; 
speakText: UNIV Ptr; 
speakLength: Size): OSErr;
FUNCTION SRSpeakAndDrawText(recognizer: SRRecognizer;
text: UNIV Ptr; 
textLength: Size): OSErr;
FUNCTION SRProcessBegin(recognizer: SRRecognizer; failed: Boolean): OSErr;
FUNCTION SRProcessEnd(recognizer: SRRecognizer; failed: Boolean): OSErr;
FUNCTION SRStopSpeech(recognizer: SRRecognizer): OSErr;
FUNCTION SRSpeechBusy(recognizer: SRRecognizer): Boolean;

Application-Defined Routines

Callback Routines

PROCEDURE MyCallBackProc(param: SRCallBackStructPtr);

Result Codes

kSRNotAvailable	-5100	Requested service not available or applicable
kSRInternalError	-5101	Internal system or hardware error condition
kSRComponentNotFound	-5102	Required component cannot be located
kSROutOfMemory	-5103	Not enough memory available
kSRNotASpeechObject	-5104	Object is not valid
kSRBadParameter	-5105	Invalid parameter specified
kSRParamOutOfRange	-5106	Parameter is out of valid range
kSRBadSelector	-5107	Unrecognized selector specified
kSRBufferTooSmall	-5108	Buffer is too small
kSRNotARecSystem	-5109	Specified object is not a recognition system
kSRFeedbackNotAvail	-5110	No feedback window associated with recognizer
kSRCantSetProperty	-5111	Cannot set the specified property
kSRCantGetProperty	-5112	Cannot get the specified property
kSRCantSetDuringRecognition	-5113	Cannot set property during recognition
kSRAlreadyListening	-5114	System is already listening
kSRNotListeningState	-5115	System is not listening
kSRModelMismatch	-5116	No acoustical models available to match request
kSRNoClientLanguageModel	-5117	Cannot access specified language model
kSRNoPendingUtterances	-5118	No utterances to search
kSRRecognitionCanceled	-5119	Search was canceled
kSRRecognitionDone	-5120	Search has finished, but nothing was recognized
kSROtherRecAlreadyModal	-5121	Another recognizer is already operating modally
kSRHasNoSubItems	-5122	Specified object has no subitems
kSRSubItemNotFound	-5123	Specified subitem cannot be located
kSRLanguageModelTooBig	-5124	Language model too big to be built
kSRAlreadyReleased	-5125	Specified object has already been released
kSRAlreadyFinished	-5126	Specified language model has already been finished
kSRWordNotFound	-5127	Spelling could not be found
kSRNotFinishedWithRejection	-5128	Language model not finished with rejection
kSRExpansionTooDeep	-5129	Language model is left recursive or is embedded too many levels
kSRTooManyElements	-5130	Too many elements added to phrase, path, or other language object
kSRCantAdd	-5131	Can't add specified type of object to the base language object
kSRSndInSourceDisconnected	-5132	Sound input source is disconnected
kSRCantReadLanguageObject	-5133	Cannot create language object from file or pointer
kSRNotImplementedYet	-5199	Feature is not yet implemented