IAudioEndpointVolume Interface
| Previous | Next |
IAudioEndpointVolume Interface
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. However, clients of the EndpointVolume API should not rely on this behavior because it might change in future releases.
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.
IAudioEndpointVolume inherits from the IUnknown interface. In addition to the methods inherited from IUnknown, IAudioEndpointVolume supports the following methods.
| Method | Description |
| GetChannelCount | Gets a count of the channels in the audio stream. |
| GetChannelVolumeLevel | Gets the volume level, in decibels, of the specified channel in the audio stream. |
| GetChannelVolumeLevelScalar | Gets the normalized, audio-tapered volume level of the specified channel of the audio stream. |
| GetMasterVolumeLevel | Gets the master volume level of the audio stream, in decibels. |
| GetMasterVolumeLevelScalar | Gets the master volume level, expressed as a normalized, audio-tapered value. |
| GetMute | Gets the muting state of the audio stream. |
| GetVolumeRange | Gets the volume range of the audio stream, in decibels. |
| GetVolumeStepInfo | Gets information about the current step in the volume range. |
| QueryHardwareSupport | Queries the audio endpoint device for its hardware-supported functions. |
| RegisterControlChangeNotify | Registers a client's notification callback interface. |
| SetChannelVolumeLevel | Sets the volume level, in decibels, of the specified channel of the audio stream. |
| SetChannelVolumeLevelScalar | Sets the normalized, audio-tapered volume level of the specified channel in the audio stream. |
| SetMasterVolumeLevel | Sets the master volume level of the audio stream, in decibels. |
| SetMasterVolumeLevelScalar | Sets the master volume level, expressed as a normalized, audio-tapered value. |
| SetMute | Sets the muting state of the audio stream. |
| UnregisterControlChangeNotify | Deletes the registration of a client's notification callback interface. |
| VolumeStepDown | Decreases the volume level by one step. |
| VolumeStepUp | Increases the volume level by one step. |
Requirements
Client: Windows Vista
Header: Include Endpointvolume.h.
See Also
| Previous | Next |