Key Light Controller for Linux

A modern, standalone Linux alternative to Elgato's Control Center for Controlling Key Light devices. Native Linux support for both X11 and Wayland. Does not collect any data or "call home"

Features

🔍 Automatic device discovery via mDNS/Bonjour
🎨 Modern dark theme UI styled to match professional control software
💡 Real-time brightness control (1-100% - prevents accidental off)
🌡️ Color temperature control (2900K-7000K)
🔧 System tray integration with minimize/restore
⚡ Smooth, throttled updates to prevent device overload
🖥️ Native Wayland and X11 support - works everywhere
🚀 Single instance enforcement - no duplicate windows
📦 Standalone binary - no installation required
🔄 Dynamic window sizing - adjusts to number of devices
⌨️ Keyboard shortcuts for quick control

Compatibility

Supported Systems

Linux: All major distributions (Ubuntu, Fedora, Arch, Debian, etc.)
Display Servers: X11, Wayland, XWayland
Python: 3.8 or higher
Qt: Uses PySide6 (Qt6)

Quick Start (Pre-built Binary)

Download Latest Release

Go to Releases
Download keylight-controller-linux-x64.tar.gz
Extract and run:

tar -xzf keylight-controller-linux-x64.tar.gz
chmod +x keylight-controller
./keylight-controller

That's it! No installation required.

Installation Options

Option 1: Standalone Binary (Easiest)

# Download from releases page
wget https://github.com/sandwichfarm/keylight-control/releases/latest/download/keylight-controller-linux-x64.tar.gz
tar -xzf keylight-controller-linux-x64.tar.gz
chmod +x keylight-controller
./keylight-controller

# Optional: Install system-wide
sudo mv keylight-controller /usr/local/bin/

Option 2: Build from Source

Prerequisites

Python 3.8+ (python3 --version)
pip package installer

Install Dependencies

# Clone the repository
git clone https://github.com/sandwichfarm/keylight-control.git
cd keylight-control

# Install dependencies
pip3 install --user -r requirements.txt

# Make executable
chmod +x keylight_controller.py

# Run
./keylight_controller.py

Option 3: Using Virtual Environment

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run
python keylight_controller.py

Option 4: System packages (Distribution-specific)

For Arch Linux:

sudo pacman -S python-pyside6 python-aiohttp python-zeroconf
pip install --user qasync

For Ubuntu 22.04+:

sudo apt install python3-pyside6.qtcore python3-pyside6.qtgui python3-pyside6.qtwidgets
pip3 install --user aiohttp zeroconf qasync

Desktop Integration

Create Desktop Entry

# Copy the desktop file
cp keylight-controller.desktop ~/.local/share/applications/

# Update desktop database
update-desktop-database ~/.local/share/applications/

Add to PATH (Optional)

# Create symlink in local bin
ln -s $(pwd)/keylight_controller.py ~/.local/bin/keylight-controller

# Ensure ~/.local/bin is in PATH (add to ~/.bashrc if needed)
export PATH="$HOME/.local/bin:$PATH"

Usage

Launching

From Terminal: ./keylight_controller.py or keylight-controller
From Desktop: Search for "Keylight Control" in your application launcher

Controls

Power Button: Toggle light on/off
Brightness Slider: Adjust light intensity (1-100%)
Temperature Slider: Adjust color temperature (2900K-7000K)
System Tray: Click to show/hide, right-click for menu

Keyboard Shortcuts

Ctrl+Q: Quit application
Escape: Minimize to system tray
Shift+Click X: Force quit (bypass tray)

Local API

A local API allows external scripts and window-manager keybindings to control your lights without interacting with the GUI. Two transports are available: a Unix socket (enabled by default) and an optional HTTP server.

Configuration

API settings are under Settings → Advanced in the application.

Setting	Type	Default	Description
`advanced.api_enabled`	bool	`true`	Master switch — disables all API transports when off
`advanced.api_unix_socket`	bool	`true`	Enable the Unix socket transport
`advanced.api_http`	bool	`false`	Enable the HTTP transport
`advanced.api_http_port`	int	`27301`	Port for the HTTP server

Socket path: $XDG_RUNTIME_DIR/keylight-control.sock (fallback: /tmp/keylight-control.sock). The socket is created with 0600 permissions (owner-only).

API Command Reference

