FrankieMa77/qudelix

# 适用于 macOS 的 Qudelix 一款原生 macOS 菜单栏应用，可通过 USB 配置 **Qudelix 5K** DAC/功放。 [](https://github.com/FrankieMa77/qudelix/releases/latest) [](https://github.com/FrankieMa77/qudelix/releases) [](https://github.com/FrankieMa77/qudelix/releases/latest) [](https://github.com/FrankieMa77/qudelix/releases/latest) [](LICENSE) 非官方应用，与 Qudelix, Inc 无任何关联，也未经其认可。 Qudelix 提供了一款基于浏览器的配置应用。在 macOS 上，它非常不稳定 — Chrome 的 WebHID 使用的系统调用与之前相同，如果某个报告的帧结构 哪怕只有一字节的偏差，也会导致 5K 停止响应并从 USB 总线上掉线。本 应用转而通过 IOKit 直接与设备通信，并确保了帧结构的正确性。 ## 截图 | 均衡器 | 预设 | 导入 | |---|---|---| |  |  |  | ## 功能 - **实时设备状态** — 电池、充电、固件、采样率、输入源 - **音量**控制（支持静音） - **10 段参数 EQ** 编辑器：滤波器类型、频率、增益、Q 值以及前置增益 - **20 段模式** — 跟随设备当前所处的任意 EQ 模式 - **实时响应曲线**，展示组合后的滤波器形状 - **20 个预设槽位**，支持按名称加载和保存 - **预设导入**，可从文件或 [AutoEq](https://github.com/jaakkopasanen/AutoEq) 数据库（6000+ 款耳机）导入 - 以标准参数格式**导出**你的 EQ - **诊断面板**，记录与设备交换的每一个数据包 未使用蓝牙。本应用通过 USB HID 控制接口与 5K 通信，且 绝不触碰音频传输路径，因此播放不受任何影响。 ## 安装 从 [Releases](../../releases) 下载 `.dmg`，将其拖入 “应用程序”，然后启动。 macOS 在首次打开时会拒绝运行它 — 因为该应用仅使用了临时签名，而非 付费的 Apple Developer ID。要允许运行，请打开**系统设置 → 隐私与 安全性**，滚动至安全性部分，然后点击**仍要打开**。（旧版的 右键点击 → 打开的技巧在当前的 macOS 上已不再有效。） 如果你不想信任二进制文件，可以自行构建 — 见下文。 要求 macOS 14 或更高版本。通用二进制文件，支持 Apple Silicon 和 Intel。 ## 支持的设备 原版 **Qudelix 5K**，固件版本 3.x，支持 10 段或 20 段 EQ 模式。 应用会在连接握手期间识别设备，如果发现 尚未实现的功能，它会明确告知且不会写入任何内容， 而不是静默地执行错误的操作： | 情况 | 原因 | |---|---| | 5K Plus, T71, Aura Vita | 不同的 EQ 命令集 | | 固件 2.x | Qudelix 在固件 3 中更改了命令格式 | | 固件 1.x | 版本过旧；官方应用也会拒绝这些版本 | ## 从源码构建 ``` git clone https://github.com/FrankieMa77/qudelix.git cd qudelix/QudelixBar ./build-app.sh # current architecture, fast ./build-app.sh --universal # arm64 + x86_64 ./make-dmg.sh # universal build, packaged as a DMG ``` 仅需 Swift 5.9+ 和 Xcode 命令行工具；没有 任何第三方依赖。 ## 隐私 - 唯一会连接的主机是 `raw.githubusercontent.com`，且仅用于获取 AutoEq 耳机列表和你选择的预设。这仅在你打开 导入面板时发生，绝不在启动时进行。 - 无任何遥测、分析、标识符或崩溃报告。 - 仅会写入一个本地文件：`~/Library/Logs/QudelixBar.log`，用于保存设备 数据包跟踪记录。该文件永远不会被传输。 - 仅 EQ、音量和预设设置会被写入设备 — 这与 官方应用写入的内容完全相同。绝不触碰固件。 ## 协议说明 5K 的 USB 协议记录在 [`docs/`](docs/) 中，是为了实现互操作性，从 Qudelix 自家的浏览器应用中逆向工程得出的： - [`FINDINGS.md`](docs/FINDINGS.md) — 传输、HID 报告布局、EQ 组， 以及导致设备从 USB 总线掉线的 report-ID 陷阱 - [`PROTOCOL_STATUS.md`](docs/PROTOCOL_STATUS.md) — 状态/配置位域 结构体、通知和预设格式 这些内容可能对任何想要编写自己的 Qudelix 工具的人有所帮助。 ### 开发者工具 `Sources/qxusb` 和 `Sources/qxprobe` 是用于诊断的 CLI，并非应用的组成部分。 如果误用，它们可能会导致设备不稳定 — `qxusb --noid` 会刻意 复现总线掉线故障，而 `qxprobe` 会发送蓝牙 GAIA 命令。 在运行它们之前，请先阅读源码。 ## 已知限制 - 目前仅开放了用户（耳机）EQ 组，未开放扬声器组。 - 除非你已在设备上命名，否则预设槽位会显示通用名称。 - 20 段模式是根据 Qudelix 的预设格式实现的，但尚未 在真实硬件上进行过测试。写入行为应该与 10 段模式完全一致；如果 20 段曲线回读错误，应用会保持平直的默认设置，而不会 显示无意义的数据。欢迎反馈。 - 暂无自动更新机制。 ## 反馈与贡献 欢迎提交 Bug 报告、想法和 Pull Request — 请提交 [issue](../../issues) 或 PR。 目前特别有用的反馈： - **20 段 EQ 模式** 已实现，但从未在真实硬件上运行过。如果你 使用了该模式，请告诉我你的曲线是否能正确回读。 - **非 3.1.8 版本的其他固件**，或任何表现异常的 5K 设备 — 诊断 面板和 `~/Library/Logs/QudelixBar.log` 会捕获所需的一切信息。 - **Intel Mac。** 该二进制文件虽然是通用的，但目前仅在 Apple Silicon 上运行过。 ## 许可证 [MIT](LICENSE)。可随意使用、构建、复刻；不提供任何担保。 ## 致谢 - [devicePEQ](https://github.com/jeromeof/devicePEQ) — 针对 Qudelix HID 协议的开源先行工作 - 由 Jaakko Pasanen 开发的 [AutoEq](https://github.com/jaakkopasanen/AutoEq) — 耳机修正数据库

标签：Qudelix 5K, 均衡器, 硬件控制, 菜单栏应用, 音频处理