Vista Audio Control Function Reference (version 2.3)

VA_GetMasterVolume

Gets the master volume level of an audio endpoint device.

VA_GetMasterVolume(channel, device_desc)

Parameters

Remarks

Volume levels returned by this function follow the same curve as the Windows Vista Sound Mixer.

Example

; Get the master volume of the default playback device.
volume := VA_GetMasterVolume()

; Get the volume of the first and second channels.
volume1 := VA_GetMasterVolume(1)
volume2 := VA_GetMasterVolume(2)

; Get the master volume of a device by name.
lineout_volume := VA_GetMasterVolume("", "Line Out")

; Get the master volume of the default recording device.
recording_volume := VA_GetMasterVolume("", "capture")

MsgBox, % "Playback volume:`t" volume
        . "`n  Channel 1:`t" volume1
        . "`n  Channel 2:`t" volume2
        . "`nLine Out volume:`t" lineout_volume
        . "`nRecording volume:`t" recording_volume
        

VA_SetMasterVolume

Sets the master volume level of an audio endpoint device.

VA_SetMasterVolume(vol, channel, device_desc)

Parameters

Remarks

Volume levels set by this function follow the same curve as the Windows Vista Sound Mixer.

VA_GetMasterChannelCount

Gets the number of channels an audio endpoint device has.

VA_GetMasterChannelCount(device_desc)

Parameters

Example

Loop % VA_GetMasterChannelCount()
    Message .= "Channel " A_Index ": " VA_GetMasterVolume(A_Index) "`n"
MsgBox %Message%

VA_GetMasterMute

Gets the mute status of an audio endpoint device.

VA_GetMasterMute(device_desc)

Parameters

VA_SetMasterMute

Mutes or un-mutes an audio endpoint device.

VA_SetMasterMute(mute, device_desc)

Parameters

VA_GetVolume

Gets the volume level of a subunit.

VA_GetVolume(subunit_desc, channel, device_desc)

Parameters

Remarks

Volume levels returned by this function follow the same curve as the Sound applet in Control Panel, not the Sound Mixer.

Example

; Note that subunit names are audio driver-specific.
; The following will match "Line", "Line In", "Line Volume", etc.
linein_feedback := VA_GetVolume("Line")
mic_feedback := VA_GetVolume("Mic", "", "Line Out")
MsgBox, % "Line In feedback through default playback device: " linein_feedback
        . "`nMicrophone feedback through Line Out: " mic_feedback
        . "`n(Note: these may be muted.)"

VA_SetVolume

Sets the volume level of a subunit.

VA_SetVolume(vol, subunit_desc, channel, device_desc)

Parameters

Remarks

Volume levels set by this function follow the same curve as the Sound applet in Control Panel, not the Sound Mixer.

VA_GetChannelCount

Gets the number of channels a subunit has.

VA_GetChannelCount(subunit_desc, device_desc)

Parameters

VA_GetMute

Gets the mute status of a subunit.

VA_GetMute(subunit_desc, device_desc)

Parameters

VA_SetMute

Mutes or un-mutes a subunit.

VA_SetMute(mute, subunit_desc, device_desc)

Parameters

VA_GetAudioEndpointVolume

Gets a pointer to the IAudioEndpointVolume interface of an audio endpoint device.

VA_GetAudioEndpointVolume(device_desc)

Parameters

Remarks

Use ObjRelease(pointer) to release the interface pointer when it is no longer needed.

VA_GetAudioMeter

Gets a pointer to the IAudioMeterInformation interface of an audio endpoint device.

VA_GetAudioMeter(device_desc)

Parameters

Remarks

Use ObjRelease(pointer) to release the interface pointer when it is no longer needed.

Example

#SingleInstance, Force
MeterLength = 30

audioMeter := VA_GetAudioMeter()

VA_IAudioMeterInformation_GetMeteringChannelCount(audioMeter, channelCount)

; "The peak value for each channel is recorded over one device
;  period and made available during the subsequent device period."
VA_GetDevicePeriod("capture", devicePeriod)

Loop
{
    ; Get the peak value across all channels.
    VA_IAudioMeterInformation_GetPeakValue(audioMeter, peakValue)    
    meter := MakeMeter(peakValue, MeterLength)
    
    ; Get the peak values of all channels.
    VarSetCapacity(peakValues, channelCount*4)
    VA_IAudioMeterInformation_GetChannelsPeakValues(audioMeter, channelCount, &peakValues)
    Loop %channelCount%
        meter .= "`n" MakeMeter(NumGet(peakValues, A_Index*4-4, "float"), MeterLength)

    ToolTip, %meter%
    Sleep, %devicePeriod%
}

