# 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/uk/architecture.md](docs/uk/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).