openajazz 0.4.0__tar.gz

openajazz-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyas Deb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openajazz-0.4.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: openajazz
+Version: 0.4.0
+Summary: Unofficial control for AJAZZ keyboards (AK820 Max Plus so far): lighting, per-key RGB, remaps, macros, music sync. CLI, TUI and web.
+Author-email: Shreyas Deb <shreyasdeb@gmail.com>
+License-Expression: MIT
+Project-URL: Web app, https://openajazz.vercel.app
+Project-URL: Homepage, https://github.com/shrey715/openajazz
+Project-URL: Releases, https://github.com/shrey715/openajazz/releases
+Project-URL: Issues, https://github.com/shrey715/openajazz/issues
+Project-URL: Protocol, https://github.com/shrey715/openajazz/blob/main/PROTOCOL.md
+Keywords: ajazz,ak820,ak820 max plus,keyboard,mechanical keyboard,rgb,hid,hidraw,linux,tui,macro
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=12
+Requires-Dist: textual>=3.0
+Provides-Extra: music
+Requires-Dist: numpy>=1.21; extra == "music"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# openajazz
+
+Control **AJAZZ keyboards** without the Windows app: lighting effects, per-key RGB, key remaps, macros, music sync, sleep and battery. Works over the USB cable or the 2.4G dongle.
+
+![the tui lighting tab with a live effect preview](https://raw.githubusercontent.com/shrey715/openajazz/main/docs/tui-lighting.svg)
+
+> [!WARNING]
+> Unofficial. Not affiliated with AJAZZ. The protocol was reverse engineered from the vendor's Windows driver, and the lighting, colours, per-key RGB and live frames have been confirmed on real keyboards. It only sends the settings packets the official app sends and never touches firmware. Use at your own risk; `openajazz factory-reset` puts the keyboard back to stock.
+
+## Supported keyboards
+
+| Keyboard | Wired | 2.4G dongle | Bluetooth |
+|---|---|---|---|
+| AK820 Max Plus (tri-mode RGB) | yes | yes | no (the keyboard doesn't expose settings over Bluetooth) |
+
+Have another AJAZZ board? Open an issue with the output of `openajazz devices` and the name of the vendor driver package; most of them share this protocol.
+
+## Get it
+
+Pick one:
+
+| | |
+|---|---|
+| **Web, no install** | open **[openajazz.vercel.app](https://openajazz.vercel.app)** in Chrome, Edge or Opera on a computer |
+| **pipx / uv** | `pipx install 'openajazz[music]'` or `uv tool install 'openajazz[music]'` |
+| **AppImage** | grab it from [releases](https://github.com/shrey715/openajazz/releases/latest), `chmod +x`, run |
+
+### Linux permissions
+
+Once, so you don't need sudo (the web app needs this too):
+
+```sh
+openajazz udev --install      # then replug the keyboard or dongle
+```
+
+It only opens the keyboard's settings interface to your user, never the typing one.
+
+## Use it
+
+```sh
+openajazz                          # full-screen TUI
+openajazz status                   # battery
+openajazz light breathing -c cyan  # effect + colour (openajazz modes lists them)
+openajazz lights off               # and `on` brings your lighting back
+openajazz custom -a 101010 w=red a=red s=red d=red
+openajazz remap capslock esc
+openajazz macro f12 +lctrl c -lctrl
+openajazz music --background       # lights follow what's playing, terminal can close
+openajazz autostart music          # ...and start that at every login
+openajazz --help                   # everything else
+```
+
+Coming from ak820ctl? Same commands under the new name; your saved settings and presets move over on first run.
+
+## What doesn't work (yet)
+
+- Bluetooth: plug in the cable or dongle to change settings.
+- Phones: browsers on phones don't support WebHID.
+- Firmware updates and mouse-button assignments aren't supported.
+
+More detail: [CHANGELOG](https://github.com/shrey715/openajazz/blob/main/CHANGELOG.md) · [PROTOCOL.md](https://github.com/shrey715/openajazz/blob/main/PROTOCOL.md) · [issues](https://github.com/shrey715/openajazz/issues)
+
+## Credits
+
+Hardware test results, the colour palette, live-frame behaviour and the effect previews come from [prasoondev/ajazz-linux](https://github.com/prasoondev/ajazz-linux) (MIT).
+
+MIT licensed. "AJAZZ" and "AK820" are trademarks of their owner, used here only to say what hardware this is for.

openajazz-0.4.0/README.md

@@ -0,0 +1,67 @@
+# openajazz
+
+Control **AJAZZ keyboards** without the Windows app: lighting effects, per-key RGB, key remaps, macros, music sync, sleep and battery. Works over the USB cable or the 2.4G dongle.
+
+![the tui lighting tab with a live effect preview](https://raw.githubusercontent.com/shrey715/openajazz/main/docs/tui-lighting.svg)
+
+> [!WARNING]
+> Unofficial. Not affiliated with AJAZZ. The protocol was reverse engineered from the vendor's Windows driver, and the lighting, colours, per-key RGB and live frames have been confirmed on real keyboards. It only sends the settings packets the official app sends and never touches firmware. Use at your own risk; `openajazz factory-reset` puts the keyboard back to stock.
+
+## Supported keyboards
+
+| Keyboard | Wired | 2.4G dongle | Bluetooth |
+|---|---|---|---|
+| AK820 Max Plus (tri-mode RGB) | yes | yes | no (the keyboard doesn't expose settings over Bluetooth) |
+
+Have another AJAZZ board? Open an issue with the output of `openajazz devices` and the name of the vendor driver package; most of them share this protocol.
+
+## Get it
+
+Pick one:
+
+| | |
+|---|---|
+| **Web, no install** | open **[openajazz.vercel.app](https://openajazz.vercel.app)** in Chrome, Edge or Opera on a computer |
+| **pipx / uv** | `pipx install 'openajazz[music]'` or `uv tool install 'openajazz[music]'` |
+| **AppImage** | grab it from [releases](https://github.com/shrey715/openajazz/releases/latest), `chmod +x`, run |
+
+### Linux permissions
+
+Once, so you don't need sudo (the web app needs this too):
+
+```sh
+openajazz udev --install      # then replug the keyboard or dongle
+```
+
+It only opens the keyboard's settings interface to your user, never the typing one.
+
+## Use it
+
+```sh
+openajazz                          # full-screen TUI
+openajazz status                   # battery
+openajazz light breathing -c cyan  # effect + colour (openajazz modes lists them)
+openajazz lights off               # and `on` brings your lighting back
+openajazz custom -a 101010 w=red a=red s=red d=red
+openajazz remap capslock esc
+openajazz macro f12 +lctrl c -lctrl
+openajazz music --background       # lights follow what's playing, terminal can close
+openajazz autostart music          # ...and start that at every login
+openajazz --help                   # everything else
+```
+
+Coming from ak820ctl? Same commands under the new name; your saved settings and presets move over on first run.
+
+## What doesn't work (yet)
+
+- Bluetooth: plug in the cable or dongle to change settings.
+- Phones: browsers on phones don't support WebHID.
+- Firmware updates and mouse-button assignments aren't supported.
+
+More detail: [CHANGELOG](https://github.com/shrey715/openajazz/blob/main/CHANGELOG.md) · [PROTOCOL.md](https://github.com/shrey715/openajazz/blob/main/PROTOCOL.md) · [issues](https://github.com/shrey715/openajazz/issues)
+
+## Credits
+
+Hardware test results, the colour palette, live-frame behaviour and the effect previews come from [prasoondev/ajazz-linux](https://github.com/prasoondev/ajazz-linux) (MIT).
+
+MIT licensed. "AJAZZ" and "AK820" are trademarks of their owner, used here only to say what hardware this is for.

openajazz-0.4.0/openajazz/__init__.py

@@ -0,0 +1,3 @@
+"""openajazz: unofficial control for AJAZZ keyboards (AK820 Max Plus supported)."""
+
+__version__ = "0.4.0"

openajazz-0.4.0/openajazz/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())