Visualize hotkeys on a Razer keyboard
A tool to show possible hotkeys or commands (e.g. i3 or vim commands) on a Razer keyboard with rgb lighting. It is highly customizable: select which key is lit in which color on which action. I encourage to write your own configuration to match your hotkeys.
Disclaimer This program only runs on Linux, depends on the linux openrazer client and X server
The openrazer driver can be installed from here, just select your OS and follow the instructions.
To install i3razer run:
$ pip install i3razer
If installed with privileged rights the executable i3razer will already be in the path.
Otherwise it can be found in $HOME/.local/bin
$ i3razer --config CONFIG
This runs i3razer with the given config file. Look here for the configuration. If the config is not given the examle_config will be used.
exec --no-startup-id i3razer --config CONFIG
Add this line to your i3-config to start the visualization on i3 startup.
Find and report bugs on github.
Run i3razer --map to map your keyboard Layout. Consider opening a pull request with the new Layout.
- modes can have a base mode to inherit from. Useful to combine modes, e.g. mode for num_lock on / off, but still same commands
- switch mode stack: possibility to return to the previous mode and not to a defined mode (call stack instead of goto)
- dbus interface to change layout, current_mode, reload config and a program to connect to this interface
With the configuration file the user can set the colors of keys and add keybindings to change the colors. The file format is yaml. It consists of the sections colors, keys, color_schemes, modes
Semantic Overview:
- Colors: define custom colors, e.g.
my_red: '0xe01010' - Keys: define set of keys for short access, e.g.
numbers: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 - Color schemes: A color scheme specifies the look of the keyboard. Keys can be assigned to colors, or a color effect can be set
- Modes: Modes define, when to show which color scheme. Color schemes can be shown, depending on which keys are pressed. Modes can switch to another mode to change keys and color schemes
The colors sets values to their color name.
The definition is just color_name: '0xrrggbb', where color_ name can be any value except starting with '0x'.
Make sure yaml interprets 0xrrggbb as string.
Default colors example:
colors:
black: '0x000000'
red: '0xff0000'
green: '0x00ff00'
blue: '0x0000ff'The keys section defines sets of keys.
When you have multiple color scheme which wants to set e.g. all numbers to the same color, the number keys can be predefined here.
The definition is keyset_name: key_array. For the name all values can be used except the reserved ones.
all: Predefined keyset which contains all keys of the keyboard
type, name, default, inherit, switch_mode, scheme: These names have a predefined usage in the configuration.
A keyarray defines multiple keys. key_name or keyset_name can be included in an array:
key1, keyset, key2 The names are separated by ','. In a keyset definition newlines can be included.
keys:
prime_numbers: 2, 3, 5, 7
numbers: 0, 1, 4, 6, 8, 9, prime_numbers # contains all numbers (0-9)
arrows: up, left, down, right
new_line: # newlines could improve readability
shift_l,
shift_r,
control_l,
control_r
all: a # built in keyset, which has all keys of the keyboardA color scheme describes the look of the keyboard, which keys are lit in which color or what effect to play.
Which color scheme is drawn on the keyboard is determined in the modes section.
The default use case of a color scheme is to assign colors to keys: keys: color.
Keys is a key array (no newlines allowed) and color is either direct an hexstring '0xrrggbb'
of a color defined in the colors section.
color_schemes:
my_scheme:
all: green # sets all keys to green
numbers: '0xffffff' # the number keys are white
w, a, s, d: red If a key is present in multiple key arrays, the assigned color will be the one defined latest in the file.
# this is directly the scheme definition
override_scheme:
a: red
all: black # overrides the previous definition for 'a' to be red and 'a' will be shown blackcolor scheme inheritance and effect definition
Maybe multiple color schemes wants to set the same colors to many keys, as the schemes are very similar.
There is no need for a redundant color scheme definition,
as it is possible to inherit from another color scheme:inherit: color_scheme.
This adds the color information from the inherited scheme to this scheme.
default:
all: green
other_keys: yellow
gaming:
inherit: default
w, a, s, d: red
some_scheme:
numbers: orange
inherit: default # this overrides the numbers defined previouslyTo show an effect on the keyboard a color scheme type must be set: type: effect.
Possible types are: static, breath, reactive, ripple, spectrum, starlight, wave right, wave left
The static type is the default type and does not need to be specified. Each key can be assigned a static color.
All other types are keyboard build in effects, they can take a color or time, dependant on the keyboard or effect.
With these types (except static) inheritance is not possible,
as the definitions are quite simple and one could only inherit from the same type.
Colors of the effect are defined with color1: white, up to three colors can be specified.
If only one color is needed for the effect color: white will suffice.
| Effect | Number of colors |
|---|---|
| breath | up to three colors |
| reactive | exactly one color |
| ripple | up to one color |
| starlight | up to two colors |
| spectrum, wave {right / left} | no color |
If no color is given the effect is always executed with a random color
Some effects take a timing value: time: value. If no value is given, the default is used.
| Effect | Time values, (default) | Description |
|---|---|---|
| reactive | '500', ('1000'), '1500', '2000' | milliseconds the pressed key is lit |
| starlight | fast, (normal), slow | speed of starlight blinking |
All other effects have no time option.
effect_scheme:
type: reactive
color1: green # or just color: green
time: '1000'
effect_stars:
type: starlight
color1: blue
color2: green
time: slowA Mode defines which color scheme gets drawn on the keyboard. The scheme depends on the currently pressed keys.
Possible hotkeys can be visualized on the keyboard, e.g. if the super key is pressed.
However sometimes the available hotkeys change, depended on what you do on your computer.
Many modes can be defined with different keys to show color schemes, but there needs to be the starting mode default.
Switching from one mode to another is done with hotkeys, defined in the mode.
Each mode must have a default color scheme, which will be drawn if no key is pressed: scheme: default_scheme.
Displaying other color schemes is done by assigning them to hotkeys: key_combinations: color_scheme.
Key combinations are an array of combinations, delimited by ','.
A combination can be a single key, or multiple keys delimited by '+': key1 + key2
Such a combination is pressed if all the keys in the combination are pressed.
The combination with nothing: nothing + key1 + key2 holds only if exactly key1 and key2 are pressed,
no other key is allowed to be pressed.
If one of the combinations of the array is pressed, the whole combination array is fulfilled and the corresponding action applied. If multiple combination arrays have a matching combination, the value of array defined first gets applied.
modes:
default: # default mode must exist, this is the start mode
scheme: default
super_l + shift_l: some_scheme
super_l: mod_scheme # also holds if super+shift is pressed, but is defined later
nothing + control_r, numbers: scheme # more complicated combinationSwitching the mode gives a new default color scheme and new hotkeys. It is defined in a mode as follows:
switch_mode:
key_combinations: next_modemodes:
default:
scheme: color/default
super_l: super_hotkeys # light key r
# more hotkeys
switch_mode:
nothing + super_l + r: mode/resize
mode/resize:
scheme: color/resize
# no hotkeys to display
switch_mode:
nothing + escape, nothing + return: default # switch back to default mode with escape or returnHere is the default config.yaml which hotkeys are based on the default i3 configuration.