Edit

IAudioSessionControl2::SetDuckingPreference method (audiopolicy.h)

  • Article

The SetDuckingPreference method enables or disables the default stream attenuation experience (auto-ducking) provided by the system.

Syntax

HRESULT SetDuckingPreference(
  [in] BOOL optOut
);

Parameters

[in] optOut

A BOOL variable that enables or disables system auto-ducking.

Return value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return value Description
AUDCLNT_E_DEVICE_INVALIDATED
 The audio session is disconnected on the default audio device.

Remarks

By default, the system adjusts the volume for all currently playing sounds when the system starts a communication session and receives a new communication stream on the default communication device. For more information about this feature, see Using a Communication Device.

If the application passes TRUE in optOut, the system disables the Default Ducking Experience. For more information, see Disabling the Default Ducking Experience.

To provide a custom implementation, the application needs to get notifications from the system when it opens or closes the communication stream. To receive the notifications, the application must call this method before registering itself by calling IAudioSessionManager2::RegisterForDuckNotification. For more information and example code, see Getting Ducking Events.

If the application passes FALSE in optOut, the application provides the default stream attenuation experience provided by the system.

We recommend that the application call SetDuckingPreference during stream creation. However, this method can be called dynamically during the session to change the initial preference.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps only]
Minimum supported server Windows Server 2008 R2 [desktop apps only]
Target Platform Windows
Header audiopolicy.h

See also

IAudioSessionControl2