# Keylegend

**Интерактивная подсветка клавиатуры для Razer Chroma — клавиши светятся по тому, что они на самом деле делают.**

[English](README.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Nederlands](README.nl.md) ·
[Polski](README.pl.md) · [Português](README.pt.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [简体中文](README.zh-cn.md)

> **Версия 1.2.0.** Подсветка, интерфейс, обнаружение игр и профили приложений работают.
> [Скачайте установщик или переносимую копию](https://github.com/Eistee82/Keylegend/releases/latest),
> либо соберите из исходников. См. [CHANGELOG.md](CHANGELOG.md).

![Keylegend окрашивает клавиши по их текущему значению и меняет профиль, когда на передний план выходит другая программа](docs/images/keylegend.png)

---

## Что он делает

Большинство программ для RGB считает клавиатуру украшением. Keylegend считает её **экраном**.

Каждая клавиша окрашена по тому, что она значит *сейчас*, — и цвет меняется в тот же миг, когда
меняется её значение:

- **Состояние фиксаторов с одного взгляда.** Num Lock, Caps Lock и Scroll Lock показывают своё
  состояние на самой клавише.
- **Цвет по классу символа.** Цифры, строчные буквы, прописные буквы, символы и управляющие
  клавиши получают каждый свой цвет.
- **Удерживайте модификатор — увидите слой.** Нажмите `AltGr`, и гореть останутся только те
  клавиши, на которых действительно есть символ AltGr. Нажмите `Windows` — загорятся сочетания
  Windows, сгруппированные по назначению. То же для `Alt`, `Ctrl` и их комбинаций.
- **Shift и Caps Lock работают сами собой.** Поскольку символ, который выдаёт клавиша,
  запрашивается у Windows в реальном времени, буквы сами переходят из цвета «строчная» в цвет
  «прописная». Цифровой блок перекрашивается в навигацию, когда Num Lock выключен.
- **Игры получают отдельное обращение.** Они распознаются автоматически — в том числе в окне без
  рамки, — и WASD, клавиши вокруг и ряд цифр получают постоянные цвета: во время игры важно, куда
  ложатся руки, а не какую букву набирает клавиша.
- **Профили для приложений, около девяноста в комплекте.** Photoshop, Visual Studio Code, Excel,
  Elden Ring и остальные вступают в силу, как только программа получает фокус, а профиль, в
  котором названа программа, важнее общего игрового профиля. Измените один — и только изменённая
  часть перестанет следовать поставляемой версии, остальное будет улучшаться с новыми выпусками.
- **Подсветка может отвечать на набор.** Восемь эффектов на выбор, по умолчанию *нет*: нажатая
  клавиша гаснет и возвращается, вспыхивает или продолжает светиться, капля воды или тёмная
  волна пробегает по клавиатуре, клавиши вокруг вздрагивают, летят искры, или клавиши нагреваются
  от использования и снова остывают. Наложено поверх цветов, а не подмешано в них — каждая
  клавиша по-прежнему говорит, что она значит.
- **Возвращает подсветку.** По истечении настраиваемого времени простоя (по умолчанию 60 с)
  Keylegend освобождает клавиатуру, и ваш эффект Chroma Studio снова берёт управление.
- **Одиннадцать языков.** Английский, немецкий, испанский, французский, итальянский,
  нидерландский, польский, португальский, русский, украинский и упрощённый китайский. Интерфейс
  следует языку интерфейса Windows и переключается в настройках. Надписей на клавишах это не
  касается: они следуют вашей клавиатуре, а не меню.

Поскольку значения клавиш берутся из **активной раскладки Windows**, а не из жёсткой таблицы,
Keylegend работает с любой раскладкой — русской, немецкой, американской, Дворака — без изменений.

## Как это устроено

Keylegend спрашивает у Windows, какой символ выдала бы каждая клавиша при текущем состоянии
клавиатуры (`ToUnicodeEx`), выводит из этого символа категорию и отправляет получившуюся карту
цветов в Razer Chroma SDK через его локальный интерфейс REST.

Он намеренно **не** устанавливает глобальный клавиатурный хук. Он читает *состояния* — нажата ли
клавиша в этот момент — и никогда не перехватывает, не пересылает и не записывает нажатия. Без
выбранного эффекта при наборе он смотрит только на состояние модификаторов и фиксаторов; эффект
дополнительно спрашивает, какие клавиши этой клавиатуры нажаты, — и ничего сверх того.
См. [docs/ru/architecture.md](docs/ru/architecture.md).

## Требования

- Windows 10 или 11
- Razer Synapse с работающей службой Chroma SDK
- Подключённая клавиатура Razer Chroma (см. ниже)
- Среда выполнения .NET 10

## Установка

```powershell
winget install Eistee82.Keylegend
```

Самый короткий путь: winget подтянет среду .NET как объявленную зависимость, так что вручную
устанавливать ничего не придётся. Иначе возьмите файл:

[**Скачать последнюю версию.**](https://github.com/Eistee82/Keylegend/releases/latest)

| Файл | Что это |
|---|---|
| `Keylegend-1.2.0-setup.exe` | Устанавливается для текущего пользователя — права администратора не нужны. Пункт в меню «Пуск» и удаление, которое убирает и запись автозапуска. |
| `Keylegend-1.2.0-portable.zip` | Та же программа для распаковки. Папки языков (`de`, `fr`, …) должны остаться рядом с исполняемым файлом, иначе интерфейс переключится на английский. |

Ни один файл не подписан, поэтому Windows назовёт издателя неизвестным: сертификат стоит в год
больше, чем есть у этого проекта. В каждом выпуске есть `SHA256SUMS.txt` для проверки загрузки, а
журнал сборки, которая его создала, открыт.

## Поддерживаемые клавиатуры

**Любая клавиатура Razer Chroma.** Нет ни списка, ни файла на каждую модель, потому что Keylegend не
нужно распознавать вашу клавиатуру — он спрашивает. Razer Synapse описывает подключённую: модель по
имени, физическую раскладку числом и клавиши, которые у устройства действительно есть. Собственный
чертёж Razer для этой модели даёт остальное — настоящие размеры клавиш, корпус с колесом и
мультимедийными клавишами и контуры символов, напечатанных на колпачках, на нужном языке.

Единственное, чего чертёж не сообщает, — к какой ячейке матрицы подсветки относится каждая клавиша.
Это константа протокола Chroma, одинаковая на всех моделях, — поэтому и Synapse не нужна таблица по
моделям. Проверено по единственной клавиатуре, откалиброванной вручную: все 105 клавиш совпадают.

**Физическая раскладка** описывает *форму* клавиатуры, а не язык, на котором вы печатаете. Какой символ даёт
клавиша, выясняется у Windows во время работы, так что немецкая клавиатура работает правильно и при
раскладке US или Dvorak в Windows.

**Требуется Razer Synapse**, установленный и запущенный, с подключённой клавиатурой. Именно там
описана клавиатура и там же лежит её чертёж.

## Документация

| Тема | |
|---|---|
| Архитектура | как определяется раскраска и почему нет клавиатурного хука |
| Добавление профиля | раскраска для отдельных приложений |
| Настройка | параметры, файл настроек, автозапуск |

Доступна на одиннадцати языках:

[English](docs/en/) · [Deutsch](docs/de/) · [Español](docs/es/) · [Français](docs/fr/) ·
[Italiano](docs/it/) · [Nederlands](docs/nl/) · [Polski](docs/pl/) · [Português](docs/pt/) ·
[Русский](docs/ru/) · [Українська](docs/uk/) · [简体中文](docs/zh-cn/)

Английский и немецкий — поддерживаемые оригиналы; там, где перевод им противоречит, прав
английский текст. Исправления приветствуются, см. [CONTRIBUTING.md](CONTRIBUTING.md).

## Сборка и запуск

```bash
git clone https://github.com/Eistee82/Keylegend.git
cd Keylegend
dotnet build
dotnet test
```

`Keylegend.exe` (`src/Keylegend.App`) — это вся программа: окно, значок в области уведомлений,
настройки. Единственный ключ, который стоит знать: `--verify` проверяет, несёт ли копия
поставляемые профили и все одиннадцать языков, записывает найденное по указанному после него пути и
отвечает кодом выхода. Именно это скрипт выпуска запускает на упакованной копии.

Настройки находятся в `%APPDATA%\Keylegend\settings.json` и записываются приложением.

## Как помочь

Сообщения об ошибках, профили приложений и переводы одинаково желанны — см.
[CONTRIBUTING.md](CONTRIBUTING.md) и [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Лицензия

[MIT](LICENSE). Исключение — две чужие кнопки пожертвований; кода, заголовков, библиотек или
изображений производителя здесь нет вовсе — см. [NOTICE.md](NOTICE.md).

## О товарных знаках

Этот проект **не связан с Razer Inc. и не поддерживается и не спонсируется ею.**

RAZER и RAZER CHROMA — товарные знаки или зарегистрированные товарные знаки Razer Inc. Они
используются здесь исключительно для обозначения оборудования и программного интерфейса, с
которыми работает проект, как это допускает референциальное употребление. Keylegend —
независимый проект, поддерживаемый сообществом.

То же относится к любому другому имени в этом репозитории. Профили приложений и игр называют около
девяноста программ — Photoshop, Visual Studio Code, Excel, Elden Ring и другие, — а документация
называет производителей и модели клавиатур. Это товарные знаки их владельцев, и они приведены
только для того, чтобы сказать, к какой программе или к какой клавиатуре что-то относится.
Keylegend не связан ни с одним из них и не содержит ни их кода, ни их материалов. См.
[NOTICE.md](NOTICE.md).