ISpSREngine::RecognizeStream (Windows CE 5.0)
This method indicates to the SR engine that recognition processing should start. During processing the engine can read data, perform recognition, and send results and events back to SAPI. When all the data to be recognized has been read, or the application has deactivated recognition, this method finishes processing and returns.
The engine does not have direct access to the input audio device. The lack of direct access allows the engine to react in a consistent way, regardless of input source: desktop audio, wave files, or custom audio device.
HRESULT RecognizeStream( REFGUID rguidFmtId, const WAVEFORMATEX* pWaveFormatEx, HANDLE hRequestSync, HANDLE hDataAvailable, HANDLE hExit, BOOL fNewAudioStream, BOOL fRealTimeAudio, ISpObjectToken* pAudioObjectToken);
Parameters
- rguidFmtId
[in] Identifier of the input audio format to recognize. The identifier is SPDFID_WaveFormatEx for wave formats. - pWaveFormatEx
[in] Pointer to a WAVEFORMATEX structure describing the input format (if it is a wave format). The input format specified by this parameter must be a format that the engine has already indicated it can process through a prior call to ISpSREngine::GetInputAudioFormat. - hRequestSync
[in] Handle to a Win32 event that is set when there are tasks (for example, grammar changes) waiting for the engine. The engine processes these tasks when it calls Synchronize. The engine can call this function regularly or do so only when the event is set. - hDataAvailable
[in] Handle to a Win32 event that is set when data is available for reading. The amount of data to be available can be controlled by calling the ISpSREngineSite::SetBufferNotifySize method. By default this event is set when any amount of data is available. The event can be used as an alternative to a call to the ISpSREngineSite::DataAvailable method. - hExit
[in] Handle to a Win32 event that is set when the engine should exit. The engine should exit both when there is no more data in the stream and it has finished processing, and when this event is set. When this event is set, the engine should exit immediately without completing processing. The setting of the event is also indicated by a Recognition or Synchronize call returning S_FALSE. - fNewAudioStream
[in] Value indicating if the input is a new stream. Set this value to TRUE to specify a newly created stream, and to FALSE otherwise. For example, if an application deactivates the active rules and RecognizeStream returns, and then later the application activates some rules, the RecognizeStream call will have this parameter set as FALSE. Only if the application makes a new call to ISpRecognizer::SetInput will this parameter be set to TRUE. Some engines may find this information useful. - fRealTimeAudio
[in] Value indicating if the input is real-time audio. Set this value to TRUE to specify real-time audio, and to FALSE otherwise. Real-time inputs in SAPI are those that implement the ISpAudio interface, for example, the standard multi-media microphone input. Non-real-time streams are those that only implement ISpStreamFormat, for example, input from wave files. With non-real-time streams all the data is available for reading immediately. The hDataAvailable parameter is always set and a call to ISpSREngineSite::DataAvailable will always return INFINITE. - pAudioObjectToken
[in] Pointer to an object implementing ISpObjectToken for the audio from which the stream was created. Engines do not need to do anything with this parameter, but it may be useful in some circumstances.
Return Values
The following table shows the possible return values.
| Value | Description |
|---|---|
| S_OK | Function completed successfully. This value is returned if the engine is exiting because the stream has ended, or because SAPI has signaled it to exit. |
| FAILED(hr) | Appropriate error message if the engine is terminating for an unexpected reason. |
Remarks
When SAPI calls ISpSREngine::RecognizeStream, the audio format is given in the rguidFmtId and pWaveFormatEx parameters, and additional details of the audio device can be found from the fNewAudioStream, fRealTimeAudio, and pAudioObjectToken parameters. The engine determines how much data is available for reading with the ISpSREngineSite::DataAvailable method. It can then read the associated audio data using the ISpSREngineSite::Read method. When the Read method indicates that there is no more data available, RecognizeStream completes processing on the data it has and returns.
During recognition processing, the engine uses the ISpSREngineSite::Synchronize method to become informed of any grammar changes, or any other changes, that are pending. The engine also uses the ISpSREngineSite::UpdateRecoPos method to keep SAPI informed of how far through the stream it has recognized. The engine passes back to SAPI details of events and recognition results with the ISpSREngineSite::AddEvent and ISpSREngineSite::Recognition methods.
The SR engine should recognize data from all rules or dictation grammars that have been activated. If there are multiple active rules or dictations, the engine is expected to recognize from all things "in parallel" (for example, the user is enabled to say something from anything that is active). It is possible for ISpSREngine::RecognizeStream to be called with nothing active. In this case, the engine can just read data and then discard it, or use it to gather noise environment information.
Because the engine remains in the RecognizeStream method all the time that it is recognizing, SAPI has effectively given the engine one thread on which to perform recognition. It is possible to write an engine that does all processing on this one thread and thus does not require any additional threads, or critical sections or other thread locking. It is also possible to have alternative arrangements with additional threads. For example, one thread can read data, while another thread can do the actual recognition processing. SAPI makes no restrictions about which threads call which methods or whether the methods are called simultaneously.
Requirements
OS Versions: Windows CE .NET 4.1 and later.
Header: Sapiddk.h, Sapiddk.idl.
Link Library: Sapilib.lib.
See Also
Send Feedback on this topic to the authors