ISpRecognizer::SetInput (SAPI 5.3)

Microsoft Speech API 5.3

ISpRecognizer::SetInput

ISpRecognizer::SetInput specifies which input stream the SR engine should use.

  
    HRESULT SetInput(
   IUnknown  *pUnkInput,
   BOOL       fAllowFormatChanges
);

Parameters

• pUnkInput
  [in] The stream object token. See Remarks section.
• fAllowFormatChanges
  [in] Boolean indicating whether SAPI should try to change the input stream format to the engine's preferred format. This method can normally be set to TRUE; however, when performing both speech recognition and speech output at the simultaneously, some soundcards may require that both input and output are in the same audio format. Setting this to FALSE prevents the audio format on the input device from being changed. Instead, SAPI will try to convert the audio format itself to something the SR engine can use. 

Return values

Value

S_OK

E_INVALIDARG

SPERR_ENGINE_BUSY

FAILED(hr)

Remarks

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 a pointer to an actual object implementing ISpStreamFormat.

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 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. ISpRecognizer::SetInput must be called 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, SAPI automatically sets up the audio input. However, ISpRecognizer::SetInput may be called with NULL as the pUnkInput parameter to force the recognizer to re-check the default audio input and re-set up the audio input (e.g., the default audio input object changes while recognizing, and the new audio input is to be used).

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

Example

The following code snippet illustrates the use of ISpRecognizer::SetInput.

  
// Declare local identifiers:
HRESULT                      hr = S_OK;
CComPtr<ISpRecognizer>       cpRecognizer;
CComPtr<ISpObjectToken>      cpObjectToken;
CComPtr<ISpAudio>            cpAudio;

// Set up the inproc recognizer audio
// input with an audio input object token.

// Get the default audio input token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_AUDIOIN, &cpObjectToken;);

if (SUCCEEDED(hr))
{
   // Set the audio input to our token.
   hr = cpRecognizer->SetInput(cpObjectToken, TRUE);
}

if (SUCCEEDED(hr))
{
   // Set up the inproc recognizer audio input with an audio input object.

   // Create the default audio input object.
   hr = SpCreateDefaultObjectFromCategoryId(SPCAT_AUDIOIN, &cpAudio;);
}

if (SUCCEEDED(hr))
{
   // Set the audio input to our object.
   hr = cpRecognizer->SetInput(cpAudio, TRUE);
}

if (SUCCEEDED(hr))
{
   // Ask the shared recognizer to re-check the default audio input token.
   hr = cpRecognizer->SetInput(NULL, TRUE);
}

if (SUCCEEDED(hr))
{
   // If hr = SPERR_ENGINE_BUSY, then retry later.
}