KailasMahavarkar/elgato-wave3-ubuntu

## 👋 这是什么？ Wave:3 是一款非常出色的麦克风，但在 Linux 上你可能只能用到它一半的功能。插上它，它就是一个普通的 USB 麦克风——但 Clipguard、低切、麦克风/PC 平衡旋钮以及整个 Stream/Monitor 混音模式都依赖于 **Wave Link**，而 Elgato 仅为 Windows 和 macOS 提供了 Wave Link。 这就是缺失的那一半功能，已作为原生 Linux 应用重新构建。它使用与 Wave Link 相同的 USB 协议与麦克风进行通信，并使用 PipeWire 而非专有音频驱动程序来构建混音器。 如果你在 Linux 上进行直播或录音，并且拥有一台 Wave:3，这应该就是你原本期望开箱即用的体验。 ## ✨ 你将获得什么 | | | |---|---| | 🎛️ **真正的硬件控制** | 增益、静音、Clipguard、低切、耳机音量、麦克风/PC 平衡、旋钮模式和 LED 环——真实的设备设置，而非软件模拟 | | 🎚️ **Stream 和 Monitor 混音** | 九个通道，每个通道都为观众听到的声音和你听到的声音提供独立的推子。这是 Wave Link 的核心意义所在，而且在这里完美运行 | | 📊 **真正有意义的电平表** | 具有适当衰减和峰值保持的每通道和每总线峰值电平表 | | 🎨 **真正可用的 EQ** | 六个频段以人声常见的问题命名——Rumble、Boom、Boxy、Nasal、Presence、Air。拖动圆点即可调节 | | 🔊 **Gate、Compressor、Limiter** | 作为 LADSPA 插件在 PipeWire 内部运行，没有额外进程，也不增加延迟 | | ⚡ **专为实时使用设计的控制面板** | 带有数字快捷键的大图块，可满足你在直播中途的各种操作需求，包括一键紧急静音 | | 📹 **兼容 OBS** | 你的 Stream Mix 将显示为普通的捕获源 | ## 🚀 开始使用 **简单方法** —— 从 [Releases](https://github.com/KailasMahavarkar/elgato-wave3-ubuntu/releases) 下载 `.deb`： ``` sudo apt install ./wave3_1.0.1_all.deb ``` **从源码构建：** ``` git clone https://github.com/KailasMahavarkar/elgato-wave3-ubuntu.git cd elgato-wave3-ubuntu sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 \ lsp-plugins-ladspa pipewire-pulse sudo make install-udev ``` 无论选择哪种方式，接下来执行： ``` systemctl --user restart wireplumber pipewire # pick up the new rules wave3 setup # build the mixer and effects rack wave3 # or launch it from your app menu ``` 然后在 OBS 中，添加一个 **Audio Input Capture** 并选择 **Monitor of Wave:3 Stream Mix**。这就是你完成的混音，排除了你不想让其进入混音的内容。 ## 📸 浏览一下

Microphone - the real device settings. Each one is badged so you know how well understood it is	Equaliser - drag the dots. The curve you see is the curve the filter is running
Compressor - watch your voice go by and drag the threshold to suit	Noise gate - set the threshold against your actual room, not a number
Limiter - your safety ceiling, so a laugh never clips the stream	Deck - press 1-9 for the things you need in a hurry

## 🏗️ 架构解析 这里有两个独立的路径：一个是通过 USB 连接改变麦克风本身设置的 **控制** 路径，另一个是完全由 PipeWire 节点构建的 **音频** 路径。 ``` ╔═══════════════════════════════════════════════════════════════════════════╗ ║ CONTROL PATH USB interface 3, EP0 ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ wave3 app ──── bRequest 0x85 read ───▶ ┌──────────────────┐ ║ ║ ◀─── bRequest 0x05 write ──── │ Wave:3 firmware │ ║ ║ wIndex 0x3303 │ 16-byte config │ ║ ║ └──────────────────┘ ║ ║ gain · mute · clipguard · low cut · headphone vol · dial mode · LEDs ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ``` ``` ╔═══════════════════════════════════════════════════════════════════════════╗ ║ AUDIO PATH all PipeWire, no driver ║ ╚═══════════════════════════════════════════════════════════════════════════╝ ┌── microphone ─────────────────────────────────────────────────┐ │ │ │ capsule ──▶ gate ──▶ EQ ──▶ comp ──▶ limiter ──▶ wave3.fx.mic│ │ └──────── LADSPA filter-chain ───────┘ │ └───────────────────────────────────────────────┬───────────────┘ │ ┌── applications ──────────────────────┐ │ │ │ │ │ game ─▶ ┐ │ │ │ music ─▶│ │ │ │ chat ──▶├─▶ wave3.ch. ───────┼────────┤ │ browser▶│ (one null sink each) │ │ │ … ─▶┘ │ │ └──────────────────────────────────────┘ │ │ every source fans out twice, with an independent fader on each leg │ ┌─────────────────────────┴─────────────────────────┐ │ │ ▼ ▼ ┌───────────────────────────┐ ┌───────────────────────────┐ │ wave3.streammix │ │ wave3.monitormix │ │ what your audience hears│ │ what you hear │ └─────────────┬─────────────┘ └─────────────┬─────────────┘ │ .monitor │ ▼ ▼ ╭───────────╮ ╭───────────────╮ │ OBS │ │ Wave:3 phones │ ╰───────────╯ ╰───────────────╯ ``` 这种扇出结构是最关键的部分。一个麦克风和一组应用程序，但有 **两个完全独立的目标**。在你自己的耳机中调低游戏音量，你的观众完全不知道；在直播流中将浏览器静音，你却依然可以听到它。这种不对称性正是 Wave Link 的真正用途，也是本应用所实现的核心。

