EN
Данное содержимое не доступно на вашем языке, используйте версию на английском языке.

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. 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.

Note  Clients of the EndpointVolume API should not rely on the preceding 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.

Members

The IAudioEndpointVolume interface inherits from the IUnknown interface. IAudioEndpointVolume also has these types of members:

Methods

The IAudioEndpointVolume interface has these methods.

MethodDescription
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

Minimum supported client

Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 [desktop apps | Windows Store apps]

Header

Endpointvolume.h

See also

EndpointVolume API
IMMDevice::Activate
ISimpleAudioVolume Interface

 

 

Добавления сообщества

Показ:
© 2014 Microsoft