ISpRecoContext::SetAudioOptions

Article
06/30/2006

This method 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.

By default, SAPI does not retain recognition audio. When an audio format is not specified, the audio will be retained in the same format as the SR engine used to perform the recognition.

This method returns successfully, but does not retain the audio, if the application specifies a WAVEFORMATEX-based retained audio format but the SR engine and the audio input stream agree on a non-WAVEFORMATEX-based audio input format (for example, custom audio object/format).

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

Parameters

Options
[in] The audio option to set. Possible values are defined for the SPAUDIOOPTIONS enumeration.
pAudioFormatId
[in] Pointer to the audio stream format identifier (type GUID). Usually this value is SPDFID_WaveFormatEx. If this value is NULL, the retained audio format will not be changed. The application can reset the retained audio format to the SR engine recognition format by setting this value to GUID_NULL and pWaveFormatEx to NULL.
pWaveFormatEx
[in] Pointer to a WAVEFORMATEX structure defining the audio stream wave format. This value is only valid if pAudioFormatId is set to SPFID_WaveFormatEx.

Return Values

The following table shows the possible 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

A related enumeration is SPSTREAMFORMAT, which defines SAPI-supported stream formats. A related class is CspStreamFormat, which manages SAPI-supported stream formats and WAVEFORMATEX structures.

Example

The following code snippet illustrates the use of this method.

HRESULT hr = S_OK;
// start retained audio settings with default format (such as SR engine
recognition format)
hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO, NULL, NULL);
// Check hr
// deactivate retained audio settings
hr = cpRecoContext->SetAudioOptions(SPAO_NONE, NULL, NULL);
// Check hr
// change the retained audio format to 11 kHz, 16-bit Stereo
// use the stream format helper to fill the WAVEFORMATEX structure
CSpStreamFormat sfRetained(SPSF_24kHz16BitStereo, &hr);
// Check hr
// change the settings to the selected stream format
hr = cpRecoContext->SetAudioOptions(SPAO_RETAIN_AUDIO,
&sfRetained.FormatId(), sfRetained.WaveFormatExPtr());
// Check hr

Requirements

OS Versions: Windows CE .NET 4.1 and later.
Header: Sapi.h, Sapi.idl.
Link Library: Sapilib.lib.

Share via