TempoClick

音乐律动敲击器项目根目录。包含**上位机（PC 端软件）与固件（STM32）**两部分。

详细使用说明见 docs/README.md，通信协议见 docs/PROTOCOL.md。

---

目录结构

KEYHUB/
├── app/                 # 上位机控制软件
│   ├── tempo_tool.py    # 主程序入口（python app/tempo_tool.py, PyQt6）
│   ├── device.py        # 共享 HID 设备层
│   ├── beat.py          # 节拍检测模块
│   ├── keypanel.py      # 按键协议逻辑（键名表/文本↔HID码/KeyActions）
│   ├── keypanel_qt.py   # 按键设置界面（7键输入框 + 可视化键盘）
│   ├── keyboard_widget.py # 可视化键盘控件（自绘, 点击插入按键）
│   ├── qt_widgets.py    # 通用Qt控件（背景图/波形/自绘标题栏）
│   ├── theme.py         # 主题配色（预设+自定义覆盖）
│   ├── settings.py      # 配置持久化（config.json + 开机自启注册表）
│   ├── tray.py          # 系统托盘图标（Qt 原生 QSystemTrayIcon）
│   ├── colorpicker_qt.py # 自绘颜色选择器
│   ├── app_icon.ico     # 应用图标（exe 打包用）
│   ├── app_icon.png     # 应用图标（窗口/托盘运行时加载）
│   ├── default_bg.jpg   # 内置默认背景图（打包随附）
│   ├── TempoClick.spec  # PyInstaller 打包配置
│   ├── build_release.bat # 一键发布脚本
│   └── dist/            # 发布目录（TempoClick.exe）
├── docs/                # 文档：README、PROTOCOL、BOM、原理图
├── TempoClick/          # STM32 固件工程（STM32F1，Keil，CubeMX 生成，已并入本仓库）
├── aubio_patch/         # aubio 源码树副本（构建参考，不入版本库）
└── README.md

上位机源码（app/）

文件	作用
tempo_tool.py	主程序入口。PyQt6 三标签页 GUI：「按键设置」+「音乐检测」+「设置」；无边框窗口+自绘标题栏
device.py	共享 HID 设备层。统一管理 USB Vendor 接口通信（RLock 防并发、send2/send16、自动重连、读独占）
beat.py	节拍检测模块。声卡环回捕获 + aubio 频谱通量算法检测节拍、估算 BPM、实时音量、超时归零
keypanel.py	按键协议逻辑。键名映射表、文本↔HID码转换、KeyActions（改键协议）
keypanel_qt.py	按键设置界面。上半 7 键输入框（点击选中高亮）+ 下半可视化键盘，操作按钮
keyboard_widget.py	可视化键盘。QPainter 自绘精简键盘（字母/数字/F键/方向键），点击插入到当前编辑键位
qt_widgets.py	通用控件。BackgroundWidget（背景图缩放铺满+压暗+圆角描边）、WaveWidget（音频波形）、TitleBar（自绘标题栏，支持拖动）
theme.py	主题系统。5 套预设配色（Catppuccin/Dracula/Nord/Rose Pine/Everforest）+ 自定义颜色覆盖
settings.py	配置持久化。JSON 配置读写 + 开机自启动（注册表 Run 键）
tray.py	系统托盘。Qt 原生 QSystemTrayIcon，显示窗口/退出菜单
colorpicker_qt.py	自绘颜色选择器。受主题控制、带描边，替代原生对话框
app_icon.ico/.png	应用图标。exe 打包（.ico）与窗口/托盘（.png）使用，替换文件即可更换图标
default_bg.jpg	内置默认背景图。首次启动/清除自定义背景后显示，打包随 exe 携带

依赖关系：tempo_tool.py → 其余全部模块；keypanel_qt.py/keyboard_widget.py → keypanel.py；beat.py → device.py；tempo_tool.py/qt_widgets.py → theme.py

发布与打包（app/ 内）

文件	作用
build_release.bat	一键发布脚本。双击自动重新打包 exe 到 dist/，保证 dist/ 始终是最新发布物
TempoClick.spec	PyInstaller 打包配置文件（--onefile 单文件模式）
dist/	发布目录。含 TempoClick.exe（打包好的程序，拷给别人双击即用）

---

功能一览

