Microsoft Speech Platform

ISpRecognizer::SetInput

ISpRecognizer::SetInput specifies which input stream the speech recognition (SR) engine should use.

<pre IsFakePre="true" xmlns="http://www.w3.org/1999/xhtml"> HRESULT SetInput( IUnknown *pUnkInput, BOOL fAllowFormatChanges ); </pre>

Parameters

pUnkInput
[in] The stream object token. See Remarks section.
fAllowFormatChanges
[in] Boolean indicating whether the Speech Platform 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, the Speech Platform will try to convert the audio format to something the SR engine can use.

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

This method can be used to switch the input for the recognizer to an input stream in WAV audio format, 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 the Speech Platform. For example, reading data from the application with ISequentialStream::Read will prevent the correct data from being passed to the speech recognition 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 the Speech Platform.

The Speech Platform does not automatically setup the audio input. An application must 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_UNINITIALIZED, but actual recognition will not start.

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 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 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))
{
// Reset the audio input token.
hr = cpRecognizer->SetInput(NULL, TRUE);
}
if (SUCCEEDED(hr))
{
// If hr = SPERR_ENGINE_BUSY, then retry later.
}

Share via