tobi/KDEAmbi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update README.md for environment variable configuration and new features

Browse Source
This commit is contained in:
Tobias J. Endres 2025-08-16 05:47:50 +02:00
parent c46fade6b0
commit 32b32adbe0
1 changed files with 42 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
README.md
View File

@ -1,7 +1,5 @@
# Hyperion_Grabber_Wayland_QT
Hyperion image grabber for Wayland / Linux. https://github.com/hyperion-project
Hyperion image grabber for Wayland / Linux. This application captures screen content, processes it using a Hyperion-like algorithm, and sends the calculated LED colors directly to a WLED device.
## Compilation
@ -9,7 +7,7 @@ To compile run `cmake . && make`, qt6 (core / gui / multimedia / multimediawidge
## Wayland Proof of Concept
This project now includes a proof-of-concept Wayland grabber, `wayland_poc`. This executable is used to test and develop screen capturing on Wayland.
This project includes a proof-of-concept Wayland grabber, `wayland_poc`. This executable is used to test and develop screen capturing on Wayland.
To build and run the Wayland POC:
1. Make sure you have the required dependencies installed (Qt6, PipeWire).
@ -20,28 +18,54 @@ This will open a window and, after you grant permission in the system's dialog,
## Usage
Run `Hyperion_Grabber_Wayland_QT` with no arguments or argument `--help` to get a list of options and descriptions.
This application is configured entirely through environment variables. This provides flexibility for deployment and integration into various systems.
Example usage: `Hyperion_Grabber_X11_QT --address 192.168.2.213 --port 19444 --frameskip 1 --scale 48 --inactive 600 --redadjust "255,10,0" --greenadjust "75,210,0" --blueadjust "0,10,160" --temperature "255,255,255" --threshold "0.0,0.0,0.0" --transform "1.0,0.0,1.0"`
To run the grabber, set the following environment variables and then execute the `Hyperion_Grabber_Wayland_QT` executable:
```bash
# --- Required WLED Connection Settings ---
# IP address of your WLED device (e.g., 192.168.1.177)
export HYPERION_GRABBER_WLED_ADDRESS="<YOUR_WLED_IP_ADDRESS>"
# UDP port of your WLED device for Realtime data (default: 21324)
export HYPERION_GRABBER_WLED_PORT="21324"
# --- Grabber Settings ---
# Divisor used to scale your screen resolution (e.g., 8)
# If your screen is 1920x1080 and SCALE is 8, the image sent to HyperionProcessor is 240x135.
# A smaller value means higher resolution and more CPU/bandwidth usage.
export HYPERION_GRABBER_SCALE="8"
# Number of frames to skip between captures (0 means no frames are skipped)
export HYPERION_GRABBER_FRAMESKIP="0"
# Threshold for image change detection (0-255). Only emit new frames if difference exceeds this.
# Higher values reduce flickering but might miss subtle changes. (default: 100)
export HYPERION_GRABBER_CHANGE_THRESHOLD="100"
## Info
# --- LED Layout Configuration ---
# Number of LEDs on the bottom edge of your display (e.g., 70)
export HYPERION_GRABBER_LEDS_BOTTOM="70"
# Number of LEDs on the right edge of your display (e.g., 20)
export HYPERION_GRABBER_LEDS_RIGHT="20"
# Number of LEDs on the top edge of your display (e.g., 70)
export HYPERION_GRABBER_LEDS_TOP="70"
# Number of LEDs on the left edge of your display (e.g., 20)
export HYPERION_GRABBER_LEDS_LEFT="20"
The -i option can turn off the Hyperion LED's after a configurable amount of time.
The -s option will scale your input resolution by dividing it by this option.
If your display is 3840x2160 and you put in -s 10, the image sent to Hyperion will be 384x216 for example
You should set this option so the image resolution sent to Hyperion is at least the size of your LED array, if you have for example 64 high by 36 wide of LED's, you would want to set -s to 60 or smaller (between 1 and 60) on a 3840x2160 display. The closer to 1 this setting is, the more CPU / bandwith will be used.
Ideally you want a perfect dividor, for example if your LED array is 70x39 and screen sis 3840x2160, then you get (3840/70) 54.86 for the width and (2160/39) 55.38 for the height, the nearest perfect dividor is 48 (3840/48 = 80 ; 2160/48 = 45), if you were to use 54, then there would be rounding error (3840/54 = 71.111, but is truncated to 71) and the image sent to hyperion will not be correctly scaled.
# --- Hyperion Algorithm Settings ---
# Black border detection threshold (0.0 to 1.0). Higher values are more aggressive.
# This helps ignore dark UI elements or black bars in videos. (default: 0.2)
export HYPERION_GRABBER_BLACK_BORDER_THRESHOLD="0.2"
# Smoothing factor for color transitions (0.0 to 1.0). Higher values result in smoother transitions.
# 0.0 = no smoothing, 1.0 = full smoothing (colors won't change). (default: 0.1)
export HYPERION_GRABBER_SMOOTHING_FACTOR="0.1"
# --- Run the application ---
./Hyperion_Grabber_Wayland_QT
```
Replace `<YOUR_WLED_IP_ADDRESS>` with the actual IP address of your WLED device.
For more detailed information on the Hyperion processing algorithm and development lessons learned, please refer to the `docs/` directory.
## Contributing
There are probably bugs, please submit a pull request if you can.
There are probably bugs, please submit a pull request if you can.