# Sound 函数

适用于:

- SoundGetVolume / SoundSetVolume
- SoundGetMute / SoundSetMute
- SoundGetName
- SoundGetInterface

其他声音相关的函数:

- SoundBeep
- SoundPlay

## 终端设备

SoundGet 和 SoundSet 函数引用的 "devices" 是 音频终端设备. 单个设备驱动程序或物理设备通常具有多个终端, 例如用于不同类型的输出或输入. 例如:

名称 | 描述
--- | ---
扬声器(例如 HD Audio) | 此设备的主模拟输出(在环绕声的情况下使用多个插孔).
数字输出(例如 HD Audio) | 光纤或同轴数字输出.
麦克风(例如 HD Audio) | 通过麦克风插孔捕获音频.
立体声混音(例如 HD Audio) | 捕获任何输出到扬声器终端的音频.

设备名称通常由终端名称(如 "Speakers") 和括号中的音频驱动程序名称组成. 脚本可以使用全名, 也可以仅使用名称的开头, 如 "Mic" 或 "Microphone". 音频驱动程序具有固定名称, 但是管理员可以随时通过声音控制面板更改终端名称.

声音控制面板列出了设备, 从命令行运行 `mmsys.cpl`, 或通过运行对话框(`Win`+`R`) 或 Run 函数可以打开该面板. 默认情况下, 控制面板只列出启用和插入的设备(如果合适), 但这可以通过右键菜单进行更改. AutoHotkey 检测没有插入的设备, 但不检测禁用的设备.

## 组件

组件显示在声音设备属性对话框的级别选项卡上.

在本例中, 主控制位于顶部, 其次是前四个组件: Microphone, FrontMic, Line In 和 Side. 所有的控制都有音量和静音控制, 除了第四个组件, 它只有音量.

声音设备的属性对话框可以通过声音控制面板打开.

音频驱动程序能够显示其他控制, 如低音和高音. 但是, 常见的音频驱动程序往往只具有音量和静音控制, 或者根本没有组件. 音量和静音控制是通过 SoundGetVolume, SoundSetVolume, SoundGetMute 和 SoundSetMute 直接支持的. 所有其他控制仅通过 SoundGetInterface 和 ComCall 间接支持.

### 详细信息

组件可以通过 DeviceTopology API 发现, 该 API 公开 Connectors 和 Subunits 的图表. 上面显示的每个组件都有一个连接器, 而连接器定义了组件的名称. 每个控制(例如音量或静音) 由位于连接器和终端之间的子单元表示. 数据从连接器 "流出" 或流入, 并随着流过每个子单元而改变, 例如调节音量或抑制(静音) 所有声音.

SoundGet 和 SoundSet 函数通过遍历 device topology 图并计算具有给定名称的连接器(或所有未指定名称的连接器) 来标识组件. 一旦找到匹配的连接器, 就可以从最近的连接器开始通过查询图形的该特定分支上的每个子单元来检索控制接口(例如 IAudioVolumeLevel 或 IAudioMute).

应用于多个连接器的子单元被排除在外 - 例如与主音量和静音控制对应的子单元. 如果连接器至少有一个自己的子单元, 即使该子单元不是所请求的类型, 该连接器也会被计数.

实际上, 最终结果的可用的组件和级别选项卡中列出的是一样的, 并且它们的顺序是相同的. 但是, 这个过程是基于观察, 反复尝试的, 所以可能不是 100% 的准确.

## 通用参数

Component

  类型: 字符串或整数

  以下之一:

  - component 的索引, 其中 1 是第一个组件.
  - 组件的完整显示名称(不区分大小写).
  - 如上, 但后跟冒号和整数, 其中 1 是第一个使用该名称的组件. 例如, `"Line In:2"` 是名称为 "Line In" 的第二个组件. 仅当 Component 可能导致歧义时, 例如多个组件具有相同的名称, 或显示名称为空, 为整数或包含冒号时, 才需要这样做.
  - 如果省略或为空, 则该函数以主音量/静音控制或由 IMMDevice::Activate 返回的接口为目标.

  如果只指定索引, 则忽略显示名称. 例如, `1`, `"1"` 和 `":1"` 使用第一个组件, 而不管名称如何, 而 `""` 使用主控制.

  如果声音设备缺少指定的 Component, 则抛出 TargetError.

Device

  类型: 字符串或整数

  以下之一:

  - 介于 1 和支持的设备总数之间的数字(整数).
  - 设备的显示名称; 全名或开头部分(不区分大小写). 例如, `"Speakers"` 或 `"Speakers (Example HD Audio)"`.
  - 如上, 但后跟冒号和整数, 其中 1 是具有匹配名称的第一个设备. 例如, `"Speakers:2"` 表示名称为 "Speakers" 的第二个设备. 仅当 Device 可能导致歧义时, 例如多个组件具有相同的名称, 或包含冒号时, 才需要这样做.
  - 如果省略或为空, 则默认为系统的默认播放设备(不一定是设备 1).

  声卡分析脚本可以帮助确定要使用的名称和/或编号.

## 示例

声卡分析. 使用以下脚本发现可用的音频设备和组件名称, 以及每个设备或组件是否支持音量和/或静音控件. 它在一个简单的 ListView 中显示结果. 如果可以检索当前音量和静音设置, 则会显示它们, 但不会实时更新.

    scGui := Gui(, "Sound Components")
    scLV := scGui.Add('ListView', "w600 h400"
        , ["Component", "#", "Device", "Volume", "Mute"])

    devMap := Map()

    loop
    {
        ; 对于每一次循环迭代, 尝试获取相应的设备.
        try
            devName := SoundGetName(, dev := A_Index)
        catch  ; 没有更多的设备.
            break

        ; 如果需要, 使用 ":index" 来限定名称.
        devName := Qualify(devName, devMap, dev)

        ; 如有可能, 获取主音量和静音设置.
        vol := mute := ""
        try vol := Round(SoundGetVolume( , dev), 2)
        try mute := SoundGetMute( , dev)

        ; 仅在至少检索到一项时显示主设置.
        if vol != "" || mute != ""
            scLV.Add("", "", dev, devName, vol, mute)

        ; 对于每个组件, 首先查询其名称.
        cmpMap := Map()

        loop
        {
            try
                cmpName := SoundGetName(cmp := A_Index, dev)
            catch
                break
            ; 如有可能, 检索该组件的音量和静音设置.
            vol := mute := ""
            try vol := Round(SoundGetVolume(cmp, dev), 2)
            try mute := SoundGetMute(cmp, dev)
            ; 显示此组件, 即使它不支持音量或静音,
            ; 因为它可能通过 SoundGetInterface() 支持其他控制.
            scLV.Add("", Qualify(cmpName, cmpMap, A_Index), dev, devName, vol, mute)
        }
    }

    loop 5
        scLV.ModifyCol(A_Index, 'AutoHdr Logical')
    scGui.Show()

    ; 如果需要, 使用 ":index" 来限定名称.
    Qualify(name, names, overallIndex)
    {
        if name = ''
            return overallIndex
        key := StrLower(name)
        index := names.Has(key) ? ++names[key] : (names[key] := 1)
        return (index > 1 || InStr(name, ':') || IsInteger(name)) ? name ':' index : name
    }

dftg