qmk/qmk_firmware

[Bug] Early release of Tap-Hold key when tap.count > 1

Open

#25,647 opened on Sep 11, 2025

View on GitHub
 (3 comments) (0 reactions) (0 assignees)C (20,368 stars) (43,867 forks)batch import
bughelp wanted

Description

Describe the Bug

When chaining a quick double tap of a Tap-Hold key with a tap of an other Tap-Hold key, the firmware releases the double tapped key before that key is physically released, and then triggers an extra key release when the key is physically released (see attached debug report). I added a debug entry in process_record_user to get a better sense of what's happening. As you can see, on line 40, the quickly double tapped key is released early by the firmware while the physical key is still pressed. At the end of the report, on line 70, when the physical key is released, the firmware processes an extra key release.

report.txt

Keyboard Used

No response

Link to product page (if applicable)

No response

Operating System

No response

qmk doctor Output

Is AutoHotKey / Karabiner installed

  • AutoHotKey (Windows)
  • Karabiner (macOS)

Other keyboard-related software installed

No response

Additional Context

I started to fix this, taking advantage of the registered_taps buffer (currently only used by the chordal hold and flow tap features). I had to extend the data type of the buffer to also remember the current tap count.

One issue I'm currently facing is when a combo resolves to a Tap-Hold keycode. In that case the keypos of the corresponding keyreport is set to (0,0), clashing with the key at that position and making it impossible to uniquely identify different combos. My dirty solution to that problem is to "cast" the combo index into a keypos, just before calling action_tapping_process from release_combo and dump_key_buffer, and then check the type of event I'm dealing with to choose how to interpret the keypos value stored in registered_taps.

Here is a link to the changes I made so far: https://github.com/qmk/qmk_firmware/compare/master...shards-of-wisdom:qmk_firmware:fix-quick-tap.

P.S.: this my first time contributing to an open source project.

Contributor guide

Tech stack
c
Domain
backend
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
active
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
QMK firmware developmentC programmingUnderstanding of tapping and combo logic
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
45
Research direction
Review the current tapping logic in the QMK firmware, particularly the handling of Tap Hold keys and the registered taps buffer. Examine the author's branch at https://github.com/qmk/qmk firmware/compare/master...shards of wisdom:qmk firmware:fix quick tap to understand the proposed changes and the remaining issue with combos. The problem involves correctly identifying the key when a combo resolves to a Tap Hold keycode, where keypos is set to (0,0). A possible solution is to cast the combo index into a keypos in release combo and dump key buffer, then check the event type to interpret the stored keypos.