SoundGet

Retrieves various settings of a sound device (master mute, master volume, etc.)

SoundGet, OutputVar , ComponentType, ControlType, DeviceNumber

Parameters

OutputVar

The name of the output variable in which to store the retrieved setting, which is either a floating point number between 0 and 100 (inclusive) or the word ON or OFF (used only for the control types ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, and BASSBOOST). The variable will be made blank if there was a problem retrieving the setting. The format of the floating point number, such as its decimal places, is determined by SetFormat.

ComponentType

If blank or omitted, it defaults to MASTER. Otherwise, specify one of the following words: MASTER (synonymous with SPEAKERS), DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER, WAVE, AUX, ANALOG, HEADPHONES, or N/A. If the sound device lacks the specified component type, ErrorLevel will indicate the problem.

The component labeled Auxiliary in some mixers might be accessible as ANALOG rather than AUX.

If a device has more than one instance of the component type (two of type LINE, for example), usually the first contains the playback settings and the second contains the recording settings. To access an instance other than the first, append a colon and a number to this parameter. For example, Analog:2 is the second instance of the analog component.

ControlType

If blank or omitted, it defaults to VOLUME. Otherwise, specify one of the following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, EQUALIZER, or the number of a valid control type (see soundcard analysis script). If the specified component type lacks the specified control type, ErrorLevel will indicate the problem.

Note: Sound devices usually support only VOLUME (or VOL) and MUTE, although others may be available depending on Windows and the sound device.

DeviceNumber

If blank or omitted, it defaults to 1 (the first sound device), or on Windows Vista or above, the system's default device for playback. Otherwise, specify a number between 1 and the total number of supported devices. This parameter can be an expression. The soundcard analysis script may help determine which number to use.

Error Handling

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

ErrorLevel is set to 0 if the command succeeded. Otherwise, it is set to one of the following phrases:

Remarks

[v1.1.10+]: This command supports Windows Vista and later.

To discover the capabilities of the sound devices (mixers) installed on the system -- such as the available component types and control types -- run the soundcard analysis script.

For more functionality and finer grained control over audio, consider using the VA library.

Use SoundSet to change a setting.

SoundSet, SoundGetWaveVolume, SoundSetWaveVolume, SoundPlay

Examples

Retrieves and reports the master volume.

SoundGet, master_volume
MsgBox, Master volume is %master_volume% percent.

Retrieves and reports the master mute setting.

SoundGet, master_mute,, Mute
MsgBox, Master mute is currently %master_mute%.

Retrieves and reports the master bass level if possible, otherwise an error message is displayed.

SoundGet, bass_level, Master, Bass
if ErrorLevel
    MsgBox, Error description: %ErrorLevel%
else
    MsgBox, The BASS level for MASTER is %bass_level% percent.

Retrieves the microphone mute setting. If the microphone is not muted, a message box is displayed.

SoundGet, microphone_mute, Microphone, Mute
if (microphone_mute = "Off")
    MsgBox, The microphone is not muted.