Skip to content

README.md

Latest commit

 

History

History
88 lines (66 loc) · 3.62 KB

README.md

File metadata and controls

88 lines (66 loc) · 3.62 KB
Raw

Luminos

DDC brightness companion for external monitors on Apple Silicon Macs. Closes the gap where macOS only adjusts the built-in display's brightness.

What it does

  • Auto-sync: keeps the external monitor's hardware backlight mapped to the built-in display's brightness (polls 1×/s). This means F14/F15 and the ambient-light sensor drive both displays — no Accessibility permission needed.
  • Movie mode: one-command hardware backlight boost for dark movies. Saves current DDC luminance/contrast, sets max; running it again restores.
  • Status bar item: monitor icon in the menu bar with a gamma slider (0.5–3.5) for the external display — lift shadow detail in dark scenes — plus Reset Gamma, Sync toggle, Movie Mode toggle, and Quit.

Usage

Luminos is a menu-bar app (LSUIElement agent, no Dock icon). It installs to ~/Applications/Luminos.app and starts at login via LaunchAgent.

# CLI (works while the app is running)
~/Applications/Luminos.app/Contents/MacOS/Luminos --movie   # toggle movie mode
~/Applications/Luminos.app/Contents/MacOS/Luminos --test    # diagnostics + DDC write probe

Log: /tmp/luminos.log (launchd stdout) and the unified log (log show --predicate 'process == "Luminos"' --last 10m).

Install / autostart

./build.sh    # build → bundle → ad-hoc sign → deploy to ~/Applications → (re)start

LaunchAgent: ~/Library/LaunchAgents/dev.luminos.daemon.plist (starts at login, KeepAlive with 30 s throttle)

launchctl kickstart -k gui/$(id -u)/dev.luminos.daemon   # restart
launchctl bootout gui/$(id -u)/dev.luminos.daemon        # stop

Configuration

Tunables at the top of Sources/luminos/main.swift:

Constant Default Meaning
DISPLAY_ARG 2 m1ddc display index (m1ddc display list)
STEP 8 DDC step for key mirroring (if tap enabled)
SYNC_MIN/MAX 10 / 100 DDC range the built-in 0–100% maps onto
SYNC_HYSTERESIS 2 min change before writing to the monitor
MOVIE_LUMINANCE/CONTRAST 100 / 85 movie mode targets

Rebuilding

Just run ./build.sh — it builds, bundles, signs, stops the daemon, replaces the app and restarts it in one go.

Important: the script replaces Luminos.app with rm -rf + cp -R (new inode). Never overwrite the app in place — macOS tracks the running binary by inode (code-signature provenance); overwriting it makes the kernel SIGKILL future launches with "Taskgated Invalid Signature".

Note: the binary is ad-hoc signed; if you ever enable the CGEvent tap code path (media-key interception), macOS Accessibility grants bind to the build hash and must be re-granted after each rebuild. A self-signed identity (certs/) was created for this but is not currently wired into the build.

Dependencies

  • m1ddc (brew install m1ddc) — DDC/CI transport
  • No other dependencies; single-file Swift executable.

Known limitations

  • External monitor must support DDC/CI over its connection (USB-C/DP on Apple Silicon; built-in HDMI on M1 does not pass DDC).
  • Some monitors accept DDC contrast writes but silently ignore luminance writes (often due to a dynamic-contrast/eco picture mode). Auto-sync and movie mode require a monitor that accepts luminance writes; the gamma slider works regardless. Run bin/luminos --test to probe your display.
  • Sync has ~1–2 s latency by design (polling + hysteresis) to avoid spamming the monitor's I²C bus.
  • Gamma is a GPU color-table adjustment: it resets on display sleep, reconnect, or reboot (re-apply via the slider), and conflicts with f.lux-style tools.