Mac Developer Library

Developer

Carbon Framework Reference Speech Recognition Manager Reference

Options
Deployment Target:

On This Page
Language:

Speech Recognition Manager Reference

The Speech Recognition Manager provides speech recognition support in applications.

Functions

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

    Declaration

    Swift

    func SRCloseRecognitionSystem(_ system: SRRecognitionSystem) -> OSErr

    Objective-C

    OSErr SRCloseRecognitionSystem ( SRRecognitionSystem system );

    Parameters

    system

    A recognition system.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRCloseRecognitionSystem function closes the recognition system specified by the system parameter. If any speech objects are still attached to that recognition system, they are disposed of and any references you have to those objects are thereby rendered invalid.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Opens a recognition system.

    Declaration

    Swift

    func SROpenRecognitionSystem(_ system: UnsafeMutablePointer<SRRecognitionSystem>, _ systemID: OSType) -> OSErr

    Objective-C

    OSErr SROpenRecognitionSystem ( SRRecognitionSystem *system, OSType systemID );

    Parameters

    system

    On return, a reference to the recognition system having the specified system ID.

    systemID

    A recognition system ID.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    Generally, you should open a single recognition system when your application starts up and close it (by calling the function SRCloseRecognitionSystem) before your application exits.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Cancels the attempt to recognize the current utterance.

    Declaration

    Swift

    func SRCancelRecognition(_ recognizer: SRRecognizer) -> OSErr

    Objective-C

    OSErr SRCancelRecognition ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRCancelRecognition function instructs the recognizer specified by the recognizer parameter to stop recognizing speech. You need to call either SRContinueRecognition or SRCancelRecognition each time your application is notified that the user has started speaking (using Apple events or through an application-defined callback routine).

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Causes a recognizer to continue recognizing speech.

    Declaration

    Swift

    func SRContinueRecognition(_ recognizer: SRRecognizer) -> OSErr

    Objective-C

    OSErr SRContinueRecognition ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    You need to call either SRContinueRecognition or SRCancelRecognition each time your application is notified that the user has started speaking (using Apple events or through an application-defined callback routine).

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Gets a recognizer’s active language model.

    Declaration

    Swift

    func SRGetLanguageModel(_ recognizer: SRRecognizer, _ languageModel: UnsafeMutablePointer<SRLanguageModel>) -> OSErr

    Objective-C

    OSErr SRGetLanguageModel ( SRRecognizer recognizer, SRLanguageModel *languageModel );

    Parameters

    recognizer

    A recognizer.

    languageModel

    On return, a reference to the language model currently active for the specified recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    SRGetLanguageModel increases the reference count of the specified language model. You should call the SRReleaseObject function to release the language model reference returned by SRGetLanguageModel when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRIdle() -> OSErr

    Objective-C

    OSErr SRIdle ( void );

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRIdle function grants processing time to the Speech Recognition Manager, thereby allowing it to process incoming sound and send recognition results.

    Most applications do not need to call the SRIdle function. You need to call it only if your application does a significant amount of processing without periodically calling WaitNextEvent. If you do use the SRIdle function, you should call it often enough that the Speech Recognition Manager can perform its work.

    Note, however, that if you call SRIdle and not WaitNextEvent, you give time to the recognizer but not to the feedback window. You must call WaitNextEvent periodically to have the feedback animations work correctly if your recognizer is using the standard feedback window.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Creates a new recognizer.

    Declaration

    Swift

    func SRNewRecognizer(_ system: SRRecognitionSystem, _ recognizer: UnsafeMutablePointer<SRRecognizer>, _ sourceID: OSType) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    recognizer

    On return, a reference to a new recognizer associated with the specified recognition system and using the specified speech source.

    sourceID

    A speech source ID. See Speech Source Constants.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    SRNewRecognizer may need to load substantial amounts of data from disk into memory. As a result, you might want to change the cursor to the watch cursor before you call SRNewRecognizer.

    You should call the SRReleaseObject function to release the object reference returned by SRNewRecognizer when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Sets a recognizer’s active language model.

    Declaration

    Swift

    func SRSetLanguageModel(_ recognizer: SRRecognizer, _ languageModel: SRLanguageModel) -> OSErr

    Objective-C

    OSErr SRSetLanguageModel ( SRRecognizer recognizer, SRLanguageModel languageModel );

    Parameters

    recognizer

    A recognizer.

    languageModel

    The language model you wish to become the active model for the specified recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    If no other references exist to the language model currently in use by the specified recognizer, calling SRSetLanguageModel with a different language model causes the current one to be released.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Starts a recognizer listening and reporting results to your application.

    Declaration

    Swift

    func SRStartListening(_ recognizer: SRRecognizer) -> OSErr

    Objective-C

    OSErr SRStartListening ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRStartListening function instructs the recognizer specified by the recognizer parameter to begin processing sound from its speech source and reporting its results to your application (either using Apple events or through a speech recognition callback routine).

    You must already have built a language model and attached it to the recognizer (by calling the SRSetLanguageModel function) before you call SRStartListening.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Stops a recognizer listening and reporting results to your application.

    Declaration

    Swift

    func SRStopListening(_ recognizer: SRRecognizer) -> OSErr

    Objective-C

    OSErr SRStopListening ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRStopListening function instructs the recognizer specified by the recognizer parameter to stop processing sound from its speech source and reporting its results to your application.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRGetProperty(_ srObject: SRSpeechObject, _ selector: OSType, _ property: UnsafeMutablePointer<Void>, _ propertyLen: UnsafeMutablePointer<Size>) -> OSErr

    Objective-C

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

    Parameters

    srObject

    A speech object.

    selector

    A property selector. See Recognizer Properties, Recognizer Listen Key Properties, Language Object Properties, and Recognition System Properties for lists of the available property selectors.

    property

    A pointer to a buffer into which the value of the specified property is to be copied.

    propertyLen

    On entry, a pointer to the length, in bytes, of the specified buffer. If the value is of a fixed size, then propertyLen should point to a variable of type Size that specifies that size. If the size of the value can vary (for example, if the value is a string), then propertyLen should point to a variable of type Size that specifies the number of bytes in the buffer pointed to by the property parameter.

    On return, if the buffer is large enough to hold the returned property value and no error occurs, SRGetProperty sets propertyLen to the total number of bytes in the value of the specified property. If the buffer is not large enough to hold the returned property value, SRGetProperty sets propertyLen to the number of bytes required to store the requested property and returns the kSRBufferTooSmall error code.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    Not all selectors are valid for all types of speech objects. If the selector you specify does not specify a property of the specified speech object, SRGetProperty returns the result code kSRCantGetProperty.

    If SRGetProperty returns an object reference, you must make sure to release that object reference (by calling SRReleaseObject) when you are finished using it. Most selectors do not cause SRGetProperty to return object references. For example, passing the selector kSRSpelling causes SRGetProperty to return a buffer of text, not an object reference.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Obtains an extra reference to a speech object.

    Declaration

    Swift

    func SRGetReference(_ srObject: SRSpeechObject, _ newObjectRef: UnsafeMutablePointer<SRSpeechObject>) -> OSErr

    Objective-C

    OSErr SRGetReference ( SRSpeechObject srObject, SRSpeechObject *newObjectRef );

    Parameters

    srObject

    A speech object.

    newObjectRef

    On return, a new reference to the specified speech object.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The original object reference (contained in srObject) and the new reference (returned in newObjectRef) may have different values. Accordingly, you cannot simply compare two object references to determine whether they are references to the same speech object.

    SRGetReference increases the reference count of the specified speech object. You should call the SRReleaseObject function to release the object reference returned by SRGetReference when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Releases a speech object.

    Declaration

    Swift

    func SRReleaseObject(_ srObject: SRSpeechObject) -> OSErr

    Objective-C

    OSErr SRReleaseObject ( SRSpeechObject srObject );

    Parameters

    srObject

    A speech object.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    If there are no other remaining references to the object, SRReleaseObject disposes of the memory occupied by the object.

    Your application should balance every function call that returns an object reference with a call to SRReleaseObject. This means that every call to a function whose name begins with SRNew or SRGet that successfully returns an object reference must be balanced with a call to SRReleaseObject.

    In addition, you should call SRReleaseObject to release references to SRSearchResult objects that are passed to your application (via an Apple event handler or a callback routine).

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Sets the value of a property of a speech object.

    Declaration

    Swift

    func SRSetProperty(_ srObject: SRSpeechObject, _ selector: OSType, _ property: UnsafePointer<Void>, _ propertyLen: Size) -> OSErr

    Objective-C

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

    Parameters

    srObject

    A speech object.

    selector

    A property selector. See Recognizer Properties, Recognizer Listen Key Properties, Language Object Properties, and Recognition System Properties for lists of the available property selectors.

    property

    A pointer to a buffer containing the value to which the specified property is to be set.

    propertyLen

    The length, in bytes, of the specified buffer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRSetProperty function sets the value of the property of the speech object specified by the srObject parameter to the value specified through the property parameter. The selector parameter specifies which property is to be set and the propertyLen parameter specifies it size, in bytes.

    Not all properties can be set. If you attempt to set a property that cannot be set, SRSetProperty returns the result code kSRCantSetProperty or kSRBadSelector as its function result.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Determines the number of subitems in a container object.

    Declaration

    Swift

    func SRCountItems(_ container: SRSpeechObject, _ count: UnsafeMutablePointer<Int>) -> OSErr

    Objective-C

    OSErr SRCountItems ( SRSpeechObject container, long *count );

    Parameters

    container

    A speech object.

    count

    On return, a pointer to a long containing the number of subitems in the specified speech object.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    This function is useful only for speech objects that have distinguishable subitems, such as phrases (which contain words), paths (which contain words, phrases, and language models), and language models (which contain words, phrases, paths, and possibly other language models).

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Gets a subitem in a container object.

    Declaration

    Swift

    func SRGetIndexedItem(_ container: SRSpeechObject, _ item: UnsafeMutablePointer<SRSpeechObject>, _ index: Int) -> OSErr

    Objective-C

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

    Parameters

    container

    A speech object.

    item

    On return, a reference to the subitem in the specified speech object that has the specified index.

    index

    An integer ranging from 0 to one less than the number of subitems in the specified speech object. (You can call the SRCountItems function to determine the number of subitems contained in a speech object.) If the index you specify is not in this range, SRGetIndexedItem returns the result code kSRParamOutOfRange.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    This function is useful for iterating through all subitems in a container object.

    SRGetIndexedItem increases the reference count of the specified speech object. You should call the SRReleaseObject function to release the object reference returned by SRGetIndexedItem when you are done using it. For example, you can get a reference to the third word in a phrase by executing this code:

    myErr = SRGetIndexedItem(myPhrase, &myWord, 2)

    Then, when you are finished using the word, you should execute this code:

    myErr = SRReleaseObject(myWord);

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Removes a subitem from a container object.

    Declaration

    Swift

    func SRRemoveIndexedItem(_ container: SRSpeechObject, _ index: Int) -> OSErr

    Objective-C

    OSErr SRRemoveIndexedItem ( SRSpeechObject container, long index );

    Parameters

    container

    A speech object.

    index

    An integer ranging from 0 to one less than the number of subitems in the specified speech object. (You can call the SRCountItems function to determine the number of subitems contained in a speech object.) If the index you specify is not in this range, SRRemoveIndexedItem returns the result code kSRParamOutOfRange.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRRemoveIndexedItem function removes from the speech object specified by the container parameter the subitem located at the position specified by the index parameter. If SRRemoveIndexedItem completes successfully, the number of subitems in the container object is reduced by 1, and the index of each subitem that follows the removed item is reduced by 1.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRSetIndexedItem(_ container: SRSpeechObject, _ item: SRSpeechObject, _ index: Int) -> OSErr

    Objective-C

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

    Parameters

    container

    A speech object.

    item

    A speech object.

    index

    An integer ranging from 0 to one less than the number of subitems in the specified speech object.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRSetIndexedItem function replaces the subitem having the index specified by the index parameter in the container object specified by the container parameter with the speech object specified by the item parameter. A reference to the replacement item is maintained separately by the container; as a result, you can release any reference to that item if you no longer need it. The reference to the replaced item is removed from the container; if that reference was the last remaining reference to the object, the object is released.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Creates a new language model.

    Declaration

    Swift

    func SRNewLanguageModel(_ system: SRRecognitionSystem, _ model: UnsafeMutablePointer<SRLanguageModel>, _ name: UnsafePointer<Void>, _ nameLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    model

    On return, a reference to a new empty language model associated with the specified recognition system.

    name

    A pointer to a buffer that contains the name of the language model. The name of the language model should be unique among all the language models your application creates, and it should be comprehensible to users. (For example, a language model that defined a list of names might be called “«Names»”).

    The convention that language model names begin with the character “«” and end with the character “»” is adopted to support future utilities that display the names of language models to the user (perhaps as part of showing the user what he or she can say).

    nameLength

    The size, in bytes, of the specified name.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    You can add language objects (that is, words, phrases, paths, and other language models) to a language model by calling the SRAddText and SRAddLanguageObject functions.

    SRNewLanguageModel sets the reference count of the specified language model to 1. You should call the SRReleaseObject function to release the language model reference returned by SRNewLanguageModel when you are done using it.

    You can get or set the name of an existing language model by calling the SRGetProperty or SRSetProperty functions with the kSRSpelling property selector.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Creates a new path.

    Declaration

    Swift

    func SRNewPath(_ system: SRRecognitionSystem, _ path: UnsafeMutablePointer<SRPath>) -> OSErr

    Objective-C

    OSErr SRNewPath ( SRRecognitionSystem system, SRPath *path );

    Parameters

    system

    A recognition system.

    path

    On return, a reference to a new empty path associated with the specified recognition system.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    You can then add objects to a path by calling the SRAddText or SRAddLanguageObject functions.

    You should call the SRReleaseObject function to release the path reference returned by SRNewPath when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Creates a new phrase.

    Declaration

    Swift

    func SRNewPhrase(_ system: SRRecognitionSystem, _ phrase: UnsafeMutablePointer<SRPhrase>, _ text: UnsafePointer<Void>, _ textLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    phrase

    On return, a reference to a new phrase associated with the specified recognition system.

    text

    A pointer to a buffer that contains the words that comprise the phrase.

    textLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The phrase’s contents (that is, the words that comprise the phrase) is specified by the text and textLength parameters. You can, if you wish, create a new empty phrase and then add words to it by calling the SRAddText or SRAddLanguageObject functions.

    You should call the SRReleaseObject function to release the phrase reference returned by SRNewPhrase when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Creates a new word.

    Declaration

    Swift

    func SRNewWord(_ system: SRRecognitionSystem, _ word: UnsafeMutablePointer<SRWord>, _ text: UnsafePointer<Void>, _ textLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    word

    On return, a reference to a new word associated with the specified recognition system.

    text

    A pointer to a buffer that contains the characters that comprise the word.

    textLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    You should call the SRReleaseObject function to release the word reference returned by SRNewWord when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Adds a language object to some other language object.

    Declaration

    Swift

    func SRAddLanguageObject(_ base: SRLanguageObject, _ addon: SRLanguageObject) -> OSErr

    Objective-C

    OSErr SRAddLanguageObject ( SRLanguageObject base, SRLanguageObject addon );

    Parameters

    base

    The language object to which to add the language object specified by the addon parameter.

    addon

    The language object to add on to the language object specified in the base parameter. For example, if addon specifies a word and base specifies a phrase, then SRAddLanguageObject appends that word to the end of that phrase.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRAddLanguageObject function is useful for adding language objects to phrases, paths, and language models. For a phrase or a path, SRAddLanguageObject appends the specified object to the end of the phrase or path. For a language model, SRAddLanguageObject adds the specified object to the list of alternative recognizable utterances.

    The language object to which you add an object acquires a new reference to that object. Accordingly, any changes you subsequently make to the added object are reflected in any object to which you added it. The base object releases its reference to the added object when the base object is disposed of.

    SRAddLanguageObject does not alter the value of the reference constant property of the language object specified by the base parameter.

    See SRAddText for a useful shortcut function.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Adds text to the contents of a language object.

    Declaration

    Swift

    func SRAddText(_ base: SRLanguageObject, _ text: UnsafePointer<Void>, _ textLength: Int32, _ refCon: SRefCon) -> OSErr

    Objective-C

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

    Parameters

    base

    A language object to which to add the text.

    text

    A pointer to a buffer that contains the words or phrase to add to the contents of the specified language object.

    textLength

    The size, in bytes, of the specified text.

    refCon

    An application-defined reference constant. The value of the reference constant property of the new word or phrase representing the specified text is set to this value.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRAddText function is useful for phrases, paths, and language models. If the base parameter specifies a path or language model, SRAddText is equivalent to calling SRNewPhrase, SRAddLanguageObject, and SRReleaseObject for the phrase specified by the text parameter and calling SRSetProperty to reset the value of the reference constant property of the new phrase.

    If the base parameter specifies a phrase, SRAddText is equivalent to calling SRNewPhrase, SRAddLanguageObject, and SRReleaseObject for each distinguishable word in the text parameter and calling SRSetProperty to set the value of the reference constant property of the new words.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Changes the contents of a language object.

    Declaration

    Swift

    func SRChangeLanguageObject(_ languageObject: SRLanguageObject, _ text: UnsafePointer<Void>, _ textLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    languageObject

    A language object.

    text

    A pointer to a buffer that contains the words or phrase to which the contents of the specified language object are to be changed.

    textLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    SRChangeLanguageObject is a convenient shortcut for calling SREmptyLanguageObject and then SRAddText.

    SRChangeLanguageObject does not alter the value of the reference constant property of the language object specified by the languageObject parameter.

    If there are no other references to the language object specified by the languageObject parameter, calling SRChangeLanguageObject causes that object to be released.

    If you want to swap rapidly among several language models, you should use the SRSetLanguageObject function instead of SRChangeLanguageObject. Or, you could use the kSREnabled property to rapidly enable and disable parts of the current language model to reflect the current context.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Empties the contents of a language object.

    Declaration

    Swift

    func SREmptyLanguageObject(_ languageObject: SRLanguageObject) -> OSErr

    Objective-C

    OSErr SREmptyLanguageObject ( SRLanguageObject languageObject );

    Parameters

    languageObject

    A language object.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SREmptyLanguageObject function empties the contents of the language object specified by the languageObject parameter. (For example, if languageObject specifies a phrase containing two words, calling SREmptyLanguageObject would result in a phrase that contains no words.) Any properties of that object that are not related to its contents are unchanged. In particular, SREmptyLanguageObject does not alter the value of the reference constant property of that language object.

    If there are no other references to the words, phrases, and paths that were contained in the language object, calling SREmptyLanguageObject causes them to be disposed of.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRNewLanguageObjectFromHandle(_ system: SRRecognitionSystem, _ languageObject: UnsafeMutablePointer<SRLanguageObject>, _ lObjHandle: Handle) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    languageObject

    On return, a reference to a new language object created and initialized using the private data to which the lobjHandle parameter is a handle.

    lObjHandle

    A handle to a language object. The data specified by lobjHandle should have been created by a previous call to the SRPutLanguageObjectIntoHandle function; if that data is not appropriately formatted, SRNewLanguageObjectFromHandle returns the result code kSRCantReadLanguageObject as its function result.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    You can use this function to load language objects from resources (for example, by using the Resource Manager function GetResource).

    You should call the SRReleaseObject function to release the language object reference returned by SRNewLanguageObjectFromHandle when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Reads a language object from a data file.

    Declaration

    Swift

    func SRNewLanguageObjectFromDataFile(_ system: SRRecognitionSystem, _ languageObject: UnsafeMutablePointer<SRLanguageObject>, _ fRefNum: Int16) -> OSErr

    Objective-C

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

    Parameters

    system

    A recognition system.

    languageObject

    On return, a reference to a new language object whose description is stored in the open data file that has the file reference number specified by the fRefNum parameter.

    fRefNum

    A file reference number of an open data file.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    SRNewLanguageObjectFromDataFile reads data beginning at the current file mark.

    If the language object is successfully created and initialized, the file mark is left at the byte immediately following the language object description. Otherwise, if the language object data is not appropriately formatted, SRNewLanguageObjectFromDataFile returns the result code kSRCantReadLanguageObject as its function result and the file mark is not moved.

    You should call the SRReleaseObject function to release the language object reference returned by SRNewLanguageObjectFromDataFile when you are done using it.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRPutLanguageObjectIntoHandle(_ languageObject: SRLanguageObject, _ lobjHandle: Handle) -> OSErr

    Objective-C

    OSErr SRPutLanguageObjectIntoHandle ( SRLanguageObject languageObject, Handle lobjHandle );

    Parameters

    languageObject

    A language object.

    lobjHandle

    A handle to a block of memory into which the data describing the specified language object is to be put. On entry, this handle can have a length of 0.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRPutLanguageObjectIntoHandle function puts a description of the language object specified by the languageObject parameter into the block of memory specified by the lobjHandle parameter. This replaces the data in the handle and resizes the handle if necessary.

    You can use Resource Manager functions (such as AddResource) to store language objects into resources.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRPutLanguageObjectIntoDataFile(_ languageObject: SRLanguageObject, _ fRefNum: Int16) -> OSErr

    Objective-C

    OSErr SRPutLanguageObjectIntoDataFile ( SRLanguageObject languageObject, short fRefNum );

    Parameters

    languageObject

    A language object.

    fRefNum

    A file reference number of an open data file into which the data describing the specified language object is to be put.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRPutLanguageObjectIntoDataFile function puts a description of the language object specified by the languageObject parameter into the data file specified by the fRefNum parameter. Data are written starting at the current file mark, and the file mark is moved to the end of the written data.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRRemoveLanguageObject(_ base: SRLanguageObject, _ toRemove: SRLanguageObject) -> OSErr

    Objective-C

    OSErr SRRemoveLanguageObject ( SRLanguageObject base, SRLanguageObject toRemove );

    Parameters

    base

    The language object containing the language object to remove.

    toRemove

    The language object to remove.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The object specified by the base parameter should be a container one of whose subitems is the object specified by the toRemove parameter.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Draws recognized text in the feedback window.

    Declaration

    Swift

    func SRDrawRecognizedText(_ recognizer: SRRecognizer, _ dispText: UnsafePointer<Void>, _ dispLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    recognizer

    A recognizer.

    dispText

    A pointer to a buffer that contains the text to be drawn.

    dispLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRDrawRecognizedText function draws the text specified by the dispText and dispLength parameters in the transcript portion of the feedback window associated with the recognizer specified by the recognizer parameter. The text is drawn in the style characteristic of all recognized text. You might want to use this function to display a recognized phrase using a different spelling than the one used in the language model.

    If the value of the kSRWantsResultTextDrawn property of the specified recognizer is TRUE (which is the default value), a transcript of the text of a recognition result is automatically sent directly to the feedback window. As a result, you should call SRDrawRecognizedText only when the value of the recognizer’s kSRWantsResultTextDrawn property is FALSE.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Draws output text in the feedback window.

    Declaration

    Swift

    func SRDrawText(_ recognizer: SRRecognizer, _ dispText: UnsafePointer<Void>, _ dispLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    recognizer

    A recognizer.

    dispText

    A pointer to a buffer that contains the text to be drawn.

    dispLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRDrawText function draws the text specified by the dispText and dispLength parameters in the transcript portion of the feedback window associated with the recognizer specified by the recognizer parameter. The text is drawn in the style characteristic of all output text.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Indicates that a recognition result is being processed.

    Declaration

    Swift

    func SRProcessBegin(_ recognizer: SRRecognizer, _ failed: Boolean) -> OSErr

    Objective-C

    OSErr SRProcessBegin ( SRRecognizer recognizer, Boolean failed );

    Parameters

    recognizer

    A recognizer.

    failed

    A Boolean value that determines how the feedback gestures are to be altered and whether the response sound is to be played (FALSE) or not (TRUE).

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRProcessBegin function causes the Speech Recognition Manager to provide the relevant feedback (in the feedback window associated with the recognizer specified by the recognizer parameter) indicating that the application is in the process of responding to a spoken command. Currently, the gestures of the feedback character are changed to indicate that processing is occurring.

    If you set the value of the recognizer’s kSRWantsAutoFBGestures property to FALSE, you should call SRProcessBegin at the beginning of your response to a recognition result and SRProcessEnd at the end of your response. During the interval separating the two calls, the feedback character displays an appropriate set of gestures showing the user that the task is being processed. If you pass the value TRUE in the failed parameter (indicating that the recognition result cannot successfully be processed), the feedback character displays frowns, shrugs, or other appropriate gestures. In addition, when failed is TRUE, you do not need to call SRProcessEnd to end the processing. If you pass the value FALSE in the failed parameter but determine subsequently that the recognition result cannot successfully be processed, you should call SRProcessEnd with the failed parameter set to TRUE.

    If the value of the kSRWantsAutoFBGestures property of the specified recognizer is TRUE, the Speech Recognition Manager calls SRProcessBegin internally before notifying your application of a recognition result, and it calls SRProcessEnd internally after your application is notified. As a result, you should call SRProcessBegin or SRProcessEnd only when the value of the recognizer’s kSRWantsAutoFBGestures property is FALSE.

    Because the default value of the kSRWantsAutoFBGestures property is TRUE, most applications do not need to call SRProcessBegin. Calling SRProcessBegin is useful, however, when you know the resulting action might take a significant amount of time.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Indicates that a recognition result is done being processed.

    Declaration

    Swift

    func SRProcessEnd(_ recognizer: SRRecognizer, _ failed: Boolean) -> OSErr

    Objective-C

    OSErr SRProcessEnd ( SRRecognizer recognizer, Boolean failed );

    Parameters

    recognizer

    A recognizer.

    failed

    A Boolean value that determines how the feedback gestures are to be altered (FALSE) or not (TRUE).

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRProcessEnd function causes the Speech Recognition Manager to provide the relevant feedback (in the feedback window associated with the recognizer specified by the recognizer parameter) indicating that a recognition result is done being processed. Currently, the gestures of the feedback character are changed and a response sound is played.

    If the value of the kSRWantsAutoFBGestures property of the specified recognizer is TRUE, the Speech Recognition Manager calls SRProcessBegin internally before notifying your application of a recognition result, and it calls SRProcessEnd internally after your application is notified. As a result, you should call SRProcessBegin or SRProcessEnd only when the value of the recognizer’s kSRWantsAutoFBGestures property is FALSE.

    Because the default value of the kSRWantsAutoFBGestures property is TRUE, most applications do not need to call SRProcessBegin. Calling SRProcessBegin is useful, however, when you know the resulting action might take a significant amount of time.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRSpeakAndDrawText(_ recognizer: SRRecognizer, _ text: UnsafePointer<Void>, _ textLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    recognizer

    A recognizer.

    text

    A pointer to a buffer that contains the text to be drawn and spoken.

    textLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRSpeakText(_ recognizer: SRRecognizer, _ speakText: UnsafePointer<Void>, _ speakLength: Int32) -> OSErr

    Objective-C

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

    Parameters

    recognizer

    A recognizer.

    speakText

    A pointer to a buffer that contains the text to be spoken. The text pointed to by the speakText parameter can contain embedded speech commands to enhance the prosody of the spoken string.

    speakLength

    The size, in bytes, of the specified text.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    While speaking, the feedback character lip-syncs the spoken string using the Speech Synthesis Manager’s phoneme callback routines. SRSpeakText uses the default voice and rate selected in the Speech control panel. (The Speech Synthesis Manager was formerly called the Speech Manager. Its name has been changed to distinguish it from the Speech Recognition Manager and to describe its operation more clearly.)

    You can use the SRSpeechBusy function to determine whether the feedback character is already speaking. If it is, you can call the SRStopSpeech function to stop that speaking immediately.

    The SRSpeakText function speaks the specified text but does not display it. Use the SRSpeakAndDrawText function if you want to speak and display the text.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func SRSpeechBusy(_ recognizer: SRRecognizer) -> Boolean

    Objective-C

    Boolean SRSpeechBusy ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    On return, true if the feedback character in the feedback window associated with the recognizer specified by the recognizer parameter is currently speaking; otherwise false.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Terminates speech by the feedback character in a feedback window.

    Declaration

    Swift

    func SRStopSpeech(_ recognizer: SRRecognizer) -> OSErr

    Objective-C

    OSErr SRStopSpeech ( SRRecognizer recognizer );

    Parameters

    recognizer

    A recognizer.

    Return Value

    A result code. See Speech Recognition Manager Result Codes.

    Discussion

    The SRStopSpeech function immediately terminates any speaking by the feedback character in the feedback window associated with the recognizer specified by the recognizer parameter.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func NewSRCallBackUPP(_ userRoutine: SRCallBackProcPtr) -> SRCallBackUPP

    Objective-C

    SRCallBackUPP NewSRCallBackUPP ( SRCallBackProcPtr userRoutine );

    Parameters

    userRoutine

    A pointer to your speech recognition callback function.

    Return Value

    A UPP to the speech recognition callback function. See the description of the SRCallBackUPP data type.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func DisposeSRCallBackUPP(_ userUPP: SRCallBackUPP)

    Objective-C

    void DisposeSRCallBackUPP ( SRCallBackUPP userUPP );

    Parameters

    userUPP

    The UPP to dispose of.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Invokes your speech recognition callback function.

    Declaration

    Swift

    func InvokeSRCallBackUPP(_ param: UnsafeMutablePointer<SRCallBackStruct>, _ userUPP: SRCallBackUPP)

    Objective-C

    void InvokeSRCallBackUPP ( SRCallBackStruct *param, SRCallBackUPP userUPP );

    Discussion

    You should not have to call the InvokeSRCallbackUPP function, as the system calls your speech recognition callback function for you.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

Callbacks

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

    Declaration

    Objective-C

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

    Parameters

    param

    A pointer to a speech recognition callback structure. See SRCallBackStruct for a description of this structure.

    Discussion

    You can receive notification of recognizer events either by installing an Apple event handler or by installing a speech recognition callback function. In general, you should use an Apple event handler to process recognition notifications. You should use callbacks only for executable code that cannot easily receive Apple events.

    You can determine what event caused your function to be called by inspecting the what field of the speech recognition callback structure specified by the param parameter.

    Because the Speech Recognition Manager is not fully reentrant, you should not call any of its functions other than SRContinueRecognition or SRCancelRecognition from within your speech recognition callback. Accordingly, your callback should simply queue the notification for later processing by your software (for instance, when it receives background processing time).

    If the event is of type kSRNotifyRecognitionBeginning (which occurs only if you request speech-begun notifications), you must call either SRContinueRecognition or SRCancelRecognition before speech recognition can continue. A recognizer that has issued a recognition notification suspends activity until you call one of these two functions.

    In general, when your speech recognition callback receives the kSRNotifyRecognitionBeginning notification, it should queue an indication for your main code both to adjust the current language model (if necessary) and to call the SRContinueRecognition function. When your callback receives the kSRNotifyRecognitionDone notification, it should queue an indication for your main code to handle the recognition result passed in the message field of the speech recognition callback structure specified by the param parameter. You should make sure, however, that the message field contains a valid reference to a recognition result by inspecting the status field of that structure; if status contains any value other than noErr, the contents of the message field are undefined.

    When your callback is executed, your application is not the current process. As a result, some restrictions apply; for example, the current resource chain might not be that of your application.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

Data Types

  • Defines a speech recognition callback parameter structure.

    Declaration

    Swift

    struct SRCallBackParam { var callBack: SRCallBackUPP var refCon: SRefCon }

    Objective-C

    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.

    Discussion

    If you want to receive recognition notifications using a speech recognition callback routine instead of an Apple event handler, you must change the value of the kSRCallBackParam property of the current recognizer. The value of the kSRCallBackParam property is the address of a callback function parameter structure, defined by the SRCallBackParam data type.

    Availability

    Available in OS X v10.0 and later.

  • Defines a structure sent to your speech recognition callback function.

    Declaration

    Swift

    struct SRCallBackStruct { var what: UInt32 var message: Int var instance: SRRecognizer var status: OSErr var flags: Int16 var refCon: SRefCon }

    Objective-C

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

    Discussion

    When you receive a notification of recognition results through an application-defined callback function (instead of using an Apple event handler), the Speech Recognition Manager sends your callback function a pointer to a speech recognition callback structure, defined by the SRCallBackStruct data type.

    For information on writing a speech recognition callback function, see SRCallBackProcPtr.

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias SRCallBackUPP = SRCallBackProcPtr

    Objective-C

    typedef SRCallBackProcPtr SRCallBackUPP;

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a language model.

    Declaration

    Swift

    typealias SRLanguageModel = SRLanguageObject

    Objective-C

    typedef SRLanguageObject SRLanguageModel;

    Discussion

    A language model is a list of zero or more words, phrases, or paths.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a language object.

    Declaration

    Swift

    typealias SRLanguageObject = SRSpeechObject

    Objective-C

    typedef SRSpeechObject SRLanguageObject;

    Discussion

    A language model is built using four kinds of objects, collectively called language objects: words, phrases, paths, and language models.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a language object identifying a path.

    Declaration

    Swift

    typealias SRPath = SRLanguageObject

    Objective-C

    typedef SRLanguageObject SRPath;

    Discussion

    A path is a sequence of zero or more words, phrases, or language models.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a language object identifying a phrase.

    Declaration

    Swift

    typealias SRPhrase = SRLanguageObject

    Objective-C

    typedef SRLanguageObject SRPhrase;

    Discussion

    A phrase is a sequence of zero or more words.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias SRRecognitionResult = SRSpeechSource

    Objective-C

    typedef SRSpeechSource SRRecognitionResult;

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a speech object identifying a recognition system.

    Declaration

    Swift

    typealias SRRecognitionSystem = SRSpeechObject

    Objective-C

    typedef SRSpeechObject SRRecognitionSystem;

    Discussion

    A speech object is an instance of a speech class, which defines a set of properties for objects in the class. The behavior of a speech object is determined by the set of properties associated with the object’s class. Recognition systems have the properties associated with the SRRecognitionSystem class of speech objects.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a speech object identifying a speech recognizer.

    Declaration

    Swift

    typealias SRRecognizer = SRSpeechObject

    Objective-C

    typedef SRSpeechObject SRRecognizer;

    Discussion

    A speech object is an instance of a speech class, which defines a set of properties for objects in the class. The behavior of a speech object is determined by the set of properties associated with the object’s class. Speech recognizers have the properties associated with the SRRecognizer class of speech objects.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Declaration

    Swift

    typealias SRRejectionLevel = UInt16

    Objective-C

    typedef SRRejectionLevel;

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Defines a reference to a speech object.

    Declaration

    Swift

    typealias SRSpeechObject = COpaquePointer

    Objective-C

    typedef struct OpaqueSRSpeechObject * SRSpeechObject;

    Discussion

    The Speech Recognition Manager is object oriented in the sense that many of its capabilities are accessed by creating and manipulating speech objects. A speech object is an instance of a speech class, which defines a set of properties for objects in the class. The behavior of a speech object is determined by the set of properties associated with the object’s class.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a speech object identifying a speech source.

    Declaration

    Swift

    typealias SRSpeechSource = SRSpeechObject

    Objective-C

    typedef SRSpeechObject SRSpeechSource;

    Discussion

    A speech object is an instance of a speech class, which defines a set of properties for objects in the class. The behavior of a speech object is determined by the set of properties associated with the object’s class. Speech sources have the properties associated with the SRSpeechSource class of speech objects.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Declaration

    Swift

    typealias SRSpeedSetting = UInt16

    Objective-C

    typedef SRSpeedSetting;

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

  • Represents a language object identifying a word.

    Declaration

    Swift

    typealias SRWord = SRLanguageObject

    Objective-C

    typedef SRLanguageObject SRWord;

    Discussion

    A word represents a single speakable word.

    Import Statement

    import Carbon

    Availability

    Available in OS X v10.0 and later.

Constants

  • Identify the feedback and listening modes of the recognition system.

    Declaration

    Swift

    var kSRNoFeedbackNoListenModes: Int { get } var kSRHasFeedbackHasListenModes: Int { get } var kSRNoFeedbackHasListenModes: Int { get }

    Objective-C

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

    Constants

    • kSRNoFeedbackNoListenModes

      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.

    • kSRHasFeedbackHasListenModes

      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.

    • kSRNoFeedbackHasListenModes

      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.

    Import Statement

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

    Declaration

    Swift

    var kAESpeechDone: Int { get } var kAESpeechDetected: Int { get } var kAESpeechSuite: Int { get } var keySRRecognizer: Int { get } var keySRSpeechResult: Int { get } var keySRSpeechStatus: Int { get } var typeSRRecognizer: Int { get } var typeSRSpeechResult: Int { get }

    Objective-C

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

    Constants

    • kAESpeechDone

      kAESpeechDone

      The message ID for a speech-done event.

      Available in OS X v10.0 and later.

    • kAESpeechDetected

      kAESpeechDetected

      The message ID for a speech-detected event.

      Available in OS X v10.0 and later.

    • kAESpeechSuite

      kAESpeechSuite

      The Apple event suite for speech recognition events.

      Available in OS X v10.0 and later.

    • keySRRecognizer

      keySRRecognizer

      The ID for the recognizer parameter.

      Available in OS X v10.0 and later.

    • keySRSpeechResult

      keySRSpeechResult

      The ID for the recognition result parameter.

      Available in OS X v10.0 and later.

    • keySRSpeechStatus

      keySRSpeechStatus

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

      Available in OS X v10.0 and later.

    • typeSRRecognizer

      typeSRRecognizer

      The type for the recognizer parameter.

      Available in OS X v10.0 and later.

    • typeSRSpeechResult

      typeSRSpeechResult

      The type for the recognition result parameter.

      Available in OS X v10.0 and later.

    Import Statement

  • Represents a default rejection level.

    Declaration

    Swift

    var kSRDefaultRejectionLevel: Int { get }

    Objective-C

    enum { kSRDefaultRejectionLevel = 50 };

    Constants

    • kSRDefaultRejectionLevel

      kSRDefaultRejectionLevel

      The default rejection level.

      Available in OS X v10.0 and later.

    Import Statement

  • Define property selectors for language objects.

    Declaration

    Swift

    var kSRSpelling: Int { get } var kSRLMObjType: Int { get } var kSRRefCon: Int { get } var kSROptional: Int { get } var kSREnabled: Int { get } var kSRRepeatable: Int { get } var kSRRejectable: Int { get } var kSRRejectionLevel: Int { get }

    Objective-C

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

    Constants

    • kSRSpelling

      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.

    • kSRLMObjType

      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.

    • kSRRefCon

      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.

    • kSROptional

      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.

    • kSREnabled

      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.

    • kSRRepeatable

      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.

    • kSRRejectable

      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.

    • kSRRejectionLevel

      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.

    Discussion

    Every language object (that is, any instance of a subclass of the SRLanguageObject class) has a set of properties that you can inspect and change by calling the SRGetProperty and SRSetProperty functions. You specify a property by passing a property selector to those functions.

    Import Statement

  • Identify the four subclasses of the SRLanguageObject class.

    Declaration

    Swift

    var kSRLanguageModelType: Int { get } var kSRPathType: Int { get } var kSRPhraseType: Int { get } var kSRWordType: Int { get }

    Objective-C

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

    Constants

    • kSRLanguageModelType

      kSRLanguageModelType

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

      Available in OS X v10.0 and later.

    • kSRPathType

      kSRPathType

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

      Available in OS X v10.0 and later.

    • kSRPhraseType

      kSRPhraseType

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

      Available in OS X v10.0 and later.

    • kSRWordType

      kSRWordType

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

      Available in OS X v10.0 and later.

    Discussion

    You can use these constants, for instance, to help interpret the value of a language object’s kSRLMObjType property.

    Import Statement

  • Identify listen key modes.

    Declaration

    Swift

    var kSRUseToggleListen: Int { get } var kSRUsePushToTalk: Int { get }

    Objective-C

    enum { kSRUseToggleListen = 0, kSRUsePushToTalk = 1 };

    Constants

    • kSRUseToggleListen

      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.

    • kSRUsePushToTalk

      kSRUsePushToTalk

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

      Available in OS X v10.0 and later.

    Discussion

    You can get (but not set) a recognizer’s listen key mode by accessing its property of type kSRListenKeyMode. That property’s value is a 2-byte unsigned integer that determines whether the listen key operates in push-to-talk or toggle-listening mode.

    Import Statement

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

    Declaration

    Swift

    var kSRNotifyRecognitionBeginning: Int { get } var kSRNotifyRecognitionDone: Int { get }

    Objective-C

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

    Constants

    • kSRNotifyRecognitionBeginning

      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.

    • kSRNotifyRecognitionDone

      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.

    Discussion

    You can indicate which recognizer events you want your application be to notified of by setting the recognizer’s notification property, which is a property of type kSRNotificationParam. That property’s value is a 4-byte unsigned integer. The Speech Recognition Manager defines these masks for bits in that value.

    Import Statement

  • Identify property selectors for recognition results.

    Declaration

    Swift

    var kSRTEXTFormat: Int { get } var kSRPhraseFormat: Int { get } var kSRPathFormat: Int { get } var kSRLanguageModelFormat: Int { get }

    Objective-C

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

    Constants

    • kSRTEXTFormat

      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.

    • kSRPhraseFormat

      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.

    • kSRPathFormat

      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.

    • kSRLanguageModelFormat

      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.

    Discussion

    Every recognition result object has a set of properties that you can inspect by calling the SRGetProperty function. You specify a property by passing a property selector to those functions.

    SRGetProperty returns an object reference as the value of a recognition result’s kSRPhraseFormat, kSRPathFormat, or kSRLanguageModelFormat property. You must make sure to release that object reference (by calling SRReleaseObject) when you are finished using it.

    Import Statement

  • Defines a recognition system ID.

    Declaration

    Swift

    var kSRDefaultRecognitionSystemID: Int { get }

    Objective-C

    enum { kSRDefaultRecognitionSystemID = 0 };

    Constants

    • kSRDefaultRecognitionSystemID

      kSRDefaultRecognitionSystemID

      The default speech recognition system.

      Available in OS X v10.0 and later.

    Discussion

    When you call SROpenRecognitionSystem to open a recognition system, you indicate the system to open by passing a recognition system ID.

    Import Statement

  • Define property selectors for recognition systems.

    Declaration

    Swift

    var kSRFeedbackAndListeningModes: Int { get } var kSRRejectedWord: Int { get } var kSRCleanupOnClientExit: Int { get }

    Objective-C

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

    Constants

    • kSRFeedbackAndListeningModes

      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.

    • kSRRejectedWord

      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.

    • kSRCleanupOnClientExit

      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.

    Discussion

    A recognition system (that is, an instance of the SRRecognitionSystem class) has a set of properties that you can inspect and change by calling the SRGetProperty and SRSetProperty functions. You specify a property by passing a property selector to those functions.

    Import Statement

  • Define listen key property selectors for recognizers.

    Declaration

    Swift

    var kSRListenKeyMode: Int { get } var kSRListenKeyCombo: Int { get } var kSRListenKeyName: Int { get } var kSRKeyWord: Int { get } var kSRKeyExpected: Int { get }

    Objective-C

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

    Constants

    • kSRListenKeyMode

      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.

    • kSRListenKeyCombo

      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.

    • kSRListenKeyName

      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.

    • kSRKeyWord

      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.

    • kSRKeyExpected

      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.

    Discussion

    Every recognizer has a set of properties that you can inspect and change by calling the SRGetProperty and SRSetProperty functions. You specify a property by passing a property selector to those functions.

    The listen key properties 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.

    Import Statement

  • Define property selectors for recognizers.

    Declaration

    Swift

    var kSRNotificationParam: Int { get } var kSRCallBackParam: Int { get } var kSRSearchStatusParam: Int { get } var kSRAutoFinishingParam: Int { get } var kSRForegroundOnly: Int { get } var kSRBlockBackground: Int { get } var kSRBlockModally: Int { get } var kSRWantsResultTextDrawn: Int { get } var kSRWantsAutoFBGestures: Int { get } var kSRSoundInVolume: Int { get } var kSRReadAudioFSSpec: Int { get } var kSRCancelOnSoundOut: Int { get } var kSRSpeedVsAccuracyParam: Int { get }

    Objective-C

    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

      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.

    • kSRCallBackParam

      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.

    • kSRSearchStatusParam

      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.

    • kSRAutoFinishingParam

      kSRAutoFinishingParam

      The auto-finishing parameter.

      Available in OS X v10.0 and later.

    • kSRForegroundOnly

      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.

    • kSRBlockBackground

      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.

    • kSRBlockModally

      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.

    • kSRWantsResultTextDrawn

      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.

    • kSRWantsAutoFBGestures

      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.

    • kSRSoundInVolume

      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.

    • kSRReadAudioFSSpec

      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.

    • kSRCancelOnSoundOut

      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.

    • kSRSpeedVsAccuracyParam

      kSRSpeedVsAccuracyParam

      The speed vs accuracy parameter.

      Available in OS X v10.0 and later.

    Discussion

    Every recognizer has a set of properties that you can inspect and change by calling the SRGetProperty and SRSetProperty functions. You specify a property by passing a property selector to those functions.

    Import Statement

  • Indicate the status of a recognizer search.

    Declaration

    Swift

    var kSRIdleRecognizer: Int { get } var kSRSearchInProgress: Int { get } var kSRSearchWaitForAllClients: Int { get } var kSRMustCancelSearch: Int { get } var kSRPendingSearch: Int { get }

    Objective-C

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

    Constants

    • kSRIdleRecognizer

      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.

    • kSRSearchInProgress

      kSRSearchInProgress

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

      Available in OS X v10.0 and later.

    • kSRSearchWaitForAllClients

      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.

    • kSRMustCancelSearch

      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.

    • kSRPendingSearch

      kSRPendingSearch

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

      Available in OS X v10.0 and later.

    Discussion

    You can determine the current status of a recognizer search by getting the recognizer’s search status, which is a property of type kSRSearchStatusParam. That property’s value is a 4-byte unsigned integer. The Speech Recognition Manager defines these masks for bits in that value.

    Import Statement

  • Identify Speech Recognition Manager-supported speech sources.

    Declaration

    Swift

    var kSRDefaultSpeechSource: Int { get } var kSRLiveDesktopSpeechSource: Int { get } var kSRCanned22kHzSpeechSource: Int { get }

    Objective-C

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

    Constants

    • kSRDefaultSpeechSource

      kSRDefaultSpeechSource

      The default speech source.

      Available in OS X v10.0 and later.

    • kSRLiveDesktopSpeechSource

      kSRLiveDesktopSpeechSource

      Live desktop sound input.

      Available in OS X v10.0 and later.

    • kSRCanned22kHzSpeechSource

      kSRCanned22kHzSpeechSource

      AIFF file based 16 bit, 22.050 KHz sound input.

      Available in OS X v10.0 and later.

    Discussion

    The Speech Recognition Manager supports several speech sources, which you can specify using these constants. In version 1.5, the default speech source is kSRLiveDesktopSpeechSource.

    Import Statement

Result Codes

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

  • Requested service not available or applicable

    Value

    -5100

    Description

    Requested service not available or applicable

    Available in OS X v10.0 and later.

  • Internal system or hardware error condition

    Value

    -5101

    Description

    Internal system or hardware error condition

    Available in OS X v10.0 and later.

  • Required component cannot be located

    Value

    -5102

    Description

    Required component cannot be located

    Available in OS X v10.0 and later.

  • Not enough memory available

    Value

    -5103

    Description

    Not enough memory available

    Available in OS X v10.0 and later.

  • Object is not valid

    Value

    -5104

    Description

    Object is not valid

    Available in OS X v10.0 and later.

  • Invalid parameter specified

    Value

    -5105

    Description

    Invalid parameter specified

    Available in OS X v10.0 and later.

  • Parameter is out of valid range

    Value

    -5106

    Description

    Parameter is out of valid range

    Available in OS X v10.0 and later.

  • Unrecognized selector specified

    Value

    -5107

    Description

    Unrecognized selector specified

    Available in OS X v10.0 and later.

  • Buffer is too small

    Value

    -5108

    Description

    Buffer is too small

    Available in OS X v10.0 and later.

  • Specified object is not a recognition system

    Value

    -5109

    Description

    Specified object is not a recognition system

    Available in OS X v10.0 and later.

  • No feedback window associated with recognizer

    Value

    -5110

    Description

    No feedback window associated with recognizer

    Available in OS X v10.0 and later.

  • Cannot set the specified property

    Value

    -5111

    Description

    Cannot set the specified property

    Available in OS X v10.0 and later.

  • Cannot get the specified property

    Value

    -5112

    Description

    Cannot get the specified property

    Available in OS X v10.0 and later.

  • Cannot set property during recognition

    Value

    -5113

    Description

    Cannot set property during recognition

    Available in OS X v10.0 and later.

  • System is already listening

    Value

    -5114

    Description

    System is already listening

    Available in OS X v10.0 and later.

  • System is not listening

    Value

    -5115

    Description

    System is not listening

    Available in OS X v10.0 and later.

  • No acoustical models available to match request

    Value

    -5116

    Description

    No acoustical models available to match request

    Available in OS X v10.0 and later.

  • Cannot access specified language model

    Value

    -5117

    Description

    Cannot access specified language model

    Available in OS X v10.0 and later.

  • No utterances to search

    Value

    -5118

    Description

    No utterances to search

    Available in OS X v10.0 and later.

  • Search was canceled

    Value

    -5119

    Description

    Search was canceled

    Available in OS X v10.0 and later.

  • Search has finished, but nothing was recognized

    Value

    -5120

    Description

    Search has finished, but nothing was recognized

    Available in OS X v10.0 and later.

  • Another recognizer is already operating modally

    Value

    -5121

    Description

    Another recognizer is already operating modally

    Available in OS X v10.0 and later.

  • Specified object has no subitems

    Value

    -5122

    Description

    Specified object has no subitems

    Available in OS X v10.0 and later.

  • Specified subitem cannot be located

    Value

    -5123

    Description

    Specified subitem cannot be located

    Available in OS X v10.0 and later.

  • Language model too big to be built

    Value

    -5124

    Description

    Language model too big to be built

    Available in OS X v10.0 and later.

  • Specified object has already been released

    Value

    -5125

    Description

    Specified object has already been released

    Available in OS X v10.0 and later.

  • Specified language model has already been finished

    Value

    -5126

    Description

    Specified language model has already been finished

    Available in OS X v10.0 and later.

  • Spelling could not be found

    Value

    -5127

    Description

    Spelling could not be found

    Available in OS X v10.0 and later.

  • Language model not finished with rejection

    Value

    -5128

    Description

    Language model not finished with rejection

    Available in OS X v10.0 and later.

  • Language model is left recursive or is embedded too many levels

    Value

    -5129

    Description

    Language model is left recursive or is embedded too many levels

    Available in OS X v10.0 and later.

  • Too many elements added to phrase, path, or other language object

    Value

    -5130

    Description

    Too many elements added to phrase, path, or other language object

    Available in OS X v10.0 and later.

  • Can't add specified type of object to the base language object

    Value

    -5131

    Description

    Can't add specified type of object to the base language object

    Available in OS X v10.0 and later.

  • Sound input source is disconnected

    Value

    -5132

    Description

    Sound input source is disconnected

    Available in OS X v10.0 and later.

  • Cannot create language object from file or pointer

    Value

    -5133

    Description

    Cannot create language object from file or pointer

    Available in OS X v10.0 and later.

  • Feature is not yet implemented

    Value

    -5199

    Description

    Feature is not yet implemented

    Available in OS X v10.0 and later.

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.