Recently I bought a mechanical keyboard, the Qisan Magicforce 68. A nice compact keyboard with proper arrow-keys. Disadvantage, it has a PC layout and a combined Escape, grave accent and tilde key.
The Window (❖)- and Command (⌘) key both send the same USB scancode. Same for the Option (⌥) key on an Apple keyboard and the Alt key on PC keyboards, both send the same USB scancode. Functionally everything is there but at the wrong place on the keyboard. When muscle memory kicks-in it results in unexpected behaviour.
Without remapping the Windows key acts as a Mac Option/Alt (⌥) key and the PC Alt key acts as a Mac Command (⌘) key. Very confusing.
The Magicforce 68 is a mechanical keyboard with replaceable keycaps, swapping the physical keys was easy. At least the “Alt” key has some similarity with the “Option/Alt” (⌥) key. Looking at the possibilities of remapping the keys in software there are different ways with different options.
I could have sticked to the simplest option and just change the modifier keys within macOS but I already played with remapping my Capslock (⇪) key to Escape (⎋) and read about the possibilities of using the Capslock (⇪) key as a “Hyper” key. A slippery slope …
In this post I will write about the tools and native ways I encountered to customize my keyboard. In a follow-up post I will describe my personal setup.
macOS: Remapping modifier keys
By far the easiest way to swap the behaviour of these two keys is already built into the operating system. OSXDaily has a nice page on remapping the keys.
The tools are already available in macOS. Go to your System Preferences and select the Keyboard.
Click on the “Modifier Keys…”.
Select the PC keyboard from the dropdown menu at the top and swap the Option (⌥) and Command (⌘) keys. Done!
In the image above the Caps Lock (⇪) Key is set to “No Action”. Please ignore this for now, this is part of my personal configuration and described in the follow-up post.
- Pro
- One-trick-pony, simple, clean and easy to implemement
- No external dependencies
- One-trick-pony, simple, clean and easy to implemement
- Con
- Only applies to modifier keys
- No other keybindings possible
macOS: Change default keybindings
This option does not enable you to swap the modifier keys, but does offer you a way to natively set keybindings on macOS.
The keybindings on macOS can be modified through the file ‘DefaultKeyBindings.dict’ in the directory ‘~/Library/KeyBindings’. By default the directory and file do not exist.
To play around with it you have to create the file ‘~/Library/KeyBindings/DefaultKeyBinding.dict’. As an example you can add the following text:
/* set coding to utf-8 to use Unicode characters */
/* Character | Meaning */
/* --------- | ------------------ */
/* ~ | Option key */
/* $ | Shift key */
/* ^ | Control key */
/* @ | Command key */
/* # | keys on number pad */
{
/* Use Control-Option-x to insert exploding-head emoji */
"^~x" = ("insertText:", "🤯");
}
Now when you open a file-editor or any other text-input field using the key combination Control (⌃) + Option (⌥) + ‘x’ results in an exploding head emoji.
Additional info on macOS keybindings:
- developer.apple.com - Text System Defaults and Key Bindings
- xahlee.info - macOS: create Custom Keyboard Layout
- xahlee.info - Mac OS X Keybinding Key Syntax
- github/ttscoff - ttscoff/KeyBindings
This is an interesting native solution to (re)bind keys. The keybindings work for most applications, some applications have specific keybindings that overrule these keybindings.
- Pro:
- Native solution to (re)bind keys
- Relative simply to implement without external dependencies
- Con:
- Keybindings work for all applications and text-input fields
- Restricted to keybindings of regular keys, does not work for modifier keys
- No “hyper”-key or other advanced scripting possibilities
macOS: Applescript
Just after I finished part 2 I found Doug’s AppleScripts page on how to remap keys in AppleScript. The content of the page might be outdated the basic thought is the same.
Due to the “per app” restrictions not very usable.
- Pro:
- Native solution to remap keys
- No external dependencies
- Con:
- Requires some programming skills
- Access must be set on a per-app basis.
Karabiner-Elements
Karabiner-Elements is a powerful and stable keyboard customizer for macOS.
A brief overview of its core features:
- Simple Modifications: Change normal keys to other keys
- Complex Modifications: Change keys by complex rules
- Function Keys: Change f1-f12 keys to media controls
- Devices: Apply modifications to specified keyboards only
- Profiles: Support multiple profiles
- Modifier Flag Sync: Synchronize modifier flags across all connected keyboards
- Secure Keyboard Entry Support: Work well on Secure Keyboard Entry environment such as a password prompt, terminal with Secure Keyboard Entry, etc
Installation can be simply done with homebrew:
brew cask install karabiner-elements
Karabiner-Elements uses low-level kexts to capture the keyboard input. During the installation you need to allow “Input Monitoring” for the Karabiner sub-apps karabiner_grabber and karabiner_observer. Without the permissions for these sub-apps Karabiner-Elements will not function properly. Just follow the installation instructions of the Karabiner- Elements documentation
Swapping the left Option (⌥) and left Command (⌘) keys can be done via the GUI in the “Simple modifications” tab:
- Click on the “Add item” button at the bottom
- Select the “left_option” key in the “From key” field
- Select the “left_command” key in the “To key” field
- Click on the “Add item” button at the bottom
- Select the “left_command” key in the “From key” field
- Select the “left_option” key in the “To key” field
The result should look like the image below.
With the “Add rule” button on the “Complex modifications” tab you get access to a repository for Complex modifcations. You can download and enable/disable these rules to your liking. The rules, just JSON files will be downloaded to your local “Karabiner-repository”. Enabling a downloaded rule inserts the rule into your “.config/karabiner/karabiner.json” configuration file. On the repository page you can view the JSON before installing it.
It’s also possible to write your own rules or modify existing rules. These complex rules can open applications, run shell-commands or call apple scripts.
Additional info on Karabiner-Elements:
- Karabiner-Elements, a powerful and stable keyboard customizer for macOS.
- Karabiner at Nikita Voloboev, personal stuff and a collection of links.
- Karabiner God Mode, article by Nikita Voloboev on Medium
Karabiner-Elements is a very powerfull tool to customize your keyboard. The many possibilities make it difficult to choose what functionality you want. There are predefined rules to choose from or you can create your own.
- Pro:
- Powerfull and highly configurable keyboard customizer
- Many predefined rules available
- Community support
- Powerfull eventviewer “Karabiner-Eventviewer” for advanced configurations
- Con
- Advanced configuration requires working with the JSON file directly
- Installation requires extra permissions to be set
Goku
Goku is a tool that lets you manage your advanced Karabiner-Elements configuration.
Karabiner-Elements uses JSON as its config file format. This leads to very large configuration files, which makes it very difficult to edit the ‘karabiner.json’ config file without making mistakes.
Goku uses the edn format. The edn-format (extensible data notation) is used as a data transfer format. It’s dense and at first seems very complex but after some time you get used to the compact syntax and it becomes a pleasure to work with.
By default Goku uses the file “~/.config/karabiner.edn' to generate the Karabiner-Elements configuration file in “~/.config/karabiner/karabiner.json”.
As an example of the file size my fully documented ‘karabiner.edn’ file is about 340 lines and fully documented. (about 200 without the comments). The generated ‘karabiner.json’ is more than 1500 lines. The generated file is roughly six times the size, hard to read and lost most documentation. More on my .edn configuration file in the follow-up post.
Installation can be simply done with homebrew:
brew install yqrashawn/goku/goku
Keep in mind that a “Default” profile in Karabiner-Elements is a requirement.
The learning curve is steep but there is a good tutorial to get you started.
Some Goku examples:
- GokuRakuJoudo:
- Kaushik Gopal:
- Kun Chen: config
You can use the predefined rules from the Karabiner-Elements repository or take it one step further and let Goku generate your Karabiner configuration file. The learning curve is steep but in return it gives you an easy way of modifying your configuration and adding documentation.
- Pro
- Full potential of Karabiner-Elements
- Easy to read configuration compared to the original JSON file
- Small configuration file
- Documentation can be added to the configuration file
- Con
- Steep learning curve on the syntax
Hammerspoon
Although it’s possible to remap keys, Hammerspoon presents itself as a powerful automation tool:
“Hammerspoon is just a bridge between the operating system and a Lua scripting engine”
With Hammerspoon you have a powerfull tool for automation of your system. From the website: “You can write Lua code that interacts with OS X APIs for applications, windows, mouse pointers, filesystem objects, audio devices, batteries, screens, low-level keyboard/mouse events, clipboards, location services, wifi, and more.”
Hammerspoon also offers pre-made plugins called Spoons . This is where Hammerspoon shines, a large collection of Spoons with numerous possibilities. From preventing you screen to go to sleep to setting up a VPN connection. Browse through the Spoons repository to get a feeling of the possibilities.
Installation is simple, download the latest version un-zip it and drag the application to you Applications folder.
Once installed you will need to create the Lua script ‘~/.hammerspooon/init.lua’. Do read the Getting Started Guide and check the full API documentation.
More info on the Lua scripting language can be found at lua.org.
- Pro:
- Powerfull and highly configurable automation tool
- A large collection of diverse plugins (Spoons)
- Community support
- Con
- No easy way to start
- Configurations only possible by editing the files manually
- I was unable to address the left modifier keys
Keyboard Maestro
Keyboard Maestro can automate applications or websites, text or images, simple or complex, on command or scheduled. You can automate virtually anything.
I have not used KM myself but it’s used by many of the keyboard afficinados. Often in combination with Karabiner. It’s not free, KM has a one-time purchase model for major releases. Just how I like it, I still not decided to jump the KM bandwagon but it’s tempting.
It depends on how much you want to automate and how much time you want to spent to justify KM as a purchase. If I look at all the time it took to automate stuff with the free tools it might be worth the money.
- Pro:
- Powerfull and highly configurable automation tool
- Many built-in actions
- Support
- Con
- Commercial offering
SpaceLauncher
SpaceLauncher, hold down spacebar while pressing a key to launch or switch to an app.
If you are looking for a simple application launcher, this might be it. No-nonsense app that let’s you use the spacebar as a hyperkey to launch apps, simulate keystrokes (even child actions) or open URLs.
- Pro:
- Nice “hyperkey” application launcher, “one-trick-pony”
- Solid choice of actions
- Free
- Con
- Everything starts with the spacebar
skhd
skhd, is a simple hotkey daemon for macOS that focuses on responsiveness and performance. Hotkeys are defined in a text file through a simple DSL. skhd is able to hotload its config file, meaning that hotkeys can be edited and updated live while skhd is running.
skhd uses a pid-file to make sure that only one instance is running at any moment in time. This also allows for the ability to trigger a manual reload of the config file by invoking skhd –reload at any time while an instance of skhd is running. The pid-file is saved as /tmp/skhd_$USER.pid and so the user that is running skhd must have write permission to that path.
- Pro
- Nice feature set, like hotkey passthrough, application specific hotkey, blacklist applications and more
- Homebrew support
- Free
- Con
- Secure Keyboard Entry must be disabled
USB Overdrive
USB Overdrive, is a macOS device driver that handles any USB or Bluetooth mouse, keyboard, trackball, joystick, gamepad or gaming device from any manufacturer and lets you configure it either globally or for specific applications. “any” in this means any except the Apple mouse, trackpad or keyboard.
USB Overdrive uses a kext like Karabiner to override device functonality.
- Pro:
- Low level hardware remapping tool
- Shareware
- Con
- Does not support Apple hardware
- Unable to determine how this could be usefull
ControllerMate
ControllerMate, is a macOS application to trigger custom keyboard, mouse, and MIDI actions using a wide variety of input devices. Its building block architecture gives users exceptional freedom in the types of actions that can be created and the inputs that trigger them. Programming actions can be as simple as a single keyboard key that is triggered by a generic button, or a complex combination of timing and logic that is triggered by a combination of controls (source).
This application implements keyboard mapping in a visual way with building blocks. To get an idea read the detailed tutorial. The advanced use of reconfiguring drivers is impressive, what to think of a custom acceleration curve for you mouse!
- Pro:
- Extreme device configuration possibilities
- Visual design with building blocks
- Free limited version
- Con
- Learning curve
Quicksilver
Quicksilver, is a launcher utillity application and if I remember correctly one of the oldest launcher apps. It is fast and has a plugin repository. Quicksilver and Alfred used to be very competitive.
Working with the different panes needs some time to get used to but the possibilities are yours to explore.
- Pro:
- Fast powerful app launcher
- Free and Open Source (donations are welcome)
- Con
- Small learning curve
- Features no longer on par with Alfred
Alfred
Alfred, is another launcher application but with a feature set very different from Quicksilver. Launching applications, finding files, clipboard hiistory everything on par with Quicksilver. Where it gets interesting is the paid option, the Powerpack a workflow engine.
- Pro:
- Fast powerful app launcher
- Free limited version
- Con
- Free version is limited, additional Powerpack is a paid option
Recap
The need to remap two keys on my keyboard triggered me to explore the many different options and tools. Some more in-depth than others and some I actually implemented.
If you want just want to remap the two “PC” keys and do not need much automation, I recommend the combination of native macOS remapping and SpaceLauncher.
For my personal setup I choose a combination of Karabiner-Elements + Goku and Hammerspoon. I could not resist adding extra keymappings and convenient automations. In my follow-up post I will write in detail how that configuration looks like.