{"id":16328695,"url":"https://github.com/OneDeadKey/kalamine","last_synced_at":"2025-10-25T21:30:34.557Z","repository":{"id":39708354,"uuid":"126943790","full_name":"OneDeadKey/kalamine","owner":"OneDeadKey","description":"Keyboard Layout Maker","archived":false,"fork":false,"pushed_at":"2024-12-09T02:43:34.000Z","size":3003,"stargazers_count":118,"open_issues_count":47,"forks_count":29,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-02-05T06:01:56.025Z","etag":null,"topics":["altgr","altgr-dead-keys","dead-keys","keyboard","keyboard-layout"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OneDeadKey.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-27T07:07:22.000Z","updated_at":"2025-02-02T17:15:24.000Z","dependencies_parsed_at":"2024-01-07T18:32:44.617Z","dependency_job_id":"96b5db7c-6a71-4976-9c8f-2106177ffecb","html_url":"https://github.com/OneDeadKey/kalamine","commit_stats":{"total_commits":173,"total_committers":17,"mean_commits":"10.176470588235293","dds":0.5606936416184971,"last_synced_commit":"272f9ebec1e25a12b75a6916887fed74ffbc30db"},"previous_names":["onedeadkey/kalamine","fabi1cazenave/kalamine"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDeadKey%2Fkalamine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDeadKey%2Fkalamine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDeadKey%2Fkalamine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OneDeadKey%2Fkalamine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OneDeadKey","download_url":"https://codeload.github.com/OneDeadKey/kalamine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238212336,"owners_count":19434944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["altgr","altgr-dead-keys","dead-keys","keyboard","keyboard-layout"],"created_at":"2024-10-10T23:14:28.189Z","updated_at":"2025-10-25T21:30:34.203Z","avatar_url":"https://github.com/OneDeadKey.png","language":"Python","readme":"Kalamine\n================================================================================\n\nA text-based, cross-platform Keyboard Layout Maker.\n\n\nInstall\n--------------------------------------------------------------------------------\n\nTo install kalamine, all you need is a Python 3.8+ environment and ``pip``:\n\n.. code-block:: bash\n\n    # to install kalamine\n    python3 -m pip install --user kalamine\n\n    # to upgrade kalamine\n    python3 -m pip install --user --upgrade kalamine\n\n    # to uninstall kalamine\n    python3 -m pip uninstall --user kalamine\n\nHowever, we recommend using pipx_ rather than ``pip`` as it provides ``pyenv``\ncontainment, which is a much saner approach and is becoming mandatory on many\noperating systems (e.g. Arch Linux). It is even simpler from a user perspective:\n\n.. code-block:: bash\n\n    # to install kalamine\n    pipx install kalamine\n\n    # to upgrade kalamine\n    pipx upgrade kalamine\n\n    # to uninstall kalamine\n    pipx uninstall kalamine\n\nArch Linux users may use the `AUR package`_:\n\n.. code-block:: bash\n\n   yay -S kalamine-git\n\nDeveloper-specific installation instructions can be found in the CONTRIBUTING.md_ file.\n\n.. _pipx: https://pipx.pypa.io\n.. _`AUR package`: https://aur.archlinux.org/packages/kalamine-git\n.. _CONTRIBUTING.md: https://github.com/OneDeadKey/kalamine/blob/main/CONTRIBUTING.md\n\n\nBuilding Distributable Layouts\n--------------------------------------------------------------------------------\n\nCreate a keyboard layout with ``kalamine new``:\n\n.. code-block:: bash\n\n   kalamine new layout.toml                  # basic layout\n   kalamine new layout.toml --altgr          # layout with an AltGr layer\n   kalamine new layout.toml --1dk            # layout with a custom dead key\n   kalamine new layout.toml --geometry ERGO  # apply an ortholinear geometry\n\nEdit this layout with your preferred text editor:\n\n- the `user guide`_ is available at the end of the ``*.toml`` file\n- the layout can be rendered and emulated with ``kalamine watch`` (see next section)\n\n.. _`user guide`: https://github.com/OneDeadKey/kalamine/tree/master/docs\n\nBuild your layout:\n\n.. code-block:: bash\n\n    kalamine build layout.toml\n\nGet all distributable keyboard drivers:\n\n.. code-block:: bash\n\n    dist/\n      ├─ layout.ahk            # Windows (user)\n      ├─ layout.klc            # Windows (admin)\n      ├─ layout.keylayout      # macOS\n      ├─ layout.xkb_keymap     # Linux (user)\n      ├─ layout.xkb_symbols    # Linux (root)\n      ├─ layout.json           # web\n      └─ layout.svg\n\nYou can also ask for a single target by specifying the file extension:\n\n.. code-block:: bash\n\n    kalamine build layout.toml --out layout.xkb_symbols\n\n\nEmulating Layouts\n--------------------------------------------------------------------------------\n\nYour layout can be emulated in a browser — including dead keys and an AltGr layer, if any.\n\n\n.. code-block:: bash\n\n    $ kalamine watch layout.toml\n    Server started: http://localhost:1664\n\nCheck your browser, type in the input area, test your layout. Changes on your TOML file are auto-detected and reloaded automatically.\n\n.. image:: watch.png\n\nPress Ctrl-C when you’re done, and kalamine will write all platform-specific files.\n\n\nUsing Distributable Layouts\n--------------------------------------------------------------------------------\n\n\nWindows (user): ``*.ahk``\n`````````````````````````\n\n* download the `AHK 1.1 archive`_\n* load the ``*.ahk`` script with it.\n\nThe keyboard layout appears in the notification area. It can be enabled/disabled by pressing both Alt keys.\n\n.. _`AHK 1.1 archive`: https://www.autohotkey.com/download/ahk.zip\n\nYou may also use Ahk2Exe to turn your ``*.ahk`` script into an executable file. The ``U32 Unicode 32-bit.bin`` setting seems to work fine.\n\n\nWindows (admin): ``*.klc``\n``````````````````````````\n\nNote: this applies only if you want to use the ``*.klc`` file.\nA better approach is to use ``wkalamine`` (see below).\n\n* get a keyboard layout installer: MSKLC_ (freeware) or KbdEdit_ (shareware);\n* load the ``*.klc`` file with it;\n* run this installer to generate a setup program;\n* run the setup program;\n* :strong:`restart your session`, even if Windows doesn’t ask you to.\n\nThe keyboard layout appears in the language bar.\n\nNote: in some cases, custom dead keys may not be supported any more by MSKLC on Windows 10/11.\nKbdEdit works fine, but its installers are not signed.\nWKalamine works fine as well (see below) and its installers are signed.\n\nBasic developer info available in Kalamine’s `KLC documentation page`_.\n\n.. _MSKLC: https://www.microsoft.com/en-us/download/details.aspx?id=102134\n.. _KbdEdit: http://www.kbdedit.com/\n.. _`KLC documentation page`: https://github.com/OneDeadKey/kalamine/tree/master/docs/klc.md\n\n\nmacOS: ``*.keylayout``\n``````````````````````\n\n* copy your ``*.keylayout`` file into:\n\n  * either ``~/Library/Keyboard Layouts`` for the current user only,\n  * or ``/Library/Keyboard Layouts`` for all users;\n\n* restart your session.\n\nThe keyboard layout appears in the “Language and Text” preferences, “Input Methods” tab.\n\n\nLinux (root): ``*.xkb_symbols``\n```````````````````````````````\n\n:strong:`This is by far the simplest method to install a custom keyboard layout on Linux.`\n\nRecent versions of XKB allow *one* custom keyboard layout in root space:\n\n.. code-block:: bash\n\n    sudo cp layout.xkb_symbols ${XKB_CONFIG_ROOT:-/usr/share/X11/xkb}/symbols/custom\n\nYour keyboard layout will be listed as “Custom” in the keyboard settings.\nThis works on both Wayland and X.Org. Depending on your system, you might have to relog to your session or to reboot X completely.\n\nOn X.Org you can also select your keyboard layout from the command line:\n\n.. code-block:: bash\n\n    setxkbmap custom  # select your keyboard layout\n    setxkbmap us      # get back to QWERTY\n\nOn Wayland, this depends on your compositor. For Sway, tweak your keyboard input section like this:\n\n.. code-block:: properties\n\n    input type:keyboard {\n        xkb_layout \"custom\"\n    }\n\n\nLinux (user): ``*.xkb_keymap``\n``````````````````````````````\n\n``*.xkb_keymap`` keyboard descriptions can be applied in user-space. The main limitation is that the keyboard layout won’t show up in the keyboard settings.\n\nOn X.Org it is straight-forward with ``xkbcomp``:\n\n.. code-block:: bash\n\n    xkbcomp -w10 layout.xkb_keymap $DISPLAY\n\nAgain, ``setxkbmap`` can be used to get back to the standard us-qwerty layout on X.Org:\n\n.. code-block:: bash\n\n    setxkbmap us\n\nOn Wayland, this depends on your compositor. For Sway, tweak your keyboard input section like this:\n\n.. code-block:: properties\n\n    input type:keyboard {\n        xkb_file /path/to/layout.xkb_keymap\n    }\n\n\nWKalamine\n--------------------------------------------------------------------------------\n\n``wkalamine`` is a Windows-specific CLI tool to create MSKLC_ setup packages.\n\nThis is kind of a hack, but it provides an automatic way to build setup packages on Windows and more importantly, these setup packages overcome MSKLC’s limitations regarding chained dead keys and AltGr+Space combos.\n\nIt is done by generating the C layout file, and tricking MSKLC to use it by setting it as read-only before.\n\nMake sure MSKLC is installed and build your installer:\n\n.. code-block:: bash\n\n    wkalamine build layout.toml\n\nand you should get a ``[layout]\\setup.exe`` executable to install the layout.\n\nRemember to log out and log back in to apply the changes.\n\n\nXKalamine\n--------------------------------------------------------------------------------\n\n``xkalamine`` is a Linux-specific CLI tool for installing and managing keyboard layouts with XKB, so that they can be listed in the system’s keyboard preferences.\n\n\nWayland (user)\n``````````````\n\nOn *most* Wayland environments, keyboard layouts can be installed in user-space:\n\n.. code-block:: bash\n\n    # Install a YAML/TOML keyboard layout into ~/.config/xkb\n    xkalamine install layout.toml\n\n    # Uninstall Kalamine layouts from ~/.config/xkb\n    xkalamine remove us/prog     # remove the kalamine 'prog' layout\n    xkalamine remove fr          # remove all kalamine layouts for French\n    xkalamine remove \"*\"         # remove all kalamine layouts\n\n    # List available keyboard layouts\n    xkalamine list               # list all kalamine layouts\n    xkalamine list fr            # list all kalamine layouts for French\n    xkalamine list us --all      # list all layouts for US English\n    xkalamine list --all         # list all layouts, ordered by locale\n\nOnce installed, layouts are selectable in the desktop environment’s keyboard preferences. On Sway, you can also select a layout like this:\n\n.. code-block:: properties\n\n    input type:keyboard {\n        xkb_layout \"us\"\n        xkb_variant \"prog\"\n    }\n\nNote: some desktops like KDE Plasma, despite using Wayland, do not support\nkeyboards layouts in ``~/.config:xkb`` out of the box. In such cases, using\n``xkalamine`` as ``sudo`` is required, as described below.\n\n\nX.Org (root)\n````````````\n\nOn X.Org, a layout can be applied on the fly in user-space:\n\n.. code-block:: bash\n\n    # Equivalent to `xkbcomp -w10 layout.xkb_keymap $DISPLAY`\n    xkalamine apply layout.toml\n\nHowever, installing a layout so it can be selected in the keyboard preferences requires ``sudo`` privileges:\n\n.. code-block:: bash\n\n    # Install a YAML/TOML keyboard layout into /usr/share/X11/xkb\n    sudo env \"PATH=$PATH\" xkalamine install layout.toml\n\n    # Uninstall Kalamine layouts from /usr/share/X11/xkb\n    sudo env \"PATH=$PATH\" xkalamine remove us/prog\n    sudo env \"PATH=$PATH\" xkalamine remove fr\n    sudo env \"PATH=$PATH\" xkalamine remove \"*\"\n\nOnce installed, you can apply a keyboard layout like this:\n\n.. code-block:: bash\n\n   setxkbmap us -variant prog\n\nNote that updating XKB will delete all layouts installed using ``sudo xkalamine install``.\n\nSadly, it seems there’s no way to install keyboard layouts in ``~/.config/xkb`` for X.Org. The system keyboard preferences will probably list user-space kayouts, but they won’t be usable on X.Org.\n\n    If you want custom keymaps on your machine, switch to Wayland (and/or fix any remaining issues preventing you from doing so) instead of hoping this will ever work on X.\n\n    -- `Peter Hutterer`_\n\n.. _`Peter Hutterer`: https://who-t.blogspot.com/2020/09/no-user-specific-xkb-configuration-in-x.html\n\n\nResources\n`````````\n\nXKB is a tricky piece of software. The following resources might be helpful if you want to dig in:\n\n* https://www.charvolant.org/doug/xkb/html/\n* https://wiki.archlinux.org/title/X_keyboard_extension\n* https://wiki.archlinux.org/title/Xorg/Keyboard_configuration\n* https://github.com/xkbcommon/libxkbcommon/blob/master/doc/keymap-format-text-v1.md\n\n\nAlternative\n--------------------------------------------------------------------------------\n\n* https://github.com/39aldo39/klfc\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOneDeadKey%2Fkalamine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOneDeadKey%2Fkalamine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOneDeadKey%2Fkalamine/lists"}