PeriTray

本项目原名为 PeriphMonitor，现更名为 PeriTray。

一款轻量级的 Windows 系统托盘外设监控工具，实时显示所有连接设备的状态信息。

---

简介

PeriTray 是一款运行在 Windows 系统托盘中的轻量级外设监控工具，实时检测音频、USB、蓝牙、电池、显示器等设备状态，并提供音量控制、蓝牙管理、蓝牙音频接收、全局快捷键、任务栏信息组件等功能。

基于 Tauri v2 构建（Rust 后端 + 原生 HTML/CSS/JS 前端），界面采用 WinUI 风格，支持深浅主题。

升级提醒

• 项目正式更名为 PeriTray（原名 PeriphMonitor），仓库、配置、文档全面更新，1.3.4 之前的版本建议卸载后重新安装

功能

• 设备监控

  • 实时检测音频、USB、蓝牙、电池、显示器等设备
  • 显示连接状态、电量、连接类型标签（蓝牙/2.4G）
  • 支持重命名、隐藏、正则过滤、去重、自定义分组

• 2.4G 设备电量

  • 通过接收器厂商 HID 私有协议查询电量，后台缓存自动刷新
  • 点击刷新按钮可强制即时查询连接状态与电量
  • 支持雷蛇、罗技、飞智、狼蛛 接收器

• 蓝牙

  • 显示连接/配对状态与电量（BLE GATT / BTC 两种路径）
  • 支持连接/断开，可跳转系统蓝牙设置

• 蓝牙音频接收（实验性，需 Windows 10 2004+）

  • 把这台电脑当作蓝牙音箱：手机等设备播放的音频直接从电脑扬声器/耳机播出
  • 在设置页「设备信息」分区连接手机，或在弹出窗口设备卡右键「通过本机播放」
  • 支持启动时自动恢复上次连接、断开后自动重试（两项均可关闭）

• 音量控制

  • 切换默认输出设备、调节音量、静音
  • 音量精细调节：滑块与滚轮按 0.1 步进微调
  • 静音锁定：点击图标锁定静音，拖动音量条不改变状态
  • 强制静音：一次操作直接静音需多次点击的设备
  • 空间音效：Windows Sonic / Dolby Atmos / DTS
  • 按应用调节音量，支持为每个应用指定音频输出/输入设备
  • 设备右键菜单支持重命名、隐藏、空间音效设置

• 全局快捷键

  • 录制音量控制（提高/降低/静音）与输出设备切换快捷键
  • 可开启共享循环切换（多设备共用快捷键循环切换）

• 任务栏组件（默认关闭，在设置页「任务栏」分区开启）

  • 设备信息组件：每台已添加的设备在任务栏内显示一个图标，直接看出电量与音量，悬停显示该设备的详细信息
  • 音乐控制组件（实验性）：显示专辑封面、歌名与歌手，鼠标移入后变为「上一首 / 播放暂停 / 下一首」
  • 在组件上滚动滚轮即可调节对应应用的音量；点击音乐封面可直接打开对应的音乐软件
  • 位置可拖拽并记住；「任务栏窗口位置」支持「自动」档——自动避开任务栏已有图标找空隙放置，打开或关闭应用后约半秒内自动跟随
  • 两个组件一键互切；设备由弹出窗口右键菜单「钉到任务栏 / 移出任务栏」管理

• 系统托盘

  • 左键弹出主窗口（设备信息 / 音量控制双页）
  • 右键菜单提供各功能入口
  • 图标悬停显示设备状态

• 设置页

  • 通用设置、快捷键、设备信息、音量控制等分类
  • 深色主题与窗口背景材质（Mica / Acrylic，Win11 22H2+）

• 更新检测

  • 启动时自动检测 GitHub 新版本，支持测试版开关与手动检测

截图

• 设备信息

  

• 音量控制

  

• 托盘提示

  

• 设置页面

  

技术栈

组件	技术
框架	Tauri v2（Rust 后端 + 纯 HTML/CSS/JS 前端）
设备检测	WMI + WinRT Bluetooth + Win32 SetupDi
蓝牙音频接收	WinRT AudioPlaybackConnection（Windows 10 2004+）+ SetupDi 端点判活
音量控制	Windows Core Audio API（事件驱动）
任务栏组件	Win32 分层子窗口自绘 + UI Automation（无障碍层）位置避让
2.4G 识别	USB VID/PID 匹配（驱动内置声明 + 用户自定义文件）
电量	BLE GATT Battery Service / BTC SetupDi 设备属性 / HID Feature Report（hidapi）
异步 / 网络	tokio / WinHTTP

