sKuhLight/monix

# Monix [](https://github.com/sKuhLight/monix/actions/workflows/ci.yml) [](LICENSE) 一个独立的、原生的 Linux 控制应用程序**及**驱动，专为 Audient iD 系列 USB 音频接口设计。受 [MixiD](https://github.com/TheOnlyJoey/MixiD) 的杰出工作启发，Monix 采用了一种不同的技术 方案 —— 一个配套的内核模块加上一个从官方应用映射而来的协议 —— 因此它能实现厂商软件所能做的一切：实时状态同步、通道推子、 路由和 VU 表显示，**同时保持音频持续播放**。 ## 兼容性 - **任何现代 Linux 发行版** — Arch/CachyOS、Debian 12+、Ubuntu 22.04+、Fedora 等。模块的 Makefile 会自动检测由 Clang 还是 GCC 编译的内核，因此 CachyOS 的 Clang 内核和 Debian/Fedora 上的 GCC 内核都能顺利编译。 - **内核 ≥ 5.9** — 模块使用了内核内的 `usb_control_msg_send/recv` 辅助函数（在 5.9 版本中加入），因此控制和音频可以共存，而无需占用 音频接口。 - 推荐 **PipeWire**（用于实现 Windows 风格的虚拟设备拆分）； 其余功能在任何 ALSA 设置下均可运行。 - 已在 **iD24** 上通过硬件验证；其他 iD 型号会在力所能及的范围内进行检测和支持 （请参阅 [设备支持](#device-support)）。 ## 为什么开发此项目 在 Linux 上，iD 控制协议会被发送到由 `snd-usb-audio` 占用的 USB 接口，如果不分离音频 驱动程序（这会导致声卡失效），用户空间就无法向其发送控制请求。我们采用了内核处理其他 专业接口的相同方式来解决这个问题：通过一个 小巧的配套内核模块从内核内部转发控制传输，这样 控制和音频就能同时运行且没有任何故障。 ## 布局 ``` driver/ companion kernel module (relays USB control transfers; reads via ioctl) lib/ userspace protocol library (control + state + meters) [in progress] app/ the GUI control panel (Audient-like layout, custom theme) [in progress] docs/ PROTOCOL.md — reverse-engineering notes / protocol spec re/ reverse-engineering working files (macOS app slice, scripts) [gitignored] ``` ## 环境要求 C++17 工具链、CMake ≥ 3.16、git、你的**内核头文件**，以及 **ALSA**、**GLFW** 和 **OpenGL** 的开发包。Dear ImGui 会由 CMake 自动拉取（首次构建需要联网）。DKMS 是可选的，但推荐使用 — 它会在 内核更新时自动重新编译模块。 ``` # Arch / CachyOS / Manjaro （请使用与您的内核相匹配的 headers：linux-cachyos-headers, …） sudo pacman -S --needed base-devel cmake git linux-headers alsa-lib glfw mesa dkms # Debian / Ubuntu / Pop!_OS sudo apt install build-essential cmake git linux-headers-$(uname -r) \ libasound2-dev libglfw3-dev libgl1-mesa-dev dkms \ libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev \ libwayland-dev # Fedora sudo dnf install gcc-c++ cmake git kernel-devel alsa-lib-devel glfw-devel \ mesa-libGL-devel dkms ``` ## 安装 ``` git clone monix && cd monix ``` ### 1) 内核模块（配套驱动程序，非自定义内核） 一个小型的树外模块，它在内核内部转发控制传输，因此 GUI 能在音频播放时正常工作。它会声明设备，因此安装后会 **在插入接口时自动加载** — 无需启动时的设置。 **推荐 — DKMS**（在内核升级后依然有效）： ``` sudo cp -r driver /usr/src/audient_id-0.1 sudo dkms add -m audient_id -v 0.1 sudo dkms install -m audient_id -v 0.1 sudo cp driver/99-audient-id.rules /etc/udev/rules.d/ && sudo udevadm control --reload-rules ``` **或者 — 直接使用 make**（每次内核更新后自行重新编译）： ``` cd driver && make && sudo make install && cd .. # builds + installs module + udev rule sudo modprobe audient_id # load now (or just replug the device) ``` 然后将你自己添加到 `audio` 组中（udev 规则会授予其访问 `/dev/audient_id*` 的权限）并重新登录： ``` sudo usermod -aG audio "$USER" ``` ### 2) 应用程序 + CLI ``` cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j ./build/app/monix-gui # the GUI control panel ./build/monixctl status # CLI: dump live device state ``` 完整性检查：`ls /dev/audient_id*` 应该列出一个节点，并且 `monixctl status` 应该 打印出采样率 + 监听状态。 ## 设备支持 该库是**配置文件驱动**的：连接时它会检测 USB PID 并加载 从 macOS 应用逆向工程得出的每个设备的配置文件（通道数、混音器节点布局、路由方案） — 请参阅 [`docs/DEVICES.md`](docs/DEVICES.md)。GUI 会根据该配置文件构建其 通道条和路由矩阵，因此混音器能适应每个 型号。未知的 PID 会回退到 iD24 的布局。 | 型号 | 检测 | 混音器/推子 | 输出路由 | 已测试 | |-------|:------:|:------------:|:--------------:|:------:| | iD24 | ✅ | ✅ | ✅ 公式 | **硬件验证** | | iD48 | ✅ | ✅ | ◐ 公式（已逆向，未测试） | 仅二进制 | | iD14 / iD22 / iD44 | ✅ | ✅ | ◐ 表格方案尚未连接 | 仅二进制 | | iD4 | ✅ | —（无混音器） | — | 仅二进制 | 非 iD24 型号会显示 **“实验性”** 横幅；在表方案连接代码被解码并且拥有该硬件的人 确认之前，它们的路由 UI 将是只读的。混音器的推子/电平表使用共享方案，应该可以工作，但在非 iD24 上 未经核实。 ## 状态 - ✅ 内核模块 — 音频播放时进行控制和电平表读取（无需卸载声卡）。 - ✅ 协议库 — 路由、混音器交叉点、采样率、时钟源、 光纤 (ADAT/S-PDIF) 模式、监听/主输出切换、对讲、耳机；控制 映射已从 macOS 应用解码并在硬件上验证。 - ✅ GUI — 深紫色、Audient 风格：通道条带支持立体声/单声道链接， 推子/声相/相位/电平表，Master/Cue A/B 混音，监听部分，以及系统面板 （包括数字输出的路由矩阵、采样率、带有 S-PDIF 锁定 警告的时钟源、数字 I/O 模式、微调）。 ## 多设备与游戏（Windows 风格拆分） iD24 是符合类标准的，因此 Linux 会将其视为**一个** 16 通道输出 + 12 通道 输入节点，且通道映射全为 `aux`。游戏和支持环绕声的应用会 在你的监听设备无法承载的通道上展开或错误映射立体声 — 导致音频 “出问题”。（Windows 能够避免这一点，仅仅是因为 Audient 的驱动程序将设备拆分成了 命名的立体声端点。） **最简单的方法：在应用程序中操作。** 在 Monix 中打开 **VIRTUAL DEVICES** — 勾选你想要的立体声 接收器/源（它们会立即出现，无需重启 PipeWire），为麦克风/ADAT 勾选 *Enable inputs*，并点击 *Save as startup config* 使其永久生效。 `setup/` 中提供了同样内容的可手动编辑的 PipeWire 配置 — 立体声 接收器/源各自连接到一个通道对，同时保留完整的多通道节点 供 DAW 使用： - `setup/id24-stereo-sink.conf` — 最小化配置：在 DAW 1+2 上提供一个纯净的“iD24 Stereo”接收器。 将游戏/桌面指向它。以最少的麻烦解决游戏音频问题。 - `setup/id24-split.conf` — 完整的 Windows 风合套装：主输出 1+2 / 输出 3+4 / 耳机 5+6 接收器，以及麦克风 1+2 / ADAT / 回环 源。 ``` mkdir -p ~/.config/pipewire/pipewire.conf.d cp setup/id24-split.conf ~/.config/pipewire/pipewire.conf.d/ # or id24-stereo-sink.conf systemctl --user restart pipewire pipewire-pulse ``` 对于输入，只需设置一次声卡的 **Duplex** 配置文件（pavucontrol → “Mehrkanal-Duplex”）；WirePlumber 会记住它。然后在你的声音设置中选择你想要 设为默认的立体声设备。 ## 故障排除 - **没有 `/dev/audient_id*`** — 模块未加载。检查 `lsmod | grep audient` 和 `dmesg | grep audient_id`；确保已安装内核头文件，并且（在 Arch 上）与 正在运行的内核相匹配。 - **GUI 显示“no device” / 权限被拒绝** — 尚未加入 `audio` 组 （`usermod` 后需重新登录），或者 udev 规则未安装。 - **S/PDIF 爆音** — 在系统面板中将时钟源设置为 **Optical**，以便 iD 作为从机同步到传入的流，并在两端使用相同的采样率。 ## 致谢 非常感谢 TheOnlyJoey 开发的 [**MixiD**](https://github.com/TheOnlyJoey/MixiD) — 这是第一个将 Audient iD 控制引入 Linux 并规划了大量 基础工作（控制值、设备列表）的项目。Monix 秉承了这一精神，采用了 不同的架构（内核模块转发 + 从官方 macOS `iD.app` 解码出的协议）。如果你在 Linux 上使用 Audient 接口，也请去看看 MixiD。

标签：Bash脚本, C/C++, 事务性I/O, 内核驱动, 控制面板, 硬件控制, 网络协议, 音频接口