LightFrame

Overview

LightFrame is a cross-platform utility to capture the screen and adjust an LED strip's colors accordingly. It supports various platforms including Linux (both X11 and Wayland), macOS, and Windows. The utility reads the screen, calculates the average color of different screen segments, and sends this data over a serial connection to control an LED strip behind an ESP32 that runs light_frame_receiver.

Features

• Supports X11 and Wayland on Linux
• Supports macOS and Windows
• Configurable number of LEDs and other parameters
• Serial communication to send color data
• Automatically starts on device connection using udev rules (Linux)

• CMake 3.10 or higher
• OpenCV
• X11 libraries (for X11 support)
• Grim (for Wayland support)

Installation

Linux (Ubuntu/Debian-based distributions)

sudo apt update
sudo apt install cmake libopencv-dev grim # For Wayland
sudo apt install cmake libopencv-dev libx11-dev # For X11

Arch Linux

sudo pacman -S cmake opencv grim # For Wayland
sudo pacman -S cmake opencv xorg-server-devel # For X11

macOS

brew install cmake opencv

Windows

• Download and install CMake from cmake.org
• Install OpenCV following the official instructions

Building the Project

1. Clone the Repository:

   git clone https://github.com/stephanballer/light_frame.git
   cd light_frame

2. Create a Build Directory:

   mkdir build
   cd build

3. Run CMake:

   For X11 support:

   cmake -DUSE_X11=ON ..

   For Wayland support:

   cmake -DUSE_WAYLAND=ON ..

4. Build the Project:

   make

5. Install the Project:

   sudo make install

6. Reload udev Rules (if on Linux):

   sudo udevadm control --reload-rules
   sudo udevadm trigger
   sudo systemctl daemon-reload

Usage

Linux

The program will automatically run when a device matching the udev rule is connected. If you need to run it manually:

backlight_capture /dev/ttyUSBX

Replace /dev/ttyUSBX with the appropriate serial device.

macOS

sudo make install places a LaunchAgent in /Library/LaunchAgents, so the program starts in your GUI session at login and retries every 30 seconds until the device shows up. Load it without logging out:

launchctl bootstrap gui/$UID /Library/LaunchAgents/com.backlight_capture.backlight_capture.plist

Screen capture is gated by TCC: grant Screen Recording to /Library/Application Support/BacklightCapture/backlight_capture.app under System Settings > Privacy & Security > Screen Recording, then restart the agent:

launchctl kickstart -k gui/$UID/com.backlight_capture.backlight_capture

The app is ad-hoc signed, so a rebuild changes its code hash and invalidates the approval. If capture stops working after make install, clear the stale entry and grant it again:

tccutil reset ScreenCapture com.backlight_capture.backlight_capture

The serial port is hardcoded in /Library/Application Support/BacklightCapture/backlight_capture.sh (/dev/cu.usbserial-0001 by default); logs go to ~/Library/Logs/backlight_capture.log.

Configuration

You can configure the number of LEDs and other parameters via the config file:

• Linux: /etc/backlightcapture/config.txt
• Macos: /Library/Application Support/BacklightCapture/config.txt
• Windows: C:\ProgramData\BacklightCapture\config.txt

or via command-line arguments. For example:

backlight_capture /dev/ttyUSBX -H 21 -aH 1 -V 9 -aV 0 -t 32 -s 4 -b 0.2 -f 60

• -H, --horizontal-leds: Number of horizontal LEDs
• -aH, --add-horizontal: Add virtual LEDs left and right
• -V, --vertical-leds: Number of vertical LEDs
• -aV, --add-vertical: Add virtual LEDs top and bottom
• -t, --border-thickness: Border thickness while calculating average color
• -s, --skip-pixels: Number of pixels to skip while calculating average color
• -b, --brightness: LED brightness
• -f, --max-fps: Maximum frames per second

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• OpenCV
• CMake
• X11
• Wayland
• Grim