v1.7.0-prerelease-1
Pre-release
Configuration guide
Link to the appropriate configuration guide version: guide link.
Changelog (since v1.6.1)
Change log
Added: O-(...) for any-order overlapping keys in sequences.
Added: conditional configuration using environment variables via (environment (name val) ...)
Added: allow double-quotes within strings by adding Rust-style strings r#"<content>"#. Potentially breaking, but seems doubtful that anyone has a good reason to be doing this
Added: --log-layer-changes flag to override false configuration temporarily for testing
Added: parse numbers as a delay (unit milliseconds) for cmd-output-keys
Added: unmod can accept a modifier list as the first parameter to selectively undo only some modifiers
Added: option to eagerly release override output to help with some use cases
Added(Windows): capability to use Kanata as a library for AHK
Added(Windows): GUI tray app (gui variants of the executable)
Added(Windows-Interception): add device exclusion (include by default) in defcfg
Added(Linux): linux-use-trackpoint-property for middle mouse scrolling on ThinkPads
Added(macOS): unicode action is now implemented
Added(macOS): mouse actions are now implemented (some bugs still exist)
Fixed: chordsv2 now eagerly activates tap-hold-press|release
Fixed: block-unmapped-keys now only blocks unspecified actions, where before it would block explicitly transparent keys as well
Sample configuration file
The attached kanata.kbd file is tested to work with the current version. The one in the main branch of the repository may have extra features that are not supported in this release.
Windows
Instructions
NOTE: All Linux binaries are compiled for x86-64 architectures only.
Download kanata.exe. Optionally, download kanata.kbd. With the two files in the same directory, you can double-click the exe to start kanata. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for tips to run kanata in the background.
You need to run kanata.exe via cmd or powershell to use a different configuration file:
kanata.exe --cfg <cfg_file>
NOTE: The kanata_winIOv2.exe variant contains an experimental breaking change that fixes an issue where the Windows LLHOOK+SendInput version of kanata does not handle defsrc consistently compared to other versions and other operating systems. This variant will be of interest to you for any of the following reasons:
- you are a new user
- you are a cross-platform user
- you use multiple language layouts within Windows and want kanata to handle the key positions consistently
This variant contains the same output change as in the scancode variant below, and also changes the input to also operate on scancodes.
The gui variants only use the winiov2 I/O mechanism.
NOTE: The kanata_legacy_output.exe variant has the same input defsrc handling as the standard kanata.exe file. It uses the same output mechanism as the standard kanata.exe variant in version 1.6.1 and earlier. In other words the formerly experimental_scancode variant is now the default binary. The non-legacy variants contain changes for an issue; the fix is omitted from this legacy variant. The legacy variant is included in case issues are found with the new output mechanism.
Linux
Instructions
NOTE: All Windows binaries are compiled for x86 architectures only.
Download kanata.
Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup. See this discussion for how to set up kanata with systemd.
chmod +x kanata # may be downloaded without executable permissions
sudo ./kanata --cfg <cfg_file>`
To avoid requiring sudo, follow the instructions here.
macOS
Instructions
WARNING: feature support on macOS is limited.
For macOS 11 and newer:
- Install the Karabiner VirtualHiDDevice Driver.
To activate it:
/Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
For macOS 10 and older:
- Install the Karabiner kernel extension.
After installing the appropriate driver for your OS
Download a kanata_macos variant.
Run it in a terminal and point it to a valid configuration file. Kanata does not start a background process, so the window needs to stay open after startup.
Example
chmod +x kanata_macos_arm64 # may be downloaded without executable permissions
sudo ./kanata_macos_arm64 --cfg <cfg_file>`
cmd_allowed variants
Explanation
The binaries with the name cmd_allowed are conditionally compiled with the cmd action enabled.
Using the regular binaries, there is no way to get the cmd action to work. This action is restricted behind conditional compilation because I consider the action to be a security risk that should be explicitly opted into and completely forbidden by default.
wintercept variants
Explanation and instructions
Warning: known issue
This issue in the Interception driver exists: oblitum/Interception#25. This will affect you if you put your PC to sleep instead of shutting it down, or if you frequently plug/unplug USB devices.
Description
These variants use the Interception driver instead of Windows hooks. You will need to install the driver using the assets from the linked website or from the copy in this repo. The benefit of using this driver is that it is a lower-level mechanism than Windows hooks. This means kanata will work in more applications, including administrator-privileged apps.
Steps to install the driver
- extract the
.zip - run a shell with administrator privilege
- run the script
"command line installer/install-interception.exe" - reboot
Additional installation steps
The above steps are those recommended by the interception driver author. However, I have found that those steps work inconsistently and sometimes the dll stops being able to be loaded. I think it has something to do with being installed in the privileged location of system32\drivers.
To help with the dll issue, you can copy the following file in the zip archive to the directory that kanata starts from: Interception\library\x64\interception.dll.
E.g. if you start kanata from your Documents folder, put the file there:
C:\Users\my_user\Documents\
kanata_wintercept.exe
kanata.kbd
interception.dll
kanata_passthru.dll
Explanation and instructions
The Windows kanata_passthru.dll file allows using Kanata as a library within AutoHotkey to avoid conflicts between keyboard hooks installed by both. You can channel keyboard input events received by AutoHotkey into Kanata's keyboard engine and get the transformed keyboard output events (per your Kanata config) that AutoHotkey can then send to the OS.
To make use of this, download kanata_passthru.dll, then the simulated_passthru_ahk folder with a brief example, place the dll there, open kanata_passthru.ahk to read what the example does and then double-click to launch it.
sha256 checksums
Sums
5d3245e092e5b4f0d42669cbe666210bccbfcc11fe700f8d3b3e0c475aef3cfd kanata
fb58bbdc83f151199a0a990657f403baf08ddda532f1fe552f4e37db88671e8b kanata.exe
f7e1543ffb7c2a610c60822b753d78c29e0ac501806ea3aba5192cecac02cb25 kanata.kbd
f290678681e91688a4ee662bdd3f3f03ccf7ba54e9b9683ffe0e96ab49cbe000 kanata_cmd_allowed
09c9119d8cd3df67a47cb040028977e26ba938572128eb1b2887baf0ed9f9d76 kanata_cmd_allowed.exe
36857288e9df2227b4378013998af64a0241a6f50d99a514cb8fe9be70fd5914 kanata_gui.exe
3669ebde601388cd2bcb3e9389be0c00b283520cad457211023e87854426dfa1 kanata_gui_cmd_allowed.exe
3669ebde601388cd2bcb3e9389be0c00b283520cad457211023e87854426dfa1 kanata_gui_wintercept.exe
b1acef7457be03e0143a3d8f5cfb0c43a63eb79ee20338a7ccdde33b96633316 kanata_gui_wintercept_cmd_allowed.exe
3c7ee427208886c7269cc1483abf363b3ce09f9105b5579fe59ba3416d997360 kanata_legacy_output.exe
cb7643f72801f124935692fd7b632a0df904a1c07e27f1188605048862ebdd23 kanata_macos_arm64
5509b1bf491287408e903fc729f6d3ad03643997f2b1ebdf088857aa098920b0 kanata_macos_cmd_allowed_arm64
c8345c43d2304ba8b9af1b5e7b8c2187705329532d02aa43611f8ecfca8d6288 kanata_macos_cmd_allowed_x86_64
69ad95857db5d33ec3170f4ad0acf535dea9e340e1962979ab2368a77e603360 kanata_macos_x86_64
33144159cef3b8d4e2a45d3b9ce58c763bf188f8ca6b86029dfbfea9d2dabbce kanata_passthru.dll
8205ffb13bcd15a949d4c93d28d4c1fd48d1d749335cc7dedd566e549faaeec3 kanata_winIOv2.exe
9c07873c0fee8b23cbda2328d326290ab4f6bd13e7367cb5dcdb8120f66febc5 kanata_wintercept.exe
7e05bc70af1a82b529c89df7566fb98cb8cc2957249a731c92c68c3afcb32b6c kanata_wintercept_cmd_allowed.exe