ISpRecoContext::SetAudioOptions (SAPI 5.3)

Speech API 5.3
Microsoft Speech API 5.3


ISpRecoContext::SetAudioOptions sets the audio options for result objects from this recognition context. This method also enables or disables the retention of audio with result objects and can change the retained audio format.

HRESULT SetAudioOptions(
   SPAUDIOOPTIONS        Options,
   const GUID           *pAudioFormatId,
   const WAVEFORMATEX   *pWaveFormatEx


[in] Flag of type SPAUDIOOPTIONS indicating the option. It must be one of the following:
SPAO_NONEDo not retain audio for results.
SPAO_RETAIN_AUDIORetain audio for all future results.
[in] The audio stream format id [of type GUID]. Usually this value is SPDFID_WaveFormatEx. If this value is NULL, the retained audio format will not be changed. Reset the retained audio format to the SR engine's recognition format by setting this value to GUID_NULL and pWaveFormatEx to NULL. 
[in] The audio stream wave format [of type WAVEFORMATEX]. This is only valid if *pAudioFormatId == SPFID_WaveFormatEx.

Return values

S_OKFunction completed successfully.
E_INVALIDARGOptions is not one of the correct types, or the specified audio format is not valid.
FAILED(hr)Appropriate error message.


If a WAVEFORMATEX-based retained audio format is specified, but the SR engine and the audio input stream agree on a non-WAVEFORMATEX-based audio input format (e.g., custom audio object/format), ISpRecoContext::SetAudioOptions will return successfully, but will not retain the audio.

By default, SAPI does not retain recognition audio.

By default, when an audio format is not specified, the audio will be retained in the same format that the SR engine used to perform the recognition.


The following code snippet illustrates the use of ISpRecoContext::SetAudioOptions.

// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpRecoContext>    cpRecoContext;
CComPtr<ISpStream>         cpSpStream;
CSpStreamFormat            sfRetained;

// Activate retained audio settings with default
// format (that is, SR engine recognition format).
hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, &GUID;_NULL, NULL);

if (SUCCEEDED(hr))
   // Deactivate retained audio settings.
   hr = cpRecoContext->SetAudioOptions(SPAO_NONE, NULL, NULL);

if (SUCCEEDED(hr))
   // Use the stream format helper to fill in the WAVEFORMATEX structure.
   CSpStreamFormat sfRetained(SPSF_24kHz16BitStereo, &hr;);

if (SUCCEEDED(hr))
   // Change the settings to the selected stream format.
   hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, &sfRetained;.FormatId(), sfRetained.WaveFormatExPtr());

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

Development Helpers