Effects Gallery

uchroma supports two fundamentally different types of lighting effects: hardware effects that run directly on your device's firmware, and custom animations that are rendered by the uchroma daemon on your computer.

Hardware Effects vs Custom Animations

Aspect	Hardware Effects	Custom Animations
Execution	Runs on device firmware	Rendered by uchromad on host
CPU Usage	Zero - device handles everything	Low - daemon runs at 15-30 FPS
Persistence	Survives daemon restart/crash	Requires daemon to be running
Complexity	Simple, predefined patterns	Rich, layered, reactive
Customization	Limited parameters	Full control via traitlets
Key Reactivity	Basic (reactive, ripple)	Advanced (ripple, typewriter)
Layering	Single effect only	Multiple layers with blend modes

When to Use Which

Choose Hardware Effects When:

• You want zero CPU overhead
• You need the effect to persist when the daemon isn't running
• A simple built-in effect meets your needs
• Battery life matters (laptops, wireless devices)

Choose Custom Animations When:

• You want rich, complex visual effects
• You need multiple layered effects with blending
• You want effects that react to your typing
• You want fine-grained control over parameters
• You're creating a custom look for your setup

Quick Reference

Hardware Effects

Effect	Description	Key Parameters
Static	Solid color	color
Wave	Moving rainbow wave	direction
Spectrum	Slow color cycling	-
Breathe	Pulsing colors	colors (0-2)
Reactive	Keys light on press	color, speed
Starlight	Sparkling effect	colors, speed
Ripple	Keypress ripples	color, speed
Fire	Animated flames	color, speed
Sweep	Color sweep	color, direction, speed
Morph	Color morphing	color, base_color, speed

Custom Animations

Renderer	Description	Category
Plasma	Classic demoscene plasma	Ambient
Rainbow	Flowing HSV gradient	Ambient
Aurora	Northern lights curtains	Ambient
Nebula	Cosmic cloud formations	Ambient
Ocean	Rolling waves with caustics	Ambient
Vortex	Swirling spiral tunnel	Ambient
Copper Bars	Amiga-style raster bars	Retro
Kaleidoscope	Rotating symmetry	Geometric
Metaballs	Organic lava lamp blobs	Organic
Comets	Streaking light trails	Motion
Embers	Warm floating particles	Particle
Ripple	Keypress ripples	Reactive
Reaction	Key color change	Reactive
Typewriter	Warm key glow fade	Reactive

CLI Commands

Hardware Effects

# List available effects
uchroma fx --list

# Set an effect
uchroma fx static --color '#ff0000'
uchroma fx wave --direction left
uchroma fx breathe --colors '#ff00ff' '#00ffff'

# Disable effects
uchroma fx disable

Custom Animations

# List available renderers
uchroma anim --list

# Add a renderer layer
uchroma anim add plasma --preset sunset
uchroma anim add aurora --speed 1.5

# Show active layers
uchroma anim show

# Modify a layer
uchroma anim set 0 --speed 2.0

# Remove a layer
uchroma anim rm 0

# Stop all animations
uchroma anim stop

Layering and Blending

Custom animations can be stacked in layers with blend modes, creating complex visual effects:

# Create a layered effect
uchroma anim add aurora --speed 0.5   # Base layer (z=0)
uchroma anim add ripple                # React to keys (z=1)

Each layer has a z-index determining its stack position. Higher z-index layers render on top. See Layer Compositing for details on blend modes.

Device Support

Not all devices support all effects. Hardware effect availability depends on the device's firmware. Custom animations work on any device with an addressable LED matrix.

To check what your device supports:

# See available hardware effects
uchroma fx --list

# See device capabilities
uchroma devices --verbose