一路“下一步”，装完重启
下载安装版，保留默认勾选的 VB-CABLE 虚拟声卡；装完重启电脑。VoiceAec 本体不需要管理员权限，安装过程中会弹一次 UAC（虚拟声卡 + 局域网面板）。
不想装安装版？便携版解压即用，见“安装”一节。
原理
声音是怎么走的
把 VoiceAec 想成一根“智能音频线”：一头接麦克风和扬声器，另一头接虚拟声卡。语音软件通过虚拟声卡，接收处理后的麦克风声音。
麦克风你和房间里的声音
扬声器回采耳机 / 音箱正在放的声音
VoiceAec本机神经网络消回声
CABLE Input虚拟声卡的播放端
CABLE Output语音软件选它当麦克风
CABLE Input 和 CABLE Output 是同一根虚拟声卡的两端。CABLE Input 是“写进去”，CABLE Output 是“读出来”。VoiceAec 写 Input，语音软件读 Output；写反或读反都不会有声音。
一句话记住：VoiceAec 负责把处理后的声音放进 CABLE Input；QQ / 游戏语音从 CABLE Output 把它当麦克风拿走。
别把游戏的播放设备改成 CABLE Input。游戏/音乐仍然从你的耳机或音箱播放；只有“语音软件的麦克风”才走 CABLE Output。
准备
开始前，确认这 4 样
都是常见环境，不需要额外买硬件。缺哪一项，后面都会给出对应的解决办法。
Windows 10 / 11 64 位
安装包自带 .NET 运行时和全部模型，不用另装开发环境。
不支持 32 位系统；不支持 macOS / Linux。
WebView2 运行时
用来显示控制面板。Windows 10/11 一般已经自带。
如果面板白屏或提示 WebView2 加载失败，再装 Evergreen 运行时。
VB-CABLE 虚拟声卡
VB-Audio 提供的免费虚拟声卡。安装版默认帮你装，装完需要重启。
卸载 VoiceAec 不会卸载它；它也可以给 OBS、直播等其他软件用。
麦克风 + 耳机/音箱
能正常收音、正常出声即可。USB 麦克风、领夹麦、摄像头麦克风都可以。
蓝牙耳机的麦克风常切到低音质通话模式；能有线就优先有线。
关于管理员权限：VoiceAec 本体是“每用户安装”，装到当前用户目录，不需要管理员。只有安装 VB-CABLE、配置局域网面板这两件事会弹 UAC。
安装
装好 VoiceAec 和虚拟声卡
推荐安装版：默认勾选虚拟声卡、桌面快捷方式，升级和卸载都走 Windows 标准流程。想放 U 盘或不想写注册表，用便携版。
推荐
每用户安装
自带 VB-CABLE
安装版：一路“下一步”
-
下载安装包
从 GitHub Releases 下载
VoiceAec-v0.5.2-setup-x64.exe。不要从网盘或第三方下载站拿。 -
选择语言
双击安装包，语言选“简体中文”，点“确定”。
-
欢迎页 → 附加任务
欢迎页点“下一步”。附加任务页保持两个默认勾选：创建桌面快捷方式 和 安装 VB-CABLE 虚拟声卡，然后点“下一步”。
-
准备页 → 安装
点“安装”。弹出 UAC 时选“是”，用于安装虚拟声卡和配置局域网面板。拒绝也能装完 VoiceAec，只是这两项要稍后补。
-
完成页：先重启
如果装了 VB-CABLE，先重启电脑。重启后“播放设备”里会出现
CABLE Input，“录音设备”里会出现CABLE Output。
SmartScreen / 杀毒提示：安装包没有购买商业代码签名，Windows 可能提示“未知发布者”。先核对 Releases 页的文件名和 SHA256（见进阶 · 校验下载）；确认无误再选择“更多信息 → 仍要运行”。
升级：直接运行新安装包。安装器会自动结束旧实例，设备选择保留，不需要先手动卸载。
便携版
适合 U 盘 / 绿色使用
解压即用，不写安装记录
从 Releases 下载 VoiceAec-v0.5.2-win-x64.zip，右键“全部解压”，双击里面的 VoiceAec.exe。不要直接在压缩包里运行。
- 配置写在 exe 旁的
voiceaec.json；目录不可写时回退到%LocalAppData%\VoiceAec\voiceaec.json。 - 没装 VB-CABLE 时，面板顶部会出现引导条，可一键安装（需要管理员）。
- 局域网面板需要 URL ACL 和防火墙规则；便携版可能需要手动配置，不需要就加
--no-lan。 - 移动文件夹后，重新打开“开机自启”开关即可修正启动路径。
装完先做
别急着开语音，先看三张卡
打开 VoiceAec，确认顶栏显示 运行中，并且麦克风、参考回采、输出三张电平卡都有正常反应。参考回采如果一直“静默”，先别开语音，去选设备。
不要同时运行安装版和便携版。单实例机制会互相激活，音频也容易混在一起。
卸载：Windows“设置 → 应用 → 安装的应用”→ VoiceAec → 卸载；或开始菜单 → VoiceAec → 卸载 VoiceAec。卸载 VoiceAec 不会移除 VB-CABLE。
第一次启动
3 步，让对方听到干净人声
第一次启动会自动选择：系统默认通信麦克风、默认播放设备（参考回采）、CABLE Input（输出）。大多数电脑开箱即用；不对再手动换。
1. 看顶栏
左侧应该显示“运行中 · 计时”，中间有 CPU 占用，右侧显示当前模式。如果显示“已暂停”，点右上角“恢复处理与输出”。
2. 做两个小测试
对着麦克风说话：麦克风电平应跳动。播放一首歌：参考回采应从“静默”变成“播放中”并跳动。然后说话时，输出电平也应跳动。
3. 改语音软件
QQ / Oopz / 游戏语音里：麦克风选 CABLE Output；扬声器保持你的耳机或音箱，不要选 CABLE Input。
1
顶栏运行状态、CPU、OBS 插件、第二参考、开机自启、当前模式、暂停/恢复。
2
电平三卡麦克风、参考回采、输出。点设备名可切换；右边是 dB 和峰值。
3
处理模式四张卡片，点一下立即切换；绿色“使用中”是当前模式。
4
运行统计处理时长、推理跳数、每秒推理、参考静默、补零、降级直通。
5
底栏提示一句话提示当前该做什么；右侧可打开 Windows 系统声音设置。
30 秒自检
- ✓顶栏显示“运行中”，CPU 有数字，不是“已暂停”。
- ✓对着麦克风说话，麦克风电平会跳。
- ✓播放音乐，参考回采会跳，状态不是一直“静默”。
- ✓说话时输出电平会跳。
- ✓语音软件麦克风 = CABLE Output。
- ✓语音软件扬声器 = 你的耳机/音箱，不是 CABLE Input。
参考回采为什么最重要？
回声消除需要知道“扬声器刚才放了什么”。参考回采就是这段参考信号。参考选错、设备静音或一直没声音，AEC 就不知道要消什么，对方仍会听到回声。
头号问题：参考回采一直显示“静默”。放音乐时它必须跳动；不跳就去选设备，把它改成你实际放声音的耳机或音箱。
戴耳机时没有外放回声，其实可以退出 VoiceAec，把语音软件麦克风改回真实麦克风；见场景配方。
选设备
四个位置，各选各的
VoiceAec 面板上有三个设备下拉，语音软件里还有一个麦克风设置。四个位置各司其职，不要互相顶替。
麦克风
选你说话用的那只麦克风。
判断对了对着说话，电平跳动，峰值不长期顶到 0 dB。
常见错选了 CABLE Output（把自己的输出又收回来）或选到已拔掉的设备。
参考回采
选你实际放声音的耳机或音箱，不是麦克风。
判断对了播放音乐时电平跳动，状态从“静默”变成“播放中”。
常见错选成没在用的设备、静音设备，或选成 CABLE Input。
输出
必须是 CABLE Input（VB-Audio Virtual Cable）。
判断对了说话时输出电平跳动，语音软件能收到声音。
常见错选了耳机/音箱，处理后的声音没有进虚拟声卡。
语音软件
QQ / Oopz / 游戏语音：麦克风选 CABLE Output；扬声器保持耳机/音箱。
判断对了对方能听到你，且听不到你的游戏声/音乐声。
常见错麦克风还是默认麦克风；或扬声器选了 CABLE Input。
| 位置 | 应该选 | 选错的后果 |
|---|---|---|
| VoiceAec 输出 | CABLE Input | 语音软件收不到处理后的声音 |
| QQ / 游戏语音 麦克风 | CABLE Output | 对方听到原始麦克风，回声还在 |
| 游戏 / 音乐 播放 | 耳机 / 音箱 | 声音进了虚拟声卡，你自己听不见 |
| VoiceAec 参考回采 | 耳机 / 音箱 | AEC 没有参考信号，消不掉回声 |
| 语音软件 扬声器 | 耳机 / 音箱 | 选了 CABLE Input 会形成回环/啸叫 |
两个 CABLE 千万别选反：VoiceAec 的“输出”是 CABLE Input；语音软件的“麦克风”是 CABLE Output。记不住就看上面的表，或看声音流向图。
可选：第二参考（网吧 / 宿舍里旁人说话）
第二参考是给 AEC 的“额外噪声参考”：把第二只麦克风放在旁人/噪声源附近，帮助消掉其他人的说话声；也可以选第二个播放设备。它属于进阶功能，不是必开。
- 打开开关
顶栏“开启第二参考”。电平区会多出第四张卡。
- 选择设备
点“点击选择设备”，从当前电脑可用的音频设备里，选靠近噪声源的第二只麦克风；也可以选第二个播放设备。
- 配合强力模式
建议用 v1.3 强力模式；如果发现自己的声音被削，换回 v1.2 或关掉第二参考。
第二参考是“锦上添花”，不是“越多越好”。没有旁人噪声时开着它，可能白白削掉一点人声。
设备名太长：鼠标悬停可以看到完整名称。选择会保存到
voiceaec.json；下次启动沿用，不会每次重新猜。
选模式
四种模式，按场景选
模式决定用哪个模型、CPU 用多少、消得多干净。日常从“均衡模式”开始；不够再往上加，不要一上来就最强。
关闭（直通）
OFF不做处理
麦克风原样转发。戴耳机聊天时最省电；外放时对方会听到你音箱里的声音。
- 适合戴耳机 / 音乐监听
- 消除强度0 / 5
- 程序 CPU最低
- 代价外放串音全传对方
均衡模式
推荐默认v1.2 · 约 130 万参数
消得干净、人声自然。日常外放开黑首选，也是第一次使用的默认模式。
- 适合日常开黑 / 外放音箱
- 消除强度4 / 5
- 程序 CPU较低
- 代价很少，优先用它
强力模式
最彻底v1.3 · 约 480 万参数
消除力度最大，还会压低周围噪声。代价是偶尔轻微削掉人声，更适合嘈杂环境或大音量外放。
- 适合网吧 / 大音量外放
- 消除强度5 / 5
- 程序 CPU中等
- 代价人声可能被轻微削
纯回声消除
近场尝鲜v1.4 · 约 20 万参数
以回声消除为主，尽量保留人声，适合房间回音或近场麦克风。远距离麦克风实测效果有限，先试听再长期用。
- 适合房间回音 / 近场
- 消除强度2 / 5
- 程序 CPU低
- 代价远麦效果有限
卡片上的“消除强度 4/5”是应用内的相对刻度，用来快速比较，不是实测百分比。
怎么选：戴耳机 → 关闭直通；日常外放 → 均衡；对方还听到回声 → 强力；人声被削 → 回均衡；只想消房间回音/近场 → 纯回声。每次只改一个变量，改完让对方听一句再决定。
模式选择会写入配置：下次启动自动恢复上次模式；命令行
--model 只覆盖本次启动，不写回配置（见进阶）。
场景
四种常见用法，照抄即可
同样的软件，不同场景只需要改“模式”或“开关”。先找到最像你的那一条。
外放 + 游戏语音（最常见）
游戏声音从音箱/耳机外放，语音软件用 CABLE Output 当麦克风，VoiceAec 消掉对方听到的游戏声。
- VoiceAec 输出 = CABLE Input；参考回采 = 你实际放声音的音箱/耳机。
- 游戏/音乐播放设备保持音箱/耳机，不要改 CABLE。
- 语音软件麦克风 = CABLE Output；扬声器 = 音箱/耳机。
- 模式先用均衡 v1.2；对方还听到回声再试强力 v1.3。
- 音量别开到削波；麦克风离嘴近一点，AEC 效果更好。
戴耳机聊天
戴耳机时没有外放回声，其实不需要 AEC。想省资源，可以直接退出 VoiceAec，把语音软件麦克风改回真实麦克风。
- 如果仍想用 VoiceAec 当虚拟麦克风：模式选“关闭（直通）”或“均衡”。
- 不要把语音软件扬声器选成 CABLE Input，否则自己听不见。
- 想彻底退出：托盘右键 → 退出 VoiceAec。
网吧 / 宿舍旁人说话
除了你自己的回声，旁边人的说话声也会被麦克风收进去。第二参考可以把“旁人噪声”也作为参考，帮助压低。
- 顶栏打开“第二参考”，选贴近噪声源的第二只麦克风。
- 模式建议用强力 v1.3；第二参考是可选功能，不是必开。
- 如果自己的声音被削得明显，关掉第二参考或回均衡 v1.2。
- 不要把第二参考选成你自己的主麦克风，否则等于没有额外信息。
OBS 录制 / 直播
在 OBS 里给麦克风加 VoiceAec 音频滤镜，让录制/直播也用到 AEC。适合不想开桌面端，或已经把麦克风交给 OBS 的人。
- 先退出 OBS，在 VoiceAec 面板顶栏“OBS 插件”里一键安装。
- 重启 OBS，在麦克风“滤镜 → 音频滤镜”添加 VoiceAec。
- 滤镜里把 Reference source 选成桌面音频/游戏音频源。
- 使用 OBS 滤镜时，暂停桌面端，避免同一路麦克风被处理两次。
托盘
关掉窗口，不等于退出
VoiceAec 平时缩在系统托盘里继续处理音频。点窗口 X 只是把面板收起来，不会中断声音。
托盘图标怎么用
- 左键单击：打开或聚焦控制面板。
- 右键单击：打开菜单——打开控制面板 / 暂停并静音 / 处理模式 / 开机自启 / 关于 VoiceAec / 退出 VoiceAec。
- 点窗口 X：隐藏面板，音频继续。
- 再次双击桌面图标：只会激活已有面板，不会开第二个实例。
唯一的正常退出入口：托盘图标右键 → “退出 VoiceAec”。不要用任务管理器结束进程，除非面板/托盘都无响应，作为兜底。
想开机就静默运行：顶栏或托盘菜单打开“开机自启”。它写当前用户的 HKCU Run 项，以
--tray 静默启动，不弹面板，也不需要管理员。
“暂停并静音”和“关闭（直通）”有什么区别？
| 对比 | 暂停并静音 | 关闭（直通） |
|---|---|---|
| 采集麦克风 | 停止 | 继续 |
| 神经网络推理 | 停止 | 停止 |
| 输出到 CABLE | 静音 | 麦克风原声 |
| 适合 | 临时离开、省资源、不想让对方听到 | 戴耳机、不需要回声消除 |
| 退出并重启后 | 仍保持暂停 | 恢复上次模式（通常仍是直通） |
暂停状态会保留：暂停后退出/重启仍保持暂停；点“恢复处理与输出”会沿用暂停前的设备和模式。正常退出不会把正在运行的状态改成暂停。
如果 CABLE 缺失，点“恢复处理与输出”会保持暂停并提示；先在输出下拉里明确选择设备，或装好 CABLE 后点“重新检测”。
窗口位置和大小会在关闭/退出时保存，下次在原来的位置和尺寸打开；如果保存的位置不在任何显示器上，会回到屏幕中央。
统计
这些数字正常吗？
底部统计可以帮助你检查参考信号和处理状态：参考有没有声音、CPU 跟不跟得上、是否出现降级直通。
处理时长正常
从启动开始累计的实际处理时间。暂停时不增长。它不是延迟指标。
累计推理跳数正常
每 16 毫秒处理一跳，数字持续增长。放一整天会很大，不是错误。
每秒推理62.5 正常
正常约 62.5 跳/秒。低于 55 或高于 70 会变红；低于 55 通常说明 CPU 跟不上。
参考静默跳数重点看
参考设备没有声音的跳数。放音乐时应明显少于累计跳数；两者相等，说明参考设备选错或一直静音。
输出补零次数少量正常
启动、切换设备时少量补零正常。快速上涨通常意味着输出卡顿/欠载，声音可能断续。
降级直通次数理想为 0
大于 0 表示 AEC 处理失败，声音被直通。先确认模型文件完整、CPU 不过载；持续增长就去看日志。
CPU 占用只统计 VoiceAec 进程，百分比按整机 CPU 折算（和任务管理器口径一致），不是“单核占用”。实际数字会因 CPU 核数、频率和后台程序而异。
OBS
在 OBS 里用 VoiceAec 滤镜
如果你用 OBS 录制或直播，可以给麦克风加一个 VoiceAec 音频滤镜，让 OBS 直接拿到消过回声的声音。
- 完全退出 OBS
不是最小化，是退出程序。OBS 运行时安装器会拒绝安装/卸载，也不会自动帮你关。
- 打开 VoiceAec 的 OBS 弹窗
面板顶栏点“OBS 插件”。没装过会显示“一键安装到 OBS”；装过会显示“更新 / 重新安装”。
- 允许管理员权限
插件要写到
%ProgramData%\obs-studio\plugins\obs-localvqe。已有版本会先备份到%ProgramData%\VoiceAec\ObsPlugin\backups。 - 重启 OBS
在麦克风的“滤镜 → 音频滤镜”里点 +，添加 VoiceAec。
- 选择参考音频源
滤镜属性里的 Reference source 选桌面音频或游戏音频源。不选就只做降噪/去混响，不做回声消除。插件界面可能是英文，认准 Reference source 这一项即可。
- 暂停桌面端
同一只麦克风不要同时被桌面端和 OBS 滤镜处理；用 OBS 时，托盘菜单“暂停并静音”。
弹窗里的版本号是插件版本：截图显示“已由 VoiceAec 安装 · 0.4.0”，代表 OBS 插件版本 0.4.0，与桌面程序的 v0.5.2 是两个独立版本号。
适用范围：普通安装版 OBS 64 位。OBS 便携版不扫描这个插件目录，当前一键安装不适用。卸载会移除本程序安装的文件；如果安装前已有插件，会恢复备份。
什么时候用插件、什么时候用桌面端：语音聊天用桌面端；录制/直播用 OBS 插件。两者不要同时处理同一只麦克风。
局域网
手机 / 平板也能看电平和切模式
控制面板默认对同一局域网开放。手机浏览器打开「关于」里显示的地址，就是同一个面板，不需要装 App。
- 确认在同一局域网
手机/平板和电脑连接到同一路由器所在的局域网，电脑用网线连接也可以；访客网络常开启“客户端隔离”，会打不开。
- 打开「关于」
点面板左上角 VoiceAec 品牌区，或托盘右键“关于 VoiceAec”。里面会显示
http://192.168.x.x:8765/这样的地址。 - 手机浏览器打开
输入或点击这个地址。能看到同样的电平、模式、设备选择；没有登录密码。
安全提醒：局域网面板没有登录密码。任何能连到你家庭网络的人都能打开并调整设置。只在可信的家庭网络使用；不要把 8765 端口转发到公网，也不要在公共 Wi-Fi 长期开启。
不想开局域网：在启动参数加
--no-lan，面板只监听本机。安装版会自动配置防火墙私有网络规则；便携版可能需要手动配置，或直接用 --no-lan。
IP 变了：路由器 DHCP 可能换地址。每次以「关于」里当前显示的地址为准，不要收藏旧 IP。
手机屏幕小：面板本身是桌面布局，手机上会横向滚动、字比较小。建议横屏或平板使用；看电平、切模式可以，复杂设置还是回电脑上做。
排障
常见问题
按症状找。每条都给出“下一步做什么”，不用从头读。
声音与效果
对方还是能听到游戏声 / 回声
先按顺序检查以下三项：
- 参考回采选对了吗？必须选你实际放声音的耳机/音箱。播放音乐时参考电平要跳，状态从“静默”变成“播放中”。
- 语音软件扬声器选对了吗？保持耳机/音箱，不要选 CABLE Input；选 CABLE Input 会把声音送回虚拟声卡。
- 模式够不够？均衡 v1.2 不够就试强力 v1.3；音量别开到削波，麦克风离嘴近一点。
如果参考回采一直静默，AEC 没有参考信号，换什么模式都没用。先去选设备。
对方说我声音变小 / 断续 / 像机器人
先看底部“每秒推理”：正常约 62.5 跳/秒，低于 55 会变红，通常是 CPU 跟不上。
- 把模式从强力 v1.3 换回均衡 v1.2，或关掉第二参考。
- 关闭占用 CPU 的后台程序；笔记本插电、开高性能模式。
- “输出补零次数”快速上涨说明输出卡顿；换一个输出设备/重启 VoiceAec 再试。
- 蓝牙耳机麦克风常切到低音质通话模式，尽量用有线/USB 麦克风。
- 麦克风增益别开太大，峰值长期顶到 0 dB 会削波。
对方完全听不到我
按链路从后往前查：
- 语音软件麦克风是不是
CABLE Output？不是就改。 - VoiceAec 输出是不是
CABLE Input？说话时输出电平有没有跳？ - 是不是点了“暂停并静音”？顶栏应显示“运行中”。
- Windows 设置 → 隐私和安全性 → 麦克风：允许桌面应用访问麦克风。
- 麦克风是否被 OBS、相机或其他软件独占？先关掉那些程序再试。
- VB-CABLE 是否装了并重启过？播放设备里有没有 CABLE Input？
有延迟 / 声音变调
AEC 需要缓冲，几十毫秒级延迟是正常的，不适合专业实时乐器监听。语音聊天一般感觉不到。
如果声音变调或明显断续：检查 Windows 声音设置里 CABLE Input 和 CABLE Output 的格式，统一设成 48000 Hz；关闭占用音频设备的程序；换回均衡模式再试。
第二参考没效果，反而削人声
第二参考适合“旁边有人说话/噪声源固定”的场景，不是万能降噪。它需要第二只麦克风真的靠近噪声源，或者选第二个播放设备。
如果自己的声音被削：关掉第二参考，或把模式换回均衡 v1.2。没有旁人噪声时，不建议长期开着第二参考。
安装与设备
双击没反应 / 托盘没有图标
v0.4.9 起，保存的设备被拔掉会自动回退到系统默认并在底栏提示，不会再因此启动失败。如果仍然双击没反应：
- 先看任务管理器里有没有 VoiceAec；没有就是没启动。
- 如果所有麦克风/播放设备都不可用，程序会以暂停状态打开；接好设备后重新选择并点“恢复处理与输出”。
- 旧版本或配置损坏：先在托盘右键退出 VoiceAec，再删除安装目录的
voiceaec.json（安装版在%LocalAppData%\Programs\VoiceAec\），或%LocalAppData%\VoiceAec\voiceaec.json，然后重新启动。 - 也可以建一个快捷方式，目标写成
VoiceAec.exe --mic "你的麦克风" --ref "你的扬声器"启动。 - 如果面板白屏但音频还在跑，见下一条 WebView2。
装完没有 CABLE Input / CABLE Output
虚拟声卡装完必须重启电脑，设备才会出现。
- 重启后检查“播放设备”里有没有 CABLE Input、“录音设备”里有没有 CABLE Output。
- 没有就重新运行 VoiceAec 安装包，保留“安装 VB-CABLE”勾选；或打开 VoiceAec 面板顶部引导条，点“一键安装虚拟声卡”。
- 仍然没有：去 Windows 设备管理器看有没有未知设备，卸载后重装官方 VB-CABLE。
- 卸载 VoiceAec 不会移除 VB-CABLE，这是正常的。
v0.5.0 起，找不到 CABLE 时程序会以暂停状态打开，不会把麦克风播到物理扬声器。v0.5.2 起点“恢复处理与输出”也会保持暂停并提示；先在输出下拉里明确选择设备，或装好 CABLE 后点“重新检测”。
安装时取消了 UAC / 没装 VB-CABLE
VoiceAec 本体已经装好，只是虚拟声卡和局域网配置没做。打开 VoiceAec，面板顶部会出现黄色引导条：点“一键安装虚拟声卡”，按提示允许管理员权限，装完重启。安装期间面板仍可操作，按钮会显示“正在安装…”。
在 CABLE 装好之前，程序会以暂停状态打开，不会把麦克风播到物理扬声器；装好后重启，或在输出下拉里明确选择设备再恢复。
局域网没配置也不影响本机使用；需要手机访问时，重新运行安装包并允许 UAC，或加 --no-lan 只用本机面板。
换了麦克风 / 拔掉设备会怎样？
v0.4.9 起会自动回退到系统默认设备，底栏会提示“xxx 不在了，已临时改用 yyy”；保存的选择不会被覆盖，设备插回后重启就会用回原设备。
想立即换设备，直接在面板下拉里选择即可；重新选好设备或点“重新检测”后，底栏提示会立即刷新，不用重启。也可以建一个带 --mic / --ref 参数的快捷方式启动。
怎么升级 / 怎么卸载
升级：直接运行新版安装包，安装器会结束旧实例，设备配置保留。
卸载：Windows“设置 → 应用 → 安装的应用”→ VoiceAec → 卸载；或开始菜单 → VoiceAec → 卸载 VoiceAec。卸载不会移除 VB-CABLE。安装目录里的 voiceaec.json 会被删除；如果曾回退到 %LocalAppData%\VoiceAec\voiceaec.json，这个文件可能保留，可手动删除。
面板、托盘与启动
面板白屏 / 提示 WebView2 加载失败
音频处理仍在后台运行，只是面板显示不出来。装 Microsoft Edge WebView2 Runtime（Evergreen 版）后重启 VoiceAec。
如果仍然白屏：检查杀毒软件是否拦截了 WebView2 子进程；重启电脑；或卸载重装 VoiceAec。
托盘图标找不到
Windows 11 默认把新图标放进托盘溢出区。点任务栏右下角的 ^ 找猫咪麦克风图标；可以把它拖到任务栏常显。
也可以在“设置 → 个性化 → 任务栏 → 其他系统托盘图标”里把 VoiceAec 设为显示。如果托盘和任务管理器都没有进程，说明程序没启动，见“双击没反应”。
模式会记住吗？
v0.4.8 起会记住。在面板或托盘切换模式后会写入 voiceaec.json，下次启动（包括开机自启）自动恢复。想临时用别的模式，可以在快捷方式目标末尾加 --model v1.3；它只覆盖本次启动，不写回配置。
开机自启没生效
先看顶栏或托盘菜单里的“开机自启”开关是不是开着。它写的是当前用户的 HKCU Run 项，不需要管理员。
- 如果刚移动过便携版文件夹，关掉再打开一次开关，让它记录新路径。
- 检查任务管理器“启动应用”里 VoiceAec 是否被禁用。
- 部分安全软件会拦截开机启动项，需要手动允许。
OBS、局域网与安全
OBS 插件安装失败 / OBS 正在运行
先完全退出 OBS，再点“更新 / 重新安装”。安装器不会自动关 OBS，也不会在 OBS 运行时强行替换文件。
只支持普通安装版 OBS 64 位；OBS 便携版不扫描 %ProgramData%\obs-studio\plugins\obs-localvqe，当前一键安装不适用。需要管理员权限；拒绝 UAC 会失败。
OBS 里加了滤镜，但没有效果
检查三件事：
- 滤镜是不是加在麦克风上，而不是扬声器/桌面音频上。
- 滤镜属性里的 Reference source 有没有选桌面音频/游戏音频源；不选就只做降噪/去混响。
- 桌面端是不是还在处理同一只麦克风？用 OBS 时在托盘菜单“暂停并静音”。
手机 / 平板打不开局域网面板
确认手机和电脑在同一个 Wi-Fi；用「关于」里当前显示的地址，不要用旧 IP。访客 Wi-Fi/公司网络可能开启客户端隔离，手机访问不到电脑。
检查 Windows 防火墙是否允许 VoiceAec 在“专用网络”通信。便携版可能没有自动配置 URL ACL/防火墙；可以改用安装版，或加 --no-lan 只用本机。不要把端口转发到公网。
局域网面板安全吗？
面板没有登录密码，只按私有网段（192.168/16、10/8、172.16/12）开放。它的设计场景是可信家庭网络；同一网络里的人能打开并改设置。
不要在公共 Wi-Fi、宿舍共享网络长期开启；不要做公网端口转发；不需要时加 --no-lan。
QQ 提示 CABLE Output 加载失败
这是 QQ 侧对虚拟设备的兼容问题，音频链路本身通常是正常的。可以尝试：在 QQ 语音设置里重新选择一次 CABLE Output；重启 QQ；或换用 Oopz、Discord、游戏自带语音验证。
如果其他语音软件能正常使用 CABLE Output，可记录 QQ 版本和报错信息，再向 QQ 反馈。
杀毒软件 / SmartScreen 拦截安装包
安装包没有购买商业代码签名，新项目容易被误报。先从 GitHub Releases 核对文件名和 SHA256（见进阶 · 校验下载），确认来源无误后再决定是否放行。
不要为了安装而整体关闭杀毒软件；最多把下载的安装包/安装目录加入信任。装完可以恢复防护。
进阶
命令行、配置与校验
需要使用启动参数、修改配置或校验下载时，可查阅本节。
命令行参数
在快捷方式“目标”末尾加参数，或命令行运行 VoiceAec.exe --参数。
| 参数 | 默认 | 说明 |
|---|---|---|
--mic | 系统默认通信麦克风 | 麦克风设备名（子串匹配），优先级高于配置文件。 |
--ref | 系统默认播放设备 | 参考回采设备；也可以填麦克风（近讲场景）。 |
--ref2 | none | 第二参考；找不到会自动降级单参考。 |
--out | CABLE Input | 输出设备；缺少 CABLE 时会回退并显示引导条。 |
--threads | 2 | 推理线程数；不确定就保持默认。 |
--model | v1.2 | off / v1.2 / v1.3 / v1.4。 |
--port | 8765 | 面板端口；占用时自动 +1，直到 8774。 |
--tray | — | 静默托盘启动，不开面板；开机自启用的就是它。 |
--console | — | 保留/新建日志控制台，排查时用。 |
--list | — | 列出音频设备后退出，用来查设备全名。 |
--no-lan | — | 只监听本机，不对局域网开放面板。 |
配置文件 voiceaec.json
保存设备选择。安装版在 %LocalAppData%\Programs\VoiceAec\voiceaec.json；便携版优先在 exe 旁，目录不可写时回退到 %LocalAppData%\VoiceAec\voiceaec.json。
{
"mic": "Microphone (USB Audio)",
"ref": "耳机 (USB Audio)",
"ref2": "none",
"out": "CABLE Input (VB-Audio Virtual Cable)"
}
一般不用手改。v0.4.9 起设备缺失会自动回退到系统默认，不需要删配置；如果仍无法启动（例如配置损坏），可在退出程序后删除这个文件，或改用 --mic / --ref。
端口、日志与 HTTP API
面板默认 http://localhost:8765/；端口占用会尝试 8765–8774。局域网地址在「关于」里显示。
默认不写日志文件。排查时用 --console 启动，会保留一个日志控制台；--list 可列出设备。
HTTP API 需要请求头 X-VoiceAec-Token，面板会自动携带。接口清单和开发说明见 README。
校验下载（v0.5.2）
在 PowerShell 里运行 Get-FileHash .\文件名 -Algorithm SHA256，和下面比对。
安装版 VoiceAec-v0.5.2-setup-x64.exe
821FAC1DCEE576A9AF8E6A164B6D5E81E036A34A769BBD52914F6ECBA1A5D654
便携版 VoiceAec-v0.5.2-win-x64.zip
59F0E9CD3AE93AEAE8B8DB569A26C03BA2EB63C8AFB8701A2D805911EDBDFF2F
SHA256 来自 v0.5.2 发布说明。如果下载的是更新版本，请以对应 Release 页的校验值为准。
隐私与许可
本地处理，开源可查
VoiceAec 不提供账号、不上传音频；所有音频处理都在你的电脑上完成。
音频不上传
麦克风和参考回采只在本机内存里处理，输出到本机虚拟声卡。程序不需要登录，也没有云端账号。
局域网有边界
面板只接受私有网段访问，但没有登录密码。只在可信家庭网络开启；不需要时用 --no-lan 关掉。
开源许可
应用代码 MIT；推理引擎 LocalVQE 为 Apache-2.0；ggml、NAudio、WebView2 等第三方组件见声明。VB-CABLE 是 VB-Audio 的捐赠软件。
GitHub 仓库 ·
MIT License ·
第三方组件声明 ·
LocalVQE ·
VB-CABLE 官网
反馈
仍然遇到问题？
先确认版本和症状，再去 Issues 搜索或提问。带上信息能少一轮来回。