IAudioSessionManager2::RegisterDuckNotification method (audiopolicy.h)

Article
10/05/2021

The RegisterDuckNotification method registers the application with the session manager to receive ducking notifications.

Syntax

HRESULT RegisterDuckNotification(
  LPCWSTR                      sessionID,
  IAudioVolumeDuckNotification *duckNotification
);

Parameters

sessionID

Pointer to a null-terminated string that contains a session instance identifier. Applications that are playing a media stream and want to provide custom stream attenuation or ducking behavior, pass their own session instance identifier. For more information, see Remarks.

Other applications that do not want to alter their streams but want to get all the ducking notifications must pass NULL.

duckNotification

Pointer to the application's implementation of the IAudioVolumeDuckNotification interface. The implementation is called when ducking events are raised by the audio system and notifications are sent to the registered applications.

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
E_POINTER	duckNotification is NULL.
E_OUTOFMEMORY	Internal object could not be created due to insufficient memory.

Remarks

Stream Attenuation or ducking is a new feature in Windows 7. An application playing a media stream can make the stream behave differently when a new communication stream is opened on the default communication device. For example, the original media stream can be paused while the new communication stream is open. To provide this custom implementation for stream attenuation, the application can opt out of the default stream attenuation experience by calling IAudioSessionControl::SetDuckingPreference and then register itself to receive notifications when session events occur. For stream attenuation, a session event is raised by the system when a communication stream is opened or closed on the default communication device. For more information about this feature, see Getting Ducking Events.

To begin receiving notifications, the application calls the RegisterDuckNotification method to register its IAudioVolumeDuckNotification interface with the session manager. When the application no longer requires notifications, it calls the IAudioSessionManager2::UnregisterDuckNotification method to delete the registration.

The application receives notifications about the ducking events through the methods of the IAudioVolumeDuckNotification interface. The application implements IAudioVolumeDuckNotification. After the registration call has succeeded, the system calls the methods of this interface when session events occur.

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