Windows 音频输出一键切换工具 — 项目笔记与方案

1. 项目概述

一个常驻系统托盘的 Windows 小工具，用于在多个音频输出设备（扬声器、耳机、USB 声卡、蓝牙耳机、HDMI 等）之间一键切换：

• 右键托盘菜单逐个点击切换
• 全局热键按顺序循环切换
• 切换瞬间在屏幕底部中央弹出 OSD 提示（淡入 → 停留 → 淡出）
• 支持设置热键循环白名单：只在一组选定设备间循环
• 单实例运行，重复点击只提示不重复启动

2. 最终功能清单

3. 技术选型与架构

3.1 技术栈

3.2 进程结构（单实例）

Program.Main
├── 命名 Mutex「Local\AudioSwitcher_SingleInstance」
│   ├── 已存在（第二个实例）→ 轻量路径：只建 OSDForm 提示 → Application.Run(osd) → 自动退出
│   └── 新建（首个实例）→ Application.Run(new AudioSwitcherApp())

提示实例不枚举设备、不建托盘、不注册热键，OSD 播完（约 2 秒）即退出，弹窗迅速无卡顿。

3.3 线程模型（核心：UI 线程永不碰慢设备 I/O）

音频设备事件(AudioDeviceChanged)  ──600ms 防抖──►  RefreshDeviceList（async）
托盘右键菜单 Opening                    ────────►  RefreshDeviceList（async）
点击菜单项 / 按下热键 ──► SwitchToDevice：先弹 OSD（用预计算文本）──► Task.Run(SetAsDefault)
                                                    └ 切换在后台线程，完成与否不阻塞 OSD

• 设备枚举（GetPlaybackDevices / 默认设备查询）全部在 Task.Run 后台执行
• 菜单项显示文本（图标+名称）在枚举时预计算缓存，点击瞬间弹 OSD 零设备 I/O
• 蓝牙/HDMI 端点响应慢（数百毫秒～秒级）是主要慢源，全部隔离在线程池里

3.4 OSD 窗体（关键实现）

• 无边框 + SetWindowRgn 圆角（12px）+ 深色背景 #1C1C1E
• 整窗 alpha 由 WS_EX_LAYERED + SetLayeredWindowAttributes 控制，最高 70%（180/255）
• 动画由 Stopwatch 驱动：每帧按真实流逝时间计算 alpha（elapsed / 阶段时长），不依赖 WinForms Timer 精度（实测精度仅 ~15.6ms，负载下更差）
• WS_EX_NOACTIVATE + WS_EX_TOOLWINDOW：不抢焦点、不占任务栏
• 替换旧 OSD 用 Dismiss()：先停动画定时器再 Close()，避免定时器 tick 落到已销毁窗体

3.5 设备刷新防抖与快照

事件 → 600ms 防抖定时器 → 后台枚举 → 菜单未打开？→ 快照比对 → 无变化则跳过重建
                    │                      │
                    └─ 菜单打开中：标记 pending，菜单关闭后补刷

• 快照 = 默认设备 ID + 设备 RealId 有序拼接，绝大多数设备通知被快照挡下
• 菜单打开期间绝不重建（曾导致菜单闪烁、点不中）

4. 项目文件结构

C:\MyProject\windows音频切换\
├── Program.cs          ← 全部代码（主窗体、托盘、热键、OSD、设置对话框、设置模型，约 1350 行）
├── AudioSwitcher.csproj
├── app.manifest        ← asInvoker + DPI 感知
├── 声音.ico            ← exe 与托盘共用图标（从 exe 提取）
└── publish_v2\
    └── AudioSwitcher.exe   ← 当前最新发布版（551 KB）

代码内主要类型

Settings 模型

{
  "HotKey":      { "Control": true, "Shift": true, "Alt": false, "Win": false, "KeyCode": 112 }, // F1
  "AutoStart":   true,                       // 开机自启（HKCU Run）
  "DeviceWhitelist": [ "...RealId...", ... ] // 热键循环白名单；空数组 = 全部设备
}

