Next-gen mechanical switch acoustics synthesizer, floating HUD keystroke visualizer, and 87-key typing ergonomics & heatmap analyzer for Windows.
专为 Windows 打造的下一代低延迟机械轴体发声模拟器、置顶全局流光按键 HUD 与 87 键敲击热力图/手速工效分析仪。
-brightgreen.svg){kind=icon}
在现代数字化办公、程序开发、电竞赛事以及教学录屏/直播中，键盘是最核心的人机交互外设。
KeyPulse (按键节拍) 是专为 Windows 平台打造的高保真客制化按键体验增强与人机工效学分析中枢：
- 纯物理声学建模：通过纯数学振荡与衰减包络计算，毫秒级合成青轴、茶轴、红轴、复古打字机及灵动水滴音效，薄膜键盘瞬间拥有客制化机械手感；
- 全局按键悬浮流光 HUD：Windows 置顶亚克力半透视窗，打字或按下组合键（如
Ctrl + C、Alt + Tab、Ctrl + Shift + P）时以现代流光卡片平滑弹出，录屏直播神器； - 87键物理热力图与手部工学：根据击键频次渲染色温梯度（冷蓝 -> 赛博蓝 -> 翡翠绿 -> 琥珀黄 -> 烈焰红），提供左右手触键负荷平衡度与打字手速（WPM / KPS）动态雷达；
- 硬核隐私安全红线 (Zero-Keylogger)：纯本地离线运行，仅在内存统计单键计数值，绝不记录任何连贯字符文本序列，彻底杜绝键盘记录器安全隐患。
- 青轴 (Blue Switch - Clicky)：3.2kHz 极窄金属弹片瞬态爆鸣 + 480Hz 机械腔体微共振，清脆利落；
- 茶轴 (Brown Switch - Tactile)：1.1kHz 柔和段落摩擦音 + 420Hz 减震触底撞击，舒适微段落；
- 红轴 (Red Switch - Linear)：340Hz 低沉饱满木质感 Thock，平滑线性直上直下；
- 复古打字机 (Vintage Typewriter)：清脆金属撞针敲击音，回车键 (Enter) 独家配备经典打字机换行叮当铃声 (Chime Bell)；
- 灵动水滴 (Aqua Bubble)：指数级向上调频正弦水滴啁啾音（Chirp）；
- 大键位定制：空格键 (Spacebar)、退格键 (Backspace)、回车键 (Enter) 配备更深沉的卫星轴共振；
- 有机微扰动 (Organic Jitter)：每次敲击注入 ±4% 的微量自然音量扰动，彻底摆脱机械呆板感。
- 半透明现代卡片：亚克力深色视窗，组合键自动组装为
[Ctrl] + [Shift] + [P]流光胶囊； - 智能过滤模式：
- 全部按键：所有按键均显示；
- 仅快捷组合键 (录课推荐)：日常输入英文或中文时不打扰视线，仅在触发组合键或功能键时浮现；
- 自由拖拽与居中复位：支持按住鼠标左键任意拖曳停靠；
- 智能消隐：0.6s ~ 3.0s 可调淡出时长，打字停顿时自动优雅隐藏。
- 87 键标准 TKL 布局：毫秒级响应每次击键，键帽伴随霓虹青蓝瞬时高亮闪烁；
- 六级热力渐变：0击 (冷灰) -> 1
5击 (深蓝) -> 625击 (赛博蓝) -> 2670击 (翡翠绿) -> 71150击 (琥珀黄) -> 151+击 (烈焰红)； - 左右手受力平衡：根据标准盲打键位分区，实时度量左手区 vs 右手区敲击负荷比；
- 打字手速测速仪：滑动窗口实时测算当前 KPS (Keys/Sec) 与 WPM (Words/Min)，绘制动态波动折线图；
- 安全合规导出：支持一键导出结构化 JSON 报告或 CSV 频次表 (Excel 零乱码)。
- 绝对零文本捕获：内部数据结构仅为哈希映射字典
counts[key_id] += 1，绝不以任何形式拼接、缓存或存储连续键入文本； - 100% 离线脱机：无需网络连接，零网络通信、零端口监听；
- Windows 钩子超轻量化：底层
WH_KEYBOARD_LL仅耗时 < 0.05ms，通过无锁队列解耦，绝对防止 Windows 操作系统因超时强行卸载钩子。
- WASAPI Exclusive 直驱模式：支持 Windows WASAPI 硬件独占流，将声卡缓冲区压缩至 4.3ms 极速响应；
- Windows MMCSS Pro Audio 提权：调用
avrt.dll将混音播放线程注册为Pro Audio实时任务组，抵御高 CPU 占用下的音频撕裂； - 内核时钟微秒级锁定：调用
timeBeginPeriod(1)将 Windows 系统定时器分辨率锁定至 1.0ms，确保每次物理敲击与合成声画严格对齐。
# 1. 克隆本仓库
git clone https://github.com/Luofeng-Cloud/KeyPulse.git
cd KeyPulse
# 2. 安装 Python 核心依赖 (推荐 Python 3.10+)
pip install -r requirements.txt
# 3. 启动主程序
python keypulse_app.py
# 4. (可选) 静默无黑框运行
pythonw keypulse_app.pyKeyPulse/
├── assets/ # 图标与静态音效资源
│ ├── icon.ico # Windows 应用程序图标
│ ├── icon.png # 高清 Logo
│ └── sounds/ # 辅助触觉音效库
├── core/ # 核心底层引擎
│ ├── sound_synthesizer.py # 纯数学物理声学建模 (NumPy 波形程序化合成)
│ ├── sound_player.py # sounddevice 高并发低延迟无锁多声道混音播放器
│ ├── hook_manager.py # Win32 WH_KEYBOARD_LL 无阻塞全局按键钩子
│ ├── stats_engine.py # 击键热力图聚合器、实时 WPM/KPS 与左右手平衡分析
│ └── config_manager.py # 用户偏好原子化持久存储
├── ui/ # 现代化用户界面
│ ├── main_window.py # 现代化控制中枢主视窗
│ ├── overlay_hud.py # 桌面置顶透明半透按键浮现 HUD
│ ├── keyboard_canvas.py # 87键 Tenkeyless 交互式热力图矢量画布
│ └── components.py # 灵动波形显示器、仪表盘、胶囊单选组
├── tests/ # 自动化单元测试套件
│ └── test_keypulse.py # 27 项全面回归测试
├── keypulse_app.py # 应用程序主入口 (单实例互斥、Win32 Per-Monitor DPI 感知)
├── kill_keypulse.py # 靶向安全进程终结脚本
├── create_shortcut.py # 桌面快捷方式生成脚本
├── run_as_admin.bat # 管理员权限启动脚本 (用于捕获以管理员身份运行的窗口按键)
├── run_keypulse.vbs # 0 控制台黑框静默运行脚本
├── requirements.txt # 项目运行依赖声明
├── .gitignore # 严密 Git 过滤规则 (严禁大体积安装包入库)
├── .env.example # 环境变量配置模板
├── LICENSE # MIT 开源授权协议
└── README.md # 项目官方说明文档
项目配备了严格的自动化测试用例，涵盖声学合成振幅边界、无锁混音分发、热力图统计引擎与配置原子持久化：
python -m unittest tests/test_keypulse.py运行结果输出：
Ran 27 tests in 1.55s
OK (All tests passed successfully)
本项目采用 MIT License 开源许可证。
Copyright (c) 2026 Luofeng-Cloud