ISpRecognizer::SetInput

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This method specifies the input stream that the SR engine should use. This method can be used to switch the input for the recognizer to a wave input stream, a different soundcard device, or to a custom audio object. The pUnkInput parameter can be a pointer to an object token representing an audio input device; or to an actual object implementing ISpStreamFormat.

Syntax

HRESULT SetInput(
  IUnknown* pUnkInput,
  BOOL fAllowFormatChanges
);

Parameters

• pUnkInput
  [in] Pointer to IUnknown for the stream object token. See Remarks section

• fAllowFormatChanges
  [in] Value indicating if SAPI should try to change the input stream format to the engine-preferred format. Set this value to TRUE if SAPI should try to make the change, and to FALSE otherwise. This method can typically be set to TRUE. However, when doing both speech recognition and speech output at the same time some soundcards may require both input and output to be in the same audio format. Setting this parameter to FALSE prevents changes to the audio format on the input device. Instead, SAPI will try to convert the audio format itself to something that the SR engine can use.

Return Value

The following table shows the possible return values.

Value	Description
S_OK	Function completed successfully.
E_INVALIDARG	pUnkInput is invalid or not a stream.
SPERR_ENGINE_BUSY	The current method cannot be performed while the engine is currently processing audio.
FAILED(hr)	Appropriate error message.

Remarks

The input stream object will implement IStream, ISpStreamFormat, and ISpAudio for real-time streams. Applications should NOT use methods on these interfaces that actually change the state of the audio device or read data from it at the same time that the stream is being used by SAPI. For example, reading data from the application with IStream::Read will prevent the correct data from being passed to the SR engine. Altering the state of the audio by using ISpAudio::SetState will put the audio device into an unexpected state and may cause errors. All control of the audio is done by SAPI.

When using the InProc recognizer, SAPI does not automatically setup the audio input. You must be call ISpRecognizer::SetInput with a non-null pUnkInput to setup and start the audio input stream. Until ISpRecognizer::SetInput is called, methods such as ISpRecoGrammar::SetRuleState will return success code SP_STREAM_UNITIALIZED, but actual recognition will not start.

When using the shared recognizer this, SAPI does automatically setup the audio input. However, you can call ISpRecognizer::SetInput with NULL as the pUnkInput parameter to force the recognizer to re-check the default audio input and re-set up the audio input (for example, the default audio input object changes while recognizing, and you would like to use the new audio input).

If the engine is currently processing audio, this call will fail with SPERR_ENGINE_BUSY.

Example

The following code snippet illustrates the use of this method.

// setup the inproc recognizer audio input with an audio input object token
// get the default audio input token
hr = SpGetDefaultTokenFromCategoryId(SPCAT_AUDIOIN, &cpObjectToken);
// Check hr
// set the audio input to our token
hr = cpRecognizer->SetInput(cpObjectToken, TRUE);
// Check hr
// setup the inproc recognizer audio input with an audio input object
// create the default audio input object
hr = SpCreateDefaultObjectFromCategoryId(SPCAT_AUDIOIN, &cpAudio);
// Check hr
// set the audio input to our object
hr = cpRecognizer->SetInput(cpAudio, TRUE);
// Check hr
// ask the shared recognizer to re-check the default audio input token
hr = cpRecognizer->SetInput(NULL, TRUE);
// Check hr - if SPERR_ENGINE_BUSY, then retry later

Requirements

Header	sapi.h, sapi.idl
Library	sapilib.lib
Windows Embedded CE	Windows CE .NET 4.1 and later

See Also

Reference

ISpRecognizer
SAPI Interfaces