5. 构建与发布

5.1 关键 csproj 配置

<TargetFramework>net8.0-windows</TargetFramework>
<UseWindowsForms>true</UseWindowsForms>
<ApplicationManifest>app.manifest</ApplicationManifest>
<ApplicationIcon>声音.ico</ApplicationIcon>
<RollForward>LatestMinor</RollForward>   <!-- 目标机装了 .NET 9/10 也能跑 -->

Release 条件：
<SelfContained>false</SelfContained>      <!-- 框架依赖：不带运行时 -->
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<PublishSingleFile>true</PublishSingleFile>
<PublishReadyToRun>true</PublishReadyToRun>
<DebugType>embedded</DebugType>

5.2 发布命令

dotnet publish -c Release -r win-x64 --self-contained false \
  -p:PublishSingleFile=true -p:PublishReadyToRun=true \
  -p:DebugType=embedded -o ./publish_v2

产物：单文件 AudioSwitcher.exe ≈ 551 KB。目标机器需已安装 .NET Desktop Runtime 8；
未安装时 Windows 会弹出官方下载引导（这是框架依赖 exe 的内建行为，无需自研检测）。

5.3 体积演进备忘

6. 使用说明

1. 双击 AudioSwitcher.exe → 托盘出现声音图标（图标即 exe 图标）
2. 切换：右键托盘 → 点设备；或按 Ctrl+Shift+F1 循环到下一个
3. 只看部分设备循环：右键 → 设置热键 → 在「② 热键循环范围」勾选 ≥2 个设备 → 确定
4. 改热键：右键 → 设置热键 → 在「①」直接按下新组合 → 确定
5. 开机自启：右键 → 开机自启（打勾）
6. 退出：右键 → 退出

7. 开发过程问题记录（踩坑笔记）

按时间顺序记录本项目中真实遇到并修复的问题，供后续维护参考。

7.1 编译期（首次 publish 时批量修复）

• NU1701：AudioSwitcher 库是 .NET Framework 包，在 net8.0 下还原为兼容模式 —— 仅为警告，可运行
• MethodInvoker 歧义：System.Windows.Forms 与 System.Reflection 冲突 → 改用 new Action(...)
• GraphicsPath.AddRoundRect 不存在 → 自写圆角路径（4 段弧 + 直线）
• List<Device> ↔ List<CoreAudioDevice> 不兼容；Device 抽象类没有 Name/ID，实际类型用 CoreAudioDevice 的 FullName/RealId
• device.Name 返回 int（枚举值），.Contains 编译错 —— 一切字符串判断改用 device.FullName ?? ""
• CoreAudioController 无 Dispose() —— 去掉即可
• CS0160：ObjectDisposedException 是 InvalidOperationException 子类，重复 catch

7.2 CreateRoundRectRgn 报错找不到入口点（运行时）

CreateRoundRectRgn 在 gdi32.dll，最初错声明为 user32.dll → 每次切换后 OSD 弹窗即抛 EntryPointNotFoundException，被外层 catch 误报为「切换设备失败」（其实切换成功）。
→ 修正 DLL 归属；并给 OSD 显示单独 try/catch，避免提示层故障污染切换结果。

7.3 Cannot access a disposed object. Object name: 'OSDForm'

连续快速切换时：旧 OSD 的动画定时器是局部变量，窗体 Close() 后未销毁，下一帧访问已销毁句柄。
→ 定时器改为字段随窗体释放；ShowOSD 用新方法 Dismiss()（先停定时器再关窗体）。

7.4 OSD 弹出慢

• WinForms Timer 实际精度 ~15.6ms，10ms 间隔的淡入被拉长一倍以上
• AllowTransparency = true 导致每帧全窗口 GDI 重绘，雪上加霜
  → 秒表（Stopwatch）驱动：每帧按真实流逝时间算 alpha；去掉 AllowTransparency 与 OnPaint 逐帧重绘，改整窗 alpha。

7.5 右键菜单设备列表闪烁、点不中