每个推子的实际位置

混音器中的每个通道条都映射到真实的 PipeWire 对象： ``` ┌─ one channel strip ─────────────────────────────────────────────┐ │ │ │ ▁▃█ ◀── meter reads wave3.ch.game.monitor │ │ │ │ ┃ STRM ◀── fader sets volume on wave3.play.game.stream │ │ ┃ MON ◀── fader sets volume on wave3.play.game.monitor │ │ │ │ [M][M] ◀── mutes the same two loopback nodes │ │ ⇄ link ◀── UI only: moves both faders together │ └─────────────────────────────────────────────────────────────────┘ ``` 因此，推子不是应用程序内部的软件乘数——它是真实的 PipeWire loopback 节点的音量。系统上任何其他更改该节点的操作（包括本应用自带的面板的操作）都会在下次显示混音器页面时反映出来。

🔌 硬件控制的工作原理

Wave:3 暴露了一个供应商接口（类 `ff`，子类 `f0`），并且完全没有任何端点 —— 所有操作都通过端点 0 上的控制传输完成。 ``` bmRequestType 0xA1 read / 0x21 write bRequest 0x85 read / 0x05 write wIndex 0x3303 wValue 0x0000 config (16B) | 0x0001 status (8B) | 0x000A version ``` `wIndex` 是其中有趣的部分。固件只检查 `0x33` 前缀，并且低位字节必须指定一个内核认为未被占用的接口。接口 3 符合条件，因此 `0x3303` 可以在不分离 `snd-usb-audio` 的情况下通过 —— 这意味着在应用程序与设备通信时，你的音频绝不会中断。 16 字节的配置块： | 偏移量 | 字段 | 类型 | |---:|---|---| | 0 | `/input_gain` | int16 LE Q8.8 dB, 0..40 | | 4 | `/input_mute` | bool | | 5 | `/clipguard_enable` | bool | | 6 | `/lowcut_enable` | bool | | 7 | `/headphone_volume` | int16 LE Q8.8 dB, -60..0 | | 9 | `/headphone_mute` | bool | | 10 | `/direct_monitor` | int16 LE Q8.8 percent | | 12 | `/volume_select` | u8 enum, 1 MIC / 2 HP / 3 MIX | | 13-15 | LED 标志，增益锁定 | bool | 完整的分析文档，包括它是如何被推导出来的，都在 [`research/dump/PROTOCOL.md`](research/dump/PROTOCOL.md) 中。

🛡️ 为什么让此程序写入你的麦克风是安全的

有两个偏移量是通过观察硬件自行更改它们来确认的。其余的来自对 Wave Link 的分析，这是很好的证据但并非绝对证明 —— 因此每一次写入都被当作一个事务处理： 1. 读取当前块 2. 更改其中一个字段 3. 写入它 4. 重新读取 5. 如果该字段之外的 **任何** 字节发生了变化，则恢复原始块并抛出异常 控件会相应地进行标记：**verified** 表示看到设备自行更改了该偏移量，**guarded** 表示依赖于上述的回滚机制。当你移动一个物理控件时，匹配的行会自动永久提升为 verified 状态。 固件更新 (DFU) 接口绝不会被触碰。

🎚️ 关于效果器

