SoundSetVolume

Changes a volume setting of a sound device.

SoundSetVolume NewSetting , Component, Device

Parameters

NewSetting

Type: Number or String

Percentage number between -100 and 100 inclusive (it can be a floating point number). If the number begins with a plus or minus sign, the current setting will be adjusted up or down by the indicated amount. Otherwise, the setting will be set explicitly to the level indicated by NewSetting.

Component

Type: String or Integer

The component's display name and/or index. For example, 1, "Line in" or "Line in:2".

If omitted or blank, the master volume setting is changed.

For further details, see Component (Sound Functions).

Device

Type: String or Integer

The device's display name and/or index. For example, 1, "Speakers", "Speakers:2" or "Speakers (Example HD Audio)".

If this parameter is omitted, it defaults to the system's default device for playback (which is not necessarily device 1).

For further details, see Device (Sound Functions).

Error Handling

An exception is thrown on failure. The exception's Message property may contain one of the following:

Remarks

An alternative way to adjust the volume is to have the script send volume-control keystrokes to change the master volume for the entire system, such as in the example below:

Send "{Volume_Up}"  ; Raise the master volume by 1 interval (typically 5%).
Send "{Volume_Down 3}"  ; Lower the master volume by 3 intervals.

To discover the capabilities of the sound devices installed on the system -- such as the names and available components -- run the soundcard analysis script.

SoundSetVolume attempts to preserve the existing balance when changing the volume level.

Use SoundGetVolume to retrieve the current volume setting.

Related

Sound Functions

Examples

#1: Basic examples

SoundSetVolume 50  ; Set the master volume to 50%
SoundSetVolume "+10"  ; Increase master volume by 10%
SoundSetVolume -10  ; Decrease master volume by 10%
SoundSetVolume "+20", , "Microphone"  ; Increase microphone recording volume by 20%