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 can in specialized audio application require the use of the IAudioEndpointVolume interface to control the hardware master volume level of an audio endpoint device. Currently this interface is only supported on capture devices.

If the adapter device that streams audio data to or from the endpoint device has hardware volume controls, the IAudioEndpointVolume interface uses those controls to manage the volume settings of the audio stream. Currently only usb capture devices expose a hardware volume control.

To determine whether a device has hardware volume and mute controls, call the IAudioEndpointVolume::QueryHardwareSupport Method.

The supported methods of the IAudioEndpointVolume interface enable the client to express volume levels in decibels.

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.

Syntax

interface IAudioEndpointVolume : public IUnknown

Remarks

This section provides example code that uses the IAudioEndpointVolume interface.

#include <EndpointVolume.h>

    HRESULT hr = S_OK

    DWORD hwSupport = 0; 
    float fLevelMinDB = 0;
    float fLevelMaxDB = 0;
    float fIncrementDB = 0;
    float fCurrentDB = 0;
                
    IMMDevice* captureDevice = nullptr;
    IAudioEndpointVolume* endpointVolume = nullptr;

    hr = captureDeviceCollection->Item(i, &captureDevice);
    IF_FAILED_JUMP(hr, no_volume_ctrl);

    // Get the audio endpoint volume interface.
    hr = captureDevice->Activate(__uuidof(IAudioEndpointVolume), CLSCTX_ALL, NULL, (void**)&endpointVolume);
    IF_FAILED_JUMP(hr, no_volume_ctrl);

    // Make sure h/w supports the volume control
    hr = endpointVolume->QueryHardwareSupport(&hwSupport);
    IF_FAILED_JUMP(hr, no_volume_ctrl);

    if (!(hwSupport & ENDPOINT_HARDWARE_SUPPORT_VOLUME))
    {
        goto no_volume_ctrl;
    }

    // Get the min/max/increment-gain info.
    hr = endpointVolume->GetVolumeRange(&fLevelMinDB, &fLevelMaxDB, &fIncrementDB);
    IF_FAILED_JUMP(hr, no_volume_ctrl);
                
    // Get the master volume.
    hr = endpointVolume->GetMasterVolumeLevel(&fCurrentDB);
    IF_FAILED_JUMP(hr, no_volume_ctrl);
                
    DebugPrint(L"%s:   %s: minDB:%f, maxDB:%f, incrementDB:%f, levelDB:%f\n", 
                exe, captureDeviceName[deviceIndex], fLevelMinDB, fLevelMaxDB, fIncrementDB, fCurrentDB);
                
    // If specified, set the new value.
    if (volumeSet)
    {                
        float fNewDB;
        static const GUID guidNULL = {0x00000000,0x0000,0x0000,{0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00} };

        fNewDB = fLevelMinDB + ((fLevelMaxDB - fLevelMinDB) * (volumePercent * 0.01f));
        hr = endpointVolume->SetMasterVolumeLevel(fNewDB, &guidNULL);
        IF_FAILED_JUMP(hr, no_volume_ctrl);
                    
        DebugPrint(L"%s:   %s: old-levelDB:%f, new-levelDB:%f\n", 
                    exe, captureDeviceName[deviceIndex], fCurrentDB, fNewDB);
    }
                
no_volume_ctrl:
    SafeRelease(endpointVolume);
    SafeRelease(captureDevice);

Requirements

Header: Declared in endpointvolume.h.

Library: Use MMDevApi.lib.

See also

IAudioEndpointVolume Members