Command	Parameters	Description
`lights.list`	—	List all discovered devices and their current state
`lights.get`	`id`	Get the state of a single device
`lights.set`	`id`, and any of: `on`, `brightness`, `temperature`	Set one or more properties on a device
`lights.toggle`	—	Master toggle (all lights)
`lights.toggle`	`id`	Toggle an individual device on/off

Device id — a 0-based integer index (0, 1, …) or a MAC address string ("AA:BB:CC:DD:EE:FF").

Property constraints:

Property	Type	Range	Notes
`on`	bool	`true` / `false`	Power state
`brightness`	int	1 – 100	Percentage; clamped to range
`temperature`	int	143 – 344	Elgato native units (143 ≈ 7000 K, 344 ≈ 2900 K); clamped to range

Response Format

Every response contains an "ok" field. On success additional data is included; on failure an "error" string is returned.

Success (single device):

{
  "ok": true,
  "device": {
    "index": 0,
    "name": "Key Light",
    "ip": "192.168.1.100",
    "port": 9123,
    "mac": "AA:BB:CC:DD:EE:FF",
    "on": true,
    "brightness": 75,
    "temperature": 200
  }
}

Success (device list):

{
  "ok": true,
  "devices": [
    { "index": 0, "name": "Key Light", "ip": "192.168.1.100", "port": 9123, "mac": "AA:BB:CC:DD:EE:FF", "on": true, "brightness": 75, "temperature": 200 },
    { "index": 1, "name": "Key Light Air", "ip": "192.168.1.101", "port": 9123, "mac": "BB:CC:DD:EE:FF:00", "on": false, "brightness": 50, "temperature": 250 }
  ]
}

Error:

{
  "ok": false,
  "error": "Device index 5 out of range (0-1)"
}

Unix Socket Examples

The socket speaks newline-delimited JSON. Send a request object and read back one JSON line. socat is the easiest way to interact with it from the shell.

SOCK="$XDG_RUNTIME_DIR/keylight-control.sock"

# List all devices
echo '{"command":"lights.list"}' | socat - UNIX-CONNECT:$SOCK

# Get state of device 0
echo '{"command":"lights.get","params":{"id":0}}' | socat - UNIX-CONNECT:$SOCK

# Toggle all lights (master toggle)
echo '{"command":"lights.toggle"}' | socat - UNIX-CONNECT:$SOCK

# Toggle a single light by index
echo '{"command":"lights.toggle","params":{"id":0}}' | socat - UNIX-CONNECT:$SOCK

# Toggle a single light by MAC address
echo '{"command":"lights.toggle","params":{"id":"AA:BB:CC:DD:EE:FF"}}' | socat - UNIX-CONNECT:$SOCK

# Set brightness and temperature on device 0
echo '{"command":"lights.set","params":{"id":0,"brightness":80,"temperature":200}}' | socat - UNIX-CONNECT:$SOCK

# Turn off device 1
echo '{"command":"lights.set","params":{"id":1,"on":false}}' | socat - UNIX-CONNECT:$SOCK

HTTP API Reference

Enable the HTTP transport in Settings → Advanced → Enable HTTP API. It binds to 127.0.0.1 only.

Method	Path	API Command	Notes
GET	`/api/lights`	`lights.list`
GET	`/api/lights/{id}`	`lights.get`
PUT	`/api/lights/{id}`	`lights.set`	Properties in JSON body or query string
POST	`/api/lights/toggle`	`lights.toggle`	Master toggle (all lights)
POST	`/api/lights/{id}/toggle`	`lights.toggle`	Toggle individual device

Parameters can be passed as a JSON body (Content-Type: application/json) or as query-string parameters. Returns 200 on success, 400 on error.

# List all devices
curl http://localhost:27301/api/lights

# Get device 0
curl http://localhost:27301/api/lights/0

# Toggle all lights
curl -X POST http://localhost:27301/api/lights/toggle

# Toggle device 0
curl -X POST http://localhost:27301/api/lights/0/toggle

# Set brightness via JSON body
curl -X PUT http://localhost:27301/api/lights/0 \
  -H 'Content-Type: application/json' \
  -d '{"brightness":75}'

# Set brightness and temperature via query string
curl -X PUT "http://localhost:27301/api/lights/0?brightness=75&temperature=200"

# Turn device 1 off
curl -X PUT http://localhost:27301/api/lights/1 \
  -H 'Content-Type: application/json' \
  -d '{"on":false}'

Shell Helper Function

A small wrapper makes keybindings cleaner:

