SoundSet

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

SoundSet NewSetting , ComponentType, ControlType, DeviceNumber

Command  Example: SoundSet 100
Function Example: SoundSet(100)

Parameters

NewSetting

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.

For ControlTypes with only two possible settings -- namely ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, and BASSBOOST -- any positive number will turn on the setting and a zero will turn it off. However, if the number begins with a plus or minus sign, the setting will be toggled (set to the opposite of its current state).

ComponentType

If omitted or blank, it defaults to the word MASTER. Otherwise, it can be 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 ComponentType, 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 ComponentType (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 omitted or blank, it defaults to VOLUME. Otherwise, it can be 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 ComponentType lacks the specified ControlType, 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

A number between 1 and the total number of supported devices. If this parameter is omitted, it defaults to 1 (the first sound device), or on Windows Vista or above, the system's default device for playback. The soundcard analysis script may help determine which number to use.

ErrorLevel

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

• Invalid Control Type or Component Type
• Can't Open Specified Mixer
• Mixer Doesn't Support This Component Type
• Mixer Doesn't Have That Many of That Component Type
• Component Doesn't Support This Control Type
• Can't Get Current Setting
• Can't Change Setting

Remarks

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

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.
Send {Volume_Mute}  ; Mute/unmute the master volume.

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.

Windows 2000/XP/2003: When SoundSet changes the volume of a component, all of that component's channels (e.g. left and right) are set to the same level. In other words, any off-center "balance" that may have been set previously is lost.

Windows Vista and later: SoundSet attempts to preserve the existing balance when changing the volume level.

Use SoundGet to retrieve the current value of a setting.

Related

SoundGet, SoundPlay

Examples

; BASIC EXAMPLES:
SoundSet, 50  ; Set the master volume to 50%
SoundSet +10  ; Increase master volume by 10%
SoundSet -10  ; Decrease master volume by 10%
SoundSet, 1, Microphone, mute  ; mute the microphone
SoundSet, +1, , mute  ; Toggle the master mute (set it to the opposite state)
SoundSet, +20, Master, bass  ; Increase bass level by 20%.
if ErrorLevel
    MsgBox, The BASS setting is not supported for MASTER.

Soundcard Analysis

Use the following script to discover your soundcard's capabilities (component types and control types). It displays the results in a simple ListView. Alternatively, a script for Windows Vista and later which provides more detail (such as display names of devices) can be downloaded from the following forum topic: http://www.autohotkey.com/board/topic/90877-/

; Most of the pure numbers below probably don't exist in any mixer, but they're queried for completeness.
; The numbers correspond to the following items (in order): CUSTOM, BOOLEANMETER, SIGNEDMETER, PEAKMETER,
; UNSIGNEDMETER, BOOLEAN, BUTTON, DECIBELS, SIGNED, UNSIGNED, PERCENT, SLIDER, FADER, SINGLESELECT, MUX,
; MULTIPLESELECT, MIXER, MICROTIME, MILLITIME
ControlTypes := "VOLUME,ONOFF,MUTE,MONO,LOUDNESS,STEREOENH,BASSBOOST,PAN,QSOUNDPAN,BASS,TREBLE,EQUALIZER,0x00000000,0x10010000,0x10020000,0x10020001,0x10030000,0x20010000,0x21010000,0x30040000,0x30020000,0x30030000,0x30050000,0x40020000,0x50030000,0x70010000,0x70010001,0x71010000,0x71010001,0x60030000,0x61030000"

ComponentTypes := "MASTER,HEADPHONES,DIGITAL,LINE,MICROPHONE,SYNTH,CD,TELEPHONE,PCSPEAKER,WAVE,AUX,ANALOG,N/A"

; Create a ListView and prepare for the main loop:
Gui := GuiCreate()
InfoText := Gui.Add("Text", "w400 h400", "Gathering Soundcard Info...")
LV := Gui.Add("ListView", "wp hp xp yp", "Component Type|Control Type|Setting|Mixer")
LV.Visible := false
LV.ModifyCol(4, "Integer")
Gui.Show()

Loop  ; For each mixer number that exists in the system, query its capabilities.
{
  CurrMixer := A_Index
  Setting := SoundGet(,, CurrMixer)
  if ErrorLevel = "Can't Open Specified Mixer"  ; Any error other than this indicates that the mixer exists.
    break
  ; For each component type that exists in this mixer, query its instances and control types:
  For i, CurrComponent in StrSplit(ComponentTypes, ",")
  {
    ; First check if this component type even exists in the mixer:
    Setting := SoundGet(CurrComponent,, CurrMixer)
    if ErrorLevel = "Mixer Doesn't Support This Component Type"
      continue  ; Start a new iteration to move on to the next component type.
    Loop  ; For each instance of this component type, query its control types.
    {
      CurrInstance := A_Index
      ; First check if this instance of this instance even exists in the mixer:
      Setting := SoundGet(CurrComponent ":" CurrInstance,, CurrMixer)
      ; Checking for both of the following errors allows this script to run on older versions:
      if ErrorLevel = "Mixer Doesn't Have That Many of That Component Type"
      || ErrorLevel = "Invalid Control Type or Component Type"
        break  ; No more instances of this component type.
      ; Get the current setting of each control type that exists in this instance of this component:
      For i, CurrControl in StrSplit(ControlTypes, ",")
      {
        Setting := SoundGet(CurrComponent ":" CurrInstance, CurrControl, CurrMixer)
        ; Checking for both of the following errors allows this script to run on older versions:
        if ErrorLevel = "Component Doesn't Support This Control Type"
        || ErrorLevel = "Invalid Control Type or Component Type"
          continue
        if ErrorLevel  ; Some other error, which is unexpected so show it in the results.
          Setting := ErrorLevel
        ComponentString := CurrComponent
        if CurrInstance > 1
          ComponentString .= ":" CurrInstance
        if Setting is "float"
          Setting := Format("{:0.2f}", Setting)  ; Limit number of decimal places in percentages to two.
        LV.Add(, ComponentString, CurrControl, Setting, CurrMixer)
      }  ; For each control type.
    }  ; For each component instance.
  }  ; For each component type.
}  ; For each mixer.

Loop(LV.GetCount("Col"))  ; Auto-size each column to fit its contents.
    LV.ModifyCol(A_Index, "AutoHdr")

InfoText.Visible := false
LV.Visible := true
return