At present, there are no official binary builds of kbdencode, so all installations have to be compiled from source.

To compile kbdencode, please ensure you have the Boost program_options library available on your system. This can be done by installing Boost or by downloading the necessary static libraries and header files for your system and providing paths as variables to the configure script or in a config.site file.

Once all dependencies are satisfied, the kbdencode executable can be installed like any Autotools-built software:

make install

You can change the target installation directory by supplying the --prefix option to the configuration script:

./configure --prefix=$HOME/.local

And finally—though this tip does not apply to this project since there are very few source files to compile—the performance of any make task can be boosted by supplying the -jN option, where N is the number of concurrent threads to use. For example, most if not all quad-core Intel Core i7 processors can handle up to 8 simultaneously executing threads.

make -j8


As mentioned above, kbdencode’s purpose is to translate text typed on an input layout and convert it to the output as if it were typed on a different keyboard layout. The default transform is from qwerty to dvorak.

kbdencode is designed to be a command-line utility, so it accepts input through stdin or from one or more files specified as arguments:

echo "Jdppsw ,soph!" | kbdencode
# => Hello, world!
echo "Kjg; kdbk ,a; odah yosm a ygpde" > file.txt
kbdencode file.txt
# => This text was read from a file.

The entire command-line syntax is kbdencode [options] [files...], where the options are described below.

Command-Line Options

<dt class="col-sm-3">-c FILE, --config=FILE</dt>
<dd class="col-sm-9">Path to custom layout configuration file. See <a
href="#configuration-file-format">below</a> for formatting and content
<em>Default: <code>$HOME/.kbdencoderc</code></em></dd>

<dt class="col-sm-3">-f LAYOUT, --from=LAYOUT</dt>
<dd class="col-sm-9">The actual keyboard layout recognized by the stream,
where <strong>LAYOUT</strong> is a <a href="#included-layouts">named
layout</a> or a <a href="#defining-a-custom-layout">layout definition
<em>Default: <code>qwerty</code></em></dd>

<dt class="col-sm-3">-t LAYOUT, --to=LAYOUT</dt>
<dd class="col-sm-9">The keyboard layout to which <strong>kbdencode</strong>
should map the input. Like with the <strong>--from</strong> option,
<strong>LAYOUT</strong> could be a <a href="#included-layouts">named
layout</a> or a <a href="#defining-a-custom-layout">layout definition
<em>Default: <code>dvorak</code></em></dd>

Included Layouts

The following layouts can be referenced by name in the --from and --to command-line options.



Defining a Custom Layout

Additional layouts can be specified by adding a named layout definition to the source code before compiling or by providing a layout definition string to the --from or --to command-line options.

A layout definition string is a sequence of characters formed by pressing all of the keyboard keys in a certain order. Perhaps the best way to demonstrate is with an example. The layout definition string for the qwerty layout is:

It should be easy to see the key sequence:

  1. Starting at the key in the top-left corner of the keyboard (below the function key row), type all of the keys on the top row from left to right
  2. Repeat the previous instruction for the remaining three rows on the keyboard. The last key pressed should be the key at the bottom-right corner of the keyboard.
  3. Repeat the order again, but this time holding the Shift key.

Configuration File Format

Since version 0.1.2, kbdencode can load custom layouts from a configuration file. The default configuration file location is $HOME/.kbdencoderc, and custom locations can be specified with the --config command-line option. The format is straightforward:


This is probably best explained with an example. Here is a configuration file specifying the default built-in qwerty and dvorak layouts:


Layouts in the configuration file may be referred to by name via the --from and --to command-line options.

Built-in Layouts

A layout definition string may be added as a named layout by placing it in the map initializer in src/kbdencode.cc. Be sure to escape characters as needed (i.e. the " and \ characters)

std::map<string, string> keymaps = {
    { "qwerty", "`1234567890-=qwertyuiop[]\\asdfghjkl;'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:\"ZXCVBNM<>?" },
    { "dvorak", "`1234567890[]',.pyfgcrl/=\\aoeuidhtns-;qjkxbmwvz~!@#$%^&*(){}\"<>PYFGCRL?+|AOEUIDHTNS_:QJKXBMWVZ" },
    { "my-layout", "/* put your layout definition string here */" },

The layout definition string should be the same length as the others (93 characters long, 95 including the escape backslashes). Rebuild and install the executable to start using your custom layout.

Explicit Layouts

The alternative way to specify custom layouts is by providing the layout definition string as values for the --from and --to options. Once again, be careful to escape special characters! For example, the qwerty layout could be specified as follows:

kbdencode --from='`1234567890-=qwertyuiop[]\\asdfghjkl;\'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?'


kbdencode is licensed under GPLv2. If this presents a problem for you in any way, please let me know and I will consider relicensing the software for you.