# Add to ~/.bashrc, ~/.zshrc, or a standalone script
keylight() {
  local sock="${XDG_RUNTIME_DIR}/keylight-control.sock"
  local cmd="$1"; shift
  local params=""
  if [ $# -gt 0 ]; then
    params=',"params":{'"$(printf '%s' "$@")"'}'
  fi
  echo "{\"command\":\"$cmd\"$params}" | socat - UNIX-CONNECT:"$sock"
}

# Usage:
#   keylight lights.toggle
#   keylight lights.list
#   keylight lights.set '"id":0,"brightness":80'

Compositor & Desktop Environment Keybindings

Below are copy-pasteable examples for binding light controls to keyboard shortcuts. All examples use the Unix socket; replace the socat command with a curl call if you prefer HTTP.

Hyprland

# ~/.config/hypr/hyprland.conf
bind = $mod, F5, exec, echo '{"command":"lights.toggle"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bind = $mod, F6, exec, echo '{"command":"lights.set","params":{"id":0,"brightness":50}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bind = $mod, F7, exec, echo '{"command":"lights.set","params":{"id":0,"brightness":100}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock

sway

# ~/.config/sway/config
bindsym $mod+F5 exec echo '{"command":"lights.toggle"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bindsym $mod+F6 exec echo '{"command":"lights.set","params":{"id":0,"brightness":50}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bindsym $mod+F7 exec echo '{"command":"lights.set","params":{"id":0,"brightness":100}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock

i3

# ~/.config/i3/config
bindsym $mod+F5 exec echo '{"command":"lights.toggle"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bindsym $mod+F6 exec echo '{"command":"lights.set","params":{"id":0,"brightness":50}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock
bindsym $mod+F7 exec echo '{"command":"lights.set","params":{"id":0,"brightness":100}}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock

KDE Plasma

Open System Settings → Shortcuts → Custom Shortcuts
Click Edit → New → Global Shortcut → Command/URL
Set the Trigger to your preferred key combination

Set the Action to:

bash -c 'echo '"'"'{"command":"lights.toggle"}'"'"' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock'

GNOME

# Toggle all lights on Super+F5
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/keylight-toggle/']"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/keylight-toggle/ name 'Toggle Key Lights'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/keylight-toggle/ binding '<Super>F5'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/keylight-toggle/ command "bash -c 'echo '\"'\"'{\"command\":\"lights.toggle\"}'\"'\"' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/keylight-control.sock'"

Tip: For multiple GNOME keybindings, append additional paths to the custom-keybindings array and repeat the three set calls with a different path suffix.

Troubleshooting

"No module named 'PySide6'"

pip3 install --user PySide6

"qt.qpa.plugin: Could not find the Qt platform plugin"

For Wayland:

export QT_QPA_PLATFORM=wayland

For X11:

export QT_QPA_PLATFORM=xcb

Permission Issues

If you get permission errors with pip:

pip3 install --user -r requirements.txt

Multiple Python Versions

If you have multiple Python versions:

python3.8 -m pip install -r requirements.txt
python3.8 keylight_controller.py

Device Not Found

Ensure devices are on the same network
Check firewall settings for mDNS (port 5353)
Verify devices are powered on

Dependencies

PySide6: Qt6 bindings for Python
aiohttp: Async HTTP client
zeroconf: mDNS service discovery
qasync: Qt async event loop integration

License

GPL-3.0

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github/workflows		.github/workflows
assets		assets
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
RELEASE.md		RELEASE.md
build.sh		build.sh
bump_version.sh		bump_version.sh
keylight-controller.desktop		keylight-controller.desktop
keylight_controller.spec		keylight_controller.spec
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

Key Light Controller for Linux

Features

Compatibility

Supported Systems

Quick Start (Pre-built Binary)

Download Latest Release

Installation Options

Option 1: Standalone Binary (Easiest)

Option 2: Build from Source

Prerequisites

Install Dependencies

Option 3: Using Virtual Environment

Option 4: System packages (Distribution-specific)

Desktop Integration

Create Desktop Entry

Add to PATH (Optional)

Usage

Launching

Controls

Keyboard Shortcuts

Local API

Configuration

API Command Reference

Response Format

Unix Socket Examples

HTTP API Reference

Shell Helper Function

Compositor & Desktop Environment Keybindings

Hyprland

sway

i3

KDE Plasma

GNOME

Troubleshooting

"No module named 'PySide6'"

"qt.qpa.plugin: Could not find the Qt platform plugin"

Permission Issues

Multiple Python Versions

Device Not Found

Dependencies

License

Contributing

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages