SR_Recognizer API functions


Detailed Description

Synchronous speech recognizer.


Data Structures

struct  SR_Recognizer

Recognizer Setup operations

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerCreate (SR_Recognizer **self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerDestroy (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetup (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerUnsetup (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSetup (SR_Recognizer *self, ESR_BOOL *isSetup)

Recognizer parameter operations

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerGetParameter (SR_Recognizer *self, const LCHAR *key, LCHAR *value, size_t *len)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerGetSize_tParameter (SR_Recognizer *self, const LCHAR *key, size_t *value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerGetBoolParameter (SR_Recognizer *self, const LCHAR *key, ESR_BOOL *value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetParameter (SR_Recognizer *self, const LCHAR *key, LCHAR *value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetSize_tParameter (SR_Recognizer *self, const LCHAR *key, size_t value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetBoolParameter (SR_Recognizer *self, const LCHAR *key, ESR_BOOL value)

Recognizer rule Setup/Activation operations

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetupRule (SR_Recognizer *self, struct SR_Grammar_t *grammar, const LCHAR *ruleName)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerHasSetupRules (SR_Recognizer *self, ESR_BOOL *hasSetupRules)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerActivateRule (SR_Recognizer *self, struct SR_Grammar_t *grammar, const LCHAR *ruleName, unsigned int weight)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerDeactivateRule (SR_Recognizer *self, struct SR_Grammar_t *grammar, const LCHAR *ruleName)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerDeactivateAllRules (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsActiveRule (SR_Recognizer *self, struct SR_Grammar_t *grammar, const LCHAR *ruleName, ESR_BOOL *isActiveRule)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerCheckGrammarConsistency (SR_Recognizer *self, struct SR_Grammar_t *grammar, ESR_BOOL *isConsistent)

Recognizer Advance operations

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerPutAudio (SR_Recognizer *self, asr_int16_t *buffer, size_t *bufferSize, ESR_BOOL isLast)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerAdvance (SR_Recognizer *self, SR_RecognizerStatus *status, SR_RecognizerResultType *type, SR_RecognizerResult **result)

Signal quality metrics

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalClipping (SR_Recognizer *self, ESR_BOOL *isClipping)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalDCOffset (SR_Recognizer *self, ESR_BOOL *isDCOffset)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalNoisy (SR_Recognizer *self, ESR_BOOL *isNoisy)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalTooQuiet (SR_Recognizer *self, ESR_BOOL *isTooQuiet)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalTooFewSamples (SR_Recognizer *self, ESR_BOOL *isTooFewSamples)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerIsSignalTooManySamples (SR_Recognizer *self, ESR_BOOL *isTooManySamples)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_Recognizer_Change_Sample_Rate (SR_Recognizer *self, size_t new_sample_rate)

Functions

SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerStart (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerStop (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogToken (SR_Recognizer *self, const LCHAR *token, const LCHAR *value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogTokenInt (SR_Recognizer *self, const LCHAR *token, int value)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogEvent (SR_Recognizer *self, const LCHAR *event)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogSessionStart (SR_Recognizer *self, const LCHAR *sessionName)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogSessionEnd (SR_Recognizer *self)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLogWaveformData (SR_Recognizer *self, const LCHAR *waveformFilename, const LCHAR *transcription, const double bos, const double eos, ESR_BOOL isInvocab)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLoadUtterance (SR_Recognizer *self, const LCHAR *filename)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerLoadWaveFile (SR_Recognizer *self, const LCHAR *filename)
SREC_RECOGNIZER_API
ESR_ReturnCode 
SR_RecognizerSetLockFunction (SR_Recognizer *self, SR_RecognizerLockFunction function, void *data)


Function Documentation

SREC_RECOGNIZER_API ESR_ReturnCode SR_Recognizer_Change_Sample_Rate ( SR_Recognizer self,
size_t  new_sample_rate 
)

Changes the sample rate of audio.

Parameters:
self SR_Recognizer handle
new_sample_rate [in] New Sample Rate
Returns:
ESR_ReturnCode if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerActivateRule ( SR_Recognizer self,
struct SR_Grammar_t *  grammar,
const LCHAR ruleName,
unsigned int  weight 
)

Activates rule in recognizer.

Parameters:
self SR_Recognizer handle
grammar Grammar containing rule
ruleName Name of rule
weight Relative weight to assign to self grammar vs. other activated grammars. Values: Integers 0-2^31.
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if no models are associated with the recognizer, or if the rule could not be setup, or if the acoustic models could not be setup; ESR_BUFFER_OVERFLOW if ruleName is too long

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerAdvance ( SR_Recognizer self,
SR_RecognizerStatus *  status,
SR_RecognizerResultType *  type,
SR_RecognizerResult **  result 
)

Advance the recognizer by at least one utterance frame. The number of frames advanced depends on the underlying definition. We anticipate that the recognizer will keep up with the supplied audio buffers when waiting for voicing. After this point, the number of frames may be one (for our default frame-advance mode) or it may be more if the synchronous nature of this operation is not considered a problem. The recognizer may be advanced independently of the Recognizer_PutAudio call. It is permissible to advance when there is no further data. A stop condition could be an appropriate consequence.

Parameters:
self Recognizer handle
status Resulting recognizer status
type Resulting recognition result type
result Resulting recognizer result
Returns:
ESR_INVALID_ARGUMENT if self, status, or type are null; ESR_INVALID_STATE if an internal error occurs

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerCheckGrammarConsistency ( SR_Recognizer self,
struct SR_Grammar_t *  grammar,
ESR_BOOL *  isConsistent 
)

Ensure the model usage in a pre-compiled grammar is consistent with the models that are associated with the Recognizer. You must first have called Recognizer_Setup().

Parameters:
self SR_Recognizer handle
grammar Grammar to check against
isConsistent True if rule is consistent
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerCreate ( SR_Recognizer **  self  ) 

Create a new recognizer.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory; ESR_INVALID_STATE if an internal error occurs

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerDeactivateAllRules ( SR_Recognizer self  ) 

Deactivates all grammar rule in recognizer.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerDeactivateRule ( SR_Recognizer self,
struct SR_Grammar_t *  grammar,
const LCHAR ruleName 
)

Deactivates rule in recognizer.

Parameters:
self SR_Recognizer handle
grammar Grammar containing rule
ruleName Name of rule
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if grammar is not activated

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerDestroy ( SR_Recognizer self  ) 

Destroy a recognizer.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if an internal error has occured

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerGetBoolParameter ( SR_Recognizer self,
const LCHAR key,
ESR_BOOL *  value 
)

Return copy of BOOL recognition parameter.

Parameters:
self SR_Recognizer handle
key Parameter name
value Used to hold the parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_RESULT_TYPE if the specified property is not of type bool

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerGetParameter ( SR_Recognizer self,
const LCHAR key,
LCHAR value,
size_t *  len 
)

Returns copy of LCHAR recognition parameter.

Parameters:
self SR_Recognizer handle
key Parameter name
value [out] Used to hold the parameter value
len [in/out] Length of value argument. If the return code is ESR_BUFFER_OVERFLOW, the required length is returned in this variable.
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_RESULT_TYPE if the specified property is not of type LCHAR*

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerGetSize_tParameter ( SR_Recognizer self,
const LCHAR key,
size_t *  value 
)

Return copy of size_t recognition parameter.

Parameters:
self SR_Recognizer handle
key Parameter name
value Used to hold the parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_RESULT_TYPE if the specified property is not of type size_t

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerHasSetupRules ( SR_Recognizer self,
ESR_BOOL *  hasSetupRules 
)

Indicates if Recognizer is configured with any rules within the specified Grammar.

Parameters:
self SR_Recognizer handle
hasSetupRules True if the Recognizer is configured for the Grammar
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsActiveRule ( SR_Recognizer self,
struct SR_Grammar_t *  grammar,
const LCHAR ruleName,
ESR_BOOL *  isActiveRule 
)

Indicates if rule is active in recognizer.

Parameters:
self SR_Recognizer handle
grammar Grammar containing rule
ruleName Name of rule
isActiveRule True if rule is active
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSetup ( SR_Recognizer self,
ESR_BOOL *  isSetup 
)

Indicates whether recognizer is configured for use.

Parameters:
self SR_Recognizer handle
isSetup True if recognizer is configured
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalClipping ( SR_Recognizer self,
ESR_BOOL *  isClipping 
)

Indicates if signal is getting clipped.

Parameters:
self SR_Recognizer handle
isClipping [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalDCOffset ( SR_Recognizer self,
ESR_BOOL *  isDCOffset 
)

Indicates if signal has a DC-offset component.

Parameters:
self SR_Recognizer handle
isDCOffset [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalNoisy ( SR_Recognizer self,
ESR_BOOL *  isNoisy 
)

Indicates if signal is noisy.

Parameters:
self SR_Recognizer handle
isNoisy [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalTooFewSamples ( SR_Recognizer self,
ESR_BOOL *  isTooFewSamples 
)

Indicates if there are too few samples in the signal for a proper recognition.

Parameters:
self SR_Recognizer handle
isTooFewSamples [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalTooManySamples ( SR_Recognizer self,
ESR_BOOL *  isTooManySamples 
)

Indicates if there are too many samples in the signal for a proper recognition.

Parameters:
self SR_Recognizer handle
isTooManySamples [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerIsSignalTooQuiet ( SR_Recognizer self,
ESR_BOOL *  isTooQuiet 
)

Indicates if speech contained within the signal is too quiet.

Parameters:
self SR_Recognizer handle
isTooQuiet [out] Result value
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLoadUtterance ( SR_Recognizer self,
const LCHAR filename 
)

Loads utterance from file.

Parameters:
self SR_Recognizer handle
filename File to read from
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLoadWaveFile ( SR_Recognizer self,
const LCHAR filename 
)

Loads utterance from WAVE file.

Parameters:
self SR_Recognizer handle
filename WAVE file to read from
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogEvent ( SR_Recognizer self,
const LCHAR event 
)

Log recognizer-related event and dump all previously accumulated tokens since last event to log.

Parameters:
self SR_Recognizer handle
event Event name
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogSessionEnd ( SR_Recognizer self  ) 

Log the end of a log session.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogSessionStart ( SR_Recognizer self,
const LCHAR sessionName 
)

Log the beginning of a new log session. A log session contains zero or more recognitions (transactions) and it is up to the application to decided when the session ends and a new one begins (e.g. timeout, number of recognitions, etc.)

Parameters:
self SR_Recognizer handle
sessionName Session name
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogToken ( SR_Recognizer self,
const LCHAR token,
const LCHAR value 
)

Log recognizer-related event token.

Parameters:
self SR_Recognizer handle
token Token name
value Value to be logged
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogTokenInt ( SR_Recognizer self,
const LCHAR token,
int  value 
)

Log recognizer-related event token integer.

Parameters:
self SR_Recognizer handle
token Token name
value Value to be logged
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerLogWaveformData ( SR_Recognizer self,
const LCHAR waveformFilename,
const LCHAR transcription,
const double  bos,
const double  eos,
ESR_BOOL  isInvocab 
)

Log data about a waveform obtained from a TCP file. This function is not called when doing live recognition.

Parameters:
self SR_Recognizer handle
waveformFilename Session name
transcription Transcription for the utterance
bos Beginning of speech (seconds)
eos End of speech (seconds)
isInvocab True if the transcription is accepted by the grammar, False otherwise
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerPutAudio ( SR_Recognizer self,
asr_int16_t buffer,
size_t *  bufferSize,
ESR_BOOL  isLast 
)

Get audio into the recognizer.

We decouple the Audio and frontend processing from the Recognizer processing via an internal FIFO frame buffer (aka utterance buffer). This ensures that this call is at least as fast as real time so that voicing events are not unduly delayed. The audio buffer size must be at least one frame buffer's worth and some reasonable maximum size for synchronous behaviour. This function may be called independently of Recognizer_Advance.

Parameters:
self SR_Recognizer handle
buffer Buffer containing audio data
bufferSize [in/out] Size of buffer in samples. In case of a buffer overflow, ESR_BUFFER_OVERFLOW is returned and this value holds the actual amount of samples that were pushed.
isLast Indicates if the audio frame is the last one in this recognition
Returns:
ESR_INVALID_ARGUMENT if self, buffer, or bufferSize are null; ESR_INVALID_STATE if the recognizer isn't started, or the recognizer has already received the last frame; ESR_BUFFER_OVERFLOW if the recognizer buffer is full

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetBoolParameter ( SR_Recognizer self,
const LCHAR key,
ESR_BOOL  value 
)

Sets BOOL recognition parameter.

Parameters:
self SR_Recognizer handle
key Parameter name
value Parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetLockFunction ( SR_Recognizer self,
SR_RecognizerLockFunction  function,
void *  data 
)

Associates a locking function with the recognizer. This function is used to protect internal data from multithreaded access.

Parameters:
self SR_Recognizer handle
function Locking function
data Function data
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetParameter ( SR_Recognizer self,
const LCHAR key,
LCHAR value 
)

Sets LCHAR* recognition parameters.

Key: Description of associated value

VoiceEnrollment If "true", the next recognition will produce data required for Nametag support (i.e. Aurora bitstream).

Parameters:
self SR_Recognizer handle
key Parameter name
value Parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetSize_tParameter ( SR_Recognizer self,
const LCHAR key,
size_t  value 
)

Sets size_t recognition parameter.

Parameters:
self SR_Recognizer handle
key Parameter name
value Parameter value
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY is system is out of memory

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetup ( SR_Recognizer self  ) 

Associates a set of models with the recognizer. All grammars must use models consistently.

Parameters:
self SR_Recognizer handle
See also:
SR_RecognizerCheckGrammarConsistency
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerSetupRule ( SR_Recognizer self,
struct SR_Grammar_t *  grammar,
const LCHAR ruleName 
)

Recognizer may be set up with multiple Grammars and multiple rules. All grammars must be unsetup before the recognizer can be destroyed. A pre-compiled Grammar should have undergone a model consistency check with the recognizer prior to this call.

Parameters:
self SR_Recognizer handle
grammar Grammar containing rule
ruleName Name of rule to associate with recognizer
See also:
SR_GrammarCheckModelConsistency
Returns:
ESR_INVALID_ARGUMENT if self is null

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerStart ( SR_Recognizer self  ) 

Starts recognition.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null, if no acoustic models have been associated with the recognizer, if no grammars have been activated, or if the recognizer cannot be started for an unknown reason

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerStop ( SR_Recognizer self  ) 

Stops the recognizer and invalidates the recognition result object. Calling this function before the recognizer receives the last frame causes the recognition to abort.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null; ESR_INVALID_STATE if an internal error has occured

SREC_RECOGNIZER_API ESR_ReturnCode SR_RecognizerUnsetup ( SR_Recognizer self  ) 

Unconfigures recognizer.

Parameters:
self SR_Recognizer handle
Returns:
ESR_INVALID_ARGUMENT if self is null


Generated on Thu May 1 15:37:26 2008 for SREC by  doxygen 1.5.3