Vista Audio Control Function Reference (version 2.4)

Master Controls

Subunit Controls

Advanced

Other


Browse through the topics in the contents list to the right.

VA_GetMasterVolume

Gets the master volume level of an audio endpoint device.

VA_GetMasterVolume(channel, device_desc)

Parameters

Returns A value between 0.0 and 100.0, inclusive.
channel (optional)The one-based index of the channel to retrieve.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

vol A value between 0.0 and 100.0, inclusive.
channel (optional)The one-based index of the channel to adjust.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

Returns True if the audio endpoint device is muted, otherwise false.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

VA_SetMasterMute

Mutes or un-mutes an audio endpoint device.

VA_SetMasterMute(mute, device_desc)

Parameters

mute True to mute; false to un-mute.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

VA_GetVolume

Gets the volume level of a subunit.

VA_GetVolume(subunit_desc, channel, device_desc)

Parameters

Returns A value between 0.0 and 100.0, inclusive.
subunit_desc (optional)See VA_FindSubunit. Defaults to "1".
channel (optional)The one-based index of the channel to retrieve.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

vol A value between 0.0 and 100.0, inclusive.
subunit_desc (optional)See VA_FindSubunit. Defaults to "1".
channel (optional)The one-based index of the channel to retrieve.
device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

subunit_desc (optional)See VA_FindSubunit. Defaults to "1".
device_desc (optional)See VA_GetDevice. Defaults to "playback".

VA_GetMute

Gets the mute status of a subunit.

VA_GetMute(subunit_desc, device_desc)

Parameters

Returns True if the subunit is muted, otherwise false.
subunit_desc (optional)See VA_FindSubunit. Defaults to "1".
device_desc (optional)See VA_GetDevice. Defaults to "playback".

VA_SetMute

Mutes or un-mutes a subunit.

VA_SetMute(mute, subunit_desc, device_desc)

Parameters

mute True to mute; false to un-mute.
subunit_desc (optional)See VA_FindSubunit. Defaults to "1".
device_desc (optional)See VA_GetDevice. Defaults to "playback".

VA_GetAudioEndpointVolume

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

VA_GetAudioEndpointVolume(device_desc)

Parameters

device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

device_desc (optional)See VA_GetDevice. Defaults to "playback".

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

device_desc device_id | device_number | ( friendly_name | 'playback' | 'capture' ) [ ':' index ]

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

device A pointer to an IMMDevice interface.

VA_GetDeviceList

Gets a list of all devices that match the device_desc.

VA_GetDeviceList(device_desc)

Parameters

Returns An array of device names.
device_desc (optional) See VA_GetDevice.

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

Returns True on success, otherwise false.
device_desc See VA_GetDevice.
default_period (out) The default interval, in milliseconds.
minimum_period (out) The minimum interval, in milliseconds.

VA_GetDeviceSubunit

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

VA_GetDeviceSubunit(device_desc, subunit_desc, subunit_iid)

Parameters

Returns A pointer to the requested interface of a matching subunit, or 0 if none were found.
device_desc See VA_GetDevice.
subunit_desc See VA_FindSubunit (target_desc).
subunit_iid See VA_FindSubunit (target_iid).

Remarks

See VA_FindSubunit.

VA_EnumSubunits

Enumerates matching subunits of a device.

VA_EnumSubunits(device, callback, target_name, target_iid)

Parameters

Returns See VA_EnumSubunitsEx.
device A pointer to an IMMDevice interface.
callback A callback accepting two parameters: part, interface.
target_name (optional)The full or partial friendly name of a subunit or subunits.
target_iid (optional)The ID of an interface which matching subunits must support.

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

Returns See Remarks.
part A pointer to an IPart interface.
data_flow 0 to enumerate incoming parts; 1 to enumerate outgoing parts.
callback A callback accepting two parameters: part, interface.
target_name (optional)The full or partial friendly name of a subunit or subunits.
target_iid (optional)The ID of an interface which matching subunits must support.

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

Returns If a matching subunit is found, the return value is a pointer to the requested interface. Otherwise, the return value is 0.
device A pointer to an IMMDevice interface.
target_desc friendly_name | index | friendly_name:index
target_iid An interface ID.

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

Returns
device_desc See VA_GetDevice.
role One of the following integer values:
0: eConsole - what Windows calls the "Default Device".
1: eMultimedia
2: eCommunications - what Windows calls the "Default Communication Device".

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

Returns A value between 0.0 and 1.0.
dB A decibel value.
min_dB Minimum decibel value.
max_dB Maximum decibel value.

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

Returns A decibel value.
s A value between 0.0 and 1.0.
min_dB Minimum decibel value.
max_dB Maximum decibel value.

VA_CreateAudioEndpointCallback

Registers a callback function for an audio device.

VA_CreateAudioEndpointCallback(callback_func, device_desc)

Parameters

Returns A pointer to an IAudioEndpointVolumeCallback.
callback_func The name of the function to call. Can also be a function object (or a BoundFunc object)
device_desc (optional)See VA_GetDevice.

VA_ReleaseAudioEndpointCallback

Releases a registered callback.

VA_ReleaseAudioEndpointCallback(aev, aev_cb)

Parameters

Returns
aev Pointer to an IAudioEndpointVolume
aev_cb Pointer to an IAudioEndpointVolumeCallback

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:

v2.1:

v2.1 on Windows 7 or later:

v2.2:

Copyright © Lexikos