PushkarDesai-06/Kreo-Hive65-Rgb-Linux
GitHub: PushkarDesai-06/Kreo-Hive65-Rgb-Linux
逆向了 Kreo Hive 65 键盘的 HID 协议，为 Linux 用户提供免驱的 RGB 灯效控制与实时音频可视化功能。
Stars: 30 | Forks: 3
# Kreo Hive 65 - Linux RGB 控制（内置音频可视化工具！）
在 Linux 上控制你的 Kreo Hive 65 键盘的 RGB 灯效，无需 Windows 软件。你可以为每个按键设置任意颜色，绘制渐变效果，还可以运行音频响应模式，无论你的电脑正在播放什么，它都能将整个键盘变成实时的声波。而当声音停止时，它会自动悄然过渡到环境渐变效果。
它适用于通过 USB 连接并显示为 `258a:010c` “BY Tech Gaming Keyboard” 的有线 65% 键盘（即 Kreo Hive 65）。
## 准备条件
- 任何主流 Linux 发行版（Arch、Ubuntu、Fedora、Mint，随你挑选），且使用 PipeWire 或 PulseAudio。近几年发布的所有主流发行版都内置了其中之一。
- Python 3，大多数发行版已经预装。无需安装任何 pip 包。
- 键盘需通过 USB 线缆连接并处于有线模式。蓝牙和 2.4 GHz 接收器不可用，因为 RGB 通道仅支持有线连接。
## 设置（一次性操作，约 2 分钟）
**1. 获取文件。** 将 `keyboardrgb.py` 和 `60-keyboardrgb.rules` 放入同一个文件夹，例如 `~/kbd-re`，并在该目录下打开终端。
**2. 授予与键盘通信的权限。** 默认情况下，Linux 仅允许 root 用户访问键盘的控制通道。此操作将安装一条规则，其含义基本上是“任何使用此计算机的人都可以控制这个特定的键盘”。它的权限仅限于此特定设备，且日后随时可以轻松撤销（只需删除该文件即可）：
```
sudo cp 60-keyboardrgb.rules /etc/udev/rules.d/
sudo udevadm control --reload
```
现在请拔下键盘的 USB 线缆并重新插入，以使规则生效。
**3. 尝试运行：**
```
python3 keyboardrgb.py color ff0000 # whole board red (Ctrl-C to stop)
python3 keyboardrgb.py rainbow # rainbow across the keys
python3 keyboardrgb.py off # everything off
```
如果键盘变红了，说明设置成功。如果提示 `Permission denied`，请查看下方的故障排除部分。
## 音频响应模式
https://github.com/user-attachments/assets/8e475d93-be6e-4a3d-a416-4831388860dd
效果展示的顺序为 wave -> bars -> wave
```
python3 keyboardrgb.py audio
```
就这么简单。播放一些音乐，键盘就会变成一个 16 列的频谱波浪：左侧为低音，右侧为高音，从中排向外波动。它会捕获系统当前正在输出的任何音频（Spotify、YouTube、游戏等），无论这些声音是发送到扬声器还是耳机。按下 Ctrl-C 即可停止。
### 效果 (`--effect`)
选择你想要的视觉风格。它们都会对音频进行实时响应：
| 效果 | 视觉效果表现 | 响应方式 |
| ------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wave` _(默认)_ | 从主行区向外膨胀的频谱 | 每一列代表一个频段 |
| `bars` | 经典均衡器——默认从下往上增长；`--direction` 可选择其起始增长的边缘 | 列（或行）的高度跟踪频段的音量 |
| `split` | 低音从左边缘亮起，高音从右边缘亮起，在中间渐变为暗色 | 左半部分随低音变亮，右半部分随高音变亮，节拍会从两侧向内推进 |
| `flow` | 低音“瀑布”效果——最左侧的列跟踪低音，随后每一次冲击都会向右移动 | 只有最左侧的列采样低音；该采样值每帧向右滚动，因此节拍从左边进入并滑向右边缘（速度由 `--flow-speed` 设置） |
| `vortex` | 黑洞效果，中间为暗色空洞，周围环绕着旋转的彩色光环 | 声音越大颜色旋转越快，每个频率点亮光环上对应的扇区，而低音会使空洞膨胀并将光环向外推挤，从而让节拍产生脉冲效果 |
| `ripple` | 从中间向外呼吸的同心圆环 | 低音冲击将圆环向外推，整体音量决定亮度 |
```
python3 keyboardrgb.py audio --effect vortex
python3 keyboardrgb.py audio --effect ripple
python3 keyboardrgb.py audio --effect bars
python3 keyboardrgb.py audio --effect split
python3 keyboardrgb.py audio --effect flow
```
#### 柱状方向 (`--direction`)
`bars` 默认从下往上增长。`--direction`（仅对 `bars` 有效）可以改变柱状图从哪个边缘开始增长。`bottom`/`top` 为垂直方向（每列一个频段）；`left`/`right`/`sides` 为水平方向（每行一个频段）。
| `--direction` | 均衡器柱状图… |
| ------------------ | ------------------------------------------------------ |
| `bottom` _(默认)_ | 从底行向上增长 |
| `top` | 从顶行向下悬垂 |
| `left` | 从左边缘向右延伸 |
| `right` | 从右边缘向左延伸 |
| `sides` | 从两侧向内增长并在中间相遇 |
```
python3 keyboardrgb.py audio --effect bars --direction top
python3 keyboardrgb.py audio --effect bars --direction sides
python3 keyboardrgb.py audio --effect bars --direction left --gain 1.5
```
### 个性化定制
以下参数适用于所有效果：
| 选项 | 功能说明 | 默认值 |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--mode colorful` | 在键盘上滚动的 4 色渐变（红、紫、青、琥珀） | 默认 |
| `--mode single --color ff2000` | 仅使用你选择的单一颜色 | |
| `--gain 1.5` | 振幅倍数。数值越大，反应越狂野。建议尝试 `0.5` 到 `3` 之间的值 | `1.0` |
| `--smooth 2` | 平滑度倍数。数值越大越平滑舒缓，数值越小越快速敏锐。建议尝试 `0.5` 到 `3` | `1.0` |
| `--scroll 0.3` | 渐变在按键上滚动的速度，单位为周期/秒。设为 `0` 则固定不动（`vortex` 会忽略此项，它会自行旋转） | `0.15` |
| `--radius 0.45` | 仅适用于 `vortex`：中间暗洞的大小，范围从 `0` 到 `1`。数值越大，空洞越宽，光环被推得越远 | `0.18` |
| `--flow-speed 5` | 仅适用于 `flow`：低音冲击从左向右移动的速度，单位为列/秒。数值越低，扫过的速度越慢、越可见 | `8.0` |
| `--fps 60` | 帧率。默认 30 看起来已经很流畅且对 CPU 负载较低；可以将其提高到 60（键盘支持的上限）以获得更丝滑的效果 | `30` |
几个使用示例：
```
python3 keyboardrgb.py audio --effect vortex --radius 0.4 # black hole, wider void
python3 keyboardrgb.py audio --effect ripple --mode single --color 00ffcc
python3 keyboardrgb.py audio --mode single --color 00ffcc --smooth 2
python3 keyboardrgb.py audio --effect bars --gain 1.5 --smooth 0.6
```
顺便说一下，音量大小并不重要。可视化工具会根据音乐自身的动态进行自动电平调节，而 `--gain` 会在此基础上进行额外缩放。
### 当音乐停止时 (`--default`)
你可以让可视化工具整天运行，在安静的时候它绝不会仅仅停滞在死气沉沉的黑色键盘上。静音 3 秒后，它会平滑地交叉淡入到一种环境（非音频响应）效果中；一旦声音恢复，它又会立即淡入回到音频响应模式。这两个过渡过程都非常柔和，没有任何突兀的切割感。
| 选项 | 功能说明 | 默认值 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `--default gradient` | 空闲时的效果：`gradient`（滚动的 4 色渐变）、`breathe`（整个键盘在色板中漂移）、`wave`（滚动的亮度波浪）或 `off`（熄灭） | `gradient` |
| `--idle-gap 3` | 切换效果前的静音秒数 | `3` |
| `--silence-level 0.01` | 多小的声音才算作“静音”。如果嘈杂的线路使其一直保持唤醒，可以调高此值；如果太轻微的声响就触发了切换，可以调低此值 | `0.004` |
```
python3 keyboardrgb.py audio --default breathe # breathe softly when idle
python3 keyboardrgb.py audio --default off --idle-gap 2 # just go dark after 2s of quiet
```
### 其他命令
```
python3 keyboardrgb.py key w ff0000 a ff0000 s ff0000 d ff0000 # light up WASD
python3 keyboardrgb.py gradient ff00ff 00ffff # left to right gradient
python3 keyboardrgb.py wave # rainbow animation, forever
python3 keyboardrgb.py wave 30 # ...or just 30 seconds
```
所有这些效果都会持续运行直到按下 Ctrl-C（添加 `--once` 可仅设置一帧然后退出）。
除非你指定了具体的秒数，否则 `wave` 会一直运行。
按键名称：按印在键帽上的字母和数字为准，此外还包括 `esc tab capslock lshift
rshift lctrl rctrl lwin lalt ralt fn space enter backspace del home pgup
pgdn up down left right minus equal lbracket rbracket backslash semicolon
quote comma period slash`。
## 屏幕同步
将键盘变成你屏幕的延伸氛围灯。它会捕获你的显示器画面，将其缩小为模糊的 144p 分辨率，并将其投射到按键上——这样灯光就会随着屏幕上的颜色（无论是高亮度的游戏、视频，还是你的壁纸）而闪烁。这是一种柔和、低分辨率的映射反射，而不是一块微小的显示屏。
```
python3 keyboardrgb.py screen
```
默认情况下，它会跟随当前获得焦点的显示器，并在你切换焦点时实时切换屏幕源（适用于 Hyprland）。它的设计非常轻量：你的屏幕画面由 `grim` 捕获，单个 `ffmpeg` 进程负责完成 144p 缩小、模糊以及压缩至按键网格的工作，因此 Python 几乎不消耗性能（每帧仅需几百字节的计算）。
你需要安装 `ffmpeg`，以及在 Wayland 下使用的 `grim`（在每个主流发行版中都只需一条命令即可安装）。在 X11 下，它使用 `ffmpeg` 的 `x11grab` 功能，因此不需要 `grim`。
调节参数：
| 标志 | 功能说明 |
| -------------- | ------------------------------------------------------------------- |
| `--output NAME`| 绑定到一个特定的显示器，而不是跟随焦点（使用 `hyprctl monitors` / `wlr-randr` 查看名称） |
| `--no-follow` | 停止跟随焦点；停留在当前（或 `--output` 指定）的显示器上 |
| `--saturation` | 增强色彩饱和度（默认 `1.5`）；`1` = 保持原样 |
| `--gain` | 整体亮度（默认 `1.1`） |
| `--blur` | 144p 下的模糊半径，单位为像素（默认 `2`，`0` = 接近清晰） |
| `--smooth` | 时间平滑度 `0..0.95`（默认 `0.5`；数值越高越平稳） |
| `--raw` | 忠实还原色彩——不使用饱和度/增益/伽马校正，如实地镜像画面 |
| `--fps N` | 帧率（默认 `24`；降低此值可进一步节省 CPU 性能） |
```
python3 keyboardrgb.py screen --output HDMI-A-1 # pin the external monitor
python3 keyboardrgb.py screen --raw --smooth 0.7 # true colors, extra calm
python3 keyboardrgb.py screen --saturation 2 --gain 1.3 # vivid and bright
```
## 有趣的命令尝试
复制粘贴以下任意命令。按下 Ctrl-C 即可停止。
### 音频响应（请先播放一些音乐）
```
# 黑洞，宽广的黑暗虚空，极具冲击力
python3 keyboardrgb.py audio --effect vortex --radius 0.4 --gain 1.5
# 霓虹黑洞，热粉色圆环，单一颜色而非 gradient
python3 keyboardrgb.py audio --effect vortex --mode single --color ff0055
# 贝斯涟漪从中心向外呼吸
python3 keyboardrgb.py audio --effect ripple --gain 1.4 --smooth 1.5
# 极具攻击性的跳跃 equalizer，在每一个节拍上猛烈吸附
python3 keyboardrgb.py audio --effect bars --smooth 0.5 --gain 2
# 梦幻的 chill wave，缓慢，丝滑，色彩近乎静止
python3 keyboardrgb.py audio --effect wave --smooth 2.5 --scroll 0.05
# rave mode，快速变化的 gradient 撕裂键盘
python3 keyboardrgb.py audio --scroll 0.6 --gain 1.5
# cyberpunk 青色圆环
python3 keyboardrgb.py audio --effect ripple --mode single --color 00ffcc
# 全天开启：对音乐产生反应，安静时呈现 gradient 的呼吸效果
python3 keyboardrgb.py audio --default breathe
# 先 party 后 chill：充满力量感的 bar，在安静 3 秒后融化成缓慢的 gradient
python3 keyboardrgb.py audio --effect bars --gain 1.8 --default gradient --idle-gap 3
```
### 环境氛围（无需音乐）
```
python3 keyboardrgb.py wave # endless flowing rainbow
python3 keyboardrgb.py gradient ff6a00 8a2be2 # sunset: orange to purple
python3 keyboardrgb.py gradient 001b8a 00ffd5 # deep ocean: navy to aqua
python3 keyboardrgb.py color 00ffaa # solid neon mint
python3 keyboardrgb.py key w ff2200 a ff2200 s ff2200 d ff2200 # gamer WASD
```
### 三个值得尝试的调节参数
- `--gain` 控制强度。`0.5` 比较微妙，`2` 及以上则开始狂野。
- `--smooth` 控制个性。数值低（`0.4`）会显得跳动和干脆；数值高（`2.5`）
则显得如流水般梦幻。
- `--scroll` 控制渐变滚动的速度。`0` 为静止，`0.6` 则是完全的狂欢模式。
你可以将它们与你喜欢的任何 `--effect`（`wave`、`bars`、`split`、`flow`、
`vortex`、`ripple`）以及 `--mode single --color ` 混合使用。建议从 vortex 开始；
在低音强烈的音轨上它的视觉效果最好。
## Web UI（可选）
在 `client/` 目录下还有一个轻量级的浏览器应用。它的真正作用是将 shader 和 canvas 效果传输到键盘上：它运行 GPU shader 组件（如 React Bits 的 Strands、Color Bends、Dark Veil 背景，外加一个内置的渐变实验室），从 `
标签：HID协议, Python, RGB灯效, 外设控制, 无后门, 硬件交互