Uchroma
An advanced driver for Razer Chroma hardware in Linux with multi-layer animation support
Install / Use
/learn @hyperb1iss/UchromaREADME
The 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.
✦ What can it do?
- Supports Razer keyboards, mice, mouse pads, laptops, headsets, and keypads — see supported devices
- Enables activation of built-in hardware lighting effects
- Several custom effects included for devices with LED matrices, more on the way
- Rich animation/framebuffer API for creation of custom effects
- GTK4 frontend with live LED matrix preview
- Fan control and power management for laptops
- Battery monitoring for wireless devices
- Optimized for low power consumption
- Simple installation and setup
- Powerful command line interface
- D-Bus API
- 100% asyncio-powered Python, 100% open source (LGPL)
📚 Full Documentation — User guide, CLI reference, effect development
📦 Installation
Ubuntu/Debian (PPA)
sudo add-apt-repository ppa:hyperb1iss/ppa
sudo apt update
sudo apt install uchroma
Arch Linux (AUR)
yay -S uchroma
# or
paru -S uchroma
Fedora
# Build from packaging/fedora/uchroma.spec
sudo dnf install rpm-build rust cargo maturin python3-devel
rpmbuild -bb packaging/fedora/uchroma.spec
sudo dnf install ~/rpmbuild/RPMS/x86_64/uchroma-*.rpm
PyPI
pipx install uchroma
# or
uv tool install uchroma
From Source
UChroma requires Python 3.11+ and uses uv for dependency management.
# Clone and install dependencies
git clone https://github.com/hyperbliss/uchroma.git
cd uchroma
make sync
# System integration (udev rules + systemd user service)
sudo make install-udev
make install-service
systemctl --user daemon-reload
systemctl --user enable --now uchromad.service
Be sure to uninstall any other software which might alter permissions or change behavior of the devices or kernel HID drivers.
⚡ Usage
UChroma 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.
Listing devices
$ uchroma -l
[1532:0210.00]: Blade Pro (Late 2016) (BladeProLate2016 / v0.38)
[1532:0510.01]: Kraken 7.1 V2 (Kylie) (HN1649D04607845 / v1.135)
The 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.
Dump device state
$ uchroma -d 0 dump
Device properties:
device-0: Blade Pro (Late 2016)
brightness: 100.0
device_type: laptop
firmware_version: v0.38
has_matrix: True
dimensions: 6x25
manufacturer: Razer
serial_number: BladeProLate2016
Current LED state:
logo (LED: Logo)
brightness: 0.0 (float, 0.0-100.0)
color: #000000 (default: green)
mode: STATIC (blink, pulse, spectrum, static)
Current animation renderer state:
plasma: Colorful moving blobs of plasma
author: Stefanie Jane, version: v1.0
background_color: #000000 (default: black)
color_scheme: #004777 #a30000 #ff7700 #efd28d #00afb5
fps: 15.0 (0.0-30)
gradient_length: 360
preset: Qap
Built-in effects
Built-in effects are executed entirely by the hardware, and the supported types and options vary wildly between models.
List available effects:
$ uchroma -d 0 fx list
Built-in effects and arguments:
breathe - Colors pulse in and out
colors: colorscheme (max length: 2)
disable - Disable all effects
fire - Keys on fire
color: color (default: red)
speed: int (16-128, default: 64)
morph - Morphing colors when keys are pressed
base_color: color (default: darkblue)
color: color (default: magenta)
speed: int (1-4, default: 2)
rainbow - Rainbow of hues
length: int (20-360, default: 75)
stagger: int (0-100, default: 4)
reactive - Keys light up when pressed
color: color (default: skyblue)
speed: int (1-4, default: 1)
ripple - Ripple effect when keys are pressed
color: color (default: green)
speed: int (1-8, default: 3)
ripple_solid - Ripple effect on a solid background
color: color (default: green)
speed: int (1-8, default: 3)
spectrum - Cycle thru all colors of the spectrum
starlight - Keys sparkle with color
colors: colorscheme (max length: 2)
speed: int (1-4, default: 1)
static - Static color
color: color (default: green)
sweep - Colors sweep across the device
base_color: color (default: black)
color: color (default: green)
direction: choice (default: RIGHT)
speed: int (1-30, default: 15)
wave - Waves of color
direction: choice (default: RIGHT)
trackpad_effect: bool (default: False)
Activate an effect:
$ uchroma -d 0 fx fire --color magenta
Disable effects:
$ uchroma -d 0 fx disable
Brightness control
Overall brightness level of the device is represented by a percentage from 0-100.
Show current brightness:
$ uchroma -d 1 brightness
100.00
Set brightness level:
$ uchroma -d 1 brightness 85
Animations
UChroma 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.
List available animation renderers:
$ uchroma -d 0 anim list
Available renderers and arguments:
plasma - Colorful moving blobs of plasma
author: Stefanie Jane, version: v1.0
background_color: color (default: black)
color_scheme: colorscheme (min length: 2)
fps: float (0.0-30, default: 15)
gradient_length: int
preset: choice (default: Qap)
rainflow - Simple flowing colors
author: Stefanie Jane, version: 1.0
background_color: color (default: black)
blend_mode: string
fps: float (0.0-30, default: 15)
opacity: float (0.0-1.0, default: 1.0)
speed: int (0-20, default: 8)
stagger: int (0-100, default: 4)
ripples - Ripples of color when keys are pressed
author: Stefanie Jane, version: 1.0
background_color: color (default: black)
blend_mode: string
color: color (default: black)
fps: float (0.0-30, default: 15)
opacity: float (0.0-1.0, default: 1.0)
preset: choice (default: Emma)
random: bool (default: True)
ripple_width: int (1-5, default: 3)
speed: int (1-9, default: 5)
Start an animation:
$ uchroma -d 0 anim add plasma --color_scheme newer
Add another layer:
$ uchroma -d 0 anim add ripples
Modify parameters of a running layer:
$ uchroma -d 0 anim mod 0 --color-scheme emma --fps 10
Remove a layer:
$ uchroma -d 0 anim del 1
Stop and clear animations:
$ uchroma -d 0 anim stop
🔮 Frequently Asked Questions
My device is not recognized!
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!
This is great, how can I donate hardware or fund development?
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.
How do I make a custom animation?
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.
To get an out-of-tree module recognized, declare an entr
