# kbd-debounce

**Repository Path**: aeix/kbd-debounce

## Basic Information

- **Project Name**: kbd-debounce
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

* kbd-debounce

键盘按键抖动的去抖过滤工具。监听 keyd 虚拟键盘，过滤指定按键
的抖动（chatter），转发干净的事件到新的 uinput 设备。

** 原理

使用 **Eager Press + Deferred Release** 算法（与 interception-tools 相同）：

- **按下**: 立即转发（不延迟，手感无延迟）
- **弹起**: 不立即转发，等待 debounce_ms (默认 50ms)
  - 等待期间如果收到同键「按下」→ 之前的弹起是抖动，取消等待
  - 等待到期没有「按下」→ 弹起是真实的，转发
- **安全保卫**: 按键超过 max_hold_ms (默认 10 秒) 无弹起则强制释放
  - 键盘整体空闲超过 2 秒时，保卫缩水到 500ms（防止手离开后卡键）

这个算法通过 interception-tools debounce 验证，是 Linux 下处理键盘
抖动的标准方案。

#+begin_src text
Apple SPI Keyboard → keyd → keyd virtual keyboard → kbd-debounce → kbd-debounced → Hyprland
                                   ↑ grabbed

事件流 (以 H 键为例):

  按下 H:
    1. val=1 (按下)          → 立即转发             → 输出 1 个 h
    2. val=0 (抖动弹起)      → 延迟 30ms
    3. val=1 (抖动按下)      → 取消延迟，键保持按下   → 不多输出
    4. val=0 (抖动弹起)      → 延迟 30ms
    ... 最终键稳定按下

  抬起 H:
    1. val=0 (释放开始)      → 延迟 30ms
    2. val=1 (抖动按下)      → 取消延迟，键仍按下     → 不多输出
    3. val=0 (真实弹起)      → 延迟 30ms
    4. 30ms 内无新按下       → 转发弹起             → 停止输出
#+end_src

** 安装

#+begin_src sh
# 直接编译安装
make && sudo make install

# 或打 pacman 包
makepkg -si
#+end_src

** 启动

#+begin_src sh
systemctl --user enable --now kbd-debounce.service
#+end_src

** 配置

去抖参数通过环境变量设置（无需重新编译）：

| 变量 | 含义 | 默认值 |
|------|------|--------|
| =KBD_DEBOUNCE_35= | 弹起延迟时间 (ms) | 50 |
| =KBD_DEBOUNCE_MAX_HOLD= | 最大按住时间 (ms), 0=禁用 | 10000 |

其中 =35= 是 KEY_H 的键码。可以在服务文件中设置：

#+begin_src ini
[Service]
# H 键弹起延迟改为 60ms
Environment=KBD_DEBOUNCE_35=60
# 最大按住时间改为 5 秒
Environment=KBD_DEBOUNCE_MAX_HOLD=5000
#+end_src

编译时默认值在 =kbd-debounce.c= 的 =DEBOUNCE_KEYS= 数组中：

#+begin_src c
static struct debounce_key DEBOUNCE_KEYS[] = {
    { KEY_H, 50 },  /* H 键, 50ms 弹起延迟 */
};
#+end_src

** 项目结构

| 文件 | 说明 |
|------|------|
| =kbd-debounce.c= | C 源码 |
| =kbd-debounce.service= | systemd 用户服务 |
| =PKGBUILD= | Arch Linux 打包 |
| =Makefile= | 编译安装 |