[07]entry 7 of 34
Luna
this entry is written twice, in full
- 1.in brief
brightness, volume and XDR for every display on a Mac
- 2.in general
One calm menu bar panel for every display on your Mac: brightness, volume, XDR and rounded corners.
- 3.in particular
One slider per display that runs below 0% and past 100%, driving each monitor through whatever it answers to: the private framework behind the brightness keys, DDC/CI over I2C, a scaled colour table, or a lift into its HDR headroom.
- 1.in brief
a control panel for every screen plugged into a Mac
- 2.in general
One calm panel in the menu bar that sets the brightness, volume and corners of every screen on your Mac.
- 3.in particular
Each screen is reached however it can be: through the hidden part of macOS the brightness keys use, by talking to the monitor down its own cable, or by dimming the picture itself, all behind one slider that goes darker than off and brighter than full.
context
Luna is a free, open-source menu bar app for every display on a Mac: the built-in screen, Apple’s own monitors, any monitor that speaks DDC/CI, and TVs, DisplayLink, Sidecar and AirPlay displays. It is a SwiftPM package with no Xcode project, in three targets: a small C target of private display APIs, LunaCore (displays, DDC/CI, dimming, XDR, rounded corners and auto brightness, with no UI) and the app, in Swift1 6 with the main actor as default isolation. It ships as a universal DMG for macOS 14+ and updates itself through Sparkle7. Lunar has every knob there is; Luna is for everyone else, with one card per display and a control only where that display supports it.
the problem
macOS only really controls the displays Apple made. A third-party monitor ignores the brightness keys, its speakers cannot be set over HDMI or DisplayPort audio, and the only way to its backlight is DDC/CI, a VESA protocol over the display cable’s I2C lines that monitors implement unevenly: some garble replies, some answer every read with a null message and still obey writes, and many misbehave when two messages overlap. Displays with HDR headroom never spend it on ordinary content, and nothing goes darker than the panel’s own minimum.
what i built
- 1.
Four ways to set a brightness, chosen per display: DisplayServices (the private framework behind the brightness keys) for the built-in screen and Apple’s monitors, DDC/CI for other monitors, and a scaled gamma table or a black shade window for TVs, DisplayLink, Sidecar and AirPlay
- 2.
DDC/CI through IOAVService on Apple Silicon and the IOFramebuffer’s I2C bus on Intel: Get and Set VCP packets with XOR checksums, null replies told apart from garbage, garbled reads retried, and every display’s traffic on one serial queue where a newer value replaces a waiting write, so a dragged slider sends only what the monitor can take
- 3.
Private APIs resolved at runtime with dlsym in the C target, so a symbol missing from a future macOS costs one feature instead of crashing the app; displays are paired with their framebuffers by scoring EDID fields and assigning greedily
- 4.
A slider that runs below 0% into software dimming and, on displays with HDR headroom, past 100% into XDR: the colour table is lifted above 1 while a one-point window of extended-range white, drawn with Metal5, keeps the headroom open
- 5.
Auto brightness that learns: Match Mac follows the built-in display through a DisplayServices observer, Sun follows the sun’s elevation from NOAA’s solar equations (located once by CoreLocation6, or guessed from the time zone), and each manual adjustment becomes a point on a per-display curve that is kept rising
- 6.
The keyboard’s brightness and volume keys for every display, through an event tap that sees only media-key events: keys macOS already handles pass straight through, the rest drive DDC/CI or dimming with Luna’s own indicator, and ⌥⇧ gives quarter steps
- 7.
Rounded screen corners as four small windows per screen with continuous corners, a monitor’s volume, mute and input where it has them, turning a display off without unplugging it, and global shortcuts
- 8.
Private by construction: no analytics and no account, the network used only for Sparkle7’s update check, location kept on the Mac, and Accessibility used only for the brightness and volume keys
outcome
5,708 lines of Swift1 in 35 files and 248 lines of C, with 48 tests in 10 suites, written with Swift Testing8, covering the slider’s three zones, DDC/CI packets and replies, auto brightness, the solar maths, settings and which displays get XDR; all 48 pass. The universal DMG is 5.2 MB. What it builds on (MonitorControl’s DDC/CI on Apple Silicon and key tap, xdr-boost’s extended-range layer, Rounder’s corners) is credited in the repository, file by file.
A control appears only where a display supports it, and a monitor that answers nothing is still dimmed in software, so every screen on the desk gets one card and one slider.
context
Luna is a free, open-source app that lives in the Mac’s menu bar and controls every screen attached to it: the laptop’s own, Apple’s monitors, other makers’ monitors, and televisions, wireless screens and an iPad used as a screen. It is built in three layers: a small part that reaches into hidden corners of macOS, an engine that knows about screens and has no interface at all, and the app on top. It comes as a single installer for both kinds of Mac and updates itself. An older app, Lunar, has every setting anyone could want; Luna is for everyone else, with one card per screen and a control only where that screen can use it.
the problem
A Mac only properly controls the screens Apple made. Another maker’s monitor ignores the brightness keys, its speakers cannot be turned up from the Mac at all, and the only way to change its backlight is to send it messages down the video cable, in a standard that monitors follow unevenly: some send back nonsense, some answer every question with a polite non-answer and still do as they are told, and many get confused when two messages arrive at once. Screens that can go much brighter for high-dynamic-range video never do it for ordinary work, and nothing goes darker than the screen’s own lowest setting.
what i built
- 1.
Four ways of setting a brightness, chosen per screen: the hidden part of macOS the brightness keys use, for the laptop and Apple’s monitors; messages down the cable, for other monitors; and, for televisions, wireless screens and iPads, either dimming the picture’s colours or laying a dark sheet over them.
- 2.
Talking to monitors down the cable on both kinds of Mac: every message checked with a simple sum, polite non-answers told apart from nonsense, unclear replies asked again, and every screen’s messages sent one at a time, with a newer setting replacing one still waiting, so dragging a slider sends only as much as the monitor can take.
- 3.
The hidden parts of macOS looked up while the app runs rather than built in, so if a future macOS removes one, a single feature stops working instead of the whole app crashing; and each screen matched to the right connection by comparing the details it reports about itself.
- 4.
A slider that carries on below zero into extra dimming and, on screens that can go brighter for high-dynamic-range video, past full into that extra brightness, by lifting the picture’s colours while a single, almost invisible dot of extra-bright white keeps that headroom switched on.
- 5.
Brightness that learns: one mode makes other screens follow the laptop’s screen, which follows the room’s light; another follows the sun where you are, worked out from the standard astronomical formulas; and whenever you move a slider yourself, it remembers where you like it at that light.
- 6.
The keyboard’s brightness and volume keys working for every screen, by watching only those keys and never ordinary typing: what macOS can already do is left to macOS, the rest is handled with Luna’s own small indicator, and holding two modifier keys gives finer steps.
- 7.
Rounded corners on every screen, drawn as four small pieces per screen rather than one large overlay, plus a monitor’s volume, mute and input where it has them, turning a screen off without unplugging it, and keyboard shortcuts for all of it.
- 8.
Privacy built in: no tracking and no account, the internet used only to check for updates, your location never leaving the Mac, and the permission to see keys used only for brightness and volume.
outcome
About six thousand lines of code, with 48 automated tests covering the slider’s three ranges, the messages sent to monitors and the replies they send back, the learning brightness, the sun’s position, settings and which screens get the extra brightness; all of them pass. The installer is about 5 megabytes. The tricks it builds on, worked out by earlier open-source display apps, are credited by name in the project, down to the file that uses each one.
A setting only appears where that screen actually supports it, and a screen that answers nothing is still dimmed by changing the picture, so every screen on the desk gets one card and one slider.