Concurrent Macros for QMK

This Concurrent Macros QMK community module provides a macro capability that's better suited to game playing than the core QMK does. Features:

• Multiple macros can run simultaneously. This is limited only by the user-modifiable MAX_CONCURRENT_MACROS (default 10)
• Macros can set to repeat continuously, either in a toggle on/off mode, or while the key is held down
• The repeatable section of a macro can be preceded by an optional preamble and followed by an optional postamble that only run once per macro activation
• An optional animation flashes the key that triggered the macro while the macro is running, returning to the normal backlight level when the macro is done
• Macro definition is compatible with the current VIA launcher without any modifications

Macro definition

Special rarely-used keycodes are used to tell concurrent macros to repeat and how.

• KC_F21 : start macro repeat section.
• KC_F22 : repeat the keys/delays between KC_F21 and KC_F22 while the macro key is held down (momentary mode)
• KC_F23 : stop all other running macros immediately, and clear the keyboard state
• KC_F24 : repeat the keys/delays between KC_F21 and KC_F24 until the macro key is pressed again (toggle mode)

The "grammar" of a repeatable macro looks like this:

[ preamble keys/delays {KC_F21} ] repeated keys/delays {KC_F24} | {KC_F22}[ postamble keys/delays ]

So for example, let's say you want the macro to start with "abc" then repeat the string "def" as long as you hold the key down, then when you release it, it sends "ghi". To do this you create a macro like this:

abc{KC_F21}def{KC_F22}ghi

Notes:

• If you don't need a preamble, you just omit that part and also the {KC_F21}. In this case, {KC_F22} and {KC_F24} will repeat from the beginning of the macro.
• If you don't need a postamble, just omit that part.
• If you don't want a repeat section, just don't use any of the special keycodes at all.
• A maximum of one preamble, one repeat section, and one postamble is allowed. The code will catch most incorrect usages of the special keycodes, and then enter an error state. If you have the animation activated, an error is displayed as a rapidly blinking key.
• When a macro is in the error state, you can use VIA to correct the macro content, and then you can retrigger the macro to try again.

Concurrency is the devil's play toy

One thing to be mindful of is that if you activate modifier keys, such as Shift, Ctrl, Alt, AltGr, and GUI, those modifiers will affect other currently running macros as well as anything you may be typing at the moment (even on a different keyboard). So it is a very good practice to completely avoid using modifier keys in macros, unless you are running only the one macro and not providing any other keyboard input while it runs, for example you are using a single macro in a repeat mode, and not touching any other keys.

Also keep in mind that if you manually use any modifier keys while a macro is running, it will affect keys being received by the computer. For example if you have a macro that is continuously sending "a", and then while it's running, you hold down the shift key, the computer will start seeing repeated "A" keys.

Configuration

Set up the macro capability

The QMK source tree you use must have the Community Modules feature, because the Concurrent Macros module utilizes it. At the time of this writing (2025/02/27), the community modules feature is now available in the master branch of QMK. If you are not using the upstream QMK git tree, you'll need to figure out which branch (if any) will work with this community module. The git tree needs to have merged from upstream since March of 2025. For Keychron's tree specifically, use the 2025q3 branch. To get the latest source code, run these commands:

git checkout master  // see above for which branch to use
git pull origin master

To install the module, run these commands:

cd modules
git submodule add https://github.com/yeroca/qmk_concurrent_macros.git

Add to your info.json or keyboard.json file the following:

"modules": ["qmk_concurrent_macros/concurrent_macros"]

Optional: Set up the animation

Monochrome LED keyboards

If you have a keyboard with monochrome (single-color) LEDs which are individually controllable, add the following to your info.json or keyboard.json file in the modules key:

"qmk_concurrent_macros/concurrent_macros_led_matrix"

For example:

"modules": [
        "qmk_concurrent_macros/concurrent_macros",
        "qmk_concurrent_macros/concurrent_macros_led_matrix"
],

To your keyboard's info.json or keyboard.json file, add the following line inside of the "led_matrix" / "animations" section:

"concurrent_macros": true,

Optionally, you might want to:

• Make concurrent macros the default animation by adding/setting this define in your keyboard's config.h file:

#define LED_MATRIX_DEFAULT_MODE LED_MATRIX_COMMUNITY_MODULE_CONCURRENT_MACROS

RGB LED keyboards

If you have a keyboard with RGB LEDs which are individually controllable, add the following to your info.json or keyboard.json file in the modules key:

"qmk_concurrent_macros/concurrent_macros_rgb_matrix"

For example:

"modules": [
        "qmk_concurrent_macros/concurrent_macros",
        "qmk_concurrent_macros/concurrent_macros_rgb_matrix"
],

To your keyboard's info.json or keyboard.json file, add the following line inside of the "rgb_matrix" / "animations" section:

"concurrent_macros": true,

Optionally, you might want to:

• Make concurrent macros the default animation by adding/setting this define in your keyboard's config.h file:

#define RGB_MATRIX_DEFAULT_MODE RGB_MATRIX_COMMUNITY_MODULE_CONCURRENT_MACROS

In order to get the concurrent macros animation option to show up in VIA, you'll need to modify your keyboard's VIA .json file to add (and possibly remove) the animations in the list, adjusting the index numbers appropriately. The concurrent macros animation will appear after the QMK included animations, but before the keyboard-specific animations. For example, Keychron added a keyboard-specific animation called "Per-key RGB", which appears near the end of the list, so you'd need to add the concurrent macros animation before that one.

For both monochrome and RGB keyboards you might want to:

• Set other undesired/unused animations to false in your info.json or keyboard.json file
• Modify your keyboard layout .json file that is used by VIA to add this lighting animation option and remove any ones that you set to false in info.json or keyboard.json.
• Modify the blink rate for the monochrome LEDs or the color cycle rate for the RGB LEDs by adding this definition to your keyboard's config.h file:

#define COMMUNITY_MODULE_CONCURRENT_MACROS_RATE_ADJ rate_adjustment

where rate_adjustment is a small integer that adjusts upward or downward the rate of blinking/color cycling. Positive integers speed up the rate by powers of two, while negative integers slow down the rate by powers of two. So for example:

#define COMMUNITY_MODULE_CONCURRENT_MACROS_RATE_ADJ 1

doubles the speed, whereas:

#define COMMUNITY_MODULE_CONCURRENT_MACROS_RATE_ADJ -2

cuts the speed by a factor of four.

To make the arithmetic efficient, only powers of two speed changes are possible currently.

Special keycodes can be changed

If your game (or other application) uses F21 through F24 for some purpose, and you want your macro to emit those keycodes, you'll need to change concurrent macros' special keycodes by adding new definitions in your keyboard's config.h file. The defaults are shown below:

#define KC_HARD_STOP_OTHER_MACROS KC_F23
#define KC_REPEAT_UNTIL_TOGGLE_OFF KC_F24
#define KC_REPEAT_UNTIL_MACRO_KEY_UP KC_F22
#define KC_START_REPEAT KC_F21