WaySwitch

Русский · English

WaySwitch чинит слово, набранное не в той раскладке (ghbdtn вместо «привет»), сразу же, на пробеле — без горячих клавиш и без переключения раскладки вручную. На X11 такие утилиты давно есть; на Wayland компоситор намеренно не даёт программе ни слушать чужую клавиатуру, ни подделывать ввод через окна — общего с X11 API здесь нет. WaySwitch обходит это, работая на уровень ниже графического стека: читает события клавиатуры напрямую из /dev/input (evdev) и печатает через виртуальную клавиатуру ядра (uinput), так что композитору всё равно, GNOME это, Wayland или что угодно ещё с теми же интерфейсами ядра. Демон никогда не захватывает клавиатуру устройства — если он зависнет, клавиатура продолжит работать как обычно.

Как это выглядит

• Набрали ghbdtn (латиницей вместо русской раскладки) — на пробеле само становится привет , раскладка переключается вместе со словом.
• Начали адрес не в той раскладке — реезыЖ.. — WaySwitch узнаёт схему URL и чинит её сразу, не дожидаясь пробела.
• Слово исправилось не то, которое нужно, или вручную нужно поправить то, что автоисправление пропустило, — двойной Shift чинит последнее слово, тройной (третий тап следом за двойным) — всю набранную фразу.
• Автоисправление сработало ошибочно — тот же двойной Shift в течение нескольких секунд после него откатывает слово обратно и запоминает его как исключение: второй раз WaySwitch его не тронет.

Установка

Раздел — пошаговая инструкция для тех, кто впервые открывает терминал в Linux (опытным: короткий путь из исходников и таблица команд — в конце этого раздела и раздела «Использование»).

Три термина по ходу дела: терминал — текстовое окно для ввода команд с клавиатуры, а не мышью; sudo в начале команды — «выполнить от имени администратора» (система спросит пароль вашей учётной записи, и, пока вы его набираете, на экране не появляется ничего — ни точек, ни звёздочек, это нормально); вставить скопированный текст в терминал — Ctrl+Shift+V (обычный Ctrl+V там не работает).

1. Проверьте, что система подходит

WaySwitch работает только на GNOME и только на Wayland (способ, которым система рисует окна и читает клавиатуру; старая альтернатива — X11, там WaySwitch бесполезен). Откройте «Параметры → О системе» (Settings → About): рабочий стол должен быть GNOME, а строка «Windowing System» / «Оконная система» — Wayland, не X11. Поддерживаются GNOME 46–50, Ubuntu 24.04 и новее (включая 26.04). Если указано X11 — выйдите из системы, на экране входа нажмите значок шестерёнки рядом с полем пароля и выберите GNOME (не «GNOME on Xorg» / «GNOME на Xorg»), затем войдите заново.

2. Добавьте русскую и английскую раскладки

«Параметры → Клавиатура → Источники ввода» (Settings → Keyboard → Input Sources): нужно ровно две раскладки — русская и английская (латинская); лишние удалите кнопкой «−», недостающую добавьте кнопкой «+». Проверьте, что Super (клавиша с логотипом) + Пробел переключает раскладку в верхней панели.

3. Откройте терминал и установите пакет

Нажмите Super, наберите «Терминал» (Terminal), откройте найденное приложение. Скопируйте три строки ниже и вставьте в терминал (Ctrl+Shift+V), затем нажмите Enter:

