|
|
The top-level user interface functions within VCD. These functions provide the entire functionality of VCD to the user.
| VCD_API VCD_MessageEnum VCD_init | ( | VCD_Handle * | pmh, |
| VCD_ConfigStruct * | config | ||
| ) |
Initialize an instance of the VCD recognizer. Provides a handle to the new recognizer instance. Initializes all parameters to default values. This must be the first function called when starting to use VCD.
| [in,out] | pmh | Pointer to a VCD_Handle to be set |
| [in] | config | Pointer to VCD_ConfigStruct for memory allocation |
| VCD_API VCD_MessageEnum VCD_startEnroll | ( | VCD_Handle | vh, |
| char const * | name | ||
| ) |
Set processing mode and prepare for enrolling a new model. Does initialization of VCD so that the data frames susequently processed by VCD_processFrame perform model enrollment. The model will be assigned to the lowest available model index.
| [in] | vh | VCD instance VCD_Handle |
| [in] | name | Name of model to enroll. Model names must be unique. |
| VCD_API VCD_MessageEnum VCD_processFrame | ( | VCD_Handle | vh, |
| int_least16_t const * | data | ||
| ) |
Process the incoming speech data frame based on processing mode. The frames can be processed only after setting the intended mode of operation by calling VCD_startEnroll, VCD_startUpdate, or VCD_startSearch. This function will return an error otherwise. The processing performed depends on which of the functions was called.
When VCD_startSearch has been called, this function will process a frame of captured audio data in the recognizer. Initially a number of data frames are required to set start-up parameters and the data is buffered for the number of frames prior to starting the search engine. Thus the recognizer search engine is running behind actual input data. The user should continue calling this function to process additional captured data frames. When the function returns VCD_MsgRecoComplete, the recognizer has a result. The user must call VCD_getResult to obtain the recognition result. After obtaining the recognition result, VCD_resetSearch may be called followed by further calls to this function to continue recognition. Recognition search must be terminated by calling VCD_stopSearch.
To process remaining buffered frames when no further data is available, this function can be called with data set to NULL, until the recognizer returns VCD_MsgRecoComplete, after which the user must call VCD_stopSearch.
When VCD_startEnroll has been called the function will process each data frame to try to locate a speech utterance. All frames deemed to be part of an utterance will be used to create the new model. The return value will indicate the status for each frame passed to the function. Frames of data should continue to be passed to the function until it indicates it successfully found a phrase, or a failure message occurs. Enrollment should be done in a quiet environment to ensure accurate location of speech. Once successful enrollment is indicated, the new model can be stored for use by VCD by calling VCD_addEnroll. VCD_stopEnroll must be called to exit the enrollment mode.
When VCD_startUpdate has been called the function will process each frame to try to match the speech data to the model to be updated. The return value will indicate the status for each frame passed to the function. Frames of data should continue to be passed to the function until it indicates it successfully mapped the speech data to the existing model by returning VCD_MsgKeywordFound, or a failure message occurs. Update should be done in a quiet environment to ensure accurate mapping of input speech to the existing model. Once successful update is indicated, the updated model data can be incorporated in the model by a call to VCD_addUpdate. VCD_stopUpdate must be called to exit the update mode.
| [in] | vh | VCD instance VCD_Handle |
| [in] | data | Pointer to a frame of data |
| VCD_API VCD_MessageEnum VCD_getEnrollQuality | ( | VCD_Handle | vh, |
| int_least16_t * | quality | ||
| ) |
Get the enrolled model quality score. This function provides a a measure between 0 and 1 that indicates if an enrolled phrase is likely to provide good recognition results. Phrases will provide better recognition results if they contain significant speech acoustic context. This function should be called only after VCD_processFrame returns the status message VCD_MsgKeywordFound, indicating it successfully located the enrollment utterance. The results of this function can be used to determine if the enrollment utterance should be saved by calling VCD_addEnroll, or whether the user should be notified to provide a better phrase.
| [in] | vh | VCD instance VCD_Handle |
| [out] | quality | The quality of the enrolled utterance 0-1 in Q15. |
| VCD_API VCD_MessageEnum VCD_getEnrollDifference | ( | VCD_Handle | vh, |
| int_least16_t * | difference | ||
| ) |
Get the enrolled model difference with all other currently existing models. This function provides a a measure between 0 (very similar) and 1 (very different) that indicates how different an enrolled phrase is from all other currently enrolled models. Enrolling models that are signifcantly different is likely to provide good recognition results for all enrolled phrases. This function should be called while enrolling after VCD_processFrame returns the status message VCD_MsgKeywordFound, indicating it successfully located the enrollment utterance. The results of this function can be used to determine if the enrollment utterance should be saved by calling VCD_addEnroll, or whether the user should be notified to provide a different phrase.
| [in] | vh | VCD instance VCD_Handle |
| [out] | difference | The difference measure between 0-1 in Q15. |
| VCD_API VCD_MessageEnum VCD_addEnroll | ( | VCD_Handle | vh | ) |
Add the enrolled model to the VCD active model set. This will save the enrollment model, adding it to the set of models. This function should be called only after VCD_processFrame returns the status message VCD_MsgKeywordFound, indicating it successfully located the enrollment utterance. The newly enrolled model will be enabled for recognition. Prior to calling this function, VCD_getEnrollQuality may be called to determine if the enrollment model should be added.
| [in] | vh | VCD instance VCD_Handle |
| VCD_API VCD_MessageEnum VCD_stopEnroll | ( | VCD_Handle | vh | ) |
End the enrollment mode of VCD. Calling this function ends the enrollment of a model. It can be called at any time after successfully calling VCD_startEnroll, and must be called to end the enrollment processing.
| [in] | vh | VCD instance VCD_Handle |
| VCD_API VCD_MessageEnum VCD_startUpdate | ( | VCD_Handle | vh, |
| char const * | name | ||
| ) |
Set processing mode and prepare for updating an existing model. Sets VCD so that the data frames that will be processed by VCD_processFrame perform model update to improve the model. Currently only update of Left-to-right models is supported.
| [in] | vh | VCD instance VCD_Handle |
| [in] | name | Name of model to update |
| VCD_API VCD_MessageEnum VCD_addUpdate | ( | VCD_Handle | vh, |
| int_least16_t | priorUpdates | ||
| ) |
Update the model based on the update result. This function updates model data in model memory based on the data received during update frame processing. This function should only be called after VCD_processFrame triggers the status message VCD_MsgKeywordFound, indicating it successfully mapped the update data to the model. The updated model will be enabled for recognition.
The function provides a means of weighting the relative importance of the update compared with the accumulated prior updates. To adjust weighting during the update, specify a positive integer value that acts as the prior number of occurrences for the accumulated model data. In this way varied emphasis can be put on the accumulated data relative to the update data. If the prior number of occurrences are zero or less, then 1 is used.
| [in] | vh | VCD instance VCD_Handle |
| [in] | priorUpdates | Weighting for the importance of accumulated updates |
| VCD_API VCD_MessageEnum VCD_stopUpdate | ( | VCD_Handle | vh | ) |
End the update mode of VCD. Calling this function ends the update of a model. It can be called at any time after successfully calling VCD_startUpdate, and must be called to end the update processing.
| [in] | vh | VCD instance VCD_Handle |
| VCD_API VCD_MessageEnum VCD_startSearch | ( | VCD_Handle | vh | ) |
Set mode and prepare for recognition search.
| [in] | vh | VCD instance VCD_Handle |
| VCD_API VCD_MessageEnum VCD_stopSearch | ( | VCD_Handle | vh | ) |
Stop the recognition mode. Stop recognition, freeing any allocated resources.
| [in] | vh | VCD instance VCD_Handle |
| VCD_API VCD_MessageEnum VCD_getResult | ( | VCD_Handle | vh, |
| VCD_Reco | result | ||
| ) |
Retrieve the recognition results. Places recognition results in a VCD_RecoStruct. The structure that result points to must be allocated. This function must be called immediately after VCD_processFrame returns VCD_MsgRecoComplete. If the score is too low, or the keyword model is not found, then the result contains the hypothesized model and score, even though it should not be trusted. The best hypothesized model index may be less than zero if a valid model is not the best hypothesis when the recognizer terminates, such as when the keyword model is not found. If no valid hypothesized word is available, then name pointer will be NULL.
| [in] | vh | VCD instance VCD_Handle |
| [in,out] | result | Pointer to recognition structure to hold results |
| VCD_API VCD_MessageEnum VCD_resetSearch | ( | VCD_Handle | vh | ) |
Reset search to begin processing a new utterance. Reset search scores and parameters, and reset front-end utterance detector to start recognizing another utterance immediately after a recognition result is returned. This occurs when VCD_processFrame returns VCD_MsgRecoComplete. This function is used to continue processing of subsequent frames so recognition can be done continuously. It must not be called after searching has been stopped by a call to VCD_stopSearch.
| [in] | vh | VCD handle |
| VCD_API VCD_MessageEnum VCD_getModelInfo | ( | VCD_Handle | vh, |
| char const * | name, | ||
| int_least16_t | index, | ||
| VCD_ModelInfo | info | ||
| ) |
Retrieve information about a model by name or index. Put the data in a model information structure. The user must manage the instantiation of the structure. VCD_init must be called prior to this function to create a valid VCD_Handle instance. This function must not be called after calling VCD_shutdown, which invalidates the VCD_Handle instance. The structure also returns the number of valid models. Model indices are zero-based. Model index 0 is a special unique Filler model. The valid models will be in consecutive index order.
| [in] | vh | VCD handle |
| [in] | name | Name of the model. If NULL, use model index |
| [in] | index | Index of model. Not used if name specifies a model. |
| [in,out] | info | Pointer to model info structure to hold results |
| VCD_API VCD_MessageEnum VCD_removeModel | ( | VCD_Handle | vh, |
| char const * | name, | ||
| int_least16_t | index | ||
| ) |
Remove a model with the given name or index. Model indices are zero-based. Model index 0 is a special unique Filler model which can not be removed. The valid model indices will be in consecutive order. If a valid name is given, then index is not used.
| [in] | vh | VCD handle |
| [in] | name | Name of model to be removed. Set to NULL to use index. |
| [in] | index | Model index corresponding to model data to removed |
| VCD_API VCD_MessageEnum VCD_disableModel | ( | VCD_Handle | vh, |
| char * | name, | ||
| int_least16_t | index | ||
| ) |
Disable the model with the given name or index for use during recognition. A disabled model will not be used during recognition. If the model that is currently set as the filler model (see VCD_ParamsStruct) is disabled, then no filler model processing will be done. If the model that is currently set as the keyword model (see VCD_ParamsStruct) is disabled, then no keyword early commit will be done. Model indices are zero-based. Model index 0 is a special unique Filler model. The valid model indices will be in consecutive order. If a name is given, index will not be used.
| [in] | vh | VCD handle |
| [in] | name | Name of model to disable. Set to NULL to use index. |
| [in] | index | Index of model to disable |
| VCD_API VCD_MessageEnum VCD_enableModel | ( | VCD_Handle | vh, |
| char * | name, | ||
| int_least16_t | index | ||
| ) |
Enable the model with the given name or index to be used during recognition
An enabled model will be used during recognition. Model indices are zero-based. Model index 0 is a special unique Filler model. The valid model indices will be in consecutive. If a name is given, index will not be used.
| [in] | vh | VCD handle |
| [in] | name | Name of the model to enable. Set to NULL to use index. |
| [in] | index | Index of model to enable |
| VCD_API VCD_MessageEnum VCD_getParams | ( | VCD_Handle | vh, |
| VCD_Params | params | ||
| ) |
Get parameter settings currently used by VCD Once a VCD instance is initialized, the parameters that are used during the processing can modified if required. These parameters are set to the default values in the call to VCD_init. This function fills the VCD_Params structure with the parameters that are currently in use.
| [in] | vh | VCD handle |
| [in,out] | params | Pointer to VCD_Params structure to be filled |
| VCD_API VCD_MessageEnum VCD_setParams | ( | VCD_Handle | vh, |
| VCD_Params | params | ||
| ) |
Set the VCD parameters. This function uses the parameters in the VCD_Params structure params to update the parameters used by VCD.
| [in] | vh | VCD handle |
| [in,out] | params | Pointer to VCD_Params structure holding data to set |
| VCD_API VCD_MessageEnum VCD_shutdown | ( | VCD_Handle | vh | ) |
Shut down the instance of the VCD recognizer. Free any resources that VCD may have used. This must be called as the last part of using a recognizer instance to ensure that all resources have been relinquished.
| [in] | vh | VCD handle |
| VCD_API VCD_MessageEnum VCD_checkValidModel | ( | int_least16_t * | address | ) |
Check if there is a valid model stored at the given address.
| [in] | address | The address at which to check if there is a valid model |
| VCD_API VCD_MessageEnum VCD_addList | ( | VCD_Handle | vh, |
| int_least16_t ** | modelsList, | ||
| int_least16_t | numModels | ||
| ) |
Function to add a list of models to the model map.
| [in] | vh | VCD handle |
| [in] | modelsList | An array of pointers that each point to where a valid model is stored in memory |
| [in] | numModels | The number of models to add |
| VCD_API VCD_MessageEnum VCD_writeModel | ( | VCD_Handle | vh, |
| int_least16_t * | ptrModel, | ||
| int_least32_t | mSize, | ||
| int_least16_t ** | mAddress | ||
| ) |
Application defined function to write the model data to memory. The user should not call this function in their application. This function will be called by VCD during VCD_addEnroll().
| [in] | vh | VCD handle |
| [in] | ptrModel | Pointer to where the beginning of the model data is stored in shared memory |
| [in] | mSize | Total size in bytes of the model data |
| [in] | mAddress | Pointer to where the user has stored the model in memory |
| VCD_API VCD_MessageEnum VCD_clearModel | ( | int_least16_t * | mAddress | ) |
Application defined function to clear a model from memory. The user should not call this function in their application. This function will be called by VCD during VCD_removeModel().
| [in] | mAddress | The address that points to the model that should be cleared from memory |
| VCD_MessageEnum VCD_updateModel | ( | VCD_Handle | vh, |
| int_least16_t * | ptrModel, | ||
| int_least32_t | mSize, | ||
| int_least16_t * | mAddress | ||
| ) |
Function to update model data in memory with updated modal data. The user should not call this function in their application. This function will be called by VCD during VCD_addUpdate().
| [in] | vh | VCD handle |
| [in] | ptrModel | Pointer to where the beginning of the updated model data is stored in shared memory |
| [in] | mSize | The size in bytes of the updated model data |
| [in] | mAddress | The address of the model data to overwrite with the updated model data |
