IAudioEndpointVolume interface (endpointvolume.h)
The IAudioEndpointVolume interface represents the volume controls on the audio stream to or from an audio endpoint device. A client obtains a reference to the IAudioEndpointVolume interface of an endpoint device by calling the IMMDevice::Activate method with parameter iid set to REFIID IID_IAudioEndpointVolume.
Audio applications that use the MMDevice API and WASAPI typically use the ISimpleAudioVolume interface to manage stream volume levels on a per-session basis. In rare cases, a specialized audio application might require the use of the IAudioEndpointVolume interface to control the master volume level of an audio endpoint device. A client of IAudioEndpointVolume must take care to avoid the potentially disruptive effects on other audio applications of altering the master volume levels of audio endpoint devices. Typically, the user has exclusive control over the master volume levels through the Windows volume-control program, Sndvol.exe.
If the adapter device that streams audio data to or from the endpoint device has hardware volume and mute controls, the IAudioEndpointVolume interface uses those controls to manage the volume and mute settings of the audio stream. If the audio device lacks a hardware volume control for the stream, the audio engine automatically implements volume and mute controls in software.
For applications that manage shared-mode streams to and from endpoint devices, the behavior of the IAudioEndpointVolume is different for rendering streams and capture streams.
For a shared-mode rendering stream, the endpoint volume control that the client accesses through the IAudioEndpointVolume interface operates independently of the per-session volume controls that the ISimpleAudioVolume and IChannelAudioVolume interfaces implement. Thus, the volume level of the rendering stream results from the combined effects of the endpoint volume control and per-session controls.
For a shared-mode capture stream, the per-session volume controls that the ISimpleAudioVolume and IChannelAudioVolume interfaces implement are tied directly to the endpoint volume control implemented by the IAudioEndpointVolume interface. Changing the per-session volume control through the methods in the ISimpleAudioVolume and IChannelAudioVolume interfaces changes the setting of the IAudioEndpointVolume interface's volume control, and the reverse is also true. The volume levels represented by each of the interfaces correspond to each other as follows:
- For each channel in a stream, IAudioEndpointVolume provides audio-tapered volume levels expressed in decibels (dB), that are mapped to normalized values in the range from 0.0 (minimum volume) to 1.0 (maximum volume). The possible range is dependent on the audio driver. See IAudioEndpointVolume::GetVolumeRange for details.
- The session volume represented by ISimpleAudioVolume::GetMasterVolume is the scalar value ranging from 0.0 to 1.0 that corresponds to the highest volume setting across the various channels. So, for example, if the left channel is set to 0.8, and the right channel is set to 0.4, then ISimpleAudioVolume::GetMasterVolume will return 0.8.
- When the per-channel volume level is controlled through the methods in the IChannelAudioVolume interface, the scalar indicating volume is always relative to the session volume. This means that the channel or channels with the highest volume has a volume of 1.0. Given the example of two channels, set to volumes of 0.8 and 0.4 by IAudioEndpointVolume::SetChannelVolumeLevelScalar, IChannelAudioVolume::GetChannelVolume will indicate volumes of 1.0 and 0.5.
If a device has hardware volume and mute controls, changes made to the device's volume and mute settings through the IAudioEndpointVolume interface affect the volume level in both shared mode and exclusive mode. If a device lacks hardware volume and mute controls, changes made to the software volume and mute controls through the IAudioEndpointVolume interface affect the volume level in shared mode, but not in exclusive mode. In exclusive mode, the client and the device exchange audio data directly, bypassing the software controls. However, the software controls are persistent, and volume changes made while the device operates in exclusive mode take effect when the device switches to shared-mode operation.
To determine whether a device has hardware volume and mute controls, call the IAudioEndpointVolume::QueryHardwareSupport method.
The methods of the IAudioEndpointVolume interface enable the client to express volume levels either in decibels or as normalized, audio-tapered values. In the latter case, a volume level is expressed as a floating-point value in the normalized range from 0.0 (minimum volume) to 1.0 (maximum volume). Within this range, the relationship of the normalized volume level to the attenuation of signal amplitude is described by a nonlinear, audio-tapered curve. For more information about audio-tapered curves, see Audio-Tapered Volume Controls.
In addition, to conveniently support volume sliders in user interfaces, the IAudioEndpointVolume interface enables clients to set and get volume levels that are expressed as discrete values or "steps". The steps are uniformly distributed over a nonlinear, audio-tapered curve. If the range contains n steps, the steps are numbered from 0 to n– 1, where step 0 represents the minimum volume level and step n– 1 represents the maximum.
For a code example that uses the IAudioEndpointVolume interface, see Endpoint Volume Controls.
Inheritance
The IAudioEndpointVolume interface inherits from the IUnknown interface. IAudioEndpointVolume also has these types of members:
Methods
The IAudioEndpointVolume interface has these methods.
| IAudioEndpointVolume::GetChannelCount The GetChannelCount method gets a count of the channels in the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetChannelVolumeLevel The GetChannelVolumeLevel method gets the volume level, in decibels, of the specified channel in the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetChannelVolumeLevelScalar The GetChannelVolumeLevelScalar method gets the normalized, audio-tapered volume level of the specified channel of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetMasterVolumeLevel The GetMasterVolumeLevel method gets the master volume level, in decibels, of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetMasterVolumeLevelScalar The GetMasterVolumeLevelScalar method gets the master volume level of the audio stream that enters or leaves the audio endpoint device. The volume level is expressed as a normalized, audio-tapered value in the range from 0.0 to 1.0. |
| IAudioEndpointVolume::GetMute The GetMute method gets the muting state of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetVolumeRange The GetVolumeRange method gets the volume range, in decibels, of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::GetVolumeStepInfo The GetVolumeStepInfo method gets information about the current step in the volume range. |
| IAudioEndpointVolume::QueryHardwareSupport The QueryHardwareSupport method queries the audio endpoint device for its hardware-supported functions. (IAudioEndpointVolume.QueryHardwareSupport) |
| IAudioEndpointVolume::RegisterControlChangeNotify The RegisterControlChangeNotify method registers a client's notification callback interface. |
| IAudioEndpointVolume::SetChannelVolumeLevel The SetChannelVolumeLevel method sets the volume level, in decibels, of the specified channel of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::SetChannelVolumeLevelScalar The SetChannelVolumeLevelScalar method sets the normalized, audio-tapered volume level of the specified channel in the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::SetMasterVolumeLevel The SetMasterVolumeLevel method sets the master volume level, in decibels, of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::SetMasterVolumeLevelScalar The SetMasterVolumeLevelScalar method sets the master volume level of the audio stream that enters or leaves the audio endpoint device. The volume level is expressed as a normalized, audio-tapered value in the range from 0.0 to 1.0. |
| IAudioEndpointVolume::SetMute The SetMute method sets the muting state of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::UnregisterControlChangeNotify The UnregisterControlChangeNotify method deletes the registration of a client's notification callback interface that the client registered in a previous call to the IAudioEndpointVolume::RegisterControlChangeNotify method. |
| IAudioEndpointVolume::VolumeStepDown The VolumeStepDown method decrements, by one step, the volume level of the audio stream that enters or leaves the audio endpoint device. |
| IAudioEndpointVolume::VolumeStepUp The VolumeStepUp method increments, by one step, the volume level of the audio stream that enters or leaves the audio endpoint device. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | endpointvolume.h |