ISpVoice::SetOutput (SAPI 5.3)

Microsoft Speech API 5.3

ISpVoice::SetOutput

ISpVoice::SetOutput sets the current output object.  The object may either be a stream, audio device, or an object token for an output audio device.  If pUnkOutput is NULL the default audio device will be used.

  
    HRESULT SetOutput(IUnknown   *pUnkOutput,
   BOOL        fAllowFormatChanges
);

Parameters

• pUnkOutput
  [in] IUnknown pointer to output object. The pointer must point to an object that implements ISpStreamFormat (a stream or audio device), or an object that implements ISpObjectToken. If a token is provided, this method will create the object described by the token and use it. If pUnkOutput is NULL, the default audio out device will be used.
• fAllowFormatChanges
  [in] Flag specifying whether the voice is allowed to change the format of the audio output object to match that of the engine, or a wav stream being spoken. If FALSE, the voice will use the SAPI format converter to translate between the data being rendered and the format of the output object. This should be set to TRUE if using the default audio device and the output format is of no consequence. If pUnkOutput is an ISpStreamFormat object, fAllowFormatChanges is ignored. In this case, the voice instance will render the output audio data in the format of the specified stream to the application.

Return values

Value

S_OK

E_INVALIDARG

SPERR_UNINITIALIZED

E_OUTOFMEMORY

Example:

The following is an example of how to enumerate all the available audio output devices registered under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Speech\AudioOutput.

  
// Declare local identifiers:
HRESULT                        hr = S_OK;
CComPtr<ISpObjectToken>        cpAudioOutToken;
CComPtr<IEnumSpObjectTokens>   cpEnum;
CComPtr<ISpVoice>              cpVoice;
ULONG                          ulCount = 0;

// Create the SAPI voice.
hr = cpVoice.CoCreateInstance(CLSID_SpVoice);

if (SUCCEEDED (hr))
{
   // Enumerate the available audio output devices.
   hr = SpEnumTokens( SPCAT_AUDIOOUT, NULL, NULL, &cpEnum; );
}

if (SUCCEEDED (hr))
{
   // Get the number of audio output devices.
   hr = cpEnum->GetCount( &ulCount; );
}

// Obtain a list of available audio output tokens,
// set the output to the token, and call Speak.
while (SUCCEEDED(hr) && ulCount--)
{
   if (SUCCEEDED (hr))
   {
      hr = cpEnum->Next( 1, &cpAudioOutToken;, NULL );
   }

   if (SUCCEEDED (hr))
   {
      hr = cpVoice->SetOutput( cpAudioOutToken, TRUE );
   }

   if (SUCCEEDED (hr))
   {
      hr = cpVoice->Speak( L"How are you?", SPF_DEFAULT, NULL );
   }
}

if (SUCCEEDED (hr))
{
   // Do more stuff here.
}