2021-12-23 04:35:24 +00:00
# 𝑋𝑟𝑒𝑚𝑎𝑝 :keyboard: [](https://github.com/k0kubun/xremap/actions/workflows/build.yml)
2021-12-22 09:34:09 +00:00
`xremap` is a key remapper for Linux. Unlike `xmodmap` , it supports app-specific remapping and Wayland.
2021-12-23 07:49:50 +00:00
## Concept
2021-12-22 09:34:09 +00:00
* **Fast** - Xremap is written in Rust, which is faster than JIT-less interpreters like Python.
* **Cross-platform** - Xremap uses `evdev` and `uinput` , which works whether you use X11 or Wayland.
2021-12-22 13:25:03 +00:00
* **Language-agnostic** - The config is JSON-compatible. Generate it from any language,
e.g. [Ruby ](https://github.com/xremap/xremap-ruby ), [Python ](https://github.com/xremap/xremap-python ).
2021-12-22 09:34:09 +00:00
2021-12-23 07:53:05 +00:00
## Features
* You can remap any keys, e.g. Ctrl or CapsLock.
* You can remap any key combination to another, even to a key sequence.
2021-12-26 05:31:09 +00:00
* You can remap a key sequence as well. You could do something like Emacs's `C-x C-c` .
* You can remap a key to two different keys depending on whether it's pressed alone or held.
2021-12-23 07:53:05 +00:00
* Application-specific remapping. Even if it's not supported by your application, xremap can.
2021-12-23 05:23:33 +00:00
## Prerequisite
2021-12-23 07:07:57 +00:00
`xremap` assumes that you can use `evdev` and `uinput` without sudo.
2021-12-23 07:08:33 +00:00
You can configure it as follows:
2021-12-23 05:23:33 +00:00
```bash
sudo gpasswd -a YOUR_USER input
echo 'KERNEL=="uinput", GROUP="input"' | sudo tee /etc/udev/rules.d/input.rules
```
2021-12-23 07:09:12 +00:00
Then reboot your machine to make sure the udev rule is applied.
2021-12-23 05:23:33 +00:00
2021-12-22 09:34:09 +00:00
## Installation
2021-12-23 05:23:33 +00:00
After the reboot, download a binary from [Releases ](https://github.com/k0kubun/xremap/releases ).
2021-12-22 09:34:09 +00:00
If it doesn't work, please [install Rust ](https://doc.rust-lang.org/cargo/getting-started/installation.html )
2021-12-24 04:12:25 +00:00
and run one of the following commands:
2021-12-22 09:34:09 +00:00
```bash
# X11
2021-12-24 04:12:25 +00:00
cargo install xremap --features x11
2021-12-22 09:34:09 +00:00
# GNOME Wayland
2021-12-24 04:12:25 +00:00
cargo install xremap --features gnome
2021-12-22 09:34:09 +00:00
# Sway
2021-12-24 04:12:25 +00:00
cargo install xremap --features sway
2021-12-22 09:34:09 +00:00
# Others
2021-12-24 04:12:25 +00:00
cargo install xremap
2021-12-22 09:34:09 +00:00
```
2021-12-23 05:23:33 +00:00
You may also need to install `libx11-dev` to run the `xremap` binary for X11.
2021-12-22 09:34:09 +00:00
## Usage
2021-12-22 13:25:03 +00:00
Write [a config file ](#Configuration ) directly, or generate it with
[xremap-ruby ](https://github.com/xremap/xremap-ruby ) or [xremap-python ](https://github.com/xremap/xremap-python ).
Then run:
2021-12-22 09:34:09 +00:00
```
2021-12-23 05:23:33 +00:00
xremap config.yml
2021-12-22 09:34:09 +00:00
```
### Dynamic binding
Xremap supports application-specific key remapping.
While Xremap uses `evdev` and `uinput` , which is a lower layer than X11 and Wayland,
Xremap also uses X11 or Wayland compositor-specific protocols to support `application` config.
2021-12-23 18:32:38 +00:00
If you need this feature, make sure you use the correct binary or `--features` option,
2021-12-23 05:23:33 +00:00
and pay attention to the error messages from `xremap` .
2021-12-22 09:34:09 +00:00
## Configuration
Your `config.yml` should look like this:
```yml
modmap:
- name: Except Chrome
application:
not: Google-chrome
remap:
CapsLock: Esc
keymap:
- name: Emacs binding
application:
only: Slack
remap:
C-b: left
C-f: right
C-p: up
C-n: down
```
See also: [example/config.yml ](./example/config.yml )
### modmap
`modmap` is for key-to-key remapping like xmodmap.
2021-12-23 17:58:45 +00:00
Note that remapping a key to a modifier key, e.g. CapsLock to Control\_L,
2021-12-23 19:56:48 +00:00
is supported only in `modmap` since `keymap` handles modifier keys differently.
2021-12-22 09:34:09 +00:00
```yml
modmap:
- name: Name # Required
remap: # Required
2021-12-26 05:31:09 +00:00
KEY_XXX: KEY_YYY # Required
# or
KEY_XXX:
held: KEY_YYY # Required
alone: KEY_ZZZ # Required
alone_timeout_millis: 1000 # Optional
2021-12-22 09:34:09 +00:00
application: # Optional
not: [Application, ...]
# or
only: [Application, ...]
```
For `KEY_XXX` and `KEY_YYY` , use [these names ](https://github.com/emberian/evdev/blob/1d020f11b283b0648427a2844b6b980f1a268221/src/scancodes.rs#L26-L572 ).
You can skip `KEY_` and the name is case-insensitive. So `KEY_CAPSLOCK` , `CAPSLOCK` , and `CapsLock` are the same thing.
Some [custom aliases ](src/config/key.rs ) like `SHIFT_R` , `CONTROL_L` , etc. are provided.
2021-12-26 05:31:09 +00:00
If you specify a map containing `held` and `alone` , you can use the key for two purposes.
The key is considered `alone` if it's pressed and released within `alone_timeout_millis` (default: 1000)
before any other key is pressed. Otherwise it's considered `held` .
2021-12-22 09:34:09 +00:00
### keymap
2021-12-23 17:54:15 +00:00
`keymap` is for remapping a sequence of key combinations to another sequence of key combinations or other actions.
2021-12-22 09:34:09 +00:00
```yml
2021-12-26 12:24:46 +00:00
keymap:
2021-12-22 09:34:09 +00:00
- name: Name # Required
remap: # Required
# key press -> key press
MOD1-KEY_XXX: MOD2-KEY_YYY
# sequence (MOD1-KEY_XXX, MOD2-KEY_YYY) -> key press (MOD3-KEY_ZZZ)
MOD1-KEY_XXX:
remap:
MOD2-KEY_YYY: MOD3-KEY_ZZZ
# key press (MOD1-KEY_XXX) -> sequence (MOD2-KEY_YYY, MOD3-KEY_ZZZ)
MOD1-KEY_XXX: [MOD2-KEY_YYY, MOD3-KEY_ZZZ]
application: # Optional
not: [Application, ...]
# or
only: [Application, ...]
```
For `KEY_XXX` , use [these names ](https://github.com/emberian/evdev/blob/1d020f11b283b0648427a2844b6b980f1a268221/src/scancodes.rs#L26-L572 ).
You can skip `KEY_` and the name is case-insensitive. So `KEY_CAPSLOCK` , `CAPSLOCK` , and `CapsLock` are the same thing.
For the `MOD1-` part, the following prefixes can be used (also case-insensitive):
* Shift: `SHIFT-`
* Control: `C-` , `CTRL-` , `CONTROL-`
* Alt: `M-` , `ALT-`
* Windows: `SUPER-` , `WIN-` , `WINDOWS-`
You may use multiple prefixes like `C-M-Shift-a` .
### application
`application` can be used for both `modmap` and `keymap` , which allows you to specify application-specific remapping.
```yml
application:
not: Application
# or
not: [Application, ...]
# or
only: Application
# or
only: [Application, ...]
```
To check the application names, you can use the following commands:
#### X11
```
$ wmctrl -x -l
0x0280000a 0 gnome-terminal-server.Gnome-terminal ubuntu-focal Terminal
0x02600001 0 nocturn.Nocturn ubuntu-focal Nocturn
```
Use the name after `.` in the third column (`WM_CLASS`), i.e. `Gnome-terminal` or `Nocturn` in the above output.
#### GNOME Wayland
```
busctl --user call org.gnome.Shell /org/gnome/Shell org.gnome.Shell Eval s 'global.get_window_actors().map(a => a.get_meta_window().get_wm_class());'
```
#### Sway
```
swaymsg -t get_tree
```
Locate `app_id` in the output.
## License
The gem is available as open source under the terms of the [MIT License ](https://opensource.org/licenses/MIT ).
