ISpRecoContext::SetAudioOptions (Microsoft Speech Platform)

Microsoft Speech Platform SDK 11

Microsoft Speech Platform

ISpRecoContext::SetAudioOptions

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
);

Parameters

Options
[in] Flag of type SPAUDIOOPTIONS indicating the option. It must be one of the following:
Value Description
SPAO_NONE Do not retain audio for results.
SPAO_RETAIN_AUDIO Retain audio for all future results.
pAudioFormatId
[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. 
pWaveFormatEx
[in] The audio stream wave format [of type WAVEFORMATEX]. This is only valid if *pAudioFormatId == SPFID_WaveFormatEx.

Return values

Value Description
S_OK Function completed successfully.
E_INVALIDARG Options is not one of the correct types, or the specified audio format is not valid.
FAILED(hr) Appropriate error message.

Remarks

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.

Example

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

Helper Enumerations and Functions Description
SPSTREAMFORMAT SAPI supported stream formats
CSpStreamFormat Class for managing SAPI supported stream formats and WAVEFORMATEX structures