szamski/Prismatic-for-macOS

Prismatic 是一款小巧的原生 macOS 菜单栏应用，它通过 **USB HID** **直接驱动** **SteelSeries Arena 7** 音箱的 RGB 灯效 —— 因此你无需在后台运行 庞大的 SteelSeries GG 套件。你可以直接在菜单栏中挑选左右颜色、从壁纸中 提取调色板、调节亮度并进行开关切换。 ## 功能 - **左右独立颜色** —— 每个音箱驱动 Arena 4 个 RGB 区域中的 2 个 - **从壁纸中获取颜色** —— 一键提取主色调色板 - **硬件亮度**调节与即时**开/关** - **自定义内联取色器** —— 直接在菜单内操作（无需笨重的系统面板） - **无需 SteelSeries GG** —— 通过 USB 直接与音箱通信 - **开机启动**，内置**更新检查**，约 1 MB 的原生 SwiftUI 应用 ## 为什么需要它？ SteelSeries GG 是一个重达数百兆字节的 Electron + 后台服务套件，仅仅是为了 改变一种颜色。而 Prismatic 以原生、即时且不干扰你的方式做好这一件事 —— 灯光控制。 其 USB 协议经过了**逆向工程**，因此该应用可以自行与硬件通信 （[了解它是如何工作的](#how-it-works)）。 ## 安装 ### Homebrew ``` brew install szamski/tap/prismatic ``` ### 手动安装 下载最新的 **[`Prismatic.dmg`](https://github.com/szamski/Prismatic-for-macOS/releases/latest)**，打开它，然后将 **Prismatic.app** 拖入 **应用程序**。每个发布版本中还附带了普通的 **`Prismatic.zip`**。 ## 使用方法 1. 通过 **USB 连接 Arena 7**（灯效仅支持 USB —— 蓝牙无法实现）。 2. 如果 **SteelSeries GG** 正在运行，请**退出**（两者无法同时独占设备）。 3. 启动 Prismatic —— 菜单栏图标出现。挑选颜色、亮度，完成。 ## 工作原理 Arena 7 暴露了一个供应商 HID 接口（`UsagePage 0xFFC0`，VID:PID `0x1038:0x1A00`）。 灯光通过 **Output report，ID `0x06`** 进行设置（作为控制传输 `SET_REPORT` 发送）： ``` byte 0 : 0x06 report ID byte 1 : 0xA1 command (0xA1 = set static colors, 0x09 = off) byte 2…: 4 × zone each zone = [R, G, B, 0x01, 0x1E, brightness(0…10)] zone order: left-base, left-rear, right-base, right-rear …0x0F : terminator ``` 该协议是从 SteelSeries GG 的 USBPcap 抓包中还原出来的。有关具体实现请参阅 [`ArenaUSBController.swift`](prisma-led-macos/ArenaUSBController.swift)，用于逆向工程（RE）期间的 HID 诊断脚本请参阅 [`tools/`](tools/)。 ## 从源码构建 ``` git clone https://github.com/szamski/Prismatic-for-macOS.git cd Prismatic-for-macOS xcodebuild -project prisma-led-macos.xcodeproj -scheme Prismatic -configuration Release build ``` 需要完整版的 **Xcode**（不仅仅是 Command Line Tools）。 ### 发布（维护者） Prismatic 发布时**使用 Developer ID 证书签名、启用 Hardened Runtime 构建并经过公证**，因此运行时不会有 Gatekeeper 警告。 **一次性操作：** 添加一个 **Developer ID Application** 证书（Xcode → Settings → Accounts → Manage Certificates → 点击 **+** → *Developer ID Application*），并使用你的付费开发者团队登录。 #### 选项 A —— Xcode（最简单） 1. **Product → Archive**。 2. 在 **Organizer** 中，选择 **Distribute App → Direct Distribution**。Xcode 会使用 Developer ID + Hardened Runtime 进行签名，通过你登录的账号进行公证，并装订 票据 —— 全部在图形界面中完成。 3. 导出应用，然后将其打包为发布版本： ditto -c -k --keepParent Prismatic.app Prismatic.zip && shasum -a 256 Prismatic.zip #### 选项 B —— 脚本（适用于 CI） `scripts/notarize.sh` 会以无头模式执行相同操作（归档 → Developer ID 签名 → 公证 → 装订 → zip 压缩 → sha256）。它需要一个名为 `prismatic` 的 `notarytool` 凭据配置文件： ``` xcrun notarytool store-credentials prismatic \ --apple-id "you@example.com" --team-id CKWYP7CT7C --password ``` 无论哪种方式：将 `Prismatic.zip` 上传到标记为 `v` 的 GitHub release 中，并更新 [`Casks/prismatic.rb`](Casks/prismatic.rb) 中的 `version` 和 `sha256`。 ### 添加对新设备的支持 Prismatic 很可能能够驱动 **任何可被 SteelSeries GG 点亮的 SteelSeries 设备** —— 只需要 对其 USB 灯效协议进行逆向工程即可。**[新设备支持 issue](../../issues/new?template=new-device.yml)** 表单会收集 以下所有信息；这里是涉及内容的完整概述。 **需要提供的内容** 1. **设备** —— 准确的型号名称，并确认 SteelSeries GG 能在你的机器上更改其 灯效（这样我们才知道这是一款由 GG 管理的设备）。 2. **USB 标识符 + HID 布局** —— 在连接设备的情况下运行 `swift tools/hid-probe.swift` 并粘贴输出结果。它会打印出 `VID:PID`、供应商使用页，以及带有 Input / Output / Feature 大小的 report ID —— 即 *哪个* HID report 最有可能是灯效通道。 3. **一份 USBPcap 抓包 —— 这是解锁一切的关键。** 在一台通过 USB 连接了该设备的 Windows PC 上： - 安装 **Wireshark**（在安装程序中勾选 **USBPcap**）和 **SteelSeries GG**。 - 在承载 VID `1038` 的 USBPcap 接口上开始抓包。 - 在 GG 中，将灯效设置为**静态、全亮度**，并以大约 2 秒的间隔依次执行一个已知序列：**全红 → 全绿 → 全蓝 → 每个区域一种不同颜色 → 关闭**。 - 停止，**另存为** `.pcapng`，压缩后附上。 该抓包包含 GG 发送的准确 `SET_REPORT` 数据包，这些数据包揭示了 **report ID**、 **command byte**、**按区域的字节布局** 以及 **RGB 顺序** —— 这正是 Arena 7 当初被解码的方式。 4. **区域布局** —— 有多少个可独立寻址的区域以及它们的位置（例如 “4 个区域：两个音箱各自包含一个底部光环 + 一个后置灯簇”），以便应用可以将 颜色映射到正确的物理 LED 上。 5. **运行环境** —— 你的 macOS 版本，以及你使用的是 Apple Silicon 还是 Intel。 **随后如何进行实现** 1. 解码抓包数据：找到灯效传输（`bmRequestType 0x21`，`bRequest 0x09`）， 读取数据字节，并分析出数据帧 —— `[report id][command][zone data…][terminator]` 以及任何亮度/效果字节。 2. 实时验证：使用 `tools/led-probe.swift` 发送候选报告并观察设备 （写入停滞意味着数据帧错误；成功接受则意味着正确）。 3. 添加一个小型设备配置 —— USB ID、report id、command、区域映射 —— 参考 [`ArenaUSBController.swift`](prisma-led-macos/ArenaUSBController.swift) 进行建模，并将应用的 左/右（或按区域）颜色对应接入。 **没有 Windows 机器？** 没关系，带上 `hid-probe` 的输出结果直接提交 issue。如果没有抓包数据， 进度会慢一些（必须推断字节布局），但这通常仍然是可行的。 ## 免责声明 Prismatic 是**非官方**应用，不附属于 SteelSeries，也未获得其认可。USB 协议的逆向工程是为了实现互操作性。使用风险自负。 ## 许可证 [MIT](LICENSE) © 2026 Maciej Szamowski

SteelSeries、Arena 和 PrismSync 是其各自所有者的商标。

标签：RGB灯效, SteelSeries, SwiftUI, USB HID, 硬件控制, 菜单栏应用