Document immediate brightness architecture

README.md

@@ -6,6 +6,21 @@ The internal display is the master. Brightness keys change the internal panel, s
 
 This avoids drift from letting two outputs auto-adjust independently.
 
+## Architecture
+
+The real brightness change is intentionally immediate:
+
+```text
+brightness-up/down-all
+  -> brightnessctl immediately changes the internal display
+  -> brightness-osd only displays or updates the visual feedback
+  -> external-brightness-sync.service mirrors the internal percentage later
+```
+
+The actual `brightnessctl` call must not be debounced. Only the OSD may be smoothed by reusing the running OSD process and extending its hide timer.
+
+The external monitor is not changed in the key-binding scripts. `ddcutil` is slower than an internal backlight write, so it runs separately in the sync service.
+
 ## Features
 
 - Internal display controlled with `brightnessctl`
@@ -82,6 +97,7 @@ Default config:
 ```bash
 BRIGHTNESS_BACKLIGHT_DEVICE="intel_backlight"
 BRIGHTNESS_SYNC_BACKLIGHT="/sys/class/backlight/intel_backlight"
+BRIGHTNESS_OSD_BACKLIGHT="/sys/class/backlight/intel_backlight"
 BRIGHTNESS_STEP="10"
 BRIGHTNESS_DDCUTIL_MODEL="HG342PCB"
 BRIGHTNESS_DDCUTIL_DISPLAY="1"

bin/brightness-down-all

@@ -3,12 +3,15 @@ set -euo pipefail
 
 CONFIG="${BRIGHTNESS_AUTOMATION_CONFIG:-$HOME/.config/brightness-automation/env}"
 if [[ -f "$CONFIG" ]]; then
+  set -a
   # shellcheck disable=SC1090
   source "$CONFIG"
+  set +a
 fi
 
 BACKLIGHT_DEVICE="${BRIGHTNESS_BACKLIGHT_DEVICE:-intel_backlight}"
 STEP="${BRIGHTNESS_STEP:-10}"
+export BRIGHTNESS_OSD_BACKLIGHT="${BRIGHTNESS_OSD_BACKLIGHT:-${BRIGHTNESS_SYNC_BACKLIGHT:-/sys/class/backlight/${BACKLIGHT_DEVICE}}}"
 
 brightnessctl -q -d "$BACKLIGHT_DEVICE" set "${STEP}%-"
 "$HOME/.local/bin/brightness-osd" || true

bin/brightness-up-all

@@ -3,12 +3,15 @@ set -euo pipefail
 
 CONFIG="${BRIGHTNESS_AUTOMATION_CONFIG:-$HOME/.config/brightness-automation/env}"
 if [[ -f "$CONFIG" ]]; then
+  set -a
   # shellcheck disable=SC1090
   source "$CONFIG"
+  set +a
 fi
 
 BACKLIGHT_DEVICE="${BRIGHTNESS_BACKLIGHT_DEVICE:-intel_backlight}"
 STEP="${BRIGHTNESS_STEP:-10}"
+export BRIGHTNESS_OSD_BACKLIGHT="${BRIGHTNESS_OSD_BACKLIGHT:-${BRIGHTNESS_SYNC_BACKLIGHT:-/sys/class/backlight/${BACKLIGHT_DEVICE}}}"
 
 brightnessctl -q -d "$BACKLIGHT_DEVICE" set "+${STEP}%"
 "$HOME/.local/bin/brightness-osd" || true

install.sh

@@ -26,6 +26,7 @@ if [[ ! -f "$HOME/.config/brightness-automation/env" ]]; then
   cat >"$HOME/.config/brightness-automation/env" <<EOF
 BRIGHTNESS_BACKLIGHT_DEVICE="$BACKLIGHT_DEVICE"
 BRIGHTNESS_SYNC_BACKLIGHT="$BACKLIGHT_PATH"
+BRIGHTNESS_OSD_BACKLIGHT="$BACKLIGHT_PATH"
 BRIGHTNESS_STEP="$STEP"
 BRIGHTNESS_DDCUTIL_MODEL="$DDC_MODEL"
 BRIGHTNESS_DDCUTIL_DISPLAY="$DDC_DISPLAY"