项目结构

PeriTray/
├── tools/check.mjs                  # 前端完整性守护脚本（pre-commit 调用）
├── src-tauri/
│   ├── src/                         # Rust 后端（音频、蓝牙、托盘、快捷键、材质、更新检测等）
│   ├── dist/                        # 前端（无构建，直接编辑）
│   │   ├── popup.html / settings.html
│   │   ├── styles/                  # base.css 共享基类 + popup.css + settings.css
│   │   └── scripts/                 # common.js + 双页分区脚本（命名镜像）+ 各页入口
│   ├── icons/                       # 应用图标
│   └── tauri.conf.json
└── .github/workflows/               # CI/CD（x64 / ARM64 构建与发布）

2.4G 设备支持

通过接收器暴露的厂商自定义 HID 接口（Feature Report）查询设备电量，后台缓存刷新、不阻塞设备列表；点击设备信息页顶部的刷新按钮可强制现查连接状态与电量（设备休眠时可能需数秒）。

已支持品牌

品牌	说明
雷蛇	鼠标、键盘共 76 个 VID/PID（Orochi V2 经实机验证，其余基于同族协议移植）
罗技	Unifying / Lightspeed / Bolt / Nano 接收器（PID 范围启发识别，单下游设备时显示名称与电量）
飞智	Vader 4 Pro
狼蛛	F75 Max（仅 2.4G 接收器模式）

完整设备清单见 Wiki · 支持设备列表。

其中仅部分设备经实机验证，并未逐一实测——若你的型号显示异常，欢迎提 Issue 并附 debug.log 中 [24g] 开头的日志行。

自定义设备

在设置页点击「打开」编辑 wireless_24g_devices_user.json 添加未收录设备（应用更新时不会覆盖），同 VID/PID 时用户条目优先。VID/PID 可通过 USB 设备查看器 获取：

{
  "VID": {
    "PID": { "name": "设备名称", "type": "mouse|keyboard|audio|other" }
  }
}

其中 mouse/keyboard 归入输入设备，audio 归入音频设备，other 或空归入其他设备。

扩展支持

新品牌需在 src-tauri/src/wireless_24g/drivers/ 下按协议族新增驱动文件（实现 BatteryDriver trait）。若想自行逆向其它品牌协议，可参考 2.4G 无线设备电量获取项目 的方法论。欢迎贡献代码或思路。

构建

npm install
npm run tauri dev

Rust 工具链版本由仓库根的 rust-toolchain.toml 固定（当前 1.98.1），本地与 CI 同版； rustup 会自动按该文件安装对应版本，无需手动切换、也不必改本机 rustup default。 徽章上的版本号即该固定版本，不是「最低支持」——改版本见该文件头注释里的升级流程。

开发须知

前端位于 src-tauri/dist/（无构建流程，直接编辑）。提交涉及 dist/ 的改动会自动经过完整性守护脚本校验。重新克隆后安装钩子：

cp tools/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

也可手动自检：node tools/check.mjs。详见 AGENTS.md。

架构、模块详解与开发指南见 项目 Wiki。

下载

从 Releases 页面下载最新版本，支持 x64 和 ARM64 架构。

CI/CD

推送 v* 格式的 tag 时自动构建 x64 / ARM64 安装包并创建 GitHub Release（tag 名含 - 时标记为 Pre-release）：

git tag v1.1.0 && git push origin v1.1.0

许可证

GPL-3.0 LICENSE

致谢

• BluetoothAutoConnect — 蓝牙连接方案参考
• BlueGauge — 蓝牙电量方案参考（PnP 设备属性读取）
• EarTrumpet — 托盘音量入口参考
• win11React — WinUI 样式参考
• WinUIonWeb — WinUI 样式参考
• 2.4G-wireless-device-battery — 2.4G 私有协议逆向方法论
• OpenRazer — 雷蛇私有协议参考
• Solaar — 罗技电量读取路径参考
• OpenLogi — 罗技 HID++ Rust 参考实现