ISpRecoContext::SetVoice (SAPI 5.3)

Speech API 5.3
Microsoft Speech API 5.3


ISpRecoContext::SetVoice sets the associated ISpVoice to an object. 

   ISpVoice   *pVoice,
   BOOL        fAllowFormatChanges


[in] The voice interface to be associated. If NULL, the currently associated Voice is Released.
[in] Boolean allowing the voice format alteration by the engine. See Remarks section.

Return values

S_OKFunction completed successfully.
E_POINTERpVoice is invalid or bad.
FAILED(hr)Appropriate error message.


If fAllowFormatChanges is TRUE, the Voice's output format will be changed to be the same format as the associated SR engine's audio input format (see ISpRecognizer and ISpSREngine::GetInputAudioFormat). However, if this voice object has already been bound to a stream which has specific format, the voice's format will not be changed to the SR engine's audio input format even if fAllowFormatChanges is true.

Using the same audio format for input and output source is useful for sound cards that do not support full-duplex audio (i.e., input format must match output format). If the input format quality is lower than the output format quality, the output format quality will be reduced to equal the input quality.

After calling ISpRecoContext::SetVoice, an application that calls ISpRecoContext::GetVoice will retrieve the originally "set" ISpVoice interface pointer.


The following code snippet illustrates the use of ISpRecoContext::SetVoice and "barge-in" setup.

// Declare local identifiers:
HRESULT	                   hr = S_OK;
CComPtr<ISpRecoContext>    cpRecoContext;
CComPtr<ISpVoice>          cpVoice;

// Create a shared recognition context.
hr = cpRecoContext.CoCreateInstance(CLSID_SpSharedRecoContext);

if (SUCCEEDED(hr))
   // Create a voice.
   hr = cpVoice.CoCreateInstance(CLSID_SpVoice);

if (SUCCEEDED(hr))
   // Associate the voice with the context
   // (with same audio format as context).
   hr = cpRecoContext->SetVoice(cpVoice, TRUE);

if (SUCCEEDED(hr))
   // Tell the associated Voice to stop speaking when
   // the SR Engine hears a recognizable sound.
   hr = cpRecoContext->SetVoicePurgeEvent(SPFEI(SPEI_SOUND_START));

if (SUCCEEDED(hr))
   // Do stuff here.