SPDUI_AudioVolume (SAPI 5.3)

Article
04/17/2012

Microsoft Speech API 5.3

SPDUI_AudioVolume (C/C++)

SpeechAudioVolume (Automation)

SPDUI_AudioVolume defines the string for displaying an audio object's volume UI.

When to Implement

An application can modify the object's volume settings for a custom audio object. For example, the SAPI implementation in the multimedia audio object displays the Windows Mixer associated with the audio device.

Using Speech properties in Control Panel, select the default audio input and output objects. Click Volume to directly access each audio object's volume UI using SPDUI_AudioVolume. If the audio object does not support the Volume UI (see ISpTokenUI::IsUISupported), Volume will be unavailable.

When to Access

The application accesses the audio object's volume UI if the output is too loud, or the input is too quiet.

Also, an SR engine can send an SPEI_REQUEST_UI event to the application if it determines that the user should perform microphone training. Typically the UI type will be SPDUI_MicTraining to ensure that the SR engine is adapted to the current input audio settings. For example, if the audio input volume is very low, it is preferable to raise the audio input volume, rather than request the SR engine to amplify a poor audio input signal.

SAPI will generally not recognize changes to the Windows Mixer settings. This Mixer is made available solely as a last resort in adjusting the sound system if the Microphone Training wizard fails to set the volume suitably.

  
#define SPDUI_AudioVolume        L"AudioVolume"

Example

The following code snippet illustrates the use of ISpTokenUI::IsUISupported using SPDUI_AudioVolume.

  
// Declare local identifiers:
HRESULT                    hr = S_OK;
CComPtr<ISpObjectToken>    cpObjectToken;
CComPtr<ISpTokenUI>        cpTokenUI;
BOOL                       fSupported;

// Get the default input audio object token.
hr = SpGetDefaultTokenFromCategoryId(SPCAT_AUDIOIN, &cpObjectToken;);

if (SUCCEEDED(hr))
{
   // Get the object token's UI.
   hr = cpObjectToken->QueryInterface(&cpTokenUI;);
}

// Check if the default audio input object has UI for Volume.
hr = cpTokenUI->IsUISupported(SPDUI_AudioVolume, NULL, NULL, NULL, &fSupported;);

if (SUCCEEDED(hr))
{
   // If fSupported = TRUE, then default audio
   // input object has UI for Volume.
}

Share via