{"id":19713756,"url":"https://github.com/hyperb1iss/uchroma","last_synced_at":"2026-03-11T17:31:01.684Z","repository":{"id":249453946,"uuid":"76679782","full_name":"hyperb1iss/uchroma","owner":"hyperb1iss","description":"An advanced driver for Razer Chroma hardware in Linux","archived":false,"fork":false,"pushed_at":"2021-03-17T16:17:28.000Z","size":907,"stargazers_count":49,"open_issues_count":17,"forks_count":9,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-07-21T00:27:41.422Z","etag":null,"topics":["animation","blade","chroma","color","driver","hardware","keyboard","led","linux","mouse","python","python-library","razer","razer-chroma","userspace"],"latest_commit_sha":null,"homepage":"https://cyanogen.github.io/uchroma/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperb1iss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2016-12-16T19:27:07.000Z","updated_at":"2024-07-21T00:27:53.029Z","dependencies_parsed_at":"2024-07-21T00:27:43.308Z","dependency_job_id":"40636dea-1e53-4836-a21f-6847f56287c7","html_url":"https://github.com/hyperb1iss/uchroma","commit_stats":null,"previous_names":["hyperb1iss/uchroma"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fuchroma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fuchroma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fuchroma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fuchroma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperb1iss","download_url":"https://codeload.github.com/hyperb1iss/uchroma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224183962,"owners_count":17269763,"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":["animation","blade","chroma","color","driver","hardware","keyboard","led","linux","mouse","python","python-library","razer","razer-chroma","userspace"],"created_at":"2024-11-11T22:24:45.074Z","updated_at":"2026-03-11T17:31:01.677Z","avatar_url":"https://github.com/hyperb1iss.png","language":"Python","readme":"## 💜 uChroma\n\n**RGB Control for Razer Chroma on Linux**\n\n\u003cp\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.10+-3776ab?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/GTK4-Frontend-4a86cf?style=for-the-badge\u0026logo=gtk\u0026logoColor=white\" alt=\"GTK4\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/D--Bus-API-e135ff?style=for-the-badge\u0026logo=freedesktoporg\u0026logoColor=white\" alt=\"D-Bus\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-LGPL--3.0-50fa7b?style=for-the-badge\u0026logo=gnu\u0026logoColor=white\" alt=\"License\"\u003e\n\u003c/p\u003e\n\nThe Razer Chroma line of peripherals have flashy features such as embedded LED matrices and macro keys. This project aims to provide rich support for these features under Linux without requiring kernel modifications.\n\n## ✦ What can it do?\n\n- Supports Razer keyboards, mice, mouse pads, laptops, headsets, and keypads — **[see supported devices](docs/reference/devices.md)**\n- Enables activation of built-in hardware lighting effects\n- Several custom effects included for devices with LED matrices, more on the way\n- Rich animation/framebuffer API for creation of custom effects\n- GTK4 frontend with live LED matrix preview\n- Fan control and power management for laptops\n- Battery monitoring for wireless devices\n- Optimized for low power consumption\n- Simple installation and setup\n- Powerful command line interface\n- D-Bus API\n- 100% _asyncio_-powered Python, 100% open source (LGPL)\n\n📚 **[Full Documentation](docs/)** — User guide, CLI reference, effect development\n\n## 📦 Installation\n\n#### Debian/Ubuntu\n\nPackaging assets live in `debian/` and target modern Python (3.10+). If you're building locally,\nuse your distro's standard `dpkg-buildpackage` workflow.\n\n---\n\n#### Arch\n\nAn AUR package is available, and `packaging/arch/PKGBUILD` provides a modern PKGBUILD baseline.\n\n---\n\n#### Snap\n\nSnap packaging is provided in `snap/snapcraft.yaml` (strict confinement, session D-Bus).\n\n---\n\n#### From Source\n\nUChroma requires Python 3.10 or newer and uses `uv` for dependency management.\n\nSystem integration (udev + systemd user service):\n\n    sudo make install-udev\n    sudo make install-service\n    systemctl --user daemon-reload\n    systemctl --user enable --now uchromad.service\n\nBe sure to uninstall any other software which might alter permissions or change behavior of the devices or kernel HID drivers.\n\n## ⚡ Usage\n\nUChroma consists of two main executables, _uchromad_ and _uchroma_. The _uchromad_ executable runs in the background as a systemd user service, handles all hardware interactions, executes animations, stores preferences, and publishes several D-Bus services for clients to use. The _uchroma_ command provides a uniform interface to all discovered devices. The CLI tool is based on subcommands (similar to Git), and help can be viewed at any level by passing the \"-h\" flag.\n\n---\n\n### Listing devices\n\n    $ uchroma -l\n    [1532:0210.00]: Blade Pro (Late 2016) (BladeProLate2016 / v0.38)\n    [1532:0510.01]: Kraken 7.1 V2 (Kylie) (HN1649D04607845 / v1.135)\n\nThe number after the dot is the device index. You may select a target device with the -d flag using the full identifier or just the device index.\n\n---\n\n### Dump device state\n\n    $ uchroma -d 0 dump\n\n    Device properties:\n\n             device-0 │ Blade Pro (Late 2016)\n     ─────────────────┼────────────────────────────────────────────────────\n           brightness │ 100.0\n          device_type │ laptop\n       driver_version │ 0.99\n     firmware_version │ v0.38\n           has_matrix │ True\n               height │ 6\n                  key │ 1532:0210.00\n          key_mapping │ {'KEY_F12': [[0, 14]], 'KEY_ENTER': [[3, 15], [(...)\n         manufacturer │ Razer\n           product_id │ 528\n        serial_number │ BladeProLate2016\n            suspended │ False\n             sys_path │ /sys/devices/pci0000:00/0000:00:14.0/usb1/1-8\n            vendor_id │ 5426\n                width │ 25\n\n\n\n     Current LED state:\n\n                 logo │ LED: Logo\n     ─────────────────┼────────────────────────────────────────────────────\n           brightness │ 0.0\n              (float) │ a float\n                      │ min: 0.0, max: 100.0, default: 0.0\n     ─────────────────┼────────────────────────────────────────────────────\n                color │  #000000\n              (color) │ a color\n                      │ default: green\n     ─────────────────┼────────────────────────────────────────────────────\n                 mode │ STATIC\n             (choice) │ one of: blink, pulse, spectrum, static\n                      │ default: STATIC\n\n\n\n     Current animation renderer state:\n\n               plasma │ Colorful moving blobs of plasma\n     ─────────────────┼────────────────────────────────────────────────────\n               author │ Stefanie Jane\n          description │ Colorful moving blobs of plasma\n                 name │ Plasma\n              version │ v1.0\n     ─────────────────┼────────────────────────────────────────────────────\n     background_color │  #000000\n              (color) │ a color\n                      │ default: black\n     ─────────────────┼────────────────────────────────────────────────────\n         color_scheme │  #004777  #a30000  #ff7700  #efd28d  #00afb5\n        (colorscheme) │ a list of colors\n                      │ min length: 2\n     ─────────────────┼────────────────────────────────────────────────────\n                  fps │ 15.0\n              (float) │ a float\n                      │ min: 0.0, max: 30, default: 15\n     ─────────────────┼────────────────────────────────────────────────────\n      gradient_length │ 360\n                (int) │ an int\n                      │ min: 0, max: None, default: 360\n     ─────────────────┼────────────────────────────────────────────────────\n               preset │ Qap\n             (choice) │ one of: best, bluticas, bright, emma, newer, qa(...)\n                      │ default: Qap\n\n---\n\n### Built-in effects\n\nBuilt-in effects are executed entirely by the hardware, and the supported types and options vary wildly between models.\n\n#### List available effects:\n\n     $ uchroma -d 0 fx list\n\n     Built-in effects and arguments:\n\n              breathe │ Colors pulse in and out\n     ─────────────────┼────────────────────────────────────────────────────\n               colors │ colorscheme: max length: 2\n\n\n              disable │ Disable all effects\n\n\n                 fire │ Keys on fire\n     ─────────────────┼────────────────────────────────────────────────────\n                color │ color: default: red\n                speed │ int: min: 16, max: 128, default: 64\n\n\n                morph │ Morphing colors when keys are pressed\n     ─────────────────┼────────────────────────────────────────────────────\n           base_color │ color: default: darkblue\n                color │ color: default: magenta\n                speed │ int: min: 1, max: 4, default: 2\n\n\n              rainbow │ Rainbow of hues\n     ─────────────────┼────────────────────────────────────────────────────\n               length │ int: min: 20, max: 360, default: 75\n              stagger │ int: min: 0, max: 100, default: 4\n\n\n             reactive │ Keys light up when pressed\n     ─────────────────┼────────────────────────────────────────────────────\n                color │ color: default: skyblue\n                speed │ int: min: 1, max: 4, default: 1\n\n\n               ripple │ Ripple effect when keys are pressed\n     ─────────────────┼────────────────────────────────────────────────────\n                color │ color: default: green\n                speed │ int: min: 1, max: 8, default: 3\n\n\n         ripple_solid │ Ripple effect on a solid background\n     ─────────────────┼────────────────────────────────────────────────────\n                color │ color: default: green\n                speed │ int: min: 1, max: 8, default: 3\n\n\n             spectrum │ Cycle thru all colors of the spectrum\n\n\n            starlight │ Keys sparkle with color\n     ─────────────────┼────────────────────────────────────────────────────\n               colors │ colorscheme: max length: 2\n                speed │ int: min: 1, max: 4, default: 1\n\n\n               static │ Static color\n     ─────────────────┼────────────────────────────────────────────────────\n                color │ color: default: green\n\n\n                sweep │ Colors sweep across the device\n     ─────────────────┼────────────────────────────────────────────────────\n           base_color │ color: default: black\n                color │ color: default: green\n            direction │ choice: default: RIGHT\n                speed │ int: min: 1, max: 30, default: 15\n\n\n                 wave │ Waves of color\n     ─────────────────┼────────────────────────────────────────────────────\n            direction │ choice: default: RIGHT\n      trackpad_effect │ bool: default: False\n\n#### Activate an effect:\n\n    $ uchroma -d 0 fx fire --color magenta\n\n#### Disable effects:\n\n    $ uchroma -d 0 fx disable\n\n---\n\n### Brightness control\n\nOverall brightness level of the device is represented by a percentage from 0-100.\n\n#### Show current brightness:\n\n    $ uchroma -d 1 brightness\n    100.00\n\n#### Set brightness level:\n\n    $ uchroma -d 1 brightness 85\n\n---\n\n### Animations\n\nUChroma supports custom animations on devices which support a lighting matrix, such as Blade laptops, BlackWidow keyboards, and Mamba mice. Several animation renderers are included, and may also be provided by third-party modules. Multiple concurrent (stacked) animations are supported, and layers will be alpha-blended together. Animations may run at different frame rates, and may trigger from input events or sound. Current animation parameters are shown in the \"uchroma dump\" command, shown above.\n\n#### List available animation renderers:\n\n     $ uchroma -d 0 anim list\n\n     Available renderers and arguments:\n\n                plasma │ Colorful moving blobs of plasma\n     ──────────────────┼───────────────────────────────────────────────────\n                author │ Stefanie Jane\n           description │ Colorful moving blobs of plasma\n                  name │ Plasma\n               version │ v1.0\n     ──────────────────┼───────────────────────────────────────────────────\n      background_color │  #000000\n               (color) │ a color\n                       │ default: black\n     ──────────────────┼───────────────────────────────────────────────────\n          color_scheme │  #004777  #a30000  #ff7700  #efd28d  #00afb5\n         (colorscheme) │ a list of colors\n                       │ min length: 2\n     ──────────────────┼───────────────────────────────────────────────────\n                   fps │ 15.0\n               (float) │ a float\n                       │ min: 0.0, max: 30, default: 15\n     ──────────────────┼───────────────────────────────────────────────────\n       gradient_length │ 360\n                 (int) │ an int\n                       │ min: 0, max: None, default: 360\n     ──────────────────┼───────────────────────────────────────────────────\n                preset │ Qap\n              (choice) │ one of: best, bluticas, bright, emma, newer, q(...)\n                       │ default: Qap\n\n\n              rainflow │ Simple flowing colors\n     ──────────────────┼───────────────────────────────────────────────────\n                author │ Stefanie Jane\n           description │ Simple flowing colors\n                  name │ Rainflow\n               version │ 1.0\n     ──────────────────┼───────────────────────────────────────────────────\n      background_color │ color: default: black\n            blend_mode │ string\n                   fps │ float: min: 0.0, max: 30, default: 15\n               opacity │ float: min: 0.0, max: 1.0, default: 1.0\n                 speed │ int: min: 0, max: 20, default: 8\n               stagger │ int: min: 0, max: 100, default: 4\n\n\n               ripples │ Ripples of color when keys are pressed\n     ──────────────────┼───────────────────────────────────────────────────\n                author │ Stefanie Jane\n           description │ Ripples of color when keys are pressed\n                  name │ Ripples\n               version │ 1.0\n     ──────────────────┼───────────────────────────────────────────────────\n      background_color │ color: default: black\n            blend_mode │ string\n                 color │ color: default: black\n                   fps │ float: min: 0.0, max: 30, default: 15\n               opacity │ float: min: 0.0, max: 1.0, default: 1.0\n                preset │ choice: default: Emma\n                random │ bool: default: True\n          ripple_width │ int: min: 1, max: 5, default: 3\n                 speed │ int: min: 1, max: 9, default: 5\n\n#### Start an animation:\n\n    $ uchroma -d 0 anim add plasma --color_scheme newer\n\n#### Add another layer:\n\n    $ uchroma -d 0 anim add ripples\n\n####Modify parameters of a running layer:\n\n    $ uchroma -d 0 anim mod 0 --color-scheme emma --fps 10\n\n#### Remove a layer:\n\n    $ uchroma -d 0 anim del 1\n\n#### Stop and clear animations:\n\n    $ uchroma -d 0 anim stop\n\n## 🔮 Frequently Asked Questions\n\n#### _My device is not recognized!_\n\n\u003e If you have a device which is not yet supported, you have a couple of options. If the device does not require a new protocol, it can simply be added to the appropriate YAML file under uchroma/server/data. If you like to see a particular model added, please open an issue on Github. If you've added support for a new device, please open a pull request!\n\n#### _This is great, how can I donate hardware or fund development?_\n\n\u003e Razer makes a lot of devices, each with it's own quirks. If you'd like to see a piece of hardware supported, the best way to motivate me is to ship me a device to work with. If you'd like to help ensure continued development, please consider [sending a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=2UQ62RBEANCHQ).\n\n#### _How do I make a custom animation?_\n\n\u003e Proper documentation on this topic is forthcoming, but having a look at the bundled renderers in uchroma/fxlib should be enough to get started on. Implementations must extend **Renderer** and implement the _init_, _finish_, and _draw_ methods. The animation system is a framebuffer and the draw method will be invoked at the FPS requested by your implementation. It's important to keep the FPS as low as possible to avoid unnecessary CPU usage! The draw method is called with a **Layer** object, which provides primitives for drawing shapes and setting individual pixels. The buffer of a frame is a Numpy matrix and may be manipulated directly, if desired. Functions for performing color math and generating gradients/color schemes can be found in the _uchroma.color_ module. We use **Traitlets** for user-configurable parameters.\n\u003e\n\u003e To get an out-of-tree module recognized, declare an entry point to your effect in your module's setup.py:\n\n    entry_points={\n        'uchroma.plugins': ['renderer = my.effect.module:MyClass']\n    }\n\nSend a pull request if you implement a new renderer and would like to have it included!\n\n\u003e\n\n#### _Are you affiliated with Razer Inc?_\n\n\u003e Not in any way, but I won't mind if they deliver a truckload of hardware to me :)\n\n#### _Is Windows supported?_\n\n\u003e No. UChroma relies on UDev and other Linux-specific subsystems to operate.\n\n#### _Is macro recording supported?_\n\n\u003e The skeleton of macro support is there, and will be finished in an upcoming release.\n\n#### _The ripple effect seems misaligned with my keypresses!_\n\n\u003e This is because a mapping of keycodes to LED matrix coordinates must be provided, and the layout varies wildly among devices. Full support in the initial release is provided for the Blade Pro laptop, and a \"generic\" mapping is provided for other models which is almost certainly wrong. If you'd like to create a proper mapping for your device (and contribute it back!), I've created a simple tool which will help. You'll need to start _uchromad_ with UCHROMA_DEV=1 set in the environment, then run \"scripts/devstuff keys\" from the source distribution. The tool will illuminate matrix cells and you just press the key that is lit, repeating for all cells. After creating a new mapping, it will need merged into the appropriate YAML file under uchroma/server/data (and send a pull request!). Support for cell swapping and relocation is also provided, see the Blade Pro configuration for an example of this.\n\n#### _There are other projects with similar functionality, why this?_\n\n\u003e This project was born after realizing that there is zero chance to have the required code used by other projects merged into the Linux kernel since it's very specialized and can be done entirely in userspace. I also wanted rich animation support and low power consumption, which required rewriting large portions of the existing project (and my patches weren't moving forward). After implementing the initial user-space driver, I decided to keep going and try to make the hardware really shine under Linux. Choose what works best for you!\n\n#### _Is a GUI available?_\n\n\u003e Yes! A GTK4 frontend with libadwaita styling is included. Run `uchroma-gtk` to launch it. The GUI provides a live LED matrix preview, effect configuration, and layer management.\n\n#### _How can I contribute?_\n\n\u003e Fork the project and send a pull request with a description of your changes. As this project is currently at the initial release stage, a lot of testing across different models is needed. Documentation is lacking, and support for more distributions is also high on the list. If you find a bug, please file an issue on Github.\n\n## 🧪 Powered by...\n\n#### _Awesome libraries used by UChroma:_\n\n- [Numpy](http://numpy.org)\n- [Scikit-Image](http://scikit-image.org)\n- [ColorAide](https://facelessuser.github.io/coloraide/)\n- [HIDAPI](https://github.com/NF6X/pyhidapi)\n- [Traitlets](https://github.com/ipython/traitlets)\n- [dbus-fast](https://github.com/Bluetooth-Devices/dbus-fast)\n- [pyudev](https://pyudev.readthedocs.io/en/latest/)\n- [python-evdev](https://python-evdev.readthedocs.io/en/latest/)\n\n## Credits\n\n[Copyright (C) 2017-2026 Stefanie Jane](https://github.com/hyperb1iss)\n\n[Inspired by work from Tim Theede and Terry Cain](https://github.com/terrycain/razer-drivers)\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the **GNU Lesser General Public License** as published by the Free Software Foundation, version 3.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Lesser Public License for more details.\n\nYou should have received a copy of the GNU Lesser General Public License along with this program. If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=2UQ62RBEANCHQ"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fuchroma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperb1iss%2Fuchroma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fuchroma/lists"}