Skip to content

v1.8.0-prerelease-1

Pre-release
Pre-release
Compare
Choose a tag to compare
@jtroo jtroo released this 11 Dec 08:34
· 44 commits to main since this release
v1.8.0-prerelease-1
c5e9e19

Configuration guide

Link to the appropriate configuration guide version: guide link.

Changelog (since v1.7.0)

BEHAVIOUR CHANGE (Linux): defcfg to include device names now disregards mouse-like/keyboard-like check, now grabbing more devices than previously

Change log
  • Added: use-defsrc action
  • Added: zippychord-experimental, yet another chording implementation
  • Added: chordsv2 is no longer marked experimental; using -experimental now generates an error
  • Added: macro variant that cancels on another press
  • Added: hold-for-duration action for virtual keys
  • Added: one-shot-pause-processing action
  • Added: all-except configuration for process-unmapped-keys
  • Added(macOS): now uses the v5 karabiner driver
  • Fix(Windows): keypad enter now works when passed through without remapping
  • Fix(macOS): mouse drag now works

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 Windows 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.

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 Linux 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.

Install Karabiner driver for macOS 11 and newer:

To activate it:

sudo /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate

Then you need to run the daemon. You should run this in the background somehow or leave the terminal window where you run this command open.

sudo '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-VirtualHIDDevice-Daemon.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Daemon'

Install Karabiner driver for macOS 10 and older:

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>`

If the above shows Kanata running but keys are not being sent, you may need to add permissions: #1211.

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 release 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.

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 
f2b611dfd8f24be77550d94f1a962240abbde6a91651e6d40abf9a2bc6774753  kanata
0c1861bbb950264811601a4ff15562b2e3bd53ced7736fc0e5426b3a2bf0f5bd  kanata.exe
578de9340f710a687a68562cac11667f1be66bcbc9f2a863d75eb6102670e4ff  kanata.kbd
49efab53c96f685f2149cb12dc8be7cc4671616916104215967dd8112cd89420  kanata_cmd_allowed
405b54709a7745464dab0fe959d002cfb88f7b6922503c2bf2347caee8b09dfc  kanata_cmd_allowed.exe
83343f798edb4ecfd0837946eb7b5c153960ac07eda2292ea306a37ad2e05848  kanata_gui.exe
29c92373971275a06815eff530e7cd722438871123d8210ff49f7b4ef1cdbccb  kanata_gui_cmd_allowed.exe
19ca1458d79bf66d0631dedc577ce08f62e3bb8b1d5bb586ac1671804339512c  kanata_gui_wintercept.exe
0a148987272028f22b6eb0a1b753b843f6e237aa39ff243d694b4ef9302e5bd5  kanata_gui_wintercept_cmd_allowed.exe
c6b6009ed79d919bf2f5b7c0cc3df2fbd20fdb68d63e6e900efb42f1cfb68f97  kanata_legacy_output.exe
c0c4b88eb026f9767ac626b5950c0d4c423e52d37d05d54d0d328e4c1e30bbba  kanata_macos_arm64
bdf52fe6610d60fc49eb055ad6ed9361a9119075c9b164a6cf29d12bf515254b  kanata_macos_cmd_allowed_arm64
08446f4c646748233c2aafa73d2aafa019745f532ceb6d7930366c0b5b893015  kanata_macos_cmd_allowed_x86_64
f827fdd8c8260ae94b033ddb2213a8bbf2c377047679de11f649efa32fd91be6  kanata_macos_x86_64
78fc5b925ec0b0bff5e0ec60e19f02dedc17c4a93c49af059d6d34788b3d76d5  kanata_passthru.dll
46ea129bfdb970b9a7be5e2868be97a2a248ff137718777eedbbb83df9f88fa7  kanata_winIOv2.exe
12c8f75d8a0c207c9fb1c6176be20be1e848159a59f54eace2692c9095e85b89  kanata_wintercept.exe
9956313ffefa0a4168ab02a09f8ac4805be437bcc4d557458c6e593a8c63445d  kanata_wintercept_cmd_allowed.exe
Assets 21
Loading