• 🎵 节拍检测：声卡环回实时检测节拍、估算 BPM、驱动固件音柱；歌曲结束自动归零
• 🖥️ 按键自定义：7 键配置单键/组合/宏，固件 Flash 持久化
• ⌨️ 可视化键盘：下半区自绘真实键盘，点击按键自动插入到当前选中的键位输入框（支持 Ctrl/Shift/Win/Alt 修饰键）
• 🪟 无边框窗口：去掉系统标题栏，背景图铺满整个窗口顶部；自绘标题栏（圆角+描边，可拖动，最小化/关闭按钮）
• ⚙️ 设置页：音乐检测参数（音量节流/平滑/超时）、系统监控开关、启动与托盘、主题
• 🎨 主题系统：5 套知名配色一键切换，支持自定义颜色（自绘选色器）
• 🖼️ 背景图：任意图片做窗口背景（压暗程度可调），内置默认背景图，设置页随时更换
• 🚀 开机自启：注册表自启动，后台运行不弹窗
• 📌 系统托盘：关闭窗口最小化到托盘，后台继续运行（托盘菜单真正退出）
• 🔒 单实例：重复启动自动唤醒已有窗口（隐藏到托盘也能唤出），不再弹框提示
• ⟳ 一键刷新：连接状态 + 刷新按钮固定在标签栏右侧

快速使用

最终用户：拷 app/dist/TempoClick.exe 到任意电脑，双击即用（无需安装 Python）。

开发者（两个 bat，区分用途）：

• 开发调试：双击根目录 开发运行.bat —— 直接跑源码（python app/tempo_tool.py），秒开、不用打包，改完代码重启即生效
• 发布给别人：双击 app/build_release.bat —— 才需要打包 exe 到 app/dist/

固件开发：进入 TempoClick/（注意：Core/ 下 CubeMX 生成区勿手动改，改 Drivers/ 自建文件）。

界面说明

窗口为无边框圆角卡片，背景图铺满整个窗口顶部，左上角自绘标题栏：

• 拖动窗口：按住标题栏空白处（含 "TempoClick" 标题文字）拖动
• 最小化（─）：最小化到任务栏
• 关闭（✕）：最小化到系统托盘（后台继续跑节拍检测）；真正退出用托盘菜单「退出」

三个标签页：

标签页	内容
按键设置	上半：7 键位输入框（点击选中高亮，可滚动）；下半：可视化键盘（点击按键插入到当前选中的键位）；顶部：全部下发 / 读取当前映射 / 恢复默认
音乐检测	状态条、BPM/节拍数/设备值、开始/停止/麦克风选择、实时波形
设置	音乐检测参数、系统监控、启动与托盘、背景图、主题

依赖安装

pip install hidapi numpy soundcard aubio psutil PyQt6 pyinstaller

库	用途	缺失时影响
hidapi	USB HID 通信	上位机无法连接设备
numpy	频谱计算（节拍检测/波形）	音乐检测无法启动
soundcard	声卡环回捕获	音乐检测无法启动
aubio	节拍检测算法	音乐检测无法启动
psutil	系统监控（CPU/内存/网络）	该功能静默禁用，其他功能不受影响
PyQt6	GUI 框架（窗口/控件/背景图/托盘）	程序无法启动
pyinstaller	打包 exe（仅开发需要）	无法打包

PyQt6 为 GUI 框架（替代原 tkinter），并原生支持系统托盘（不再需要 pystray/Pillow）。

运行 python app/tempo_tool.py 时如缺库，缺失项仅影响对应功能（除 hidapi 外均可降级运行），GUI 仍能打开。

---

更新历史

• 2026-08（最新）：
  • 界面：无边框窗口 + 自绘标题栏（背景图铺满顶部、圆角描边、可拖动、最小化/关闭按钮）；关闭按钮最小化到托盘、真正退出走托盘菜单
  • 按键设置：全新可视化键盘（点击插入按键），支持 Ctrl/Shift/Win/Alt 修饰键；7 键输入框点击选中高亮、可滚动；F1~F12 每 4 个分组、顶排与数字行对齐；右 Shift 移除、方向键对齐
  • 背景图：内置默认背景图（打包随附），清除背景后回到默认图
  • 音乐检测：布局压缩防重叠；过滤节拍线程重复状态文本（BPM/节拍数/设备只显示一次）
  • 稳定性：修复退出残留（补 QApplication.quit() 结束事件循环）、单实例改为唤醒已有窗口（隐藏到托盘也能唤出）、键盘控件渲染崩溃（sizeHint/浮点坐标）
• 2026-08（早期）：上位机大规模迭代 —— 新增设置页（音乐检测参数/系统监控/启动托盘/主题）、5 套知名主题配色 + 自定义颜色、自绘颜色选择器、开机自启动、系统托盘、单实例锁、自定义标签栏（刷新按钮固定）、可滚动设置页、连接状态置顶；修复音柱消失（平滑公式）、BPM 显示 --（FFT 滤波 + 回调遗漏）、回读丢包（固件逐包等待 + 上位机解析）、节拍数不归零；固件回读丢包修复并 DAP 烧录。