多设备时 AudioDeviceChanged 事件风暴（插拔/默认设备变化/无效通知），每个事件都同步重建整个菜单；菜单打开期间重建=闪烁+无法点击。
→ 四层防护：600ms 防抖；快照比对（无变化不重建）；菜单 Visible 时延后（关闭后补刷）；Opening 前刷新 + 设备按名排序保证条目稳定。

7.6 切换后约 4 秒才有反应

菜单点击处理器里的 RefreshDeviceList() 在 UI 线程同步枚举（蓝牙端点每个几百 ms）→ UI 冻结。
→ 枚举与 SetAsDefault() 全部移入 Task.Run；菜单文本预计算，OSD 点击即弹（见 §3.3）。

7.7 开机自启不生效（requireAdministrator 之坑）

注册表 Run 值写入正确，但 manifest 为 requireAdministrator：开机时 Run 项以标准权限启动，系统弹 UAC 确认——看不到/不点/自动登录场景即静默失败。
→ 实际上切换默认设备不需要管理员权限（IPolicyConfig 普通接口）。改为 asInvoker：无 UAC 弹窗、自启静默生效。

7.8 设置热键对话框报错

预览键盘图标的 Bitmap 在 using 内创建并赋给 PictureBox.Image，块结束即被 Dispose → 首次绘制即崩。
→ 图片生命周期交给 PictureBox，不手动释放。

7.9 热键捕获逻辑缺陷（即使不崩也用不了）

• 原逻辑「无修饰键按下时才记录按键」→ Ctrl+Shift+F1 这种带修饰键组合永远录不进，「确定」永远灰
• 修饰键实时跟踪 → 一松手预览塌成「F1」
  → 改为按下功能键瞬间快照修饰键状态（snapshot 与物理状态分离），显示与保存都用快照。
  → 对话框打开期间临时注销全局热键，否则按当前热键会触发切换而非录入。

7.10 设置热键弹窗位置跑偏（右上角）

CenterParent 相对父窗口居中，但父窗体是隐藏的托盘窗 → 跑偏。
→ 改 CenterScreen，并加大窗体容纳设备列表。

7.11 重复点击可启动多个实例

→ 命名 Mutex 单实例守护；第二实例走轻量 OSD 路径提示后自动退出（§3.2）。实测连续启动 3 次最终仅 1 个常驻进程。

7.12 经验法则汇总

1. P/Invoke 先核对 DLL 归属（user32/gdi32/kernel32），错误 DLL 只在运行时暴露
2. 对象生命周期交给容器控件，避免 using/手动 Dispose 与控件引用冲突
3. UI 线程禁止任何设备 I/O；慢 COM 查询一律 Task.Run
4. 定时器精度 ≠ Interval：动画按时长用 Stopwatch，不用 tick 计数
5. 提权不是免费的：UAC 与开机自启不可兼得时，先确认功能是否真的需要管理员
6. 事件风暴用 防抖 + 快照 + 可见性守卫 三件套
7. WinForms 项目发布不要用 Trim/AOT（不支持），单文件框架依赖 + ReadyToRun 是体积/兼容的最优解
8. 发布前先确认无旧实例锁目录（Get-Process AudioSwitcher），否则单文件打包报 MSB4018

8. 后续可优化方向

• [ ] 托盘图标改为自定义多态图标（切到不同设备换不同小图标）
• [ ] OSD 显示设备当前音量 / 静音状态
• [ ] 白名单保存后同步重建「循环顺序」用户自定义排序
• [ ] 开机自启附加「启动时最小化验证」或任务计划程序（HIGHEST）备选方案
• [ ] 数字签名（消除 SmartScreen 提示）
• [ ] 把 osd/白名单文案抽成可配置项
• [ ] 设备枚举结果做本地缓存加速（COM 查询结果缓存 + 短 TTL）

9. 发布状态

复制到新电脑前需确认装有 .NET 8 Desktop Runtime（未安装时 Windows 会引导下载）；或将 csproj 改回 SelfContained=true 出 170MB 全内置版作为兜底分发。