url=$(curl -s https://api.github.com/repos/Wetoshkin/WaySwitch/releases/latest | grep -o 'https://[^"]*\.deb' | head -1)
wget "$url"
sudo apt install ./wayswitch_*.deb

Первые две строки скачивают последний релиз (пара секунд); третья начинается с sudo, спросит пароль, покажет список зависимостей и Продолжить? [Д/н] — нажмите Enter или Y. Меньше минуты; apt сам подтянет GTK4, IBus и остальные библиотеки.

4. Перелогиньтесь

Выйдите из системы и войдите заново (подойдёт и перезагрузка) — правило доступа к устройствам ввода (udev), которое поставил пакет, применяется только к новому сеансу: без перелогина демон не сможет читать клавиатуру.

5. Проверьте окружение

wayswitch doctor

✓ — всё в порядке, ✗ — чего-то не хватает, под строкой — подсказка, что сделать; в конце — «Всё готово.» либо «Не пройдено обязательных проверок: N.». Строки «Расширение GNOME Shell» и «systemd user-сервис» необязательны: к расширению вернётесь ниже. Если обязательная проверка не пройдена — выполните подсказку и запустите doctor заново.

6. Запустите демон и включите автозапуск

systemctl --user enable --now wayswitch

--now запускает WaySwitch сразу, enable — включает автозапуск при каждом входе в систему. Проверить, что демон работает: wayswitch status или systemctl --user status wayswitch (ищите строку Active: active (running)).

Из исходников / Fedora (для опытных)

git clone https://github.com/Wetoshkin/WaySwitch.git wayswitch
cd wayswitch
sudo packaging/install.sh

Ставит системные пакеты, копирует код в /usr/local/lib/wayswitch, кладёт udev-правило, systemd user-юнит и расширение GNOME Shell в профиль вызвавшего пользователя (sudo от обычного пользователя, не от root). Дальше — шаги 4–6 выше. На Debian/Ubuntu предпочтителен .deb-пакет; этот путь — для Fedora и сборки из исходников.

Удаление

sudo apt remove wayswitch          # если ставили .deb
sudo packaging/uninstall.sh        # если ставили из исходников

Настройки (~/.config/wayswitch) не трогаются — на случай переустановки; чтобы стереть и их: rm -rf ~/.config/wayswitch.

Использование

Первое исправление

Откройте текстовое поле — например, «Текстовый редактор» (Text Editor, есть в Ubuntu по умолчанию; найдите через Super). Переключитесь на английскую раскладку (Super+Пробел), наберите ghbdtn и нажмите пробел — слово станет «привет», раскладка переключится на русскую.

Опробуйте сразу ещё три жеста (нажатия Shift подряд, без пауз; точные тайминги — в таблице «Жесты» ниже): двойной Shift сразу после слова исправляет его вручную, даже если автоисправление промолчало; тройной Shift (третье нажатие сразу за двойным) исправляет всю фразу целиком; двойной Shift в течение нескольких секунд после автоисправления откатывает слово обратно и запоминает его как исключение.

Точнее: расширение GNOME Shell (необязательно)

После перелогина (шаг 4) включите расширение, которое пакет уже положил в систему, — оно даёт демону точное знание раскладки и печатает мгновенно: gnome-extensions enable wayswitch@siberia.ru, либо через приложение «Расширения» (Extensions). Затем в окне настроек WaySwitch (ниже) на странице «Настройки» в поле «Бэкенд раскладки» выберите «Расширение GNOME Shell». Без него WaySwitch работает через IBus с небольшой задержкой (settle_ms, 30 мс по умолчанию) — обычно незаметно, но расширение точнее.

Окно настроек и значок в трее

wayswitch-gui

или «WaySwitch» в списке приложений (Super). Четыре страницы:

• Статус — работает ли демон, бэкенд, раскладка, счётчик исправлений, тестовое поле.
• Настройки — автоисправление, чувствительность, жест ручного исправления, окно отката, задержки, бэкенд.
• Исключения — слова, которые никогда не исправляются; можно добавлять и удалять вручную.
• Автозапуск — переключатели «Демон при входе в систему» и «Значок в трее при входе».

Чтобы значок был в трее сразу после входа, включите второй переключатель на странице «Автозапуск» — для него в Ubuntu нужно расширение AppIndicator, оно включено по умолчанию.

Пароли

Перед вводом пароля в необычном поле (не в системном диалоге входа, а, например, в форме на сайте) поставьте WaySwitch на паузу — в трее («Пауза») или командой wayswitch pause — и возобновите после (wayswitch resume). Демон старается не трогать поля паролей, но полагаться на это не стоит.

Если что-то не работает

wayswitch doctor — не появился ли новый ✗; journalctl --user -u wayswitch -n 50 — последние строки лога демона; wayswitch dry-run в терминале — демон наблюдает и печатает решения в лог, ничего не меняя на экране. Не помогло — заведите issue в репозитории проекта и приложите вывод этих трёх команд.

Жесты (справочно)

Жест	Действие
Двойной Shift (второй тап в пределах 0,4 с)	исправить последнее слово; при пустом буфере — просто переключить раскладку
Тройной Shift (третий тап следом за двойным)	исправить всю фразу в раскладке, которую выбрал двойной Shift
Двойной Shift в течение undo_window_sec после автоисправления	откатить слово и запомнить его как исключение

Жесты не работают, пока экран заблокирован или демон на паузе.

Команды (справочно)

Команда	Действие
wayswitch run [--verbose] [--dry-run] [--config PATH]	запустить демон
wayswitch dry-run	демон в режиме наблюдения (verbose, без действий)
wayswitch doctor	диагностика окружения
wayswitch devices	список устройств ввода
wayswitch pause / resume	пауза/возобновление по D-Bus
wayswitch fix	исправить последнее слово по D-Bus
wayswitch status	состояние демона
wayswitch gui	открыть окно настроек
wayswitch version	версия
wayswitch-gui [--tray]	настройки; --tray — сразу в трей, без окна

Значок в трее открывает меню: переключатель автоисправления, пауза/ возобновление, «исправить последнее слово», настройки, выход.

Настройка

~/.config/wayswitch/config.toml (создаётся при первом сохранении из GUI или руками):

[general]
auto_correct = true           # включено ли автоисправление на пробеле
sensitivity = "normal"        # conservative | normal | aggressive
phrase_timeout_sec = 8.0      # пауза между словами, после которой фраза для тройного Shift обнуляется (1..300)
undo_window_sec = 5.0         # сколько секунд после автоисправления двойной Shift ещё откатывает слово (0..60)

[gesture]
manual = "double_shift"       # double_shift | pause_key | none
pause_hotkey = ""             # клавиша паузы, например "scroll_lock" (пусто — не назначена)

[typing]
settle_ms = 30                # запас после сигнала о смене раскладки на пути IBus, мс (0..2000)
key_delay_ms = 0              # задержка между отправляемыми клавишами, мс (0..100)

[backend]
prefer = "auto"               # auto | shell | ibus | hotkey

sensitivity регулирует порог: conservative реже ошибается, но и реже чинит короткие/редкие слова; aggressive — наоборот.

~/.config/wayswitch/exceptions.txt — слова, которые никогда не исправляются автоматически (по слову в строке, регистр не важен); пополняется откатом жестом или из GUI.

Как это работает

1. evdev слушает клавиатуры напрямую по /dev/input/event*, без захвата устройства и без прав root: правило udev с тегом uaccess выдаёт доступ пользователю активного сеанса, никаких групп добавлять не нужно.
2. Буфер копит коды клавиш текущего слова и фразы, отдельно отслеживает Shift/CapsLock.
3. На пробеле детектор декодирует нажатия двумя способами — в текущей раскладке и в альтернативной — по таблицам libxkbcommon, построенным из настоящих раскладок пользователя (не зашитых QWERTY/ЙЦУКЕН).
4. Решение «оставить» или «исправить» принимается по словарю и модели символьных триграмм, с стоп-правилами для цифр, смешанных алфавитов, camelCase, путей/URL и коротких слов вне словаря.
5. Для исправления строится план: N×Backspace, переключение раскладки через выбранный бэкенд (расширение GNOME Shell → IBus → хоткей как резерв) и перепечатка символов через uinput.
6. Ранний триггер отдельно ловит начало URL (http://, https://, ftp://), набранное не в той раскладке, — не дожидаясь пробела.
7. Жесты (двойной/тройной Shift) и откат с запоминанием слова в исключениях работают поверх того же плана исполнения; пока экран заблокирован или демон на паузе, ничего не происходит.

Качество детектора на отложенной части словаря (не участвовавшей в обучении): ru — полнота 96,5 %, ложные срабатывания 0,07 %; en — полнота 96,8 %, ложные срабатывания 0,07 %.

Требования

• GNOME 46–50 на Wayland.
• Ровно две раскладки ввода: одна ru*, одна латинская.
• Ubuntu 24.04+ или Fedora 40+.
• Python 3.11+.

Статус и ограничения

WaySwitch v2 — альфа, полностью переписанная с нуля. Вся логика покрыта юнит-тестами и проверена на Windows и в CI (Linux), но ни разу не запускалась на живом GNOME — чек-лист первого запуска в VM: docs/testing-vm.md. Известные ограничения:

• Демон не видит текст в полях паролей — на время ввода пароля ставьте его на паузу.
• Поля с автодополнением (например, адресная строка браузера) могут вести себя неожиданно при перепечатке.
• Если исправление прервано на середине (физическое нажатие клавиши во время перепечатки), уже отправленные символы не откатываются — попытка «починить» вслепую только усугубила бы расхождение с экраном.
• Правило udev uaccess даёт чтение событий клавиатуры любой программе текущего пользователя, не только WaySwitch, — это цена схемы на evdev.
• Поддерживается только GNOME; KDE и Sway/Hyprland — в планах.

Разработка

pip install pytest ruff
python -m pytest -q
python -m ruff check .

Два теста keymap.py, завязанных на настоящий libxkbcommon (tests/test_keymap_xkb.py), пропускаются на Windows и выполняются в CI (GitHub Actions, ubuntu-latest). Словарные данные пересобираются командой python tools/build_data.py. Пакет .deb собирается на Linux командой bash tools/build_deb.sh; релизы выпускаются по тегу vX.Y.Z, совпадающему с версией в pyproject.toml.

Roadmap

• Бэкенд для KDE Plasma и IPC-бэкенды для Sway/Hyprland.
• Определение полей паролей и активного приложения через AT-SPI — на любом окружении, не только через эвристики GNOME.
• Исправление уже выделенного текста через буфер обмена/портал.
• Третьи языки как подключаемый пакет словаря и триграмм.
• Привилегированный helper вместо широкого правила uaccess на клавиатуры.
• .rpm-пакет (Flatpak невозможен: нужен прямой доступ к /dev/input).

Лицензии

Код — MIT (LICENSE). Словарные данные и триграммы (wayswitch/data/*.gz) собраны из открытого проекта FrequencyWords и распространяются по CC-BY-SA 4.0 — подробности в wayswitch/data/LICENSE.