Ubuntu 构建的 PipeWire `filter-chain` 模块不支持 LV2 —— 它只认 `builtin` 和 `ladspa`。因此，效果机架使用的是 LADSPA，并采用了出色的 [LSP Plugins](https://lsp-plug.in)： | 阶段 | 插件 | 大致相当于 | |---|---|---| | Noise Gate | `gate_mono` | ReaGate | | Equaliser | `para_equalizer_x16_mono` | ReaEQ，Elgato 的 EQ | | Compressor | `compressor_mono` | ReaComp | | Limiter | `limiter_mono` | - | 所有操作都是实时生效的 —— 无需重启，音频中也不会出现爆音。 EQ 曲线由 RBJ cookbook biquads 计算得出，并且每个频段的滤波器模式都固定为 APO (DR)，这正是那些方程式所描述的滤波器。因此，屏幕上的曲线就是你实际听到的曲线，而不是一个好看的近似值。

⚠️ 它做不到的事情

- **没有每个插件独立的增益衰减表。** PipeWire 仅发布 LADSPA 的 *输入* 端口，因此无法读取插件自身的 GR 读数。Compressor 转而显示跨整个链路测量到的 `GAIN Δ`，并对此作了说明。 - **Gate 和 Limiter 的指示灯是推导出来的**，基于你的电平与阈值的对比，因此它们忽略了迟滞和启动/释放时间。这足以用来设定阈值，但不能作为插件的精确读数。 - **目前还没有 RNNoise** —— 它没有针对 Ubuntu 打包，需要从源码构建。它是 LADSPA 插件，因此一旦构建完成，就可以直接放入链路中。 - **不支持 Windows VST。** 那将意味着需要引入 Wine 和 yabridge，以及一个单独的宿主进程。 - 九个固定的通道；重命名意味着需要编辑 `~/.config/wave3/channels.json`。 - 仅支持暗色主题。

## 🩺 如果出现问题 ``` wave3 doctor ``` 它会检查捕获流、USB 控制以及拓扑结构是否已安装 —— 如果发现麦克风卡住，会自动进行修复。

麦克风没有声音且没有记录任何日志

Wave:3 的捕获流可能会卡住。每一层都坚称自己正常，但没有音频到达： ``` ┌──────────────┬───────────────────────┬──────────┐ │ reports │ actually delivering │ honest? │ ┌─────────────────┼──────────────┼───────────────────────┼──────────┤ │ USB / firmware │ streaming │ no packets │ ✗ │ │ ALSA substream │ RUNNING │ hw_ptr == 0 │ ✗ │ │ PipeWire node │ running │ no periods │ ✗ │ │ meters │ -90 dB │ nothing │ ✓ ish │ └─────────────────┴──────────────┴───────────────────────┴──────────┘ │ -90 dB is indistinguishable from a quiet room, which is why this can go unnoticed for an hour ``` 真相唯一出现的地方是 `/proc/asound`： ``` healthy wedged ─────────────────────── ─────────────────────── state : RUNNING state : RUNNING ← identical hw_ptr : 89042 ▲ climbing hw_ptr : 0 ■ frozen avail_max: 1634 avail_max: 0 ``` 因此，看门狗监视的是 `hw_ptr`，而不是音频： ``` every 0.5 s │ ▼ read hw_ptr ──── moved? ──yes──▶ healthy, reset timer │ ▲ no │ │ │ ▼ │ stalled > 2 s? ──no────────────────────── │ yes ▼ cycle card profile ──▶ wait ──▶ did hw_ptr move? ▲ │ │ ┌────yes─┴──no────┐ │ ▼ ▼ └── retry, backing off recovered 3 attempts? 0s · 5s · 20s (tell user) │ yes ▼ stop trying, say so ``` 退让然后停止很重要：每次配置文件循环都会销毁该声卡上的所有流，因此不可恢复的故障绝不能变成无限循环。 通常情况下，PipeWire 会通过挂起空闲设备并重新打开它来摆脱这种状况。这里附带的 WirePlumber 规则关闭了挂起功能，是为了防止 *另一个* 问题 —— 即麦克风组件挂起后输出数字静音 —— 因此这种自动恢复功能不可用。取而代之的是一个看门狗：它每秒读取两次 `hw_ptr`，并在其停止移动时循环切换声卡配置文件。只要应用程序处于打开状态，它就会运行，并在触发时通知你。如果尝试几次都没有帮助，它就会停止尝试并告诉你，而不是永远循环切换你的声卡。 要手动修复： ``` wave3 doctor ```

## 🧪 测试 ``` make test ``` | 测试套件 | 它证明了什么 | |---|---| | `test_mix_isolation.py` | Stream 和 Monitor 确实是独立的 | | `test_meters.py` | 每个电平表都在读取真实的音频 | | `test_ui_race.py` | 一次切换带来一次干净的过渡，没有跳动 | | `test_watchdog.py` | 能够发现并恢复卡住的捕获流，同时不干涉正常的流 | 这些测试大部分的存在是因为曾经有一些隐蔽的错误。曾经有三个独立的 bug 导致每个电平表都自信地读出 `-90 dB`：`parecord` 两秒的默认缓冲区、麦克风组件挂起并输出静音，以及一个名为 `wave3.monitor` 的 sink 产生了一个 PulseAudio 无法通过名称解析的 `wave3.monitor.monitor` 源。这三个问题现在都已得到解决。 ## 🙏 鸣谢 - [LSP Plugins](https://lsp-plug.in) - 承担真正繁重工作的 DSP - [openwave](https://github.com/rikkichy/openwave) - 在 Wave XLR 上证明了 `wIndex=0x3303` 传输方式 - [PipeWire](https://pipewire.org) 和 [WirePlumber](https://pipewire.pages.freedesktop.org/wireplumber/) ## 📄 许可证 [MIT](LICENSE)，外加一些关于商标、互操作性和硬件风险的简明说明。 与 Elgato 或 Corsair 没有任何附属、授权或认可关系。“Elgato”、“Wave:3” 和 “Wave Link” 是他们的商标。此处不包含任何 Elgato 的代码或资产。

标签：Elgato Wave:3, GTK4, PipeWire, 桌面应用, 逆向工具, 音频控制台, 音频效果器