# Vista Audio Control Function Reference (version 2.0)

#### Master Controls

- VA_GetMasterVolume
- VA_SetMasterVolume
- VA_GetMasterChannelCount
- VA_GetMasterMute
- VA_SetMasterMute

#### Subunit Controls

- VA_GetVolume
- VA_SetVolume
- VA_GetChannelCount
- VA_GetMute
- VA_SetMute

#### Advanced

- VA_GetAudioEndpointVolume
- VA_GetAudioMeter
- VA_GetDevice
- VA_GetDeviceName
- VA_GetDevicePeriod
- VA_GetDeviceSubunit
- VA_EnumSubunits
- VA_EnumSubunitsEx
- VA_FindSubunit
- VA_dB2Scalar
- VA_Scalar2dB

#### Other

- Interface Functions

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

    COM_Init()

    ; 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

    COM_Init()
    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

    COM_Init()
    ; 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 `COM_Release(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 `COM_Release(pointer)` to release the interface pointer when it is no longer needed.

#### Example

    #SingleInstance, Force
    MeterLength = 30
    COM_Init()

    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 `COM_Release(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_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.

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

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

Copyright © Lexikos