MakeMeter(fraction, size)
{
    global MeterLength
    Loop % fraction*size
        meter .= "|"
    Loop % (1-fraction)*size
        meter .= "."
    meter .= "  " fraction
    return meter
}

VA_GetDevice

Gets a pointer to the IMMDevice interface of an audio endpoint device.

VA_GetDevice(device_desc)

Parameters

Remarks

Use ObjRelease(device) to release the interface pointer when it is no longer needed.

If device_desc is a device pointer returned by a previous call to VA_GetDevice, it is returned as-is. This behaviour is useful for other functions which accept a device_desc; these functions call VA_GetDevice internally.

Examples

device := VA_GetDevice("playback")      ; default playback device
device := VA_GetDevice("playback:1")    ; first playback device
device := VA_GetDevice("nvidia:2")      ; second device whose name contains "nvidia"
device := VA_GetDevice(3)               ; third device

VA_IMMDevice_GetId(device, device_id)   ; get a device id from a device pointer
;...
device := VA_GetDevice(device_id)       ; get a device pointer from an id

VA_GetDeviceName

Gets the friendly name of an audio endpoint device.

VA_GetDeviceName(device)

Parameters

VA_GetDevicePeriod

Retrieves the length of the periodic interval separating successive processing passes by the audio engine.

VA_GetDevicePeriod(device_desc, default_period, minimum_period)

Parameters

VA_GetDeviceSubunit

Finds a subunit of a device, given a device description.

VA_GetDeviceSubunit(device_desc, subunit_desc, subunit_iid)

Parameters

Remarks

See VA_FindSubunit.

VA_EnumSubunits

Enumerates matching subunits of a device.

VA_EnumSubunits(device, callback, target_name, target_iid)

Parameters

Remarks

See VA_EnumSubunitsEx.

VA_EnumSubunitsEx

Enumerates matching subunits of a part (subunit or connector).

VA_EnumSubunitsEx(part, data_flow, callback, target_name, target_iid)

Parameters

Remarks

The callback is called once for each matching subunit. The callback's first parameter is a pointer to the subunit (IPart), while the second parameter is a pointer to the required interface (or 0 if target_iid was omitted.) If the callback returns a non-zero value, enumeration is halted and the value is passed on to the caller.

VA_FindSubunit

Finds a subunit of a device, given a device pointer.

VA_FindSubunit(device, target_desc, target_iid)

Parameters

Remarks

VA_FindSubunit requires a valid interface identifier. To retrieve a subunit by name alone, use VA_EnumSubunits or VA_EnumSubunitsEx.

Sets the default audio endpoint for a given role. Requires v2.3 or later.

VA_SetDefaultEndpoint(device_desc, role)

Parameters

Remarks

This function relies on undocumented interfaces and therefore isn't guaranteed to work.

VA_dB2Scalar

Converts a decibel value to a scalar value.

VA_dB2Scalar(dB, min_dB, max_dB)

Parameters

Remarks

The returned scalar value is usually consistent with values reported by the Sound applet in Control Panel, but not values reported by the Sound Mixer.

VA_Scalar2dB

Converts a scalar value to a decibel value.

VA_Scalar2dB(s, min_dB, max_dB)

Parameters

Interface Functions

Functions with the naming pattern "VA_IInterface_Function" are direct equivalents of interface functions. These functions are defined under INTERFACE WRAPPERS in VA.ahk. For syntax and usage, see Core Audio APIs in Windows Vista (Programming Reference).

VA_IInterface_Function

Remarks

As of v2.0, interface wrappers for the following interfaces are included:

• IMMDevice
• IDeviceTopology
• IConnector
• IPart
• IPartsList
• IAudioEndpointVolume
• IPerChannelDbLevel (usable with IAudioVolumeLevel)
• IAudioMute
• IAudioAutoGainControl
• IAudioMeterInformation

v2.1:

• IAudioClient
• IAudioSessionControl
• IAudioSessionManager

v2.1 on Windows 7 or later:

• IAudioSessionControl2
• IAudioSessionManager2
• IAudioSessionEnumerator

v2.2:

• IMMDeviceEnumerator
• IMMDeviceCollection
• IControlInterface